session-orchestrator 3.23.0 → 4.0.0

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

@@ -0,0 +1,249 @@
+#!/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]
+ *
+ * Exit codes: 0 = written / in sync; 1 = drift (with --check) or 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
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string[]} argv
+ * @returns {number} process exit code
+ */
+export function main(argv) {
+  const args = argv.slice(2);
+  const flag = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : null;
+  };
+  const pluginRoot = path.resolve(flag('--plugin-root') ?? path.resolve(import.meta.dirname, '..'));
+  const out = path.resolve(flag('--out') ?? path.join(pluginRoot, 'hooks', '_lib', 'hook-import-set.json'));
+  const check = args.includes('--check');
+
+  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/auq/parse.mjs

@@ -82,6 +82,7 @@ import {
   RECOMMENDED_MARKERS,
   isRecommendedOption,
 } from './schema.mjs';
+import { scanFenceBlocks } from '../validate/markdown-fences.mjs';
 
 // ---------------------------------------------------------------------------
 // Korpus-Abgrenzung
@@ -330,42 +331,17 @@ function lineOfOffset(starts, offset) {
 }
 
 /**
- * Zaun-Anker. **Zeilenanfangs-verankert** — ohne den Anker schließt
+ * Zerlegt eine Markdown-Datei in Code-Zaun-Blöcke. **Zeilenanfangs- UND
+ * -ende-verankert** (`{ wholeLine: true }`, gemeinsamer Zaun-Tracker
+ * `../validate/markdown-fences.mjs`, #1181) — ohne den Anker schließt
  * `skills/discovery/SKILL.md:373` seinen eigenen Block mitten im Fragetext
  * (Falle 1).
- */
-export const FENCE_LINE_PATTERN = /^[ \t]*(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/u;
-
-/**
- * Zerlegt eine Markdown-Datei in Code-Zaun-Blöcke.
  *
  * @param {string} content
  * @returns {Array<{openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number}>}
  */
 export function fencesOf(content) {
-  const lines = content.split('\n');
-  const fences = [];
-  let open = null;
-  for (let i = 0; i < lines.length; i++) {
-    const m = FENCE_LINE_PATTERN.exec(lines[i]);
-    if (!m) continue;
-    if (open === null) {
-      open = { marker: m[1][0], len: m[1].length, lang: m[2] || '', startIdx: i };
-      continue;
-    }
-    // Ein schließender Zaun muss dasselbe Zeichen und mindestens dieselbe
-    // Länge haben — sonst beendet ein ```js-Zaun einen ````-Block.
-    if (m[1][0] !== open.marker || m[1].length < open.len || m[2]) continue;
-    fences.push({
-      openLine: open.startIdx + 1,
-      closeLine: i + 1,
-      lang: open.lang,
-      bodyLines: lines.slice(open.startIdx + 1, i),
-      bodyStartLine: open.startIdx + 2,
-    });
-    open = null;
-  }
-  return fences;
+  return scanFenceBlocks(content, { wholeLine: true });
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/auto-dialectic.mjs

@@ -23,6 +23,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { filterRealSessions } from './session-schema.mjs';
+import { emitEvent, sessionAttribution } from './events.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -245,6 +246,73 @@ export async function shouldDispatchAutoDialectic({
   };
 }
 
+// ---------------------------------------------------------------------------
+// Decision + mechanical telemetry (#1200 part c)
+// ---------------------------------------------------------------------------
+
+/**
+ * `shouldDispatchAutoDialectic()` plus a MECHANICAL `orchestrator.dialectic.nudge_decided`
+ * record, so the nudge decision is observable without depending on the
+ * session-end skill prose actually reaching the emit step (#1200: 0 records of
+ * this class across 164k fleet events despite the nudge firing every close).
+ *
+ * Contract-preserving wrapper: calls `shouldDispatchAutoDialectic()` unchanged
+ * and returns its decision object verbatim — the emit is a side effect bolted
+ * on, never a change to the decision logic or its return shape.
+ *
+ * Emits on ALL FOUR return paths (kill-switch, no-new-input,
+ * cadence-threshold-met, under-threshold) — best-effort, try/catch-wrapped,
+ * because `emitEvent()` throws `EventValidationError` on a malformed record
+ * and a telemetry failure must never change what the caller decides to do
+ * (same posture as `scripts/lib/reconcile/engine.mjs`'s `emitReconcileCompleted`
+ * wrapper).
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number} [args.cadence=DEFAULT_CADENCE] `dialectic.cadence` from config.
+ * @param {object} [args.signals] Pre-computed signals (skips disk reads) — forwarded verbatim.
+ * @param {Function|null} [args.emitFn=emitEvent] DI hook for testing / disabling
+ *   emission; defaults to `emitEvent` from `./events.mjs`. Any error it throws
+ *   is swallowed — it never changes the returned decision.
+ * @param {boolean} [args.record=true] When `false`, no event is emitted at all —
+ *   for read-only PROBE callers (e.g. the session-end Phase 3.6.x tail-skip
+ *   aggregator, `scripts/lib/session-end/phase-skip.mjs`, whose documented
+ *   contract is side-effect-free) where the decision is computed for internal
+ *   branching only and must never itself be recorded as a nudge decision.
+ * @returns {Promise<{trigger:boolean, reason:string, signals:object}>}
+ */
+export async function decideAndRecordAutoDialectic({
+  repoRoot,
+  cadence = DEFAULT_CADENCE,
+  signals,
+  emitFn = emitEvent,
+  record = true,
+} = {}) {
+  const decision = await shouldDispatchAutoDialectic({ repoRoot, cadence, signals });
+
+  if (record && typeof emitFn === 'function') {
+    try {
+      await emitFn(
+        'orchestrator.dialectic.nudge_decided',
+        {
+          ...sessionAttribution(repoRoot),
+          decided: decision.trigger,
+          reason: decision.reason,
+          cadence,
+          sessions_since: decision.signals?.sessionsSinceLast,
+          learnings_since: decision.signals?.learningsSinceLast,
+        },
+        { repoRoot },
+      );
+    } catch {
+      // best-effort — a telemetry failure must never block or change the
+      // decision the caller already has in hand.
+    }
+  }
+
+  return decision;
+}
+
 // ---------------------------------------------------------------------------
 // last-run — atomic write
 // ---------------------------------------------------------------------------

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,
   });