session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/dispatcher/enumerate.mjs

@@ -2,8 +2,10 @@
  * enumerate.mjs — Candidate-repo enumeration + free/busy resolution.
  *
  * Epic #673 Phase 2 (issue #676, PRD §2 P2.1+P2.2, §4). Enumerates candidate
- * repos one level below a confinement root and resolves each as free or busy
- * via its per-repo `session.lock` v2 lease (heartbeat-based liveness).
+ * repos below a confinement root (recursive walk, fixed at a depth of
+ * {@link DEFAULT_MAX_DEPTH} — see that constant for the measurement backing
+ * the value) and resolves each as free or busy via its per-repo
+ * `session.lock` v2 lease (heartbeat-based liveness).
  *
  * Source of truth for free/busy: the same lease semantics as
  * `scripts/lib/vault-status/board-writer.mjs` collectRows —
@@ -15,8 +17,9 @@
  * the {@link Candidate} contract defined here.
  *
  * Exports:
- *   enumerateCandidates  — scan immediate children of a startDir, resolve each
- *                          repo's free/busy status from its lease.
+ *   enumerateCandidates  — walk a startDir up to {@link DEFAULT_MAX_DEPTH}
+ *                          levels deep, resolve each repo's free/busy status
+ *                          from its lease.
  *   freeCandidates       — filter helper: keep only `free === true` candidates.
  *
  * No top-level side effects. All filesystem + lock access is dependency-injected
@@ -47,6 +50,53 @@ const STATUS_FREI = 'frei';
 const STATUS_IN_PROGRESS = 'in-progress';
 const STATUS_FORCE_CLOSED = 'force-closed';
 
