session-orchestrator 3.24.0 → 4.0.1

package/scripts/generate-cursor-adapter.mjs

@@ -80,12 +80,40 @@ function parseFrontmatter(content) {
   return fields;
 }
 
+/**
+ * Values that YAML would read as a non-string scalar even though every
+ * character in them is "safe". `argument-hint: no` is a boolean, not the
+ * string "no"; `description: 3` is an integer. A consumer asserting
+ * `typeof value === 'string'` fails on a file that looks perfectly fine.
+ */
+const YAML_SCALAR_LOOKALIKE = /^(?:true|false|yes|no|on|off|null|nan|[-+]?\.?inf|~)$/i;
+
+/**
+ * A value safe to emit as a YAML *plain* (unquoted) scalar.
+ *
+ * Deliberately an ALLOW-list. Its predecessor was a deny-list of special
+ * characters, which is unenumerable by construction: it caught `[` and `:`
+ * but not a leading `-` (block-sequence entry), not surrounding whitespace,
+ * and not the scalar look-alikes above. An allow-list fails closed — an
+ * unforeseen shape gets quoted, which is never wrong, only noisier.
+ */
+const YAML_PLAIN_SAFE = /^[A-Za-z0-9_][A-Za-z0-9 _.,()/-]*$/;
+
+/**
+ * Render a frontmatter VALUE as YAML.
+ *
+ * @param {unknown} value
+ * @returns {string|null} the YAML scalar, or `null` when there is nothing to emit
+ */
 function yamlQuote(value) {
-  if (value === undefined || value === '') return null;
-  if (/[:#[\]{}&*!|>'"%@`]/.test(value) || value.includes('\n')) {
-    return JSON.stringify(value);
-  }
-  return value;
+  if (value === undefined || value === null || value === '') return null;
+  const text = String(value);
+  if (text.trim() === '') return null;
+  if (text !== text.trim()) return JSON.stringify(text);
+  if (!YAML_PLAIN_SAFE.test(text)) return JSON.stringify(text);
+  if (YAML_SCALAR_LOOKALIKE.test(text)) return JSON.stringify(text);
+  if (/^\d/.test(text)) return JSON.stringify(text);
+  return text;
 }
 
 function frontmatterLine(key, value) {
@@ -103,10 +131,16 @@ function renderCommand(commandFile) {
   const commandPath = path.join(COMMANDS_DIR, commandFile);
   const commandName = commandFile.replace(/\.md$/, '');
   const fields = parseFrontmatter(readFileSync(commandPath, 'utf8'));
+  // EVERY value goes through yamlQuote(). `argument-hint` did not, and its
+  // canonical form is a bare bracket list (`[mode] [--flag]`) — a YAML flow
+  // sequence, which is GH#54: Copilot CLI >= 1.0.65 silently DROPS a command
+  // file whose `argument-hint` is not a string. Fixed in `commands/` and
+  // `pi/prompts/` by 93b40dd (v3.16.0) and re-introduced here on every
+  // generation, because this mirror re-derived the frontmatter by hand.
   const frontmatter = [
     '---',
-    frontmatterLine('description', yamlQuote(fields.description) ?? fields.description),
-    frontmatterLine('argument-hint', fields['argument-hint']),
+    frontmatterLine('description', yamlQuote(fields.description)),
+    frontmatterLine('argument-hint', yamlQuote(fields['argument-hint'])),
     '---',
   ].filter(Boolean).join('\n');
 
@@ -132,9 +166,12 @@ function renderSkill(skillName) {
   const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
   const fields = parseFrontmatter(readFileSync(skillPath, 'utf8'));
   const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
+  // Same rule as renderCommand: no frontmatter value is emitted raw. `name` is
+  // a directory basename today, so it is plain-safe in practice — routing it
+  // through yamlQuote() is what keeps that true after the next skill is added.
   const lines = [
     '---',
-    `name: ${skillName}`,
+    `name: ${yamlQuote(skillName)}`,
     `description: ${yamlQuote(description)}`,
   ];
   if (!isUserInvocable(fields['user-invocable'])) {

package/scripts/generate-hook-import-set.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * generate-hook-import-set.mjs — build the committed allowlist of modules that
+ * are transitively reachable from a hook entry file (GitLab #1224).
+ *
+ * WHY: a hook entry file imports a helper module on EVERY tool call. A helper
+ * saved in a broken intermediate state (2026-09-04: a call to a function that
+ * did not exist yet) turns every Bash/Edit/Write call into "Internal hook error
+ * — request blocked", host-wide, for every session sharing the working copy.
+ * `hooks/post-edit-import-probe.mjs` checks a file right after it is edited —
+ * but only when the file is in THIS set, so the probe stays cheap.
+ *
+ * The set is a COMMITTED artefact (`hooks/_lib/hook-import-set.json`) rather
+ * than a runtime crawl: the probe runs inside a 5 s PostToolUse budget and must
+ * not walk 142 modules per edit. `--check` re-generates and diffs, which is the
+ * drift guard that keeps the committed copy honest.
+ *
+ * Usage:
+ *   node scripts/generate-hook-import-set.mjs [--plugin-root <dir>] [--out <file>] [--check]
+ *   node scripts/generate-hook-import-set.mjs --help
+ *
+ * Exit codes: 0 = written / in sync (or --help); 1 = drift (with --check);
+ * 2 = usage error (unknown flag, or a valued flag missing its value) — the
+ * write is NEVER performed on a usage error.
+ */
+
+import { readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+/** The four hook manifests whose entry files seed the crawl. */
+export const HOOK_MANIFESTS = [
+  'hooks.json',
+  'hooks-codex.json',
+  'hooks-cursor.json',
+  'hooks-pi.json',
+];
+
+/** Module extensions the crawl resolves an extension-less specifier against. */
+const RESOLVE_EXTS = ['.mjs', '.js', '.cjs'];
+
+/**
+ * Collect every `<something>.mjs` path mentioned in a hook manifest's command
+ * strings. The manifests differ per platform ($CLAUDE_PLUGIN_ROOT /
+ * $PI_PLUGIN_ROOT / ${PLUGIN_ROOT}), so match on the hooks/-relative tail
+ * rather than on any one variable spelling.
+ *
+ * @param {string} json - raw manifest contents
+ * @returns {string[]} plugin-root-relative entry paths (e.g. "hooks/enforce-scope.mjs")
+ */
+export function extractEntryFiles(json) {
+  const out = new Set();
+  for (const m of json.matchAll(/hooks\/((?:[\w.-]+\/)*[\w.-]+\.mjs)/g)) {
+    const rel = `hooks/${m[1]}`;
+    // run-node.sh is the launcher, never an entry module; .../hooks/_lib/* is
+    // reached through imports, not through a manifest command.
+    out.add(rel);
+  }
+  return [...out].sort();
+}
+
+/**
+ * Extract relative module specifiers (static import/export-from and dynamic
+ * `import()`) from a module's source.
+ *
+ * @param {string} src
+ * @returns {string[]} relative specifiers, e.g. ["./_lib/profile-gate.mjs"]
+ */
+export function extractRelativeSpecifiers(src) {
+  const out = new Set();
+  const patterns = [
+    /(?:^|[\s;}])(?:import|export)\s[^;'"]*?\sfrom\s*['"](\.[^'"]+)['"]/g,
+    /(?:^|[\s;}])import\s*['"](\.[^'"]+)['"]/g,
+    /\bimport\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g,
+  ];
+  for (const re of patterns) {
+    for (const m of src.matchAll(re)) out.add(m[1]);
+  }
+  return [...out];
+}
+
+/**
+ * Resolve a relative specifier against the importing file.
+ *
+ * @param {string} fromFile - absolute path of the importing module
+ * @param {string} spec     - relative specifier
+ * @returns {string|null} absolute path of an existing file, or null
+ */
+function resolveSpecifier(fromFile, spec) {
+  const base = path.resolve(path.dirname(fromFile), spec);
+  const candidates = [base, ...RESOLVE_EXTS.map((e) => base + e),
+    ...RESOLVE_EXTS.map((e) => path.join(base, `index${e}`))];
+  for (const c of candidates) {
+    try {
+      if (existsSync(c) && statSync(c).isFile()) return c;
+    } catch { /* unreadable → not a resolution */ }
+  }
+  return null;
+}
+
+/**
+ * Crawl every hook entry file transitively and return the reachable module set.
+ *
+ * @param {string} pluginRoot
+ * @returns {{file: string, reachable_from: string[]}[]} sorted by `file`
+ */
+export function buildImportSet(pluginRoot) {
+  /** @type {Map<string, Set<string>>} rel path → set of hook entry basenames */
+  const reach = new Map();
+
+  const entries = new Set();
+  for (const manifest of HOOK_MANIFESTS) {
+    const abs = path.join(pluginRoot, 'hooks', manifest);
+    if (!existsSync(abs)) continue;
+    for (const rel of extractEntryFiles(readFileSync(abs, 'utf8'))) {
+      if (existsSync(path.join(pluginRoot, rel))) entries.add(rel);
+    }
+  }
+
+  for (const entryRel of [...entries].sort()) {
+    const entryName = path.basename(entryRel);
+    const stack = [path.join(pluginRoot, entryRel)];
+    const seen = new Set();
+    while (stack.length > 0) {
+      const abs = stack.pop();
+      if (seen.has(abs)) continue;
+      seen.add(abs);
+
+      const rel = path.relative(pluginRoot, abs).split(path.sep).join('/');
+      if (!reach.has(rel)) reach.set(rel, new Set());
+      reach.get(rel).add(entryName);
+
+      let src;
+      try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+      for (const spec of extractRelativeSpecifiers(src)) {
+        const next = resolveSpecifier(abs, spec);
+        if (next) stack.push(next);
+      }
+    }
+  }
+
+  return [...reach.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([file, from]) => ({ file, reachable_from: [...from].sort() }));
+}
+
+/**
+ * Current HEAD sha of the plugin root, or "unknown" outside a git checkout.
+ *
+ * @param {string} pluginRoot
+ * @returns {string}
+ */
+function headSha(pluginRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: pluginRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Build the full artefact payload.
+ *
+ * @param {string} pluginRoot
+ * @returns {{generated_at: string, head: string, entries: {file: string, reachable_from: string[]}[]}}
+ */
+export function buildArtifact(pluginRoot) {
+  return {
+    generated_at: new Date().toISOString(),
+    head: headSha(pluginRoot),
+    entries: buildImportSet(pluginRoot),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const USAGE = [
+  'Usage: node scripts/generate-hook-import-set.mjs [--plugin-root <dir>] [--out <file>] [--check]',
+  '',
+  '  --plugin-root <dir>  repository/plugin root to crawl (default: the repo this script lives in)',
+  '  --out <file>         artefact path (default: <plugin-root>/hooks/_lib/hook-import-set.json)',
+  '  --check              re-crawl and diff against the committed artefact instead of writing',
+  '  --help, -h           print this help',
+  '',
+  'Exit codes: 0 = written / in sync; 1 = drift (with --check); 2 = usage error.',
+].join('\n');
+
+/**
+ * @param {string[]} argv
+ * @returns {number} process exit code
+ */
+export function main(argv) {
+  const args = argv.slice(2);
+
+  /** @type {{'--plugin-root': string|null, '--out': string|null}} */
+  const valued = { '--plugin-root': null, '--out': null };
+  let check = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(`${USAGE}\n`);
+      return 0;
+    }
+    if (arg === '--check') {
+      check = true;
+      continue;
+    }
+    if (arg === '--plugin-root' || arg === '--out') {
+      // A valued flag whose value is missing — or whose "value" is the next FLAG
+      // — is a usage error, not a silent default. Without the leading-dash test,
+      // `--out --check` swallows `--check` as the artefact path: checking is
+      // disabled, the WRITE branch runs, and a file literally named `--check`
+      // lands in the cwd.
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        process.stderr.write(`✗ hook-import-set: ${arg} requires a value\n${USAGE}\n`);
+        return 2;
+      }
+      valued[arg] = value;
+      i += 1;
+      continue;
+    }
+    process.stderr.write(`✗ hook-import-set: unknown argument "${arg}"\n${USAGE}\n`);
+    return 2;
+  }
+
+  const pluginRoot = path.resolve(valued['--plugin-root'] ?? path.resolve(import.meta.dirname, '..'));
+  const out = path.resolve(valued['--out'] ?? path.join(pluginRoot, 'hooks', '_lib', 'hook-import-set.json'));
+
+  const fresh = buildArtifact(pluginRoot);
+
+  if (check) {
+    if (!existsSync(out)) {
+      process.stderr.write(`✗ hook-import-set: ${path.relative(pluginRoot, out)} is missing — run generate-hook-import-set.mjs\n`);
+      return 1;
+    }
+    let committed;
+    try { committed = JSON.parse(readFileSync(out, 'utf8')); } catch {
+      process.stderr.write('✗ hook-import-set: committed file is not valid JSON\n');
+      return 1;
+    }
+    // Only `entries` is compared — generated_at/head are provenance, not content.
+    const a = JSON.stringify(committed.entries ?? null);
+    const b = JSON.stringify(fresh.entries);
+    if (a !== b) {
+      process.stderr.write('✗ hook-import-set: committed set differs from a fresh crawl — run `node scripts/generate-hook-import-set.mjs`\n');
+      return 1;
+    }
+    process.stdout.write(`✓ hook-import-set: ${fresh.entries.length} modules, in sync\n`);
+    return 0;
+  }
+
+  writeFileSync(out, JSON.stringify(fresh, null, 2) + '\n', 'utf8');
+  process.stdout.write(`✓ hook-import-set: wrote ${fresh.entries.length} modules to ${path.relative(pluginRoot, out)}\n`);
+  return 0;
+}
+
+/**
+ * True when this module was launched as the process entry script.
+ *
+ * A string compare of `import.meta.url` against `file://${process.argv[1]}` is
+ * fragile in exactly the invocations CI and husky use: any symlinked or
+ * realpath-differing path (measured: `/tmp` → `/private/tmp` on macOS) makes
+ * the compare false, so the whole CLI body becomes a silent no-op that still
+ * exits 0 — a fail-OPEN drift gate. A space or `#` in the path breaks the
+ * hand-built URL the same way. Same shape as `hooks/post-bash-write-verify.mjs`.
+ *
+ * @returns {boolean}
+ */
+function invokedAsScript() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const self = fileURLToPath(import.meta.url);
+  try {
+    return realpathSync(entry) === realpathSync(self);
+  } catch {
+    // argv[1] unresolvable (deleted/renamed mid-run) — best-effort raw compare.
+    return entry === self;
+  }
+}
+
+if (invokedAsScript()) {
+  process.exit(main(process.argv));
+}

package/scripts/lib/agent-status.mjs

@@ -166,7 +166,11 @@ function releaseLock(lockFile, _myBody) {
 }
 
 /**
- * Read the current LWW map from disk. Returns {} on miss or parse error.
+ * Read the current LWW map from disk. Returns {} on a missing file (ENOENT)
+ * silently; an unreadable/unparseable one (EACCES/EISDIR/malformed JSON/…)
+ * also returns {} but with a stderr WARN (#1210 — ENOENT and other failures
+ * are different facts, same split as `sessions-canonical.mjs`
+ * `readCanonicalSessions`).
  * @param {string} currentFile
  * @returns {Record<string, object>}
  */
@@ -176,7 +180,14 @@ function readCurrentMap(currentFile) {
     const obj = JSON.parse(raw);
     if (obj && typeof obj === 'object' && !Array.isArray(obj)) return obj;
     return {};
-  } catch {
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ readCurrentMap: cannot read ${currentFile} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
     return {};
   }
 }

package/scripts/lib/auto-dream.mjs

@@ -25,6 +25,7 @@ import { existsSync, statSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
+import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { filterRealSessions } from './session-schema.mjs';
 
 // ---------------------------------------------------------------------------
@@ -61,49 +62,50 @@ export async function readDreamSignals({ repoRoot, memoryDir }) {
   }
 
   // 2. Read sessions.jsonl entries to compute lastCleanupAt + sessionsSinceCleanup
+  //
+  // #1209: migrated from a hand-rolled parse loop to `readCanonicalSessions`
+  // — the raw file is APPEND-ONLY (a physical session can carry more than one
+  // LINE: crash-recovery re-appends, #1068 stub/supersede pairs), and the
+  // hand-rolled loop counted every line. `sessionsSinceCleanup` is a CADENCE
+  // count ("how many sessions since the last cleanup"), so counting a
+  // duplicated line twice inflated it — this migration LOWERS the count,
+  // which is the fix, not a side effect. `canonicalizeSessions` also drops
+  // lines with no `session_id` (they cannot be deduplicated, so they were
+  // never a countable "session" to begin with); the existing fixtures below
+  // were given synthetic `session_id` values so their asserted counts still
+  // reflect the same intended scenario post-migration.
   let lastCleanupAt = null;
   let sessionsSinceCleanup = 0;
 
-  if (existsSync(sessionsFilePath)) {
-    const raw = await readFile(sessionsFilePath, 'utf8');
-    const lines = raw.split('\n').filter((l) => l.length > 0);
-    const entries = [];
-    for (const line of lines) {
-      try {
-        entries.push(JSON.parse(line));
-      } catch {
-        // Malformed line — skip silently, this is a best-effort signal reader.
+  const entries = readCanonicalSessions({ filePath: sessionsFilePath });
+
+  // Abandoned-session filter (#834): sessions.jsonl carries phantom
+  // `status: 'abandoned'` stubs (session-close-backfill records for
+  // sessions that ended without a real close). They are legitimate DATA
+  // but not legitimate SIGNAL — a burst of abandoned stubs must not fire
+  // /memory-cleanup off zero real work. filterRealSessions() is the
+  // shared, tested implementation (scripts/lib/session-schema/filters.mjs).
+  const realEntries = filterRealSessions(entries);
+
+  // Find the most recent memory_cleanup_at timestamp across all REAL entries.
+  for (const entry of realEntries) {
+    const ts = entry.memory_cleanup_at;
+    if (typeof ts === 'string' && ts.length > 0) {
+      if (lastCleanupAt === null || ts > lastCleanupAt) {
+        lastCleanupAt = ts;
       }
     }
+  }
 
-    // Abandoned-session filter (#834): sessions.jsonl carries phantom
-    // `status: 'abandoned'` stubs (session-close-backfill records for
-    // sessions that ended without a real close). They are legitimate DATA
-    // but not legitimate SIGNAL — a burst of abandoned stubs must not fire
-    // /memory-cleanup off zero real work. filterRealSessions() is the
-    // shared, tested implementation (scripts/lib/session-schema/filters.mjs).
-    const realEntries = filterRealSessions(entries);
-
-    // Find the most recent memory_cleanup_at timestamp across all REAL entries.
+  // Count REAL entries newer than the last cleanup (or total REAL entries
+  // when no cleanup ever ran).
+  if (lastCleanupAt === null) {
+    sessionsSinceCleanup = realEntries.length;
+  } else {
     for (const entry of realEntries) {
-      const ts = entry.memory_cleanup_at;
-      if (typeof ts === 'string' && ts.length > 0) {
-        if (lastCleanupAt === null || ts > lastCleanupAt) {
-          lastCleanupAt = ts;
-        }
-      }
-    }
-
-    // Count REAL entries newer than the last cleanup (or total REAL entries
-    // when no cleanup ever ran).
-    if (lastCleanupAt === null) {
-      sessionsSinceCleanup = realEntries.length;
-    } else {
-      for (const entry of realEntries) {
-        const startedAt = entry.started_at;
-        if (typeof startedAt === 'string' && startedAt > lastCleanupAt) {
-          sessionsSinceCleanup += 1;
-        }
+      const startedAt = entry.started_at;
+      if (typeof startedAt === 'string' && startedAt > lastCleanupAt) {
+        sessionsSinceCleanup += 1;
       }
     }
   }

package/scripts/lib/autonomy/suitability.mjs

@@ -158,6 +158,12 @@ export function computeSuitabilityVerdict(deps = {}) {
   const ciNotRed = ciStatus !== 'red'; // null status (absent/malformed) passes
   if (ciAbsent) warnings.push('CI signal absent');
   else if (ciMalformed) warnings.push('CI signal malformed — treated as absent');
+  // `{status:'unknown'}` is a WELL-FORMED reading that establishes nothing —
+  // since #1031 it is what a degraded probe produces, and it hits neither
+  // branch above. Without this line it passed G3 with NO warning at all, i.e.
+  // more quietly than the plain-absent case it is strictly weaker than. The
+  // gate stays non-blocking (only a literal 'red' fails); only the silence goes.
+  else if (ciStatus === 'unknown') warnings.push('CI signal unknown — treated as absent');
   const ciSegment = ciAbsent ? 'absent' : ciMalformed ? 'malformed' : `${ciStatus}`;
 
   // --- G4 — resource gate (green/warn/degraded/null pass; only 'critical' fails)

package/scripts/lib/autopilot/loop.mjs

@@ -20,7 +20,7 @@ import {
   finalizeState,
 } from './telemetry.mjs';
 import { durableCommit } from './durable-telemetry.mjs';
-import { SO_STATE_DIR } from '../platform.mjs';
+import { getStateDir } from '../platform.mjs';
 
 // Internal clamp — mirrors flags.mjs internal; not re-exported there.
 function clampNumber(value, { min, max, fallback }) {
@@ -311,7 +311,7 @@ export async function runLoop(opts = {}) {
     files: [
       jsonlPath.replace(process.cwd() + '/', ''),
       '.orchestrator/metrics/sessions.jsonl',
-      `${SO_STATE_DIR}/STATE.md`,
+      `${getStateDir()}/STATE.md`,
     ],
     enabled: false,
   });