session-orchestrator 5.6.0 → 5.8.0

package/scripts/generate-pi-prompts.mjs

@@ -19,10 +19,11 @@
  *   node scripts/generate-pi-prompts.mjs --check
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+import { isUserInvocableSkill } from './lib/user-invocable-skills.mjs';
+import { listCommandFiles, listSkillDirs, parseFrontmatter } from './lib/plugin-surface.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
@@ -33,74 +34,6 @@ const PROMPTS_DIR = path.join(ROOT, 'pi', 'prompts');
 const CHECK_ONLY = process.argv.includes('--check');
 const DESCRIPTION_MAX = 1024;
 
-function isDir(p) {
-  try { return statSync(p).isDirectory(); } catch { return false; }
-}
-
-function commandFiles() {
-  if (!existsSync(COMMANDS_DIR)) return [];
-  return readdirSync(COMMANDS_DIR)
-    .filter((name) => name.endsWith('.md'))
-    .sort();
-}
-
-function skillDirs() {
-  if (!existsSync(SKILLS_DIR)) return [];
-  return readdirSync(SKILLS_DIR)
-    .filter((name) => isDir(path.join(SKILLS_DIR, name)) && existsSync(path.join(SKILLS_DIR, name, 'SKILL.md')))
-    .sort();
-}
-
-/**
- * Parse YAML-ish frontmatter including `>` / `|` folded scalars, returning
- * DECODED values (surrounding quotes stripped). Skill descriptions are folded
- * scalars in practice, which the previous line-at-a-time parser read as the
- * literal `>`. Mirrors `generate-cursor-adapter.mjs`.
- *
- * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
- * two probes below miss the block entirely: the file parsed as "no
- * frontmatter", so `user-invocable` silently disappeared and the skill was
- * demoted out of `pi/prompts/` with no diagnostic anywhere. Both are normalised
- * away first — the same treatment `parseAgentFrontmatter`
- * (`scripts/lib/agent-frontmatter.mjs`) gives them.
- *
- * @param {string} content
- * @returns {Record<string, string>}
- */
-function parseFrontmatter(content) {
-  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
-  if (!text.startsWith('---\n')) return {};
-  const end = text.indexOf('\n---\n', 4);
-  if (end === -1) return {};
-
-  const lines = text.slice(4, end).split('\n');
-  const fields = {};
-  let i = 0;
-  while (i < lines.length) {
-    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!match) {
-      i += 1;
-      continue;
-    }
-    const key = match[1];
-    const raw = match[2];
-    if (raw === '>' || raw === '| ' || raw === '|' || raw === '>-' || raw === '|-') {
-      const folded = [];
-      i += 1;
-      while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i] === '')) {
-        folded.push(lines[i].replace(/^\s+/, ''));
-        i += 1;
-      }
-      const joiner = raw.startsWith('|') ? '\n' : ' ';
-      fields[key] = folded.filter(Boolean).join(joiner).trim();
-      continue;
-    }
-    fields[key] = raw.replace(/^["']|["']$/g, '');
-    i += 1;
-  }
-  return fields;
-}
-
 /** @see generate-cursor-adapter.mjs — same allow-list, same reasoning. */
 const YAML_SCALAR_LOOKALIKE = /^(?:true|false|yes|no|on|off|null|nan|[-+]?\.?inf|~)$/i;
 const YAML_PLAIN_SAFE = /^[A-Za-z0-9_][A-Za-z0-9 _.,()/-]*$/;
