session-orchestrator 5.11.0 → 5.12.0

package/scripts/lib/session-end/vault-orphans.mjs

@@ -0,0 +1,205 @@
+/**
+ * vault-orphans.mjs - Phase 3.7e Vault Orphans (#1563).
+ *
+ * Lists the untracked files in the Meta-Vault that were modified since this
+ * session started, so the closing session can NAME what it may have left
+ * behind there.
+ *
+ * Why this exists (measured 2026-10-11): one vault checkout had accumulated 268
+ * untracked files over five days - website audits, session reports, reviews,
+ * lead handovers - written by sessions of OTHER repos into their configured
+ * `vault-dir`. None of them was ever committed: a session's close commits only
+ * in its own repo, and vault-mirror auto-commits only its own generator-marked
+ * files (`scripts/lib/vault-mirror/auto-commit.mjs`). The writing session is the
+ * only one that knows it wrote them, and nothing made it look.
+ *
+ * THE IRON RULE: this module PROPOSES, it never DISPOSES. Its only git
+ * invocation is the read-only `ls-files --others --exclude-standard -z`. No
+ * add, commit, rm, mv, clean, stash; no file is written, moved or deleted. The
+ * vault is another repo with its own rules (PSA-003).
+ *
+ * The return field is named `candidates`, not `orphans`: mtime is a HINT, not
+ * proof of ownership. A concurrent session of another repo may have written the
+ * same file in the same window. The coordinator names them and records one Open
+ * Question; it never acts on them.
+ *
+ * Three states, never two (a missing measurement must not look like zero):
+ *   - `{ status: 'ok', total: 0 }`   - measured, nothing found
+ *   - `{ status: 'ok', total: N }`   - measured, N candidates
+ *   - `{ status: 'unavailable' }`    - could not measure (no vault dir, not a
+ *                                      git repo, git failed). Never reported as
+ *                                      "no orphans".
+ *
+ * Exclusion - what another writer already owns: any file whose first 4 KB
+ * carries a `_generator: session-orchestrator-` frontmatter line. Census
+ * 2026-10-11 @ 686e2c12 (`rg -n "GENERATOR_MARKER\s*=" scripts/`): four marker
+ * values, all with that prefix - `vault-mirror@1` (40-learnings/, 50-sessions/,
+ * monthly rollups), `vault-status-narrative@1` (01-projects/<slug>/
+ * _session-narrative.md), `active-sessions@1` (01-projects/_active-sessions.md),
+ * `gitlab-portfolio@1`. The match is line-anchored so a hand-written note that
+ * merely QUOTES the marker in prose is still reported.
+ *
+ * There is deliberately NO blanket exclusion of `40-learnings/` / `50-sessions/`:
+ * vault-mirror owns only the MARKED files there. `autoCommitVaultMirror` treats
+ * an unmarked staged file in those dirs as an offender and skips its whole
+ * commit, so an unmarked untracked file there is owned by nobody AND blocks the
+ * mirror - the last thing to hide.
+ *
+ * Never throws. DI seams (#580-DI-001), synchronous like the Phase 4b sibling
+ * ./worktree-orphan-sweep.mjs: `execFileFn` (default `execFileSync`) and
+ * `statFn` (default `lstatSync` - a symlink is reported as itself, never
+ * followed out of the vault). Every git call passes an args ARRAY, no shell
+ * (#577 HARDEN-001).
+ */
+
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs';
+
+import { redactHomeDir } from '../common.mjs';
+
+/** Upper bound on the returned `candidates` list; `total` still counts all. */
+export const MAX_CANDIDATES = 200;
+
+/** Bytes read per file for the generator check - same window as auto-commit.mjs. */
+const HEAD_BYTES = 4096;
+
+/** A frontmatter line naming one of this plugin's generators. */
+const GENERATOR_LINE_RE = /^_generator:[ \t]*session-orchestrator-/m;
+
+/**
+ * Env vars that retarget git away from `-C <dir>`. An inherited `GIT_DIR` beats
+ * `-C` (incident 2026-08-19), which here would list ANOTHER repo's untracked
+ * files as vault candidates. Stripped for the one git call below.
+ */
+const REPO_REDIRECT_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'];
+
+/**
+ * Ceiling for git's NUL-separated path list: 16 MiB is ~150k paths at ~100
+ * bytes. Past it, execFileSync throws ENOBUFS and the result is `unavailable`
+ * (could not measure), never a silently cut list. Revisit if a vault ever
+ * reports that reason.
+ */
+const LS_FILES_MAX_BUFFER = 16 * 1024 * 1024;
+
+/**
+ * A vault on a hung network filesystem must not stall /close: past this the
+ * call is killed and the result is `unavailable` (git-failed). 20k untracked
+ * files took 0.46 s (2026-10-11), so 20 s is a hang, not a slow vault.
+ */
+const LS_FILES_TIMEOUT_MS = 20_000;
+
+/** @param {string} absPath @returns {boolean} true when the head names one of our generators */
+function isGeneratorOwned(absPath) {
+  let fd;
+  try {
+    fd = openSync(absPath, 'r');
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const n = readSync(fd, buf, 0, HEAD_BYTES, 0);
+    return GENERATOR_LINE_RE.test(buf.subarray(0, n).toString('utf8'));
+  } catch {
+    // Unreadable -> not provably someone else's. This module only REPORTS, so
+    // the safe direction is to show the file, not to hide it.
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} reason
+ * @param {string} [detail]
+ * @returns {{status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ */
+function unavailable(reason, detail) {
+  return detail ? { status: 'unavailable', reason, detail, candidates: [] } : { status: 'unavailable', reason, candidates: [] };
+}
+
+/**
+ * Find untracked vault files modified at or after `sinceMs`.
+ *
+ * @param {object} [opts]
+ * @param {string} opts.vaultDir - Vault working-tree root (already tilde-expanded).
+ * @param {number} opts.sinceMs - Session start, epoch ms. Files with an older
+ *   mtime are not candidates.
+ * @param {Function} [opts.execFileFn] - execFileSync seam: (file, args, options) => string.
+ * @param {Function} [opts.statFn] - lstatSync seam: (absPath) => { mtimeMs, isFile() }.
+ * @returns {{status: 'ok', candidates: Array<{path: string, mtimeMs: number}>,
+ *   total: number, truncated: boolean, untracked: number}
+ *   | {status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ *   `path` is vault-relative as git reports it. `total` counts every candidate,
+ *   `candidates` holds at most MAX_CANDIDATES of them (sorted by path),
+ *   `untracked` is everything git listed before the mtime and generator filters.
+ */
+export function findVaultOrphans({ vaultDir, sinceMs, execFileFn, statFn } = {}) {
+  try {
+    if (typeof vaultDir !== 'string' || vaultDir.trim() === '') return unavailable('no-vault-dir');
+    if (typeof sinceMs !== 'number' || !Number.isFinite(sinceMs)) return unavailable('invalid-since');
+
+    const exec = typeof execFileFn === 'function' ? execFileFn : execFileSync;
+    const stat = typeof statFn === 'function' ? statFn : lstatSync;
+    const root = path.resolve(vaultDir);
+
+    const env = { ...process.env };
+    for (const key of REPO_REDIRECT_ENV) delete env[key];
+
+    // -- THE ONLY GIT CALL - read-only --------------------------------------
+    let out;
+    try {
+      out = exec('git', ['-C', root, 'ls-files', '--others', '--exclude-standard', '-z'], {
+        encoding: 'utf8',
+        env,
+        maxBuffer: LS_FILES_MAX_BUFFER,
+        timeout: LS_FILES_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      const stderr = typeof err?.stderr === 'string' ? err.stderr : String(err?.stderr ?? '');
+      const reason = /not a git repository/i.test(stderr) ? 'not-a-git-repo' : 'git-failed';
+      const firstLine = redactHomeDir(stderr.split('\n').find((l) => l.trim() !== '') ?? err?.code ?? '');
+      return unavailable(reason, typeof firstLine === 'string' ? firstLine.trim().slice(0, 200) : undefined);
+    }
+    if (typeof out !== 'string') return unavailable('git-failed', 'non-string git output');
+
+    const untrackedPaths = out.split('\0').filter((p) => p !== '');
+
+    // Cost is linear in the untracked count: one lstat per path, plus one 4 KB
+    // read per path that passes the mtime filter (cheapest filter first). Fine
+    // for the measured 268; revisit if a close reports more than ~10k untracked
+    // files, where the per-file read would start to show in /close time.
+    const all = [];
+    for (const rel of untrackedPaths) {
+      const abs = path.join(root, rel);
+      let st;
+      try {
+        st = stat(abs);
+      } catch {
+        // Vanished between listing and stat (a concurrent writer moved it):
+        // nothing left to name.
+        continue;
+      }
+      const mtimeMs = Number(st?.mtimeMs);
+      if (!Number.isFinite(mtimeMs) || mtimeMs < sinceMs) continue;
+      if (typeof st.isFile === 'function' && st.isFile() && isGeneratorOwned(abs)) continue;
+      all.push({ path: rel, mtimeMs });
+    }
+
+    all.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+      status: 'ok',
+      candidates: all.slice(0, MAX_CANDIDATES),
+      total: all.length,
+      truncated: all.length > MAX_CANDIDATES,
+      untracked: untrackedPaths.length,
+    };
+  } catch (err) {
+    // Defensive catch-all - this probe must never throw into /close.
+    return unavailable('internal-error', String(err?.message ?? err).slice(0, 200));
+  }
+}

package/scripts/lib/session-invocation.mjs

@@ -3,15 +3,26 @@
  * This is a text boundary, not a shell/option parser: quotes and command syntax
  * in the context remain data. `unknown` is a ledger value, never a live mode.
  *
+ * A bare `/session` defaults to `deep`. In a repo without any session history
+ * of its own that default is not silent: the result carries
+ * `defaultReason: 'no-session-history'`, and the caller asks for task and mode
+ * first (#1561). `hasHistory` left undefined means "not measured" and keeps
+ * the plain default.
+ *
  * @param {string} [argumentsText] Complete text following /session.
- * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string}}
+ * @param {{hasHistory?: boolean}} [options]
+ * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string, defaultReason?: string}}
  */
-export function resolveSessionInvocation(argumentsText = '') {
+export function resolveSessionInvocation(argumentsText = '', { hasHistory } = {}) {
   if (typeof argumentsText !== 'string') {
     throw new TypeError('session invocation arguments must be a string');
   }
   const [_, mode, context = ''] = argumentsText.trimStart().match(/^(\S+)(?:\s+([\s\S]*))?$/u) ?? [];
-  if (mode === undefined) return { sessionType: 'deep', context: '' };
+  if (mode === undefined) {
+    return hasHistory === false
+      ? { sessionType: 'deep', context: '', defaultReason: 'no-session-history' }
+      : { sessionType: 'deep', context: '' };
+  }
   if (mode === 'ultradeep') return { sessionType: 'deep', profile: 'ultradeep', context };
   if (['housekeeping', 'feature', 'deep'].includes(mode)) {
     return { sessionType: mode, context };

package/scripts/lib/session-registry.mjs

@@ -38,7 +38,7 @@ import crypto from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import { digestSha256 } from './crypto-digest-utils.mjs';
 
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, mkdirSync, realpathSync } from 'node:fs';
 
 import { utcTimestamp, appendJsonl } from './common.mjs';
 import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
@@ -89,14 +89,24 @@ function entryPath(sessionId) {
 // ---------------------------------------------------------------------------
 
 /**
- * Stable SHA-256 hex of an absolute path. Used so registry entries can be
+ * Stable SHA-256 hex of a canonical repo path. Used so registry entries can be
  * correlated by repo without exposing local filesystem layout.
  */
 export function repoPathHash(absPath) {
   if (typeof absPath !== 'string' || absPath.length === 0) {
     throw new TypeError('repoPathHash: absPath must be a non-empty string');
   }
-  return digestSha256(path.resolve(absPath));
+  return digestSha256(resolveRepoPath(absPath));
+}
+
+/** Resolve symlinks and on-disk casing; unavailable paths keep their old identity. */
+function resolveRepoPath(repoPath) {
+  const resolved = path.resolve(repoPath);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
 }
 
 function _assertSessionId(sessionId) {
@@ -255,7 +265,7 @@ export async function registerSelf(opts) {
     pid: opts.pid ?? process.pid,
     platform: opts.platform ?? null,
     repo_path_hash: repoPathHash(projectRoot),
-    repo_name: path.basename(path.resolve(projectRoot)),
+    repo_name: path.basename(resolveRepoPath(projectRoot)),
     branch: opts.branch ?? null,
     started_at: now,
     last_heartbeat: now,

package/scripts/lib/so-hud/collect.mjs

@@ -0,0 +1,130 @@
+import path from 'node:path';
+import { parseStateMd } from '../state-md/yaml-parser.mjs';
+
+export const EVENT_NAMES = new Set([
+  'orchestrator.quality_gate.passed', 'orchestrator.quality_gate.failed',
+  'orchestrator.vault.mirror_run_completed', 'orchestrator.vault.board_written',
+]);
+const text = v => typeof v === 'string' && v.length ? v : null;
+const number = v => typeof v === 'number' && Number.isFinite(v) ? v : null;
+const positive = v => Number.isSafeInteger(v) && v > 0 ? v : null;
+export const safeId = v => typeof v === 'string' && /^[a-zA-Z0-9_-]{1,200}$/.test(v);
+
+export function parseEvents(tail) {
+  return tail.split('\n').flatMap(line => {
+    try {
+      const e = JSON.parse(line);
+      return EVENT_NAMES.has(e.event ?? e.event_type) ? [e] : [];
+    } catch { return []; }
+  }).sort((a, b) => (Date.parse(a.timestamp) || 0) - (Date.parse(b.timestamp) || 0));
+}
+
+export function gateFromEvent(e) {
+  if (!e) return null;
+  const failed = (e.event ?? e.event_type).endsWith('.failed') || e.check_failed === true || e.timed_out === true || (number(e.exit_code) !== null && e.exit_code !== 0);
+  const reporting = ['baseline', 'incremental', 'per-file'].includes(e.variant);
+  const proven = e.exit_code === 0 && (reporting ? e.check_failed === false : ['full-gate', 'auto-fix-loop'].includes(e.variant));
+  return { variant: text(e.variant), passed: failed ? false : proven ? true : null,
+    check_failed: typeof e.check_failed === 'boolean' ? e.check_failed : null,
+    exit_code: number(e.exit_code), at: text(e.timestamp) };
+}
+
+/** Both scope sources must be readable; incomplete dispatch never proves disjointness. */
+export function scopePaths(aggregate, dispatch) {
+  if (!Array.isArray(aggregate) || !dispatch || !Array.isArray(dispatch.agents)) return null;
+  if ((dispatch.scopeSignals?.['marker-absent'] ?? 0) > 0 || (dispatch.scopeSignals?.unparseable ?? 0) > 0) return null;
+  const rows = [...aggregate, ...dispatch.agents];
+  if (rows.some(r => !r || !Array.isArray(r.files) || r.files.some(f => typeof f !== 'string'))) return null;
+  return [...new Set(rows.flatMap(r => r.files))];
+}
+
+/** All I/O and time are supplied. No writes, host discovery or defaults hidden in this fold. */
+export async function collectSnapshot(repoRoot, readers) {
+  const degraded = [];
+  const read = async (file, json = false) => {
+    try {
+      const raw = await readers.readText(path.join(repoRoot, file));
+      return { value: json ? JSON.parse(raw) : raw, absent: false };
+    } catch (e) {
+      if (e.code !== 'ENOENT') degraded.push(`${file}:unreadable`);
+      return { value: null, absent: e.code === 'ENOENT' };
+    }
+  };
+  const now = readers.now();
+  const [lockResult, waveRead, stateRead, agentStatus, discovery, eventsRead, config, greenRead] = await Promise.all([
+    readers.lock(repoRoot), read('.claude/wave-scope.json', true),
+    readers.statePath ? read(readers.statePath) : read('.claude/STATE.md'),
+    readers.agents(repoRoot), readers.discover(repoRoot), readers.events(repoRoot), readers.config(repoRoot), read('.orchestrator/runtime/last-green-sha.txt'),
+  ]);
+  degraded.push(...(discovery.degraded ?? []), ...(eventsRead.degraded ?? []), ...(config.degraded ?? []));
+  if (!['ok', 'absent'].includes(lockResult.status)) degraded.push(`lock:${lockResult.status}`);
+  const lock = lockResult.lock ?? null;
+  const sid = readers.sessionId ?? lock?.session_id ?? null;
+  const wave = waveRead.value && typeof waveRead.value === 'object' && !Array.isArray(waveRead.value) ? waveRead.value : null;
+  const foreignWave = wave?.session_id && sid && wave.session_id !== sid;
+  if (foreignWave) degraded.push('wave:foreign-session');
+  const ownWave = foreignWave || !positive(wave?.wave) ? null : wave;
+  if (!waveRead.absent && !ownWave && !foreignWave) degraded.push('wave:invalid-or-unreadable');
+  const waveNumber = positive(ownWave?.wave);
+  const fm = parseStateMd(stateRead.value)?.frontmatter ?? {};
+  const foreignState = fm['session-id'] && sid && fm['session-id'] !== sid;
+  if (foreignState) degraded.push('state:foreign-session');
+  const state = foreignState ? {} : fm;
+  const dispatch = safeId(sid) ? (await read(`.orchestrator/wave-dispatch-scopes.${sid}.json`, true)).value : null;
+  const dispatchWave = positive(Number(String(dispatch?.waveKey ?? '').match(/\|w(\d+)\|/)?.[1]));
+  const currentDispatch = dispatch && waveNumber && dispatchWave === waveNumber && Array.isArray(dispatch.agents) ? dispatch : null;
+  const entries = new Map();
+  for (const a of currentDispatch?.agents ?? []) {
+    if (!text(a?.id)) continue;
+    entries.set(a.id, { id: a.id, typ: text(a.typ ?? a.agent_type ?? a.type), modellfamilie: text(a.modellfamilie ?? a.model), status: null, tokens: null, letzter_request_at: null, quelle: 'dispatch' });
+  }
+  for (const [id, a] of Object.entries(agentStatus.entries ?? {})) {
+    // Unbound/foreign status cannot make the current wave look alive.
+    if (!sid || (a.session_id ?? a.sessionId) !== sid) continue;
+    if (waveNumber && (a.wave ?? a.wave_number) !== waveNumber) continue;
+    const existing = entries.get(id);
+    entries.set(id, { id, typ: text(a.agent_type) ?? existing?.typ ?? null, modellfamilie: text(a.model) ?? existing?.modellfamilie ?? null,
+      status: text(a.status ?? a.text), tokens: null, letzter_request_at: null, quelle: existing ? 'dispatch+agent-status' : 'agent-status' });
+  }
+  if (agentStatus.degraded) degraded.push('agents:degraded');
+  const events = parseEvents(eventsRead.text ?? '');
+  const gates = events.filter(e => (e.event ?? e.event_type).startsWith('orchestrator.quality_gate.'));
+  const lastGate = gates.reduce((last, event) => {
+    const next = gateFromEvent(event);
+    return last?.passed === false && next.passed === null ? last : next;
+  }, null);
+  const lockLive = lock ? readers.isLockLive(lock, now) : false;
+  const sessionLockLive = lockLive && sid !== null && lock.session_id === sid;
+  const latest = name => events.filter(e => (e.event ?? e.event_type) === name && e.dry_run !== true).at(-1);
+  const mirror = latest('orchestrator.vault.mirror_run_completed');
+  const board = latest('orchestrator.vault.board_written');
+  const peers = await Promise.all((discovery.sessions ?? []).filter(s => s.sessionId !== sid).map(async s => {
+    const root = s.worktreePath;
+    const peerRead = async file => { try { return JSON.parse(await readers.readText(path.join(root, file))); } catch { return null; } };
+    const peerLock = (await readers.lock(root)).lock;
+    const peerStateRaw = await readers.readText(path.join(root, '.claude/STATE.md')).catch(() => null);
+    const peerFm = parseStateMd(peerStateRaw)?.frontmatter;
+    const bound = peerFm?.['session-id'] === s.sessionId;
+    const stateWave = bound ? positive(peerFm['current-wave']) : null;
+    const pd = safeId(s.sessionId) ? await peerRead(`.orchestrator/wave-dispatch-scopes.${s.sessionId}.json`) : null;
+    const dispatchNumber = pd?.waveKey?.startsWith(`${s.sessionId}|`) ? positive(Number(pd.waveKey.split('|')[1]?.slice(1))) : null;
+    const currentWave = stateWave ?? dispatchNumber;
+    const aggregate = currentWave ? await peerRead(`.claude/filescopes/wave-${currentWave}.scopes.json`) : null;
+    return { session_id: s.sessionId, branch: text(s.branch), status: bound ? text(peerFm.status) : null,
+      current_wave: currentWave, last_heartbeat: peerLock?.session_id === s.sessionId ? text(peerLock.last_heartbeat) : text(s.last_heartbeat),
+      gleiches_working_copy: path.resolve(root) === path.resolve(repoRoot), scope_paths: dispatchNumber !== null && dispatchNumber !== currentWave ? null : scopePaths(aggregate, pd) };
+  }));
+  return {
+    schema_version: 1, measured_at: new Date(now).toISOString(), repo: { root: repoRoot, name: path.basename(repoRoot) },
+    lock: lock ? { session_id: text(lock.session_id), live: lockLive, last_heartbeat: text(lock.last_heartbeat) } : null,
+    session: sid ? { session_id: sid, semantic_session_id: text(lock?.semantic_session_id) } : null,
+    wave: { running: waveRead.absent ? false : ownWave ? sessionLockLive : null, number: waveNumber, role: text(ownWave?.role),
+      agents_total: Array.isArray(currentDispatch?.agents) ? currentDispatch.agents.length : null, source: ownWave ? '.claude/wave-scope.json' : null },
+    agents: { entries: [...entries.values()], source: agentStatus.source ?? (currentDispatch ? 'dispatch' : null), at: agentStatus.at ?? text(currentDispatch?.updated), degraded: agentStatus.degraded ?? null },
+    state: { status: text(state.status), session_type: text(state['session-type'] ?? state.type ?? state.mode), current_wave: positive(state['current-wave']), total_waves: positive(state['total-waves'] ?? state.waves) },
+    gate: { last: lastGate, last_green_sha: typeof greenRead.value === 'string' && /^[a-f0-9]{7,64}$/i.test(greenRead.value.trim()) ? greenRead.value.trim() : null },
+    peers, vault: { enabled: config.enabled ?? null, mode: config.mode ?? null,
+      last_run: mirror ? { at: text(mirror.timestamp), created: number(mirror.created), updated: number(mirror.updated), failed: number(mirror.failed), aborted: mirror.aborted ?? null } : null,
+      board: board ? { action: text(board.action), at: text(board.timestamp) } : null }, degraded: [...new Set(degraded)],
+  };
+}

package/scripts/lib/so-hud/runtime.mjs

@@ -0,0 +1,76 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { discoverActiveSessions } from '../session-discovery.mjs';
+import { readRegistry, activeDir } from '../session-registry.mjs';
+import { readCurrentStatus } from '../agent-status.mjs';
+import { readLockDetailed, isLockLive } from '../session-lock.mjs';
+import { readTailWindow } from '../tail-window.mjs';
+import { parseSessionConfig } from '../config.mjs';
+import { resolveStateMdPath } from '../state-md.mjs';
+import { collectSnapshot } from './collect.mjs';
+const exec = promisify(execFile);
+export const MAX_EVENT_BYTES = 512 * 1024;
+
+export function readEventTail(repoRoot) {
+  try {
+    const tail = readTailWindow(path.join(repoRoot, '.orchestrator/metrics/events.jsonl'), MAX_EVENT_BYTES);
+    return { text: tail.cut ? tail.text.slice(tail.text.indexOf('\n') + 1) : tail.text, degraded: tail.cut ? ['events:tail-only'] : [] };
+  } catch (e) { return { text: '', degraded: [e.code === 'ENOENT' ? 'events:absent' : 'events:unreadable'] }; }
+}
+
+async function registryWithHealth() {
+  // The canonical reader intentionally swallows failures; distinguish its directory first.
+  try { await fs.readdir(activeDir()); }
+  catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  return readRegistry();
+}
+
+/** Capture fallback at the injected boundaries, without intercepting global stderr. */
+export async function discover(repoRoot, { run = exec, registry = registryWithHealth, discovery = discoverActiveSessions, now = Date.now() } = {}) {
+  const degraded = [];
+  let registryEntries = [];
+  const sessions = await discovery(repoRoot, {
+    now, timeoutMs: 1000,
+    listWorktreesImpl: async () => {
+      try {
+        const { stdout } = await run('git', ['-C', repoRoot, 'worktree', 'list', '--porcelain'], { timeout: 700, maxBuffer: 512 * 1024 });
+        return stdout.trim().split('\n\n').filter(Boolean).map(block => {
+          const lines = block.split('\n');
+          return { path: lines.find(l => l.startsWith('worktree '))?.slice(9), branch: lines.find(l => l.startsWith('branch '))?.slice(7).replace(/^refs\/heads\//, '') ?? '' };
+        }).filter(w => w.path);
+      } catch (e) {
+        degraded.push(e.killed || e.code === 'ETIMEDOUT' ? 'discovery-timeout' : 'discovery-fallback');
+        return [{ path: repoRoot, branch: '' }];
+      }
+    },
+    registryReader: async () => {
+      try { registryEntries = await registry(); return registryEntries; } catch { degraded.push('registry-unreadable'); return []; }
+    },
+  });
+  if (sessions.some(s => s.registryOnly)) degraded.push('discovery:registry-fallback');
+  return { sessions: sessions.map(s => ({ ...s, last_heartbeat: registryEntries.find(r => r.session_id === s.sessionId)?.last_heartbeat ?? null })), degraded };
+}
+
+async function config(repoRoot) {
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      const source = await fs.readFile(path.join(repoRoot, name), 'utf8');
+      if (!/^vault-integration:/m.test(source)) continue;
+      // No host-local owner.yaml reads and no vault path resolution outside this repo.
+      const parsed = parseSessionConfig(source, { hostPaths: { env: {}, ownerConfig: {} } });
+      const value = parsed['vault-integration'];
+      return { enabled: value?.enabled ?? null, mode: value?.mode ?? null };
+    } catch (e) { if (e.code !== 'ENOENT') return { degraded: ['config:unreadable'] }; }
+  }
+  return { enabled: null, mode: null };
+}
+export async function measure(repoRoot) {
+  return collectSnapshot(repoRoot, {
+    now: Date.now, readText: file => fs.readFile(file, 'utf8'), lock: root => readLockDetailed({ repoRoot: root }),
+    isLockLive, agents: root => readCurrentStatus({ repoRoot: root }), discover, events: readEventTail, config,
+    statePath: path.relative(repoRoot, resolveStateMdPath(repoRoot)),
+    sessionId: process.env.CLAUDE_SESSION_ID ?? process.env.SO_SESSION_ID ?? null,
+  });
+}