session-orchestrator 5.7.0 → 5.8.0

package/scripts/lib/vault-mirror/process.mjs

@@ -6,11 +6,11 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { basename, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { createSecretValueMasker } from '../secret-masker.mjs';
-import { subjectToSlug, isValidSlug, uuidPrefix8, toDate, parseFrontmatter } from './utils.mjs';
+import { subjectToSlug, isValidSlug, uuidPrefix8, recordKeySuffix8, toDate, parseFrontmatter } from './utils.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
 import { detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2, learningSourceRecord } from './render-learnings.mjs';
@@ -423,6 +423,44 @@ function notOurGenerator(fm) {
   return null;
 }
 
+/**
+ * The disambiguation slug a record uses under `slug` in `dir` (#1506.1). An
+ * EXISTING `<slug>-<uuid8>` note that is ours and owned by this record keeps
+ * its name — the owner decision was "no mass rename"; every other case gets the
+ * full-record-key hash suffix ({@link recordKeySuffix8}), so non-UUID ids that
+ * share their first 8 chars no longer land on one file.
+ *
+ * @param {string} dir - the namespace folder.
+ * @param {string} slug - the canonical note slug.
+ * @param {{ legacyId: string, recordKey: string }} keys - `legacyId` is what the
+ *   pre-#1506 suffix was derived from (the raw id); `recordKey` the full key.
+ * @returns {{ slug: string, exists: boolean|null }} `exists: true` when the
+ *   legacy name was chosen (it was just probed); `null` when not yet probed.
+ */
+function disambigSlugFor(dir, slug, { legacyId, recordKey }) {
+  const legacy = `${slug}-${uuidPrefix8(legacyId)}`;
+  const hashed = `${slug}-${recordKeySuffix8(recordKey)}`;
+  const legacyPath = join(dir, `${legacy}.md`);
+  if (legacy !== hashed && existsSync(legacyPath)) {
+    const fm = parseFrontmatter(readFileSync(legacyPath, 'utf8'));
+    if (notOurGenerator(fm) === null && foreignOwnerReason(fm, { recordKey }) === null) {
+      return { slug: legacy, exists: true };
+    }
+  }
+  return { slug: hashed, exists: null };
+}
+
+/**
+ * Replace the frontmatter `id:` line of a note — used when a displaced note
+ * moves to its disambiguated name (#1506.2), whose `id` must match the file.
+ * @param {string} content
+ * @param {string} id
+ * @returns {string}
+ */
+function withNoteId(content, id) {
+  return content.replace(/^id: .*$/m, `id: ${id}`);
+}
+
 /**
  * Emit `skipped-foreign-owner` for a note the writer must not touch: one stderr
  * `SKIP` line (vault-relative path, like every other SKIP line) and the stdout
@@ -1154,26 +1192,58 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     // that note is masked in place first — never by rewriting it from THIS
     // record, which would be the #1503 overwrite triggered by a secret.
     //
-    // BV-004 ceiling: (1) the main `<slug>.md` keeps the FIRST record that
-    // claimed it — after a re-learn it goes stale while the current record lives
-    // at `<slug>-<uuid8>.md`; (2) disambiguation is ONE level deep — a
-    // `-<uuid8>` file owned by yet another record is skipped-foreign-owner.
-    // Fine while re-learns are rare (fleet census at review time: 39 slugs in 12
-    // repos). Revisit-Trigger: a stale main note is read as current, or a
-    // skipped-foreign-owner is reported on a `-<uuid8>` path.
+    // #1506.2: the NEWEST record owns the main `<slug>.md` — a re-learned
+    // record (strictly later `created` day) takes it over, and the displaced
+    // note moves, bytes kept but `id` renamed, to its own record's
+    // disambiguation path; never lost, never overwritten. #1506.1: a NEW
+    // disambiguation file is suffixed with a hash of the full record key, so
+    // non-UUID ids sharing a prefix no longer collide; existing `-<uuid8>`
+    // files keep their names.
+    //
+    // BV-004 ceiling: "newest" is compared at DAY granularity (`created` is a
+    // date) — a same-day re-learn keeps the current owner (stable, no churn).
+    // Revisit-Trigger: a same-day re-learn is reported as a stale main note.
+    //
+    // BV-004 ceiling: the takeover ignores repo provenance — a NEWER record of
+    // another repo mirrored into this namespace (the #1503 shape) also takes the
+    // main note, and `source-repo` cannot tell it apart (both carry the writer's
+    // namespace). Nothing is lost (the displaced note moves, never overwritten);
+    // the CLI's `source-repo-mismatch` refusal is what keeps foreign records out.
+    // Revisit-Trigger: a takeover whose displaced note belongs to this repo's
+    // live store, or any mirror run accepting a foreign `--source` again.
     const recordMismatch = foreignOwnerReason(fm, writer);
     const routedByRecord = recordMismatch !== null;
     if (routedByRecord && maskerWouldChange(existingContent)) {
       healedForeignLeak = maskForeignNoteInPlace(targetPath, existingContent, ctx);
     }
 
+    const entryDay = toDate(dateSource);
+    if (
+      routedByRecord &&
+      fm['id'] === slug &&
+      !expired &&
+      /^\d{4}-\d{2}-\d{2}$/.test(entryDay) &&
+      typeof fm['created'] === 'string' &&
+      entryDay > fm['created']
+    ) {
+      const takenOver = takeOverMainNote({
+        fm, slug, targetDir, targetPath, entry, entryId, writer, generator, generatorOpts,
+        healedForeignLeak, lineNum: _lineNum, ctx,
+      });
+      if (takenOver !== null) return takenOver;
+    }
+
     if (fm['id'] !== slug || routedByRecord) {
       // Different id (or different record) → collision: disambiguate
-      const disambigSlug = `${slug}-${uuidPrefix8(entryId)}`;
+      const picked = disambigSlugFor(targetDir, slug, {
+        legacyId: String(entryId),
+        recordKey: writer.recordKey ?? String(entryId),
+      });
+      const disambigSlug = picked.slug;
       targetPath = join(targetDir, `${disambigSlug}.md`);
       slug = disambigSlug;
 
-      if (existsSync(targetPath)) {
+      if (picked.exists ?? existsSync(targetPath)) {
         // Still exists with disambig — check if it's ours
         const disambigContent = readFileSync(targetPath, 'utf8');
         const disambigFm = parseFrontmatter(disambigContent);
@@ -1241,28 +1311,55 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
       });
     }
 
+    // #1506.2: the main note is this record's — a live disambiguation copy of
+    // the same record (left by an interrupted takeover) is superseded.
+    const stale = fm['source-record'] === writer.recordKey
+      ? staleOwnDisambig(targetDir, slug, entryId, writer)
+      : null;
+
     // Same id: check if updated would advance (unless --force overrides).
     // Even when the date has not advanced, content may have changed (confidence,
     // insight, expires_at, etc.) — compare canonical fields before skipping.
     const entryUpdated = toDate(dateSource);
+    let mainUnchanged = false;
     if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
       const candidateContent = generator(entry, slug, generatorOpts);
       if (learningContentMatches(existingContent, candidateContent)) {
         // #1028 residue 1: probe the on-disk content against the CURRENT masker
         // before trusting the five-field match — see maskerWouldChange above.
-        const stillLeaks = maskerWouldChange(existingContent);
-        if (!stillLeaks) {
-          return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
-        }
+        mainUnchanged = !maskerWouldChange(existingContent);
       }
       // Content differs, or the on-disk note still leaks under the current env —
       // fall through to overwrite (same path as date-advance branch).
     }
 
+    // #1519.4: archive the stale copy AND refresh the main note in the SAME run
+    // (previously the stale branch returned first, so a simultaneous record
+    // change reached the main note one run later). Stale copy first: a crash
+    // between the two writes leaves an archived copy beside a not-yet-refreshed
+    // main note, which the next run's content diff completes.
+    if (stale !== null && !dryRun) writeFileSync(stale.path, stale.next, 'utf8');
+    if (mainUnchanged) {
+      if (stale !== null) {
+        return emitEntryAction(_lineNum, ctx, {
+          action: 'updated',
+          path: stale.path,
+          id: basename(stale.path, '.md'),
+          meta: { archived_reason: 'superseded' },
+        });
+      }
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
+    }
+
     // Overwrite with advanced updated date (or forced re-render)
     const content = generator(entry, slug, generatorOpts);
     if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-    return emitEntryAction(_lineNum, ctx, { action: 'updated', path: targetPath, id: slug });
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'updated',
+      path: targetPath,
+      id: slug,
+      ...(stale !== null ? { meta: { superseded_id: basename(stale.path, '.md') } } : {}),
+    });
   }
 
   // File does not exist — create
@@ -1282,9 +1379,85 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
 }
 
 /**
- * The note slugs a learning record can live under: the canonical slug and, for
- * v1, the pre-#725 legacy variant. Used by the CLI to keep the archive pass off
- * notes a LIVE record still owns (#1513).
+ * The writer's own disambiguation note when it is stale (#1506.2): the writer's
+ * record owns the main note, so a mirror-owned, not-yet-archived note of the
+ * SAME record (explicit `source-record` match) at its disambiguation name is a
+ * second live copy — it is marked `archived` / `superseded`. Consulted by the
+ * takeover and on every run where the main note is already ours, so a crash
+ * between a takeover's writes heals on the next run.
+ *
+ * @returns {{ path: string, next: string }|null} the rewrite, or null.
+ */
+function staleOwnDisambig(targetDir, slug, entryId, writer) {
+  if (typeof writer.recordKey !== 'string') return null;
+  const own = disambigSlugFor(targetDir, slug, { legacyId: String(entryId), recordKey: writer.recordKey });
+  const path = join(targetDir, `${own.slug}.md`);
+  if (!(own.exists ?? existsSync(path))) return null;
+  const content = readFileSync(path, 'utf8');
+  const fm = parseFrontmatter(content);
+  if (notOurGenerator(fm) !== null || fm['source-record'] !== writer.recordKey || fm['id'] !== own.slug) return null;
+  const next = markArchived(content, 'superseded');
+  return next === content ? null : { path, next };
+}
+
+/**
+ * #1506.2 takeover: the writer's record is newer than the record that owns the
+ * main note, so the writer claims `<slug>.md`. The displaced note moves to its
+ * own record's disambiguation path (`id` renamed, bytes otherwise kept); a
+ * stale disambiguation note of the writer's own record (written while the older
+ * record held the main note) is marked `archived` / `superseded`.
+ *
+ * Returns `null` — leaving the caller on the plain disambiguation route — when
+ * the displaced record's target path is occupied by a note that is not ours or
+ * belongs to yet another record: a takeover must never overwrite anything.
+ *
+ * @returns {string|null} the emitted action, or null.
+ */
+function takeOverMainNote({
+  fm, slug, targetDir, targetPath, entry, entryId, writer, generator, generatorOpts, healedForeignLeak, lineNum, ctx,
+}) {
+  const { dryRun } = ctx;
+  const displacedKey = fm['source-record'];
+  const displaced = disambigSlugFor(targetDir, slug, { legacyId: displacedKey, recordKey: displacedKey });
+  const displacedPath = join(targetDir, `${displaced.slug}.md`);
+  if (displaced.exists !== true && existsSync(displacedPath)) {
+    const dfm = parseFrontmatter(readFileSync(displacedPath, 'utf8'));
+    if (notOurGenerator(dfm) !== null || dfm['source-record'] !== displacedKey) return null;
+  }
+
+  const ownStale = staleOwnDisambig(targetDir, slug, entryId, writer);
+
+  if (!dryRun) {
+    // Re-read: an in-place leak heal above may have rewritten the note.
+    const current = readFileSync(targetPath, 'utf8');
+    // Rewritten even when it exists (and is ours, checked above): a stale copy
+    // there may carry `status: archived` from an earlier archive pass.
+    writeFileSync(displacedPath, withNoteId(current, displaced.slug), 'utf8');
+    // Before the main note: a crash between the two writes must leave the
+    // takeover re-runnable (the main note still foreign), never a main note of
+    // ours beside a stale live disambiguation note of the same record.
+    if (ownStale !== null && ownStale.path !== displacedPath) writeFileSync(ownStale.path, ownStale.next, 'utf8');
+    writeFileSync(targetPath, generator(entry, slug, generatorOpts), 'utf8');
+  }
+  return emitEntryAction(lineNum, ctx, {
+    action: 'updated',
+    path: targetPath,
+    id: slug,
+    meta: {
+      reason: 'newer record owns the main note',
+      displaced_id: displaced.slug,
+      ...(healedForeignLeak ? { healed_leak: true } : {}),
+    },
+  });
+}
+
+/**
+ * The note slugs a learning record can live under: the canonical slug, for v1
+ * the pre-#725 legacy variant, and its two disambiguation names — the
+ * pre-#1506 `-<uuid8>` and the full-key `-<hash8>` (#1506.1). Used by the CLI
+ * to keep the archive pass off notes a LIVE record still owns (#1513). The
+ * disambiguation names are record-specific, so a record displaced from the
+ * main note by a re-learn (#1506.2) is still archived once it leaves the store.
  *
  * @param {object} rawEntry
  * @returns {string[]}
@@ -1298,6 +1471,10 @@ export function learningNoteSlugs(rawEntry) {
     const legacy = legacyConcatSlug(entry.subject);
     if (isValidSlug(legacy) && !slugs.includes(legacy)) slugs.push(legacy);
   }
+  const id = String(entry.id);
+  for (const name of [`${slugs[0]}-${uuidPrefix8(id)}`, `${slugs[0]}-${recordKeySuffix8(learningSourceRecord(entry) ?? id)}`]) {
+    if (!slugs.includes(name)) slugs.push(name);
+  }
   return slugs;
 }
 
@@ -1305,12 +1482,12 @@ export function learningNoteSlugs(rawEntry) {
  * Mark the existing note of a record that left `learnings.jsonl` (#1513).
  *
  * Input is one `learnings-archive.jsonl` record. Its note — canonical slug,
- * legacy slug, or the `-<uuid8>` disambiguation, in the namespace or the flat
+ * legacy slug, or a `-<uuid8>`/`-<hash8>` disambiguation, in the namespace or the flat
  * legacy layout — gets `status: archived` + `archived-reason` (`expired` for an
  * `_archive_reason: expired` record, `superseded` for every other reason). The
  * note's bytes are otherwise kept; nothing is ever created. Ownership rules are
  * the same as for writes: mirror-owned, and a `source-record` naming another
- * record is left alone. Slugs in `ctx.liveLearningSlugs` (records still in the
+ * record is left alone. Names in `ctx.liveLearningSlugs` (records still in the
  * live store) are skipped, so a re-learned subject never flip-flops.
  *
  * @returns {Promise<string>} the emitted action
@@ -1322,10 +1499,14 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
     throw new Error(`vault-mirror: archived learning entry missing required field 'id' (id=<no id>)`);
   }
   const reason = entry._archive_reason === 'expired' ? 'expired' : 'superseded';
-  const slugs = learningNoteSlugs(entry);
   const live = ctx?.liveLearningSlugs instanceof Set ? ctx.liveLearningSlugs : new Set();
-  if (slugs.some((s) => live.has(s))) {
-    return emitEntryAction(_lineNum, ctx, {
+  // Per name, not per record (#1506.2): a live re-learn owns the canonical
+  // slug, but the displaced note at THIS record's disambiguation name is still
+  // this record's to archive.
+  const allNames = learningNoteSlugs(entry);
+  const names = allNames.filter((s) => !live.has(s));
+  const liveOwned = () =>
+    emitEntryAction(_lineNum, ctx, {
       // `skipped-noop`, not a class of its own: this is the steady state of
       // every run, and noops stay out of the per-entry ledger (#1151).
       action: 'skipped-noop',
@@ -1333,7 +1514,7 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
       id: entry.id,
       meta: { reason: 'archived record: a live record owns this note' },
     });
-  }
+  if (names.length === 0) return liveOwned();
   const repoNs = canonicalNamespace(
     vaultDir,
     resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
@@ -1341,7 +1522,6 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
   const nsDir = join(resolve(vaultDir), '40-learnings', repoNs);
   const flatDir = join(resolve(vaultDir), '40-learnings');
   const writer = { recordKey: learningSourceRecord(entry) };
-  const names = [...slugs, `${slugs[0]}-${uuidPrefix8(String(entry.id))}`];
   for (const dir of [nsDir, flatDir]) {
     for (const name of names) {
       const path = join(dir, `${name}.md`);
@@ -1363,6 +1543,7 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
       });
     }
   }
+  if (names.length < allNames.length) return liveOwned();
   return emitEntryAction(_lineNum, ctx, {
     action: 'skipped-noop',
     path: null,

package/scripts/lib/vault-mirror/utils.mjs

@@ -4,10 +4,11 @@
  * Exports: subjectToSlug, isValidSlug, uuidPrefix8, toDate,
  *          truncateAtWord, yamlQuoteIfNeeded, parseFrontmatter,
  *          slugifyTagSegment, buildTag, slugifyIdSafe, TAG_MAX_LENGTH,
- *          resolveSourceSessionLink
+ *          resolveSourceSessionLink, recordKeySuffix8
  */
 
 import { parseSessionId } from '../session-id.mjs';
+import { digestSha256Short } from '../crypto-digest-utils.mjs';
 
 /**
  * Convert a subject string to a kebab slug.
@@ -135,6 +136,20 @@ export function uuidPrefix8(id) {
   return id.replace(/-/g, '').slice(0, 8);
 }
 
+/**
+ * The disambiguation suffix of a NEW `<slug>-<suffix>.md` note (#1506.1): the
+ * first 8 hex chars of a SHA-256 over the FULL record key. `uuidPrefix8` only
+ * separates UUID ids — non-UUID ids sharing their first 8 chars collided, and
+ * the third record of a subject was never mirrored. Existing `-<uuid8>` notes
+ * keep their names; only newly created disambiguation files use this suffix.
+ *
+ * @param {string} recordKey - the record's `source-record` (or its raw id).
+ * @returns {string} 8 lowercase hex chars.
+ */
+export function recordKeySuffix8(recordKey) {
+  return digestSha256Short(String(recordKey));
+}
+
 /** Format a UTC ISO date string as YYYY-MM-DD. */
 export function toDate(isoString) {
   if (!isoString) return '';

package/scripts/lib/vault-sync-baseline.mjs

@@ -17,8 +17,9 @@
  */
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
-import { readFileSync, writeFileSync, mkdirSync, renameSync, existsSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { atomicWriteWithBackup, envelopeToError } from './io.mjs';
+import { readFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
 
 // ---------------------------------------------------------------------------
 // computeSchemaHash
@@ -60,12 +61,12 @@ export function writeBaseline(filePath, { errors, warnings, schemaHash, isoTimes
     warnings,
   };
 
-  const dir = dirname(filePath);
-  mkdirSync(dir, { recursive: true });
-
-  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
-  renameSync(tmp, filePath);
+  // Parent dirs are created by the helper (mkdir -p); a failure re-raises with
+  // the original message and `code`.
+  const res = atomicWriteWithBackup(filePath, JSON.stringify(doc, null, 2) + '\n', {
+    tmpPrefix: `.${basename(filePath)}.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/wave-transcript-tail.mjs

@@ -56,14 +56,14 @@ import {
 import { homedir } from 'node:os';
 import { join, relative, isAbsolute } from 'node:path';
 
-import { emitEvent, sessionAttribution } from './events.mjs';
+import { emitEvent, eventsFilePath, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
 import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
 import { isMainModule } from './is-main-module.mjs';
+import { getProjectDir } from './platform.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
-const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
 const WAVE_SCOPE_REL = '.claude/wave-scope.json';
 
 /**
@@ -785,7 +785,11 @@ function sleep(ms) {
  * @param {number} args.intervalS
  */
 async function tailLoop({ intervalS }) {
-  const repoRoot = process.env.CLAUDE_PLUGIN_ROOT || process.cwd();
+  // #1517: the PROJECT root (CLAUDE_PROJECT_DIR > CLAUDE.md or AGENTS.md / .git walk-up > cwd).
+  // CLAUDE_PLUGIN_ROOT is the installed plugin directory — taking it as the root
+  // put the singleton lock, the session.lock read and the projects-dir encoding
+  // inside the plugin cache.
+  const repoRoot = getProjectDir();
 
   // The monitor fires once per wave-executor INVOCATION, and a deep session
   // invokes it repeatedly — so refuse to be the second tailer.
@@ -813,7 +817,7 @@ async function tailLoop({ intervalS }) {
   // Restart-safety: do not re-announce findings already recorded for this
   // session. Seeded on the SEMANTIC id — the same key `report()` writes.
   try {
-    const evPath = join(repoRoot, EVENTS_FILE_REL);
+    const evPath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
     if (existsSync(evPath)) {
       const seeded = seedFromEvents(readFileSync(evPath, 'utf8').split('\n'), semanticSessionId, state);
       if (seeded > 0) note(`seeded ${seeded} prior finding counters from events.jsonl`);

package/scripts/lib/worktree/meta.mjs

@@ -13,6 +13,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { WORKTREE_META_DIR } from './constants.mjs';
+import { atomicWriteText, envelopeToError } from '../io.mjs';
 
 // ---------------------------------------------------------------------------
 // Public helpers
@@ -58,7 +59,10 @@ export async function _writeWorktreeMeta(suffix, { branch, wtPath, baseRef, base
     createdAt: new Date().toISOString(),
   };
 
-  const tmpPath = `${metaPath}.tmp`;
-  await fs.writeFile(tmpPath, JSON.stringify(meta, null, 2), 'utf8');
-  await fs.rename(tmpPath, metaPath);
+  // Random tmp suffix: the former fixed `<meta>.tmp` name let two concurrent
+  // writers of the same suffix clobber each other's tmp (#1032).
+  const res = await atomicWriteText(metaPath, JSON.stringify(meta, null, 2), {
+    tmpPrefix: `.${suffix}.json.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 }

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)