+/**
+ * Fixed walk depth. `1` = immediate children of the scan root only (the
+ * pre-#832 behaviour); `2` additionally covers `<root>/<org>/<repo>`.
+ *
+ * Measured on the reference host (~/Projects, 2026-07-19; warm dentry cache —
+ * a cold first walk costs roughly 10x these figures at either depth):
+ *   depth 1 →  1 of 47 repos (2%)   — the real topology is `<org>/<repo>`,
+ *                                     so the scan missed 46 repos including
+ *                                     session-orchestrator itself.
+ *   depth 2 → 45 of 47 repos, ~0.9-1.9ms
+ *   depth 3 → 47 of 47 repos, ~8ms (node_modules is pruned, but the extra
+ *                                     level still multiplies the node count)
+ *                                     for two additional repos, both archived.
+ * Depth 2 is therefore the fixed bound: it recovers 96% of the host's repos
+ * at negligible cost, while depth 3 costs ~8x the walk for two dead repos.
+ *
+ * This was previously exposed as a caller-tunable `maxDepth` option (clamped
+ * 1..3). Issue #838 removed the knob: all three production callers
+ * (`scripts/lib/dispatcher/cli.mjs`, `scripts/lib/lock-reaper.mjs`,
+ * `scripts/lib/vault-status/board-writer.mjs`) always omitted it and relied on
+ * this default, and no CLI surface ever forwarded a caller-supplied value —
+ * a config knob whose only exercised path was its own test suite. The walk
+ * BOUND is unchanged; only the ability to override it at the call boundary
+ * is gone.
+ */
+const DEFAULT_MAX_DEPTH = 2;
+
+/**
+ * Directory names never DESCENDED into during the walk.
+ *
+ * Applied to the descent decision ONLY — never to repo emission — so the
+ * depth-1 contract stays byte-identical to the pre-#832 scan (`.orchestrator`,
+ * `.claude` etc. are still probed for a `.git` marker at depth 1; they simply
+ * have none). `node_modules` is the dominant cost driver at depth 3 and can
+ * legitimately contain vendored `.git` directories that are not host repos.
+ *
+ * @param {string} name — a single path segment (Dirent.name).
+ * @returns {boolean} true iff the walk may recurse into this directory.
+ */
+function shouldDescendInto(name) {
+  if (typeof name !== 'string' || name.length === 0) return false;
+  if (name === 'node_modules') return false;
+  // Dot-directories (.git, .claude, .orchestrator, .venv, …) hold no host repos.
+  if (name.startsWith('.')) return false;
+  return true;
+}
+
 /**
  * Expand a leading `~` to the current user's home directory. Mirrors the helper
  * in board-writer.mjs (a shared extraction is deferred to a later epic). Used to
@@ -126,15 +176,26 @@ function isGitRepo(childAbs, existsSyncFn) {
  * free or busy via its local lease.
  *
  * Algorithm:
- *   1. Scan the IMMEDIATE children (one level deep) of `startDir` that are git
- *      repos (a child is a repo iff `<child>/.git` exists — dir or file).
- *   2. Drop any child failing the confinement guard
- *      (`validatePathInsideProject(childAbs, startDir)`).
+ *   1. Depth-first walk of `startDir`, up to {@link DEFAULT_MAX_DEPTH} levels
+ *      deep (depth 1 = immediate children). Every directory node is a repo
+ *      candidate iff `<node>/.git` exists (dir or file — the file form covers
+ *      worktrees).
+ *   2. Confinement guard (`validatePathInsideProject(nodeAbs, startDir)`) runs
+ *      on EVERY node BEFORE it is emitted AND before it is opened — see the
+ *      security notes on the walk body below.
  *   3. OPTIONAL secondary source: union with `getCrossRepoProjects()`
  *      config-declared paths (leading `~/` expanded, then confinement-filtered),
  *      deduped by `path.resolve()`. Additive, applied AFTER the FS scan.
  *   4. Resolve free/busy per repo from its `session.lock` lease.
  *
+ * A git repo does NOT terminate the descent: on a measured reference host, an
+ * org-level directory one level under the confinement root was itself a git
+ * repo (a small umbrella notes repo) that CONTAINED 16 independent repos —
+ * this plugin's own checkout among them. "A repo's children are not separate
+ * repos" is empirically false there, and an early-exit-on-`.git` walk dropped
+ * 45 discoverable repos to 29. Pruning is therefore by NAME
+ * ({@link shouldDescendInto}), never by `.git` presence.
+ *
  * ALL repos are returned (busy ones LISTED, not dropped — downstream rank.mjs
  * filters). Returns a plain serialisable {@link Candidate}[].
  *
@@ -179,32 +240,77 @@ export async function enumerateCandidates({ startDir, now, deps } = {}) {
     repoPaths.push(resolved);
   };
 
-  // ── 1+2. FS scan of immediate children, confinement-guarded. ──
-  let entries;
-  try {
-    entries = readdirSyncFn(root, { withFileTypes: true });
-  } catch {
-    // Unreadable/absent startDir → no FS-scanned repos. The config-declared
-    // secondary source below may still contribute.
-    entries = [];
-  }
+  // ── 1+2. Depth-capped FS walk, confinement-guarded at every node. ──
+  //
+  // SECURITY (three load-bearing invariants — do not relax without re-reading
+  // validatePathInsideProject at scripts/lib/path-utils.mjs):
+  //
+  //   (i)  Every node is validated against the ORIGINAL `root`, NEVER against
+  //        its own parent. The guard's Phase 2 calls realpathSync, which
+  //        resolves EVERY intermediate component — so validating a grandchild
+  //        against the original root is both sufficient and complete at any
+  //        depth. Re-rooting per level (`validate(grandchild, childDir)`) would
+  //        validate a symlinked subtree against ITSELF and defeat the guard.
+  //
+  //   (ii) The guard runs BEFORE `readdirSync`, not merely before emission.
+  //        Pre-#832 the guard ran only after `isGitRepo` passed, which was safe
+  //        because a non-repo directory was never opened. Under recursion an
+  //        unguarded non-repo directory WOULD be opened, so an `ok:false` node
+  //        must be refused for descent as well as for emission.
+  //
+  //  (iii) The guard call is wrapped in try/catch. path-utils.mjs rethrows any
+  //        non-ENOENT realpath error, so a single mode-000 directory under the
+  //        scan root would otherwise throw straight out of enumerateCandidates
+  //        — and runDispatch (scripts/lib/dispatcher/cli.mjs) has no try/catch
+  //        around this call. The walk now validates ~52 nodes instead of 1, so
+  //        a throwing guard is treated as "skip this node".
+  //
+  // Unbounded recursion is impossible: `Dirent.isDirectory()` is false for a
+  // symlink-to-directory (verified empirically), so symlink cycles never enter
+  // the walk — and `DEFAULT_MAX_DEPTH` bounds it regardless, including for
+  // stubbed entries that do not implement isDirectory().
+  const walk = (dirAbs, depth) => {
+    let entries;
+    try {
+      entries = readdirSyncFn(dirAbs, { withFileTypes: true });
+    } catch {
+      // Unreadable/absent directory → this subtree contributes nothing.
+      // Siblings and the config-declared secondary source are unaffected.
+      return;
+    }
 
-  for (const entry of entries) {
-    // Only directories can be repos. Dirent.isDirectory() guards against files,
-    // sockets, etc. A stubbed entry may not implement isDirectory — fall back
-    // to treating it as a directory candidate (existsSync('.git') gates anyway).
-    const isDir = typeof entry?.isDirectory === 'function' ? entry.isDirectory() : true;
-    if (!isDir) continue;
+    for (const entry of entries) {
+      // Only directories can be repos. Dirent.isDirectory() guards against
+      // files, sockets, etc. A stubbed entry may not implement isDirectory —
+      // fall back to treating it as a directory candidate (the depth cap and
+      // existsSync('.git') gate the consequences).
+      const isDir = typeof entry?.isDirectory === 'function' ? entry.isDirectory() : true;
+      if (!isDir) continue;
 
-    const childAbs = path.join(root, entry.name);
-    if (!isGitRepo(childAbs, existsSyncFn)) continue;
+      const childAbs = path.join(dirAbs, entry.name);
 
-    // Confinement guard: drop anything not strictly inside startDir.
-    const guard = validatePathInsideProjectFn(childAbs, root);
-    if (!guard || guard.ok !== true) continue;
+      // Confinement guard — invariants (i)+(ii)+(iii) above.
+      let guard;
+      try {
+        guard = validatePathInsideProjectFn(childAbs, root);
+      } catch {
+        continue;
+      }
+      if (!guard || guard.ok !== true) continue;
 
-    addRepo(childAbs);
-  }
+      if (isGitRepo(childAbs, existsSyncFn)) addRepo(childAbs);
+
+      // Descent is INDEPENDENT of repo-ness: a repo may contain further repos
+      // (the umbrella-repo case documented above). Prune by name only, and only
+      // for the descent decision — emission above is untouched, which keeps the
+      // depth-1 contract byte-identical to the pre-#832 scan.
+      if (depth < DEFAULT_MAX_DEPTH && shouldDescendInto(entry.name)) {
+        walk(childAbs, depth + 1);
+      }
+    }
+  };
+
+  walk(root, 1);
 
   // ── 3. Optional secondary source: config-declared cross-repo projects. ──
   let declared;

package/scripts/lib/dispatcher/rank.mjs

@@ -35,6 +35,7 @@ import path from 'node:path';
 import { scanBacklog } from '../backlog-scan.mjs';
 import { checkCiStatus as realCheckCiStatus } from '../ci-status-banner.mjs';
 import { probe as realProbe, evaluate as realEvaluate } from '../resource-probe.mjs';
+import { isRealSession } from '../session-schema/filters.mjs';
 
 /** Staleness cap (days). Beyond this, additional age does not raise the score. */
 export const STALENESS_CAP_DAYS = 90;
