session-orchestrator 3.16.0 → 3.17.0

package/scripts/lib/moc-staleness-banner.mjs

@@ -0,0 +1,267 @@
+/**
+ * moc-staleness-banner.mjs — Session-start banner for issue #831 (building
+ * block B2).
+ *
+ * Surfaces a `warn` banner during session-start Phase 4 when a Meta-Vault
+ * MOC (map-of-content) index note — a `<vaultDir>/08-topics/*-moc.md` file —
+ * has an `updated:` frontmatter older than a configurable threshold (default
+ * 90 days). Nothing in this repo reads `08-topics/` before this module; it
+ * is the first consumer.
+ *
+ * Design notes:
+ *  - Mirrors the contract used by every other Phase 4 banner
+ *    (`scripts/lib/peer-cards/staleness-banner.mjs`, `scripts/lib/vault-staleness-banner.mjs`,
+ *    `scripts/lib/loop-readiness-banner.mjs`, `scripts/lib/reconcile-nudge-banner.mjs`,
+ *    and sibling building block `scripts/lib/context-coverage-banner.mjs` — B4
+ *    of this same issue): a single `checkXxx()` entry point that returns
+ *    `null` (silent no-op) or `{ severity, message, ... }` — never an array,
+ *    never `undefined`, never a throw.
+ *  - Synchronous — the probe only touches `existsSync`/`readdirSync`/`readFileSync`,
+ *    so unlike the async peer-cards/reconcile-nudge probes this one needs no
+ *    `await` at the call site (mirrors `checkLoopReadiness` / `checkContextCoverage`).
+ *  - Never throws. Wrapped in an outermost defensive `try/catch`; every
+ *    individually-fallible filesystem call additionally gets its own inner
+ *    bare (no-binding) catch with a one-line explanatory comment.
+ *  - `vault-dir` resolution mirrors the host-local-override pattern used
+ *    throughout the plugin (issue #653): an injected `opts.vaultDir` test
+ *    seam wins, then `config['vault-integration']['vault-dir']`, else the
+ *    probe silently no-ops (no vault configured — nothing to check).
+ *  - The committed repo default for `vault-integration.vault-dir` is
+ *    tilde-prefixed (`~/Projects/vault`) and is NOT pre-expanded anywhere
+ *    upstream of this module — `expandTilde()` from `./common.mjs` is applied
+ *    unconditionally before the first `path.join`, exactly as
+ *    `checkContextCoverage()` does for the same reason.
+ *  - A `*-moc.md` file whose `updated:` frontmatter is missing or
+ *    unparseable is EXCLUDED, not reported stale — mirrors
+ *    `scripts/lib/peer-cards/staleness-banner.mjs` (~L61-76): the corrective
+ *    action there is "fix the frontmatter", not this banner's "refresh the
+ *    `updated:` date" remediation hint. Gated via `Number.isFinite(days)`.
+ *
+ * Cross-references:
+ *  - `scripts/lib/config/moc-staleness.mjs` (`_parseMocStaleness`) — the
+ *    `moc-staleness:` Session Config block parser. NOT wired into
+ *    `scripts/lib/config.mjs` by this module — the coordinator registers it
+ *    separately. The exact lines to add there:
+ *
+ *      import { _parseMocStaleness } from './config/moc-staleness.mjs';
+ *      // ... later, alongside the other top-level block parses:
+ *      const mocStaleness = _parseMocStaleness(mdContent);
+ *      // ... in the returned config object:
+ *      'moc-staleness': mocStaleness,
+ *
+ *  - `scripts/lib/common.mjs` (`expandTilde`) — shared tilde-expansion helper.
+ *  - `scripts/lib/context-coverage-banner.mjs` — sibling B4 building block for
+ *    the same issue; this module mirrors its structure closely.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site (wiring
+ *    snippet supplied separately; this module does not edit that file).
+ *  - Issue #831 (building block B2).
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import YAML from 'js-yaml';
+
+import { expandTilde } from './common.mjs';
+
+/** Vault-relative directory holding MOC (map-of-content) index notes. */
+const MOC_SUBDIR = '08-topics';
+
+/** Filename suffix that identifies a MOC note within `08-topics/`. */
+const MOC_SUFFIX = '-moc.md';
+
+/** Fallback staleness threshold (days) when config supplies none/invalid. */
+const DEFAULT_THRESHOLD_DAYS = 90;
+
+/** Matches a leading `---\n...\n---` YAML frontmatter fence. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/**
+ * Above this many stale filenames, the message truncates the name list and
+ * says so explicitly rather than silently dropping names past the limit.
+ */
+const MAX_STALE_NAMES_IN_MESSAGE = 20;
+
+/**
+ * Resolve the vault directory to scan.
+ *
+ * Precedence: `opts.vaultDir` (test seam) > `config['vault-integration']['vault-dir']` > null.
+ *
+ * @param {string|undefined} vaultDir
+ * @param {unknown} config
+ * @returns {string|null} raw (not-yet-tilde-expanded) vault dir, or null when unresolvable
+ */
+function _resolveRawVaultDir(vaultDir, config) {
+  if (typeof vaultDir === 'string' && vaultDir.length > 0) return vaultDir;
+
+  if (config && typeof config === 'object') {
+    const vaultIntegration = /** @type {Record<string, unknown>} */ (config)['vault-integration'];
+    if (vaultIntegration && typeof vaultIntegration === 'object') {
+      const raw = /** @type {Record<string, unknown>} */ (vaultIntegration)['vault-dir'];
+      if (typeof raw === 'string' && raw.length > 0) return raw;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Read a single MOC file and compute whole days since its `updated:`
+ * frontmatter field. Returns `NaN` (never throws) when the file cannot be
+ * read, has no frontmatter fence, the YAML fails to parse, `updated` is
+ * missing/non-string, or `updated` is not a parseable date — every one of
+ * these cases is the caller's signal to EXCLUDE the file, not report it
+ * stale.
+ *
+ * @param {string} filePath — absolute path to a `*-moc.md` file
+ * @param {number} nowMs — epoch ms clock
+ * @returns {number} whole days since `updated:`, or `NaN`
+ */
+function _readMocStalenessDays(filePath, nowMs) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return NaN;
+  }
+
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) return NaN;
+
+  let fm;
+  try {
+    fm = YAML.load(m[1]);
+  } catch {
+    return NaN;
+  }
+
+  if (!fm || typeof fm !== 'object' || Array.isArray(fm)) return NaN;
+
+  // js-yaml's default schema auto-resolves an ISO-8601-shaped scalar (the
+  // canonical `updated:` form) into a native `Date`, NOT a string — verified:
+  // `YAML.load('updated: 2026-01-01T00:00:00Z').updated instanceof Date`.
+  // Accept both shapes; anything else (missing, number, array, …) excludes.
+  const rawUpdated = fm.updated;
+  let updatedMs;
+  if (rawUpdated instanceof Date) {
+    updatedMs = rawUpdated.getTime();
+  } else if (typeof rawUpdated === 'string') {
+    updatedMs = Date.parse(rawUpdated);
+  } else {
+    return NaN;
+  }
+  if (!Number.isFinite(updatedMs)) return NaN;
+
+  return Math.floor((nowMs - updatedMs) / 86_400_000);
+}
+
+/**
+ * Format the stale-filename list for the banner message, truncating (with an
+ * explicit note) past `MAX_STALE_NAMES_IN_MESSAGE`.
+ *
+ * @param {Array<{file: string, days: number}>} stale
+ * @returns {string}
+ */
+function _formatStaleNames(stale) {
+  const parts = stale.map((s) => `${s.file} (${s.days}d)`);
+  if (parts.length <= MAX_STALE_NAMES_IN_MESSAGE) return parts.join(', ');
+  const shown = parts.slice(0, MAX_STALE_NAMES_IN_MESSAGE).join(', ');
+  const hiddenCount = parts.length - MAX_STALE_NAMES_IN_MESSAGE;
+  return `${shown}, and ${hiddenCount} more (name list truncated)`;
+}
+
+/**
+ * Check MOC staleness and produce a session-start banner.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — REQUIRED absolute path to the repo root.
+ * @param {string} [opts.vaultDir] — test seam; overrides the config-resolved vault dir.
+ * @param {Date|number} [opts.now] — injectable clock for deterministic tests.
+ * @param {object} [opts.config] — optional already-parsed Session Config (avoids
+ *   a second CLAUDE.md (or AGENTS.md on Codex CLI) read; caller passes `$CONFIG`, mirrors `checkContextCoverage`).
+ *   Read keys: `config['moc-staleness']` (`.enabled`, `.mode`, `.thresholds.moc`)
+ *   and `config['vault-integration']['vault-dir']`.
+ * @returns {null | { severity: 'warn', message: string, stale: Array<{file: string, days: number}> }}
+ */
+export function checkMocStaleness({ repoRoot, vaultDir, now, config } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const cfg =
+      config &&
+      typeof config === 'object' &&
+      config['moc-staleness'] &&
+      typeof config['moc-staleness'] === 'object'
+        ? config['moc-staleness']
+        : {};
+
+    // Config gate — returns null BEFORE any filesystem I/O. Explicit opt-in
+    // required: `cfg.enabled` must be the literal `true`, not merely
+    // truthy/absent. A config block that is entirely absent (or present
+    // without an `enabled` key) must fail CLOSED, not open — see issue #831
+    // fail-open regression (a config carrying `vault-integration.vault-dir`
+    // but no `moc-staleness` block previously ran the probe unsolicited,
+    // because `undefined !== false`).
+    if (cfg?.enabled !== true || cfg?.mode === 'off') return null;
+
+    const rawVaultDir = _resolveRawVaultDir(vaultDir, config);
+    if (!rawVaultDir) return null;
+
+    const resolvedVaultDir = expandTilde(rawVaultDir);
+    const topicsDir = path.join(resolvedVaultDir, MOC_SUBDIR);
+
+    if (!existsSync(topicsDir)) return null;
+
+    let entries;
+    try {
+      entries = readdirSync(topicsDir);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+
+    entries = [...entries].sort();
+
+    const mocFiles = entries.filter((f) => typeof f === 'string' && f.endsWith(MOC_SUFFIX));
+    if (mocFiles.length === 0) return null;
+
+    const nowMs =
+      now instanceof Date
+        ? now.getTime()
+        : typeof now === 'number' && Number.isFinite(now)
+          ? now
+          : Date.now();
+
+    const cfgThreshold =
+      cfg.thresholds && typeof cfg.thresholds === 'object' ? cfg.thresholds.moc : undefined;
+    const thresholdDays =
+      typeof cfgThreshold === 'number' && Number.isFinite(cfgThreshold) && cfgThreshold > 0
+        ? cfgThreshold
+        : DEFAULT_THRESHOLD_DAYS;
+
+    const stale = [];
+    for (const file of mocFiles) {
+      const filePath = path.join(topicsDir, file);
+      let days;
+      try {
+        days = _readMocStalenessDays(filePath, nowMs);
+      } catch {
+        days = NaN;
+      }
+      // Missing/unparseable `updated:` is EXCLUDED, not reported stale.
+      if (!Number.isFinite(days)) continue;
+      if (days > thresholdDays) stale.push({ file, days });
+    }
+
+    if (stale.length === 0) return null;
+
+    const subjectLabel = stale.length === 1 ? '1 MOC stale' : `${stale.length} MOCs stale`;
+    const finding = `${subjectLabel} (>${thresholdDays} days)`;
+    const remediation = 'review and refresh the `updated:` frontmatter.';
+    const message = `⚠ moc-staleness: ${finding} — ${_formatStaleNames(stale)} — ${remediation}`;
+
+    return { severity: 'warn', message, stale };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}

package/scripts/lib/session-end/worktree-orphan-sweep.mjs

@@ -0,0 +1,252 @@
+/**
+ * worktree-orphan-sweep.mjs — Phase 4b Worktree-Orphan Sweep (#831 / B5).
+ *
+ * Identifies worktree branches with 0 commits ahead of the base branch —
+ * orphans left behind by finished sessions — and returns them as DATA.
+ *
+ * ┌──────────────────────────────────────────────────────────────────────┐
+ * │ THE IRON RULE: this module PROPOSES, it never DISPOSES.               │
+ * │ It executes ZERO mutating commands — no `git worktree remove`, no     │
+ * │ `git worktree prune`, no `git branch -d/-D`, no `git push --delete`,  │
+ * │ no rm/rmSync/unlinkSync, no reset/clean/checkout --/stash. The only   │
+ * │ git invocations it makes are read-only: `worktree list --porcelain`,  │
+ * │ `rev-list --count --end-of-options`, and — via isWorktreeClean() —    │
+ * │ `status --porcelain` plus `status --short --branch`.                  │
+ * └──────────────────────────────────────────────────────────────────────┘
+ *
+ * Grounding: `.claude/rules/parallel-sessions.md` § PSA-003 ("Never Destroy
+ * What You Didn't Create") — the test is *"Did I create this file/commit/
+ * change? If not, it is not mine to touch."* A sweep probe created none of the
+ * worktrees it inspects, so removal is categorically not its call. The return
+ * field is deliberately named `candidates` (not `orphans`, not `toDelete`, not
+ * `removals`): the name itself encodes "the coordinator decides". The operator
+ * AUQ is rendered by the coordinator at session-end Phase 4b, never here.
+ *
+ * CONSERVATIVE DEFAULT (safety-critical): any git error, unparseable output,
+ * detached HEAD, unresolvable branch, or ambiguity of any kind → the worktree
+ * is NOT reported as a candidate. Silence must never be read as "safe to
+ * delete". Precedent: `isWorktreeClean()` in ./worktree-cleanup.mjs returns
+ * false on any git error, documented as "conservative PSA-003 default: never
+ * auto-remove a worktree we could not verify".
+ *
+ * Banner contract: mirrors the other `checkXxx()` probes
+ * (`scripts/lib/peer-cards/staleness-banner.mjs`,
+ * `scripts/lib/vault-staleness-banner.mjs`) — a single entry point returning
+ * `null` (silent no-op) or one `{ severity, message, ... }` object. Never an
+ * array, never `undefined`, never a throw.
+ *
+ * DI seam (#580-DI-001): SYNCHRONOUS `execFileFn` (default `execFileSync`),
+ * matching its Phase 4a sibling ./worktree-cleanup.mjs and
+ * scripts/lib/memory-cleanup/worktree-sweep.mjs, because session-end Phase 4b
+ * runs in a synchronous coordinator step. The autopilot worktree driver
+ * (scripts/lib/autopilot/worktree-pipeline.mjs) deliberately uses an ASYNC
+ * `opts.$` (zx) seam instead; the seams are kept divergent on purpose —
+ * unifying them would break the sync/async boundary.
+ *
+ * #577 HARDEN-001: every git call is `execFileFn('git', [args…])` with an args
+ * ARRAY and no shell. Branch and path values are attacker-influenceable and are
+ * never interpolated into a shell string.
+ */
+
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import { isWorktreeClean } from './worktree-cleanup.mjs';
+
+/**
+ * Strip a `<mainRepoName>-` prefix from a worktree directory basename to
+ * recover the session id, mirroring the auto-promoted layout
+ * `<basePath>/<repo-name>-<sessionId>/` used by `enterWorktree()`.
+ *
+ * Falls back to the full basename when the prefix does not match — a worktree
+ * created by hand still deserves a stable identifier in the report.
+ *
+ * @param {string} wtPath
+ * @param {string} mainRepoName
+ * @returns {string}
+ */
+function deriveSessionId(wtPath, mainRepoName) {
+  const basename = path.basename(wtPath);
+  if (mainRepoName && basename.startsWith(`${mainRepoName}-`)) {
+    return basename.slice(mainRepoName.length + 1);
+  }
+  return basename;
+}
+
+/**
+ * Sweep for worktree branches with 0 commits ahead of the base branch.
+ *
+ * @param {object} [opts]
+ * @param {string} opts.repoRoot - REQUIRED absolute path to the repo root.
+ * @param {string} [opts.mainCheckoutRoot] - Absolute path to the main checkout.
+ *   When omitted it is derived from the FIRST `worktree ` line of the porcelain
+ *   output. (`path.basename(repoRoot)` is explicitly NOT a correct derivation —
+ *   see the W3 T2 finding documented in ./worktree-cleanup.mjs.)
+ * @param {object} [opts.config] - Config. BOTH shapes are accepted, because the
+ *   two sibling probes take the FULL config and index their own block
+ *   internally while this one historically took the already-indexed block —
+ *   an asymmetry that made the natural copy-paste (`config: $CONFIG`) leave
+ *   `cfg.enabled` undefined:
+ *     • the FULL config — an object carrying a `worktree-orphans` key, which is
+ *       then indexed here; or
+ *     • the already-indexed BLOCK — `{ enabled, 'base-branch', mode }`.
+ *   OPT-IN: absent, `undefined`, `{}`, or any shape without `enabled: true`
+ *   returns `null` before a single git invocation.
+ * @param {Function} [opts.execFileFn] - Injectable execFileSync seam for tests.
+ *   Signature: (file: string, args: string[], options) => string. Also handed
+ *   to `isWorktreeClean()` so the dirty-check shares the same seam.
+ * @returns {null | {severity: 'warn', message: string,
+ *   candidates: Array<{wtPath: string, branch: string, sessionId: string, aheadCount: 0}>}}
+ *   `null` on bad input, when disabled, on any failure, or when nothing is
+ *   found. Otherwise ONE object whose `candidates` are proposals only —
+ *   nothing has been, or will be, removed by this module.
+ */
+export function checkWorktreeOrphans({ repoRoot, mainCheckoutRoot, config, execFileFn } = {}) {
+  // Silent no-op on bad input (consistent with the other Phase 4/4b banners).
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+  try {
+    const raw = config && typeof config === 'object' ? config : {};
+    // Accept the FULL config or the already-indexed block (see @param config).
+    const nested = raw['worktree-orphans'];
+    const cfg = nested && typeof nested === 'object' ? nested : raw;
+
+    // Config gate BEFORE any git invocation — a disabled sweep costs nothing.
+    // MUST be `!== true`, never `=== false`: `undefined !== false`, so the
+    // latter fails OPEN and runs git for a repo that never opted in —
+    // contradicting the parser's "never pays a single git invocation"
+    // guarantee, with a deletion prompt as the downstream consequence.
+    if (cfg.enabled !== true || cfg.mode === 'off') return null;
+
+    const exec = typeof execFileFn === 'function' ? execFileFn : execFileSync;
+
+    const rawBase = cfg['base-branch'];
+    const baseBranch = typeof rawBase === 'string' && rawBase.trim() ? rawBase.trim() : 'main';
+
+    // Anchor for `git worktree list`: the injected main checkout when provided,
+    // otherwise repoRoot (git reports the same worktree set from any member).
+    const listAnchor =
+      mainCheckoutRoot && typeof mainCheckoutRoot === 'string' ? mainCheckoutRoot : repoRoot;
+
+    // ── READ-ONLY GIT CALL 1 of 2 ───────────────────────────────────────────
+    let out;
+    try {
+      out = exec('git', ['-C', listAnchor, 'worktree', 'list', '--porcelain'], {
+        encoding: 'utf8',
+      });
+    } catch {
+      // Not a git repo, or git unavailable → conservative no-op.
+      return null;
+    }
+    if (typeof out !== 'string' || out.trim().length === 0) return null;
+
+    const entries = out.split('\n\n').filter(Boolean);
+
+    // Derive the canonical main checkout from the FIRST `worktree ` line.
+    let resolvedMain = mainCheckoutRoot;
+    if (!resolvedMain || typeof resolvedMain !== 'string') {
+      const firstLine = out.split('\n').find((l) => l.startsWith('worktree '));
+      if (!firstLine) return null;
+      resolvedMain = firstLine.slice('worktree '.length).trim();
+    }
+    if (!resolvedMain) return null;
+
+    const mainRepoName = path.basename(resolvedMain);
+    const candidates = [];
+
+    for (const entry of entries) {
+      const wtMatch = entry.match(/^worktree (.+)$/m);
+      if (!wtMatch) continue;
+      const wtPath = wtMatch[1].trim();
+      if (!wtPath) continue;
+
+      // The main checkout is never a candidate.
+      let isMain = false;
+      try {
+        isMain = path.resolve(wtPath) === path.resolve(resolvedMain);
+      } catch {
+        // Unresolvable path → conservative: treat as main (i.e. skip it).
+        isMain = true;
+      }
+      if (isMain) continue;
+
+      // Branch must be resolvable. A detached HEAD has no `branch` line →
+      // conservative: not a candidate.
+      const branchMatch = entry.match(/^branch refs\/heads\/(.+)$/m);
+      if (!branchMatch) continue;
+      const branch = branchMatch[1].trim();
+      if (!branch) continue;
+
+      // ── READ-ONLY GIT CALL: ahead-count ───────────────────────────────────
+      // `--end-of-options` is load-bearing, not decoration. Without it a
+      // base-branch shaped like an option (`--glob=refs/heads/*`) is parsed by
+      // rev-list as an OPTION rather than a revision: it exits 0 with `0`, so
+      // `Number.isFinite(0)` holds, no error path fires, and EVERY worktree is
+      // silently reported as a 0-ahead orphan. With it, the same value yields
+      // rc=128 ("option must come before non-option arguments") and lands in
+      // the conservative `continue` below. The config parser rejects such
+      // values too (_isSafeBaseBranch); this is the second layer, for callers
+      // that construct the config block by hand.
+      let countOut;
+      try {
+        countOut = exec(
+          'git',
+          ['-C', resolvedMain, 'rev-list', '--count', '--end-of-options', `${baseBranch}..${branch}`],
+          { encoding: 'utf8' },
+        );
+      } catch {
+        // Unknown base branch, missing ref, or any git error → conservative:
+        // not a candidate. A sibling worktree is unaffected by this failure.
+        continue;
+      }
+
+      if (typeof countOut !== 'string') continue;
+      const aheadCount = parseInt(countOut.trim(), 10);
+      // Unparseable output → conservative: not a candidate.
+      if (!Number.isFinite(aheadCount)) continue;
+      // Any work ahead of the base branch → definitively NOT an orphan.
+      if (aheadCount !== 0) continue;
+
+      // ── READ-ONLY GIT CALLS: uncommitted-work check ───────────────────────
+      // 0 commits ahead is NOT sufficient evidence of orphan-ness: a worktree
+      // can hold modified, staged, or untracked work that no commit-count ever
+      // sees. Reusing the Phase 4a sibling keeps both phases on one definition
+      // of "clean" (status --porcelain + ahead-scan, false on ANY git error —
+      // its documented conservative PSA-003 default, which maps exactly onto
+      // "not a candidate" here without needing a separate error branch).
+      //
+      // EXCLUDE rather than flag: the field is named `candidates` because the
+      // coordinator renders it as a deletion prompt, and a worktree holding
+      // live work is not a candidate for deletion review at all. A `dirty: true`
+      // flag would push that judgement into the prompt layer, where a
+      // mis-rendered label degrades straight into data loss.
+      if (!isWorktreeClean(wtPath, { execFileFn: exec })) continue;
+
+      candidates.push({
+        wtPath,
+        branch,
+        sessionId: deriveSessionId(wtPath, mainRepoName),
+        aheadCount: 0,
+      });
+    }
+
+    if (candidates.length === 0) return null;
+
+    const listed = candidates.map((c) => `${path.basename(c.wtPath)} (${c.branch})`).join(', ');
+    const subject =
+      candidates.length === 1
+        ? '1 worktree branch has 0 commits ahead of the base branch'
+        : `${candidates.length} worktree branches have 0 commits ahead of the base branch`;
+
+    // The trailing "nothing was removed" clause is MANDATORY — it is the
+    // operator-visible proof of the no-delete invariant above.
+    const message =
+      `⚠ worktree-orphans: ${subject} — ${listed} — ` +
+      `review via the cleanup prompt; nothing was removed.`;
+
+    return { severity: 'warn', message, candidates };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}

package/scripts/lib/session-schema/filters.mjs

@@ -0,0 +1,88 @@
+/**
+ * session-schema/filters.mjs — abandoned-aware session filters (#834).
+ *
+ * Pure functions. Stdlib only. No imports from siblings or parent barrel
+ * (matches the Option 1 submodule-isolation convention of the other
+ * session-schema/* modules).
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ *
+ * `.orchestrator/metrics/sessions.jsonl` holds two kinds of record:
+ *
+ *   REAL      — a session that actually ran waves and produced work.
+ *   ABANDONED — a phantom stub written by session-close-backfill from
+ *               events.jsonl for a session that ended without a real close
+ *               (0 waves, 0 agents, often seconds of runtime). The canonical
+ *               marker is `status: 'abandoned'`.
+ *
+ * Phantoms are legitimate DATA (they record that a start happened), but they
+ * are not legitimate SIGNAL. A consumer that takes "the last N lines" of the
+ * ledger as "the last N sessions" silently shrinks its own analysis window by
+ * however many stubs happen to sit in the tail. Observed in this repo at the
+ * time of writing: 20 of 70 records abandoned (28.6%), and 6 of the last 10
+ * LINES were phantoms — so a `slice(-10)` window carried only 4 real sessions.
+ *
+ * `scripts/lib/eval/session-resolve.mjs` already filtered correctly and is the
+ * behavioural reference; this module generalizes that single inline check so
+ * the other consumers stop hand-rolling it (or, more commonly, omitting it).
+ *
+ * ── WHAT THIS DELIBERATELY DOES NOT DO ─────────────────────────────────────
+ *
+ * Not every reader SHOULD filter. Collision-avoidance id scans, ledger-touch
+ * staleness banners, lifetime "sessions ever" counters, peer-overlap windows,
+ * schema migrations and dedup checks all legitimately need the phantoms. Use
+ * these helpers only where the window is meant to represent REAL WORK.
+ *
+ * Exports: isRealSession, filterRealSessions, tailRealSessions
+ */
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * True when a record represents REAL (non-phantom) work.
+ *
+ * Fail-open by design: anything that is not explicitly marked abandoned counts
+ * as real. Most historical records carry no `status` field at all, and those
+ * are genuine sessions — treating "absent" as "abandoned" would discard the
+ * majority of the ledger.
+ *
+ * @param {unknown} record — a parsed sessions.jsonl entry
+ * @returns {boolean}
+ */
+export function isRealSession(record) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) return false;
+  return record.status !== 'abandoned';
+}
+
+/**
+ * Filter parsed records to REAL sessions, preserving source order.
+ *
+ * @param {unknown} records — array of parsed sessions.jsonl entries
+ * @returns {object[]} — never null; a non-array input yields []
+ */
+export function filterRealSessions(records) {
+  if (!Array.isArray(records)) return [];
+  return records.filter(isRealSession);
+}
+
+/**
+ * Last N REAL sessions — the correct replacement for `arr.slice(-N)` on an
+ * unfiltered array.
+ *
+ * The semantic this fixes: `slice(-N)` means "last N LINES", which is only
+ * the same as "last N SESSIONS" when no phantom stubs sit in the tail.
+ *
+ * A non-positive or non-finite `n` yields [] rather than surprising the caller
+ * with JS's negative-index slice semantics.
+ *
+ * @param {unknown} records — array of parsed sessions.jsonl entries
+ * @param {number} n — how many REAL sessions to return from the tail
+ * @returns {object[]}
+ */
+export function tailRealSessions(records, n) {
+  const real = filterRealSessions(records);
+  if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) return [];
+  return real.slice(-Math.floor(n));
+}

package/scripts/lib/session-schema.mjs

@@ -69,3 +69,4 @@ export { ValidationError, validateSession } from './session-schema/validator.mjs
 export { normalizeSession } from './session-schema/normalizer.mjs';
 export { clampTimestampsMonotonic } from './session-schema/timestamps.mjs';
 export { aliasLegacyEndedAt } from './session-schema/aliases.mjs';
+export { isRealSession, filterRealSessions, tailRealSessions } from './session-schema/filters.mjs';