@@ -138,7 +71,8 @@ function clampDescription(text) {
 /**
  * Skills that declare themselves operator-facing slash commands.
  *
- * The predicate is `isUserInvocableValue` from `scripts/lib/user-invocable-skills.mjs`
+ * The predicate is `isUserInvocableSkill` from `scripts/lib/user-invocable-skills.mjs`
+ * (absent key = invocable, as Claude Code reads it — #1515; values via `isUserInvocableValue`)
  * — the ONE normaliser for this marker, shared with the Cursor and Codex
  * generators and with every counter. A local copy here is how the quoted-value
  * disagreement arose (`"true"`: wrapper generated on two adapters, counted by
@@ -147,10 +81,10 @@ function clampDescription(text) {
  * @returns {string[]} skill names, sorted
  */
 function userInvocableSkills() {
-  return skillDirs().filter((name) => {
+  return listSkillDirs(ROOT).filter((name) => {
     const file = path.join(SKILLS_DIR, name, 'SKILL.md');
     const fields = parseFrontmatter(readFileSync(file, 'utf8'));
-    return isUserInvocableValue(fields['user-invocable'], file);
+    return isUserInvocableSkill(fields, file);
   });
 }
 
@@ -217,7 +151,7 @@ Read that skill file and follow it exactly. When it references \`$ARGUMENTS\`, s
  */
 function expectedPrompts() {
   const prompts = new Map();
-  for (const commandFile of commandFiles()) {
+  for (const commandFile of listCommandFiles(ROOT)) {
     prompts.set(commandFile, renderPrompt(commandFile));
   }
 

package/scripts/github-protection-audit.mjs

@@ -124,6 +124,14 @@ function classifyFailure(err) {
 
   const stderr = err && typeof err === 'object' ? String(/** @type {any} */ (err).stderr ?? '') : '';
   const haystack = `${message}\n${stderr}`.toLowerCase();
+  // Rate limit BEFORE the auth check (#1034 item 2): GitHub answers a primary
+  // or secondary rate limit with HTTP 403, so the `http 403` test below would
+  // otherwise tell the operator to re-authenticate when waiting is the fix. A
+  // 403 without rate-limit wording (expired token, missing scope) stays
+  // `auth-error`, and so does an UNAUTHENTICATED rate limit, whose fix is to
+  // log in. `abuse detection` is GitHub's older wording for the secondary limit.
+  const rateLimited = haystack.includes('rate limit') || haystack.includes('abuse detection');
+  if (rateLimited && !haystack.includes('authenticated requests get a higher')) return 'query-failed';
   if (
     haystack.includes('gh auth login') ||
     haystack.includes('not logged in') ||

package/scripts/lib/auto-dialectic.mjs

@@ -30,10 +30,11 @@
  * separate helpers. No external deps — Node 20+ stdlib only.
  */
 
-import { readFile, writeFile, rename, unlink, mkdir, readdir, stat, lstat } from 'node:fs/promises';
+import { readFile, rename, unlink, mkdir, readdir, stat, lstat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { atomicWriteText, envelopeToError } from './io.mjs';
 
 import { filterRealSessions } from './session-schema.mjs';
 
@@ -284,7 +285,7 @@ export async function shouldDispatchAutoDialectic({
 /**
  * Write `.orchestrator/dialectic-last-run` with the given ISO timestamp.
  *
- * Atomicity: write to `<path>.<rand>.tmp`, then rename(). Same-fs rename is
+ * Atomicity: `atomicWriteText` (`<dir>/.<name>.tmp.<hex>`, then rename()). Same-fs rename is
  * atomic on POSIX — observers see either the previous file or the new one,
  * never a half-written intermediate (mirrors auto-dream.mjs:248-251).
  *
@@ -312,9 +313,10 @@ export async function writeDialecticLastRun({ repoRoot, isoTimestamp } = {}) {
   const target = lastRunPath(repoRoot);
   try {
     await mkdir(path.dirname(target), { recursive: true });
-    const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`;
-    await writeFile(tmp, `${isoTimestamp}\n`, 'utf8');
-    await rename(tmp, target);
+    const res = await atomicWriteText(target, `${isoTimestamp}\n`, {
+      tmpPrefix: `.${path.basename(target)}.tmp`,
+    });
+    if (!res.ok) return { ok: false, error: res.error };
     return { ok: true, path: target };
   } catch (err) {
     return { ok: false, error: err.message };
@@ -401,11 +403,10 @@ export async function writeDialecticPending({
   ].join('\n');
 
   const content = `${frontmatter}${diff}${diff.endsWith('\n') ? '' : '\n'}`;
-  const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`;
-  await writeFile(tmp, content, 'utf8');
-  await rename(tmp, target);
+  const res = await atomicWriteText(target, content, { tmpPrefix: `.${path.basename(target)}.tmp` });
+  if (!res.ok) throw envelopeToError(res);
 
-  return { path: target, bytes: Buffer.byteLength(content, 'utf8') };
+  return { path: target, bytes: res.bytes };
 }
 
 /**

package/scripts/lib/auto-dream.mjs

@@ -21,10 +21,10 @@
  * No external deps — Node 20+ stdlib only.
  */
 
-import { readFile, writeFile, rename, unlink, mkdir } from 'node:fs/promises';
+import { readFile, unlink, mkdir } from 'node:fs/promises';
 import { existsSync, statSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { atomicWriteText, envelopeToError } from './io.mjs';
 
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { filterRealSessions } from './session-schema.mjs';
@@ -205,7 +205,7 @@ function pendingDreamPath(repoRoot) {
  * the metadata session-end's Final Report and the next session's --apply-pending
  * step both rely on.
  *
- * Atomicity: write to `<path>.<rand>.tmp`, then rename(). Same-fs rename is
+ * Atomicity: `atomicWriteText` (`<dir>/.<name>.tmp.<hex>`, then rename()). Same-fs rename is
  * atomic on POSIX — observers see either the previous file or the new one,
  * never a half-written intermediate.
  *
@@ -245,11 +245,10 @@ export async function writePendingDream({
   ].join('\n');
 
   const content = `${frontmatter}${diff}${diff.endsWith('\n') ? '' : '\n'}`;
-  const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`;
-  await writeFile(tmp, content, 'utf8');
-  await rename(tmp, target);
+  const res = await atomicWriteText(target, content, { tmpPrefix: `.${path.basename(target)}.tmp` });
+  if (!res.ok) throw envelopeToError(res);
 
-  return { path: target, bytes: Buffer.byteLength(content, 'utf8') };
+  return { path: target, bytes: res.bytes };
 }
 
 /**
@@ -472,9 +471,8 @@ export async function applyPendingDream({ repoRoot, memoryDir, maxAgeDays = 14 }
 
   const newBody = extractedBlock.trimEnd() + '\n';
   await mkdir(path.dirname(memoryPath), { recursive: true });
-  const tmp = `${memoryPath}.${randomUUID().slice(0, 8)}.tmp`;
-  await writeFile(tmp, newBody, 'utf8');
-  await rename(tmp, memoryPath);
+  const res = await atomicWriteText(memoryPath, newBody, { tmpPrefix: '.MEMORY.md.tmp' });
+  if (!res.ok) throw envelopeToError(res);
 
   const linesAfter = newBody.length === 0 ? 0 : newBody.split('\n').length;
 

package/scripts/lib/autopilot/telemetry.mjs

@@ -17,9 +17,10 @@
  *   linkChildLoopToCoordinator(childRunId, parentRunId)— Phase D linkage documentation helper
  */
 
-import { writeFileSync, renameSync, mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
+
+import { atomicWriteWithBackup, envelopeToError } from '../io.mjs';
 
 // ---------------------------------------------------------------------------
 // Schema version
@@ -38,7 +39,11 @@ export const SCHEMA_VERSION = 1;
  * Crash-safe: a partial tmpfile is never visible at the destination path.
  * POSIX rename(2) is atomic within the same filesystem.
  *
- * The directory must already exist (callers are responsible for mkdirSync).
+ * Write path: `atomicWriteWithBackup` (`../io.mjs`), which also creates a
+ * missing parent directory (mkdir -p) and unlinks its tmp on failure. The tmp
+ * keeps the `<file>.tmp-<pid>.<hex>` shape so the `*.jsonl.tmp-*` crash-residue
+ * ignore pattern (bootstrap store-lock-ignore) still matches it. Throws on
+ * failure with the original message and `code` (`envelopeToError`).
  *
  * @param {object} record    — the record to serialize as a JSONL line
  * @param {string} jsonlPath — destination JSONL path
@@ -53,9 +58,10 @@ export function appendJsonlAtomic(record, jsonlPath) {
   if (existing.length > 0 && !existing.endsWith('\n')) existing += '\n';
 
   const line = JSON.stringify(record) + '\n';
-  const tmp = `${jsonlPath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
-  writeFileSync(tmp, existing + line, 'utf8');
-  renameSync(tmp, jsonlPath);
+  const res = atomicWriteWithBackup(jsonlPath, existing + line, {
+    tmpPrefix: `${path.basename(jsonlPath)}.tmp-${process.pid}`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/bootstrap-lock-refresh.mjs

@@ -22,9 +22,9 @@
  * — a missing or structurally invalid lock is refused, not synthesized.
  */
 
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteWithBackup, envelopeToError } from './io.mjs';
 import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
 
 const PRECONDITION_MESSAGE_SUFFIX =
@@ -84,20 +84,16 @@ function sanitizeLockValue(value) {
 }
 
 /**
- * Atomically write `content` to `filePath` via tmp-file + renameSync — the
- * same crash-safe pattern used by `scripts/lib/io.mjs#writeJsonAtomicSync`
- * and `scripts/lib/session-lock.mjs`, adapted for raw (non-JSON) text.
+ * Atomically write `content` to `filePath` via tmp-file + rename
+ * (`scripts/lib/io.mjs#atomicWriteWithBackup`). Throws on failure with the
+ * original message and `code` (`envelopeToError`).
  *
  * @param {string} filePath
  * @param {string} content
  */
 function writeTextAtomicSync(filePath, content) {
-  const dir = dirname(filePath);
-  mkdirSync(dir, { recursive: true });
-  const tmpSuffix = randomBytes(6).toString('hex');
-  const tmpFile = join(dir, `.bootstrap-lock-refresh.${tmpSuffix}.tmp`);
-  writeFileSync(tmpFile, content, { encoding: 'utf8' });
-  renameSync(tmpFile, filePath);
+  const res = atomicWriteWithBackup(filePath, content, { tmpPrefix: '.bootstrap-lock-refresh.tmp' });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 /**

package/scripts/lib/config/drift-check.mjs

@@ -14,7 +14,7 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  * GENERIC over any consumer repo, where a slash command still IS a
  * `commands/*.md` file. The 2026-09-16 command→skill fold (#1370) is a fact
  * about THIS plugin — 24 command files folded into their same-named
- * `skills/<name>/SKILL.md` behind an explicit `user-invocable: true` — so
+ * `skills/<name>/SKILL.md` behind `user-invocable: true` (absent counts as true, #1515) — so
  * teaching the shared checker that union would mis-measure every repo that never
  * folded. `scripts/site-numbers.mjs` `countCommands()` carries the union for this
  * plugin's own tile, and names the divergence in its docblock.

package/scripts/lib/config/frontend-slop-hook.mjs

@@ -13,6 +13,10 @@
  * Tolerant parser: any other value (or an absent block) resolves to disabled.
  *
  * Consumer: `hooks/post-tooluse-frontend-slop.mjs`.
+ *
+ * @deprecated since 5.8.0 (#1121) — the hook this block drives is removed in
+ * the next major. The parser stays side-effect free; the hook prints the
+ * deprecation notice when the block is enabled.
  */
 
 import { promises as fs } from 'node:fs';
@@ -32,6 +36,7 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  *
  * @param {string} content — full file contents
  * @returns {{ enabled: boolean }}
+ * @deprecated since 5.8.0 (#1121) — removal in the next major.
  */
 export function _parseFrontendSlopHook(content) {
   const defaults = { enabled: false };
@@ -85,6 +90,7 @@ export function _parseFrontendSlopHook(content) {
  *
  * @param {{ repoRoot?: string }} [opts]
  * @returns {Promise<{ enabled: boolean }>}
+ * @deprecated since 5.8.0 (#1121) — removal in the next major.
  */
 export async function loadFrontendSlopHookConfig(opts = {}) {
   // Called at USE time, never at module load: the deprecated `SO_PROJECT_DIR`

package/scripts/lib/config.mjs

@@ -186,7 +186,11 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // String fields
   const vcs = _coerceString(kv, 'vcs', undefined);
   const gitlabHost = _coerceString(kv, 'gitlab-host', undefined);
-  const mirror = _coerceString(kv, 'mirror', undefined);
+  // `mirror` keeps an explicit `none` as the string 'none' instead of the
+  // generic _coerceString null (#1034): session-end Phase 4.4 must tell an
+  // explicit opt-out (`mirror: none` → never push) from an absent key
+  // (null → push when a `github` remote exists, the pre-#1034 behaviour).
+  const mirror = _getVal(kv, 'mirror', undefined) === 'none' ? 'none' : _coerceString(kv, 'mirror', undefined);
   const special = _coerceString(kv, 'special', undefined);
   const pencil = _coerceString(kv, 'pencil', undefined);
   const testCommand = _coerceString(kv, 'test-command', 'npm test');

package/scripts/lib/convergence-monitor.mjs

@@ -44,8 +44,9 @@
  */
 
 import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
-import { join } from 'node:path';
+import { eventsFilePath } from './events.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';
@@ -454,8 +455,9 @@ function sleep(ms) {
  * @param {number} intervalS
  */
 async function tailLoop(intervalS) {
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || process.cwd();
-  const absPath = join(pluginRoot, EVENTS_FILE_REL);
+  // #1517: the PROJECT root, never CLAUDE_PLUGIN_ROOT (the installed plugin
+  // directory, whose ledger is not this repo's).
+  const absPath = eventsFilePath(getProjectDir()); // #1514: the repo's one ledger
   /** @type {Map<number, WaveSummary>} */
   const state = new Map();
   /** @type {Set<string>} */

package/scripts/lib/dispatcher/rank.mjs

@@ -202,7 +202,11 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
     const days = (nowMs - latestMs) / MS_PER_DAY;
     return days > 0 ? days : 0;
   } catch {
-    // No sessions file (or unreadable) ⇒ never worked on ⇒ maximally stale.
+    // Not the missing/unreadable-ledger path: readCanonicalSessions already
+    // returns [] for both (ENOENT silently, any other read failure with a
+    // stderr WARN — sessions-canonical.mjs § #1188), handled by the
+    // `records.length === 0` branch above. This catch only absorbs an
+    // unexpected throw (e.g. a non-string repoRoot) ⇒ maximally stale.
     return STALENESS_CAP_DAYS;
   }
 }

package/scripts/lib/ecosystem-health.mjs

@@ -39,11 +39,12 @@
 
 import { existsSync, statSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getProjectDir } from './platform.mjs';
 
 // Ceiling (BV-004): one process per session that invoked session-start
 // (monitors/monitors.json `when: on-skill-invoke:session-start`), alive until
 // SIGTERM; one stat + one full readFileSync of ONE local file per 900 s
-// (resolved against CLAUDE_PLUGIN_ROOT, not the repo); no network, no repo
+// (resolved against the project dir via getProjectDir(), #1517); no network, no repo
 // enumeration, no Session Config read (runs even with `ecosystem-health: false`).
 // The watched file has NO producer (0 writers, measured 2026-09-18:
 // `rg -l "ecosystem-health\.jsonl"` → this file only) — every run emits
@@ -129,8 +130,9 @@ function fingerprint(absPath) {
  * @param {number} intervalS
  */
 async function watchLoop(intervalS) {
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || process.cwd();
-  const absPath = join(pluginRoot, STATE_FILE_REL);
+  // #1517: the PROJECT root, never CLAUDE_PLUGIN_ROOT (the installed plugin
+  // directory, whose metrics are not this repo's).
+  const absPath = join(getProjectDir(), STATE_FILE_REL);
 
   // Startup event — confirms the watcher is alive even when nothing has
   // happened yet. Without this, a "no events" stream is indistinguishable