@@ -156,13 +157,21 @@ async function defaultFetchPriority(repoRoot, nowMs) {
 
 /**
  * Default STALENESS source: read `<repoRoot>/.orchestrator/metrics/sessions.jsonl`,
- * take the LAST record, and compute days since `completed_at` (fallback
- * `started_at`). No file / no parsable record / no timestamp ⇒
- * `STALENESS_CAP_DAYS` (treat as maximally stale = most worthwhile).
+ * find the last REAL (non-phantom) record scanning backward from the tail, and
+ * compute days since `completed_at` (fallback `started_at`). No file / no
+ * parsable REAL record / no timestamp ⇒ `STALENESS_CAP_DAYS` (treat as
+ * maximally stale = most worthwhile).
+ *
+ * Scans backward PAST any trailing `status: 'abandoned'` phantom stubs (#834)
+ * — session-close-backfill writes these for sessions that ended without a real
+ * close (0 waves, seconds of runtime). Stopping at the raw last LINE would let
+ * a single recent phantom make a genuinely neglected repo look freshly
+ * touched, defeating the dispatcher's whole purpose (this is the N=1 extreme
+ * case of the phantom-tail problem — one stub is enough to zero out staleness).
  *
  * @param {string} repoRoot
  * @param {number} nowMs
- * @returns {Promise<number>} days since last session (≥ 0)
+ * @returns {Promise<number>} days since last REAL session (≥ 0)
  */
 async function defaultStaleDaysFor(repoRoot, nowMs) {
   try {
@@ -171,14 +180,19 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
     const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
     if (lines.length === 0) return STALENESS_CAP_DAYS;
 
-    // Last non-empty line = most recent session record.
+    // Scan backward for the last REAL (non-abandoned) session record, skipping
+    // both corrupt lines and phantom stubs.
     let last = null;
     for (let i = lines.length - 1; i >= 0; i -= 1) {
+      let parsed;
       try {
-        last = JSON.parse(lines[i]);
-        break;
+        parsed = JSON.parse(lines[i]);
       } catch {
-        // Skip a corrupt trailing line and try the previous one.
+        continue; // Skip a corrupt line and try the previous one.
+      }
+      if (isRealSession(parsed)) {
+        last = parsed;
+        break;
       }
     }
     if (!last || typeof last !== 'object') return STALENESS_CAP_DAYS;

package/scripts/lib/ecosystem-wizard/config-writer.mjs

@@ -5,6 +5,10 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import {
+  findSessionConfigBlock,
+  SESSION_CONFIG_HEADING,
+} from '../config/section-extractor.mjs';
 
 // ---------------------------------------------------------------------------
 // Validation
@@ -75,18 +79,14 @@ export function validateEcosystemPolicy(policy) {
 // ---------------------------------------------------------------------------
 
 /**
- * Returns whether the Session Config section in `text` already contains an
+ * Returns whether the Session Config section already contains an
  * ecosystem-health key.
- * @param {string} text
- * @param {RegExpMatchArray|null} startMatch
+ * @param {ReturnType<typeof findSessionConfigBlock>} block
  * @returns {boolean}
  */
-function _ecosystemBlockPresent(text, startMatch) {
-  if (!startMatch || startMatch.index === undefined) return false;
-  const afterBlock = text.slice(startMatch.index + startMatch[0].length);
-  const nextHeadingMatch = afterBlock.match(/^## /m);
-  const blockContent = nextHeadingMatch ? afterBlock.slice(0, nextHeadingMatch.index) : afterBlock;
-  return /^\s*ecosystem-health\s*:/m.test(blockContent);
+function _ecosystemBlockPresent(block) {
+  if (!block) return false;
+  return /^\s*ecosystem-health\s*:/m.test(block.body);
 }
 
 /**
@@ -104,23 +104,21 @@ function _replaceEcosystemBlock(text, snippetLines) {
  * Inserts a new ecosystem-health snippet into `text` within the Session Config
  * section, or appends a new section when none exists.
  * @param {string} text
- * @param {RegExpMatchArray|null} startMatch
+ * @param {ReturnType<typeof findSessionConfigBlock>} block
  * @param {string[]} snippetLines
  * @returns {string}
  */
-function _insertEcosystemBlock(text, startMatch, snippetLines) {
+function _insertEcosystemBlock(text, block, snippetLines) {
   const snippet = '\n' + snippetLines.join('\n');
-  if (!startMatch || startMatch.index === undefined) {
-    return text + '\n## Session Config\n' + snippet + '\n';
-  }
-  const afterStartIdx = startMatch.index + startMatch[0].length;
-  const afterBlock = text.slice(afterStartIdx);
-  const nextHeadingMatch = afterBlock.match(/^## /m);
-  if (nextHeadingMatch && nextHeadingMatch.index !== undefined) {
-    const insertAt = afterStartIdx + nextHeadingMatch.index;
-    return text.slice(0, insertAt) + snippet + '\n' + text.slice(insertAt);
+  if (!block) {
+    // The one site in this repo that WRITES the heading. It takes the literal
+    // from the SSOT so a producer/comparator drift cannot open the same
+    // silent-fallback hole the predicate exists to close (#968).
+    return text + '\n' + SESSION_CONFIG_HEADING + '\n' + snippet + '\n';
   }
-  return text + snippet + '\n';
+  // `bodyEnd` is the offset of the next `## ` heading, or EOF — i.e. exactly
+  // the end of the Session Config section, which is where the snippet goes.
+  return text.slice(0, block.bodyEnd) + snippet + '\n' + text.slice(block.bodyEnd);
 }
 
 /**
@@ -211,10 +209,14 @@ export function writeSessionConfigBlock(configFilePath, config, dryRun, overwrit
     return 'error';
   }
 
-  const startMatch = text.match(/^## Session Config[ \t]*(?:\r?\n|$)/m);
+  // Heading + body span from the SSOT (#968) — the previous local regex
+  // `/^## Session Config[ \t]*(?:\r?\n|$)/m` accepted a trailing-whitespace
+  // heading the runtime parser rejects, so the wizard would write a well-formed
+  // ecosystem-health block into a section `parseSessionConfig` never reads.
+  const block = findSessionConfigBlock(text);
   const snippetLines = _buildEcosystemSnippetLines(config);
 
-  if (_ecosystemBlockPresent(text, startMatch)) {
+  if (_ecosystemBlockPresent(block)) {
     if (!overwrite) return 'skipped';
     // Replace the existing ecosystem-health block with the new snippet.
     // The block spans from "ecosystem-health:" to the next top-level key or heading.
@@ -230,7 +232,7 @@ export function writeSessionConfigBlock(configFilePath, config, dryRun, overwrit
   }
 
   // Insert path: append ecosystem-health block to Session Config section
-  const newText = _insertEcosystemBlock(text, startMatch, snippetLines);
+  const newText = _insertEcosystemBlock(text, block, snippetLines);
   if (!dryRun) {
     try { writeFileSync(configFilePath, newText, 'utf8'); } catch { return 'error'; }
   }

package/scripts/lib/ecosystem-wizard/wizard-prompt.mjs

@@ -72,7 +72,7 @@ async function _promptInteractiveAnswers(existingConfig, ciProvider, packageMana
     : `CI pipeline identifiers (format "id" or "id:label", comma-separated, blank to skip):\n> `;
   const labelsPrompt = currentLabels
     ? `Critical issue labels [current: ${currentLabels}]:\n> `
-    : `Critical issue labels (comma-separated, e.g. "priority:critical,severity:blocker", blank to skip):\n> `;
+    : `Critical issue labels (comma-separated, e.g. "priority::critical,severity:blocker", blank to skip):\n> `;
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const ask = (q) => new Promise((resolve) => rl.question(q, resolve));

package/scripts/lib/eval/engine.mjs

@@ -34,6 +34,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { resolvePluginRoot } from '../common.mjs';
 import { readJsonlFile } from '../io.mjs';
 import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './schema.mjs';
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
@@ -41,8 +42,33 @@ import { resolveSession, computeWindow, findPeerOverlap } from './session-resolv
 /** The rubric version this engine scores against. */
 export const RUBRIC_VERSION = 'rubric-v1';
 
-/** Default rubric location (created in W3; absent until then ⇒ rubric_sha256 null). */
-export const DEFAULT_RUBRIC_PATH = 'skills/eval/rubric-v1.md';
+/** Rubric location relative to the plugin root. */
+export const RUBRIC_RELATIVE_PATH = 'skills/eval/rubric-v1.md';
+
+/**
+ * Default rubric location, resolved against the PLUGIN root rather than the
+ * caller's cwd (#927).
+ *
+ * The previous cwd-relative literal only ever resolved when `/eval` happened to
+ * run from the plugin checkout itself. In a consumer repo — the normal install
+ * shape — it pointed at a non-existent `<consumer>/skills/eval/rubric-v1.md`,
+ * `computeRubricHash` returned null, and `validateEvalRecord` then rejected the
+ * record on `provenance.rubric_sha256` (schema.mjs), so the run produced no
+ * output at all.
+ *
+ * Resolution is best-effort by design: `resolvePluginRoot` THROWS when it cannot
+ * locate a plugin root, and this constant is evaluated at module load. A throw
+ * here would make the module unimportable, so we degrade to the relative literal
+ * — preserving the previous behaviour instead of turning a degraded path into a
+ * hard import failure.
+ */
+export const DEFAULT_RUBRIC_PATH = (() => {
+  try {
+    return path.join(resolvePluginRoot(import.meta.url), RUBRIC_RELATIVE_PATH);
+  } catch {
+    return RUBRIC_RELATIVE_PATH;
+  }
+})();
 
 /** Ordered rubric-v1 dimension ids — the canonical scoring order. */
 export const RUBRIC_DIMENSION_IDS = Object.freeze([
@@ -372,13 +398,29 @@ function extractKpis(record) {
 // Provenance / harness / model helpers
 // ---------------------------------------------------------------------------
 
-/** sha256 hex of the rubric file, or null when the file does not exist yet. */
+/**
+ * sha256 hex of the rubric file, or null when it cannot be read.
+ *
+ * A null return is NOT benign: `validateEvalRecord` requires a non-empty
+ * `provenance.rubric_sha256`, so a miss here aborts the whole append downstream.
+ * The downstream WARNs name the validation failure but never the path that was
+ * tried, which is the one fact needed to diagnose it — so name it here (#927).
+ */
 function computeRubricHash(rubricPath) {
   try {
-    if (!rubricPath || !existsSync(rubricPath)) return null;
+    if (!rubricPath || !existsSync(rubricPath)) {
+      process.stderr.write(
+        `[eval-engine] WARN: rubric not found at '${rubricPath ?? '<unset>'}' — ` +
+        'provenance.rubric_sha256 will be null and the record will fail validation.\n',
+      );
+      return null;
+    }
     const buf = readFileSync(rubricPath);
     return createHash('sha256').update(buf).digest('hex');
-  } catch {
+  } catch (err) {
+    process.stderr.write(
+      `[eval-engine] WARN: could not hash rubric at '${rubricPath}': ${err?.message ?? String(err)}\n`,
+    );
     return null;
   }
 }

package/scripts/lib/events.mjs

@@ -12,17 +12,61 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { SO_PROJECT_DIR, SO_SHARED_DIR } from './platform.mjs';
+import { readLock } from './session-lock.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
- * Returns the absolute path to .orchestrator/metrics/events.jsonl in the project root.
+ * Returns the absolute path to `.orchestrator/metrics/events.jsonl` under `repoRoot`.
+ *
+ * `repoRoot` defaults to the module-level `SO_PROJECT_DIR` constant, so the
+ * zero-arg call is unchanged for every existing caller (#941). Pass an explicit
+ * `repoRoot` when the destination must be pinned to a tree other than the
+ * CWD/env-resolved project — e.g. a unit test running the gate against a tmp
+ * repo, which must NOT append synthetic records to the real fleet telemetry.
+ *
+ * @param {string} [repoRoot=SO_PROJECT_DIR] — project root the events log lives under.
  * @returns {string}
  */
-export function eventsFilePath() {
-  return path.join(SO_PROJECT_DIR, SO_SHARED_DIR, 'metrics', 'events.jsonl');
+export function eventsFilePath(repoRoot = SO_PROJECT_DIR) {
+  return path.join(repoRoot, SO_SHARED_DIR, 'metrics', 'events.jsonl');
+}
+
+/**
+ * Session attribution for gate/lifecycle telemetry (#928a, hoisted here #941).
+ *
+ * The natural shared home the two former call-site copies (`quality-gate.mjs`,
+ * `run-quality-gate.mjs`) both named. Emits BOTH the UUID `session_id` and the
+ * `semantic_session_id`, mirroring the field shape of
+ * `orchestrator.session.lock.acquired` so gate events join against the same keys
+ * existing consumers already read (see `session-close-backfill.mjs`).
+ *
+ * Without a lock (CI runs have none) BOTH keys are OMITTED rather than filled
+ * with a placeholder: a fabricated id would silently collide across every
+ * unattributed run and read as a real session; an empty string would satisfy a
+ * truthiness check while attributing to nothing. An absent key is the only
+ * honest encoding of "not attributable".
+ *
+ * @param {string} [repoRoot] — repo whose `session.lock` is read for attribution.
+ * @returns {{session_id?: string, semantic_session_id?: string}}
+ */
+export function sessionAttribution(repoRoot) {
+  try {
+    const lock = readLock({ repoRoot });
+    if (!lock) return {};
+    const out = {};
+    if (typeof lock.session_id === 'string' && lock.session_id.trim()) {
+      out.session_id = lock.session_id;
+    }
+    if (typeof lock.semantic_session_id === 'string' && lock.semantic_session_id.trim()) {
+      out.semantic_session_id = lock.semantic_session_id;
+    }
+    return out;
+  } catch {
+    return {};
+  }
 }
 
 /**
@@ -43,6 +87,11 @@ export function eventsFilePath() {
  *   Used by `scripts/emit-event.mjs --file` so shell callers (e.g.
  *   compute-grounding-injection.sh) can target a pre-resolved EVENTS_JSONL path
  *   without depending on platform.mjs CWD/env resolution (#611).
+ * @param {string} [opts.repoRoot] — pin the destination to `<repoRoot>/.orchestrator/
+ *   metrics/events.jsonl` instead of the module-level `SO_PROJECT_DIR` default
+ *   (#941). Ignored when `opts.filePath` is given (explicit path wins). This is
+ *   the clean interface replacing the hand-built `join(repoRoot, …)` recipes that
+ *   used to open-code this destination at each call-site.
  * @returns {Promise<void>}
  */
 export async function emitEvent(type, payload = {}, opts = {}) {
@@ -50,10 +99,13 @@ export async function emitEvent(type, payload = {}, opts = {}) {
   const record = { timestamp: new Date().toISOString(), event: type, ...payload };
   const line = JSON.stringify(record) + '\n';
 
-  // Ensure the destination directory exists before appending. The default
-  // resolution is unchanged for 2-arg callers — only an explicit opts.filePath
-  // overrides it (#611, additive).
-  const filePath = opts.filePath ?? eventsFilePath();
+  // Ensure the destination directory exists before appending. Resolution order:
+  //   1. explicit opts.filePath (a pre-resolved path — #611)
+  //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941)
+  //   3. the SO_PROJECT_DIR default (unchanged for 2-arg callers)
+  // eventsFilePath(undefined) falls through to its SO_PROJECT_DIR default param,
+  // so a caller passing neither behaves EXACTLY as before (additive).
+  const filePath = opts.filePath ?? eventsFilePath(opts.repoRoot);
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.appendFile(filePath, line, 'utf8');
 

package/scripts/lib/evolve/autonomy-verdict.mjs

@@ -223,6 +223,11 @@ function readinessConfidence(autopilotSummary, judgmentSummary, score) {
 /**
  * Summarize autopilot run history plus type-8 mode effectiveness rollups.
  *
+ * Abandoned-session filtering (#834): `sessions` is passed straight through
+ * to `groupByMode()`, which filters phantom `status: 'abandoned'` stubs
+ * before bucketing — this function inherits that guarantee transitively and
+ * does not duplicate the filter. See `autopilot-effectiveness.mjs` `groupByMode()`.
+ *
  * @param {Array} autopilotRuns
  * @param {Array} sessions
  * @returns {object}