session-orchestrator 5.7.0 → 5.9.0

package/scripts/mcp-server.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/** Native, dependency-free MCP stdio transport. No shell, WSL, or jq required. */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isSessionConfigHeading } from './lib/config/section-extractor.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const SERVER_INFO = { name: 'session-orchestrator', version: '2.0.0' };
+const TOOLS = [
+  {
+    name: 'session_config',
+    description: 'Reads Session Config section from the project instruction file (CLAUDE.md or AGENTS.md alias)',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'session_metrics',
+    description: 'Reads the last 5 REAL session metrics entries from .orchestrator/metrics/sessions.jsonl (abandoned phantom stubs excluded)',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+];
+const textContent = (text) => ({ content: [{ type: 'text', text }] });
+const errorResponse = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/** Resolve the caller's repository without passing native paths through a shell. */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', windowsHide: true, timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isFile(path, nonempty = false) {
+  try {
+    const stat = statSync(path);
+    return stat.isFile() && (!nonempty || stat.size > 0);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+/** Read the same raw config body as the legacy shell tool (including comments). */
+export function readSessionConfig(root) {
+  const file = ['CLAUDE.md', 'AGENTS.md'].map((name) => join(root, name))
+    .find((path) => isFile(path, true));
+  if (!file) return `No CLAUDE.md or AGENTS.md found at ${root}`;
+  const body = [];
+  let inSection = false;
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (isSessionConfigHeading(line)) {
+      inSection = true;
+    } else if (line.startsWith('## ')) {
+      inSection = false;
+    } else if (inSection) {
+      body.push(line);
+    }
+  }
+  // Shell command substitution removes LF bytes, not spaces or CR bytes.
+  return body.join('\n').replace(/\n+$/, '') || `No '## Session Config' section found in ${file}`;
+}
+
+/** Read the last five real records, with whole-ledger stub count and token coverage. */
+export function readSessionMetrics(root) {
+  const file = ['.orchestrator', '.claude'].map((dir) => join(root, dir, 'metrics', 'sessions.jsonl'))
+    .find((path) => isFile(path));
+  if (!file) return 'No metrics found (checked .orchestrator/metrics/ and .claude/metrics/)';
+  const entries = [];
+  let stubCount = 0;
+  for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    // Torn writes and non-record JSON must not hide subsequent valid sessions.
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+    if (record.status === 'abandoned') { stubCount++; continue; }
+    entries.push(record);
+    if (entries.length > 5) entries.shift();
+  }
+  if (!entries.length) {
+    return stubCount ? `No real sessions (abandoned stubs excluded: ${stubCount})`
+      : 'No metrics found (file is empty)';
+  }
+  const record = entries.findLast((entry) => (entry.total_token_input !== null && entry.total_token_input !== undefined)
+    || (entry.total_token_output !== null && entry.total_token_output !== undefined));
+  const coverage = record?.subagents_with_tokens ?? 0;
+  const summary = record
+    ? `tokens: ${record.total_token_input ?? '?'} in / ${record.total_token_output ?? '?'} out`
+      + ` (coverage: ${coverage} subagents)`
+      + (coverage === 0 ? ' ⚠ partial — subagent token data missing; total is not a reliable cost estimate' : '')
+      + ` [session: ${record.session_id ?? 'unknown'}]`
+    : 'tokens: no token data in last 5 sessions (subagent telemetry not yet captured)';
+  return entries.map((entry) => JSON.stringify(entry)).join('\n')
+    + `\n\nabandoned stubs excluded: ${stubCount}\n\n--- token summary ---\n${summary}`;
+}
+
+/** Handle one JSON-RPC line. null means a notification or blank line, not a reply. */
+export function handleLine(line, { cwd = process.cwd(), resolveRoot = resolveProjectRoot } = {}) {
+  if (!line.trim()) return null;
+  let request;
+  try { request = JSON.parse(line); } catch { return errorResponse(null, -32700, 'Parse error'); }
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    return errorResponse(null, -32600, 'Invalid Request');
+  }
+  const hasId = Object.hasOwn(request, 'id');
+  const validId = request.id === null || typeof request.id === 'string' || typeof request.id === 'number';
+  const id = hasId && validId ? request.id : null;
+  if (request.jsonrpc !== '2.0' || typeof request.method !== 'string' || (hasId && !validId)) {
+    return errorResponse(id, -32600, 'Invalid Request');
+  }
+  if (!hasId || request.method.startsWith('notifications/')) return null;
+  let result;
+  switch (request.method) {
+    case 'initialize':
+      result = { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: SERVER_INFO };
+      break;
+    case 'tools/list':
+      result = { tools: TOOLS };
+      break;
+    case 'tools/call': {
+      const name = request.params?.name;
+      if (typeof name !== 'string') return errorResponse(id, -32602, 'Invalid tool name');
+      if (!TOOLS.some((tool) => tool.name === name)) return errorResponse(id, -32602, `Unknown tool: ${name}`);
+      try {
+        const root = resolveRoot(cwd);
+        result = textContent(root
+          ? (name === 'session_config' ? readSessionConfig(root) : readSessionMetrics(root))
+          : 'Error: not inside a git repository');
+      } catch {
+        return errorResponse(id, -32603, 'Unable to read session data');
+      }
+      break;
+    }
+    default:
+      return errorResponse(id, -32601, `Method not found: ${request.method}`);
+  }
+  return { jsonrpc: '2.0', id, result };
+}
+
+/** Start newline-delimited JSON-RPC on the supplied streams. */
+export async function serve({ input = process.stdin, output = process.stdout, cwd = process.cwd() } = {}) {
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const response = handleLine(line, { cwd });
+    if (response) output.write(`${JSON.stringify(response)}\n`);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  serve().catch(() => {
+    process.stderr.write('session-orchestrator: MCP stdio transport failed.\n');
+    process.exitCode = 2;
+  });
+}

package/scripts/migrate-sessions-jsonl.mjs

@@ -38,8 +38,9 @@
  *    "already_canonical":N,"unmappable":N,"parse_errors":N,"backup":"<path>|null"}
  */
 
-import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { readFileSync, copyFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
+import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
 import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
@@ -422,11 +423,12 @@ async function main() {
   // Atomic write: backup → tmp → rename
   const iso = new Date().toISOString().replace(/[:.]/g, '-');
   const backupPath = `${args.file}.bak-${iso}`;
-  const tmpPath = join(dirname(args.file), `.${basename(args.file)}.migrate-tmp-${process.pid}`);
   try {
     copyFileSync(args.file, backupPath);
-    writeFileSync(tmpPath, outputLines.join('\n') + '\n', 'utf8');
-    renameSync(tmpPath, args.file);
+    const res = atomicWriteWithBackup(args.file, outputLines.join('\n') + '\n', {
+      tmpPrefix: `.${basename(args.file)}.tmp`,
+    });
+    if (!res.ok) throw envelopeToError(res);
     summary.backup = backupPath;
   } catch (err) {
     const hint = existsSync(backupPath)

package/scripts/migrate-vault-paths.mjs

@@ -58,6 +58,7 @@ import {
 } from './lib/vault-migration-rules.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -529,12 +530,14 @@ function findHits(filePath, content) {
 }
 
 /**
- * Atomic write: write to <path>.migrate-tmp, then rename.
+ * Atomic write via `atomicWriteText` (`<dir>/.<name>.tmp.<hex>`, then rename);
+ * throws with the original message and `code` on failure.
  */
 async function atomicWrite(filePath, content) {
-  const tmp = `${filePath}.migrate-tmp-${process.pid}-${Date.now()}`;
-  await fs.writeFile(tmp, content, 'utf8');
-  await fs.rename(tmp, filePath);
+  const res = await atomicWriteText(filePath, content, {
+    tmpPrefix: `.${path.basename(filePath)}.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 /**

package/scripts/print-learnings-index.mjs

@@ -101,6 +101,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { eventsFilePath } from './lib/events.mjs';
 import { resolveStateArtifactPath } from './lib/state-md.mjs';
 import {
   CANDIDATE_POOL_SIZE,
@@ -249,7 +250,7 @@ const repoRoot = findProjectRoot(process.cwd());
 const learningsPath = opts.learnings
   ? opts.learnings
   : join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
-const eventsPath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+const eventsPath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
 // #1019 — the natively-delivered rule corpus. Every `.claude/rules/*.md` reaches
 // a dispatched agent in FULL through Claude Code's own project-instruction
 // loading (`docs/instruction-delivery.md` §1: the `globs:`/`tier:` frontmatter is

package/scripts/release.mjs

@@ -387,11 +387,14 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // `scripts/lib/locks/index.mjs` is the one-cycle deprecation shim (5.2.0 CHANGELOG, Changed): its
 // runtime warning names the version it was deprecated IN, so it legitimately carries the previous
 // release literal until its 6.0.0 removal — version history by construction, not drift.
+// `skills/eval/rubric-v3.md` (5.9.0 sweep, measured 2026-10-06): its change log quotes the dated
+// owner decision "rubric-v3 in 5.8.0" (2026-10-05, #1487) — the release that introduced the rubric.
+// Prose history, not a version surface; bumping it would falsify the quote.
 // `site/_census.json` is deliberately NOT allowlisted: it carries a `"version"` field that
 // `--set-version` re-stamps (scripts/site-numbers.mjs --write, see the post-bump hint in main()),
 // so leaving it under the drift sweep makes the sweep double as its staleness gate — a census
 // not re-stamped after a bump fails `--check` instead of shipping the previous version.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|skills\/eval\/rubric-v3\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {

package/scripts/relocate-vault-corpus.mjs

@@ -55,6 +55,7 @@ import {
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -693,7 +694,6 @@ async function writeManifest({ vaultDir, derivableOnly, summary, moves }) {
 
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   const manifestPath = path.join(manifestDir, `relocation-manifest-${ts}.json`);
-  const tmpPath = `${manifestPath}.tmp-${process.pid}`;
 
   // Store vault-relative paths in the manifest
   const movesRel = moves.map((m) => ({
@@ -714,8 +714,10 @@ async function writeManifest({ vaultDir, derivableOnly, summary, moves }) {
     moves: movesRel,
   };
 
-  await fs.writeFile(tmpPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-  await fs.rename(tmpPath, manifestPath);
+  const res = await atomicWriteText(manifestPath, JSON.stringify(manifest, null, 2) + '\n', {
+    tmpPrefix: `.${path.basename(manifestPath)}.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 
   return manifestPath;
 }

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

@@ -32,9 +32,9 @@
  *      with the next repo, and exits 2 at the end
  */
 
-import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
 import { mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import {
   migrateLegacyLearning,
@@ -43,6 +43,7 @@ import {
 import { LearningsLockError, withLearningsLock } from './lib/learnings/io.mjs';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
 
 const LEARNINGS_REL = '.orchestrator/metrics/learnings.jsonl';
 
@@ -316,12 +317,13 @@ function migrateStore(repoPath, learningsPath, apply) {
     try {
       // Backup original
       copyFileSync(learningsPath, backupPath);
-      // Write migrated content atomically
+      // Write migrated content atomically (own backup above keeps its
+      // `.bak-cross-repo-migrate-<ms>` schema, so the helper takes none)
       const body = outputLines.join('\n') + '\n';
-      const tmpPath = `${learningsPath}.migrate-cross-repo-tmp-${process.pid}-${timestamp}`;
-      mkdirSync(dirname(learningsPath), { recursive: true });
-      writeFileSync(tmpPath, body, 'utf8');
-      renameSync(tmpPath, learningsPath);
+      const res = atomicWriteWithBackup(learningsPath, body, {
+        tmpPrefix: `.${basename(learningsPath)}.tmp`,
+      });
+      if (!res.ok) throw envelopeToError(res);
     } catch (err) {
       return {
         repo: repoPath,

package/scripts/run-quality-gate.mjs

@@ -55,8 +55,8 @@ import {
   resolveGateTimeoutMs,
 } from './lib/gates/gate-helpers.mjs';
 import { buildCommandSignature, spawnInGroup } from './lib/process-group.mjs';
-import { classifyManifestSession, readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
-import { findOwnScopeFile } from './lib/scope-gate.mjs';
+import { resolveWaveNumber } from './lib/quality-gate-wave.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 import { gateKillFields } from './lib/quality-gate.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { shellQuote } from './lib/sh-quote.mjs';
@@ -266,42 +266,6 @@ function resolveLedgerRoot(value) {
   return null;
 }
 
-/**
- * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
- *
- * Mirrors `resolveWave()` in `hooks/pre-bash-memory-propose-audit.mjs` — the
- * same `.{pi,cursor,codex,claude}/wave-scope.json` precedence via
- * {@link findOwnScopeFile}, skipping a PEER session's manifest in the same
- * working copy (#1504: a peer-only result is no wave of ours, never the peer's
- * number) — with ONE deliberate difference: the hook returns `0` for "no
- * wave-scope file", this returns `null`.
- *
- * Absent is not zero. A human running `npm run quality-gate` from a `git push`
- * has no wave at all, and that is the common case; publishing `wave_number: 0`
- * would invent a wave 0 that every consumer then has to special-case. The
- * caller spreads the result so the KEY is omitted, exactly as `counts` is.
- *
- * A non-positive or non-numeric `wave` field is treated the same way — waves
- * are 1-indexed, so `0` on disk carries no more information than an absent file.
- *
- * Never throws.
- *
- * @param {string} projectDir — directory whose wave-scope sidecar to read.
- * @returns {number|null} positive wave number, or `null` when there is no wave.
- */
-function resolveWaveNumber(projectDir) {
-  try {
-    const ownIds = new Set(readProcessLocalSessionIds({ env: process.env, hookInput: null }));
-    const { path: waveFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
-    if (!waveFile || !existsSync(waveFile)) return null;
-    const wave = JSON.parse(readFileSync(waveFile, 'utf8'))?.wave;
-    if (typeof wave !== 'number' || !Number.isFinite(wave) || wave <= 0) return null;
-    return Math.trunc(wave);
-  } catch {
-    return null;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Main — the CLI body. Guarded below so a bare `import()` runs none of it.
 // ---------------------------------------------------------------------------
@@ -471,7 +435,13 @@ async function main() {
   //
   // stdout is PIPED (not inherited) so the suite counts the gate already computed
   // can be lifted straight off its JSON envelope into telemetry (#954) instead of
-  // travelling as prose through the STATE.md header. The envelope is re-emitted
+  // travelling as prose through the STATE.md header. Both skill readers select
+  // the last matching flat event by semantic_session_id + wave_number; there is
+  // no platform field on the payload. Count fallback (wave-loop step 7: this
+  // wave's own gate output; session end: the STATE.md header) is limited to
+  // pre-#954 sessions, gates outside the event wrapper, or missing wave
+  // attribution (see docs/events-schema.md).
+  // The envelope is re-emitted
   // verbatim below, so the stdout contract is unchanged — a gate sub-script writes
   // exactly one JSON line at the very end (its own child commands are captured by
   // `runCheck`), so nothing streamed before and nothing streams now.