session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/learnings/select.mjs

@@ -52,6 +52,35 @@
  *     #1015 hardened for `.claude/rules/`. The primitives are imported, never
  *     re-implemented: a second copy is how this channel shipped raw beside the
  *     hardened one in the first place.
+ *   - `extractProvenance()` from `../validate/check-learning-provenance.mjs` and
+ *     `learningKeyOf()` from `./kebab.mjs` — the already-delivered filter below.
+ *     Both readers already exist; a second provenance parser here would be the
+ *     "same fact in two copies" defect this repo keeps paying for.
+ *
+ * ## Already-delivered filter (#1019)
+ *
+ * `/reconcile` converts a learning into a `.claude/rules/*.md` file, and Claude
+ * Code delivers every such file to every dispatched agent NATIVELY, in full.
+ * Measured first-person 2026-08-15 @fd73548+wave-2: a wave subagent's context
+ * carried all 29 of `.claude/rules/*.md` — `alwaysApply: false` and `globs:`
+ * notwithstanding, because `rule-loader.mjs` (the only code that understands
+ * that frontmatter) does not run on the delivery path
+ * (`docs/instruction-delivery.md` §1/§1.1). So a rule-derived learning that also
+ * enters this index arrives TWICE, and the second copy costs a slot in a
+ * 2000-char budget — displacing a learning the agent would otherwise never see.
+ *
+ * The filter therefore runs BEFORE the split caps, not after: dropping a
+ * duplicate after the Top-N cut would remove the line without freeing its slot,
+ * which is the whole harm. Two axes, mirroring the provenance checker's own
+ * `dangling` / `superseded` split: the rule's `learning-id` (exact record) and
+ * its `learning-key` (logical identity, stable across a re-minted UUID — the
+ * state any id backfill lands in). 13 of 29 rules carry provenance and all 13
+ * resolve by id today, so the key axis is currently inert by measurement, not
+ * by design.
+ *
+ * SILENT NO-OP is a hard requirement: no rules directory, no `.md` files, or no
+ * provenance block anywhere ⇒ empty sets ⇒ byte-identical output. A repo without
+ * `/reconcile` must never see FEWER learnings because this filter exists.
  *
  * NOT used: `filterByScope()` from `./filters.mjs`. Despite the name it filters
  * the PRIVACY enum `['local','private','public']` (schema.mjs), not file scope.
@@ -96,12 +125,17 @@
  *   5. Expired and sub-floor entries are never selected.
  */
 
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
 import { affinity } from './affinity.mjs';
 import {
   INSIGHT_MAX_BYTES,
   TITLE_MAX_BYTES,
   sanitizeProse,
 } from '../reconcile/sanitize.mjs';
+import { learningKeyOf } from './kebab.mjs';
+import { extractProvenance } from '../validate/check-learning-provenance.mjs';
 import { DECAY_DEFAULTS, effectiveScore, surfaceTopN } from './surface.mjs';
 
 // ---------------------------------------------------------------------------
@@ -178,9 +212,15 @@ export const DEFAULT_CONFIDENCE_FLOOR = 0.3;
  * @typedef {{entries: object[], selected: SelectedLearning[], lines: string[],
  *            text: string, chars: number, scopeMatched: number,
  *            globalCount: number, candidates: number, truncated: boolean,
- *            rejected: number}} Selection
+ *            rejected: number, deliveredFiltered: number}} Selection
  *   `rejected` counts records dropped by the untrusted-text guard — surfaced so
  *   a drop is observable in the injection event rather than silent.
+ *   `deliveredFiltered` counts records dropped because a `.claude/rules/*.md`
+ *   file already delivers them natively (#1019) — same reason, and it is the
+ *   only way to tell "the filter bit" from "the corpus has no such learning".
+ *
+ * @typedef {{ids: Set<string>, keys: Set<string>}} DeliveredProvenance
+ *   Learning ids and logical keys already delivered as `.claude/rules/*.md`.
  */
 
 // ---------------------------------------------------------------------------
@@ -214,6 +254,43 @@ function _isActive(entry, nowMs, confidenceFloor) {
   return true;
 }
 
+/**
+ * Normalize a caller-supplied delivered-provenance option into two Sets, or
+ * `null` when there is nothing to filter against.
+ *
+ * `null` (not empty Sets) is the no-filter signal so the hot loop can skip the
+ * per-entry `learningKeyOf()` call entirely — and so the SILENT NO-OP guarantee
+ * is one explicit branch rather than an emergent property of empty membership.
+ *
+ * @param {unknown} v `{ids, keys}` with Sets or arrays; anything else ⇒ `null`
+ * @returns {DeliveredProvenance|null}
+ */
+function _resolveDelivered(v) {
+  if (!_isRecord(v)) return null;
+  const toSet = (x) => (x instanceof Set ? x : Array.isArray(x) ? new Set(x) : new Set());
+  const ids = toSet(v.ids);
+  const keys = toSet(v.keys);
+  return ids.size === 0 && keys.size === 0 ? null : { ids, keys };
+}
+
+/**
+ * True when this learning already reaches the agent as a natively-delivered
+ * `.claude/rules/*.md` file.
+ *
+ * Id first (exact record), then the logical key — a rule whose `learning-id`
+ * was re-minted by a backfill still delivers the same content, which is the
+ * `superseded-learning-id` state `check-learning-provenance.mjs` names.
+ *
+ * @param {object} entry
+ * @param {DeliveredProvenance} delivered
+ * @returns {boolean}
+ */
+function _isDelivered(entry, delivered) {
+  if (typeof entry.id === 'string' && entry.id !== '' && delivered.ids.has(entry.id)) return true;
+  const key = learningKeyOf(entry); // total: a shape-foreign entry yields null
+  return key !== null && delivered.keys.has(key);
+}
+
 /** Epoch ms from a Date | number | undefined clock option. */
 function _resolveNowMs(now) {
   if (now instanceof Date) return now.getTime();
@@ -274,9 +351,60 @@ export function emptySelection() {
     candidates: 0,
     truncated: false,
     rejected: 0,
+    deliveredFiltered: 0,
   };
 }
 
+/**
+ * Read the provenance pointers of every `.claude/rules/*.md` — the set of
+ * learnings the agent already receives natively (#1019).
+ *
+ * Reuses `extractProvenance()` rather than re-deriving the block format. Total
+ * by construction: an absent, unreadable or provenance-free directory yields
+ * empty sets, which {@link selectLearnings} reads as "no filter" (SILENT NO-OP).
+ *
+ * Read discipline mirrors `check-learning-provenance.mjs`: `readFileSync`, never
+ * a `grep` spawn — one NUL byte makes a text file invisible to a grep-based
+ * audit, and a silently-skipped rule file reads exactly like a rule with no
+ * provenance.
+ *
+ * Ceiling: one synchronous read per rule file, linear in the corpus (29 files /
+ * ~170 KB today). Revisit — cache per process or read async — if
+ * `.claude/rules/` passes a few hundred files.
+ *
+ * @param {string} rulesDir absolute path to the `.claude/rules` directory
+ * @returns {DeliveredProvenance}
+ */
+export function readDeliveredProvenance(rulesDir) {
+  /** @type {Set<string>} */
+  const ids = new Set();
+  /** @type {Set<string>} */
+  const keys = new Set();
+  if (typeof rulesDir !== 'string' || rulesDir.trim() === '') return { ids, keys };
+
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(rulesDir);
+  } catch {
+    return { ids, keys }; // no rules directory ⇒ nothing is natively delivered
+  }
+
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    let body;
+    try {
+      body = readFileSync(join(rulesDir, name), 'utf8');
+    } catch {
+      continue; // one unreadable rule must not cost the whole census
+    }
+    const { id, key } = extractProvenance(body);
+    if (id) ids.add(id);
+    if (key) keys.add(key);
+  }
+  return { ids, keys };
+}
+
 /**
  * Truncate to at most `maxUnits` UTF-16 code units, cutting on a CODE-POINT
  * boundary.
@@ -413,6 +541,9 @@ export function scoreLearning(entry, scope, opts = {}) {
  * @param {Date|number} [opts.now] — injectable clock
  * @param {object} [opts.decay] — #670 decay tuning, forwarded to effectiveScore
  * @param {object} [opts.affinityOpts] — forwarded to affinity()
+ * @param {DeliveredProvenance} [opts.delivered] — learnings already delivered
+ *   natively as `.claude/rules/*.md` (#1019); omitted/empty ⇒ no filtering, and
+ *   the selection is byte-identical to the pre-filter one
  * @returns {Selection}
  */
 export function selectLearnings(entries, scope, opts = {}) {
@@ -433,6 +564,7 @@ export function selectLearnings(entries, scope, opts = {}) {
         ? o.confidenceFloor
         : DEFAULT_CONFIDENCE_FLOOR;
     const nowMs = _resolveNowMs(o.now);
+    const delivered = _resolveDelivered(o.delivered);
     const scoreOpts = { now: nowMs, decay: o.decay, affinityOpts: o.affinityOpts };
 
     /** @type {SelectedLearning[]} */
@@ -441,12 +573,23 @@ export function selectLearnings(entries, scope, opts = {}) {
     const global = [];
     let candidates = 0;
     let rejected = 0;
+    let deliveredFiltered = 0;
 
     for (const entry of entries) {
       if (!_isRecord(entry)) continue;
       if (!_isActive(entry, nowMs, confidenceFloor)) continue;
       candidates++;
 
+      // #1019 — BEFORE the split caps below, never after. This entry already
+      // reaches the agent in full as a `.claude/rules/*.md` file; dropping it
+      // here frees its slot for a learning the agent would otherwise never see,
+      // whereas dropping it after the Top-N cut would only shorten the index.
+      // `candidates` still counts it: the pool it was drawn from is unchanged.
+      if (delivered !== null && _isDelivered(entry, delivered)) {
+        deliveredFiltered++;
+        continue;
+      }
+
       const s = scoreLearning(entry, scope, scoreOpts);
       // Fail CLOSED per entry: a record whose text forges the delivery wrapper
       // is dropped, not neutralised in place — with 100 candidates competing for
@@ -510,6 +653,7 @@ export function selectLearnings(entries, scope, opts = {}) {
       candidates,
       truncated,
       rejected,
+      deliveredFiltered,
     };
   } catch {
     // Contract point 1 — a ranking primitive on the dispatch hot path must
@@ -525,7 +669,11 @@ export function selectLearnings(entries, scope, opts = {}) {
  * @param {string} filePath — absolute path to learnings.jsonl
  * @param {AgentScope} scope
  * @param {object} [opts] — everything {@link selectLearnings} accepts, plus
- *   `poolSize` (how many active entries to pull before ranking).
+ *   `poolSize` (how many active entries to pull before ranking) and `rulesDir`
+ *   (absolute `.claude/rules` path; read via {@link readDeliveredProvenance} into
+ *   the `delivered` filter). `rulesDir` is EXPLICIT rather than derived from
+ *   `filePath`: guessing a repo root from a metrics path is the hand-maintained
+ *   fact this repo keeps getting wrong. Omit it and nothing is filtered.
  * @returns {Promise<Selection>} `emptySelection()` on a missing/unreadable file
  */
 export async function selectLearningsFromFile(filePath, scope, opts = {}) {
@@ -538,12 +686,18 @@ export async function selectLearningsFromFile(filePath, scope, opts = {}) {
         ? o.confidenceFloor
         : DEFAULT_CONFIDENCE_FLOOR;
 
+    const delivered = _isRecord(o.delivered)
+      ? o.delivered
+      : typeof o.rulesDir === 'string' && o.rulesDir.trim() !== ''
+        ? readDeliveredProvenance(o.rulesDir)
+        : undefined;
+
     const entries = await surfaceTopN(filePath, poolSize, {
       now: nowMs,
       confidenceFloor,
       decay: o.decay,
     });
-    return selectLearnings(entries, scope, { ...o, now: nowMs, confidenceFloor });
+    return selectLearnings(entries, scope, { ...o, now: nowMs, confidenceFloor, delivered });
   } catch {
     return emptySelection();
   }

package/scripts/lib/memory-cleanup-stamp.mjs

@@ -1,20 +1,41 @@
 /**
- * memory-cleanup-stamp.mjs — Pure helper: stamp `memory_cleanup_at` on a
- * session record when `/memory-cleanup` ran this session.
+ * memory-cleanup-stamp.mjs — stamp `memory_cleanup_at` on a session record when
+ * `/memory-cleanup` ran this session, and DERIVE that fact from the event log
+ * instead of from coordinator recall.
  *
  * Issue #699 fix: a healthy no-op run of `/memory-cleanup` previously left
  * `memory_cleanup_at` unstamped, so `auto-dream.mjs` `readDreamSignals`
  * never advanced `lastCleanupAt` and `shouldDispatchAutoDream` kept firing a
- * false nudge. This helper stamps the field unconditionally whenever the
- * cleanup ran — including a healthy no-op where no memory files were mutated.
+ * false nudge. `stampMemoryCleanup()` stamps the field unconditionally whenever
+ * the cleanup ran — including a healthy no-op where no memory files were mutated.
+ *
+ * #699 follow-up (Disziplin statt Mechanik): the `ranCleanup` boolean itself used
+ * to come from the coordinator-LLM remembering a prose step at session-end. It
+ * measurably failed — a `/memory-cleanup` ran on 2026-08-14 and all three session
+ * records of that day read `memory_cleanup_at: null`, so the session-start banner
+ * reported "29 days ago" while the operator's own notes said 3. Since then
+ * `/memory-cleanup` emits `orchestrator.memory.cleanup_completed` and
+ * `deriveMemoryCleanupSignal()` reads that event back out of
+ * `.orchestrator/metrics/events.jsonl`, which is what `scripts/emit-session.mjs`
+ * calls at write time. Nothing depends on recall any more.
  *
  * Design constraints:
- *   - Pure function — no I/O, no side-effects.
- *   - No-throw — invalid inputs return the record unchanged (defensive).
- *   - Testable seam — the Quality wave (Q2) unit-tests this function directly.
- *   - No external deps — Node 20+ stdlib only (none needed here).
+ *   - `stampMemoryCleanup()` stays pure — no I/O, no side-effects.
+ *   - No-throw — invalid inputs / unreadable-or-corrupt event log return the
+ *     "no cleanup" answer rather than blocking a session close.
+ *   - Testable seam — both functions are unit-tested directly.
+ *   - No external deps — Node stdlib only.
  */
 
+import { readFileSync } from 'node:fs';
+
+/**
+ * Event `/memory-cleanup` emits when a run completes (any mode, any outcome —
+ * including a healthy no-op). Emitted via `scripts/emit-event.mjs` → the
+ * canonical `emitEvent()` path; see `skills/memory-cleanup/SKILL.md` § Output.
+ */
+export const MEMORY_CLEANUP_EVENT = 'orchestrator.memory.cleanup_completed';
+
 /**
  * Stamp `memory_cleanup_at` on a session record when `/memory-cleanup` ran.
  *
@@ -54,3 +75,106 @@ export function stampMemoryCleanup(record, { ranCleanup, completedAt } = {}) {
   // Return a shallow clone with the stamp applied — never mutate the input.
   return { ...record, memory_cleanup_at: completedAt };
 }
+
+/**
+ * Derive "did `/memory-cleanup` run in THIS session?" from the event log.
+ *
+ * Reads `eventsFile` and looks for `orchestrator.memory.cleanup_completed`
+ * records that fall inside the session's own `[startedAt, completedAt]` window.
+ * This is the mechanical replacement for the coordinator-supplied boolean.
+ *
+ * Matching rule (two clauses, both mechanical):
+ *   1. the event's `timestamp` lies within `[startedAt, completedAt]` inclusive;
+ *   2. IF the event carries a non-empty `semantic_session_id`, it must equal
+ *      `sessionId` (sessions.jsonl `session_id` is the SEMANTIC id — the UUID
+ *      `session_id` some events carry lives in a different id space and is
+ *      deliberately NOT used for matching).
+ *
+ * Named ceiling (deliberate simplification): an event with NO attribution is
+ * claimed on the window alone, so two parallel sessions in one repo with
+ * overlapping windows both derive `ranCleanup: true`. The consequence is a
+ * marginally generous cadence marker on the peer's record — never a MISSED
+ * cleanup, which is the failure this whole path exists to prevent. Revisit
+ * trigger: if per-session cleanup accounting is ever needed, attach
+ * `semantic_session_id` to the emitted event and clause 2 makes it exact.
+ * Scan cost is a single linear pass over `events.jsonl` (~23k lines,
+ * size-rotated at SessionStart by `events-rotation.mjs`) — revisit if rotation
+ * is ever removed.
+ *
+ * No-throw: a missing, unreadable, or partly-corrupt event log yields
+ * `{ ranCleanup: false, ... }`. A session close must never fail because
+ * telemetry is damaged.
+ *
+ * @param {object} opts
+ * @param {string} opts.eventsFile  Absolute or CWD-relative path to events.jsonl.
+ * @param {string} [opts.sessionId] The record's `session_id` (semantic form).
+ * @param {string} opts.startedAt   Session `started_at` (ISO-8601).
+ * @param {string} opts.completedAt Session `completed_at` (ISO-8601).
+ * @returns {{ranCleanup: boolean, at: string|null, matches: number}}
+ *   `at` is the LATEST matching event timestamp (null when none matched);
+ *   `matches` is how many events matched (a run can emit more than one).
+ */
+export function deriveMemoryCleanupSignal({
+  eventsFile,
+  sessionId,
+  startedAt,
+  completedAt,
+} = {}) {
+  const none = { ranCleanup: false, at: null, matches: 0 };
+
+  if (typeof eventsFile !== 'string' || eventsFile.length === 0) return none;
+
+  const startMs = Date.parse(startedAt);
+  const endMs = Date.parse(completedAt);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs) {
+    return none;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(eventsFile, 'utf8');
+  } catch {
+    // Missing / unreadable event log — no signal, never an error.
+    return none;
+  }
+
+  const wantSession = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  let matches = 0;
+  let latestMs = -Infinity;
+  let latestTs = null;
+
+  for (const line of raw.split('\n')) {
+    // Cheap substring prefilter before the JSON.parse cost.
+    if (line.length === 0 || !line.includes(MEMORY_CLEANUP_EVENT)) continue;
+
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // corrupt line — skip, best-effort reader
+    }
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) continue;
+    if (rec.event !== MEMORY_CLEANUP_EVENT) continue;
+
+    const tsMs = Date.parse(rec.timestamp);
+    if (!Number.isFinite(tsMs) || tsMs < startMs || tsMs > endMs) continue;
+
+    const semantic = rec.semantic_session_id;
+    if (
+      wantSession !== null &&
+      typeof semantic === 'string' &&
+      semantic.length > 0 &&
+      semantic !== wantSession
+    ) {
+      continue; // attributed to a DIFFERENT session — not ours
+    }
+
+    matches += 1;
+    if (tsMs > latestMs) {
+      latestMs = tsMs;
+      latestTs = rec.timestamp;
+    }
+  }
+
+  return { ranCleanup: matches > 0, at: latestTs, matches };
+}

package/scripts/lib/mirror-issues-banner.mjs

@@ -0,0 +1,266 @@
+/**
+ * mirror-issues-banner.mjs — the mirror blind spot (#1022 follow-up)
+ *
+ * `skills/gitlab-ops/SKILL.md` § VCS Auto-Detection picks EXACTLY ONE platform
+ * via if/else. In a repo whose `origin` is GitLab and whose `github` remote is
+ * a public mirror, no code path ever reads issues from the mirror — so issues
+ * filed by external reporters against the mirror are structurally invisible to
+ * every session. This probe is the counter-measure: it asks the OTHER side.
+ *
+ * The VCS family is therefore HARD-PINNED to `'github'`, never auto-detected.
+ * Auto-detection is the defect this module exists to compensate for; deriving
+ * the family here would reproduce it.
+ *
+ * No new Session Config key by design. `resolveRepoSpec({ vcs:'github' })`
+ * derives the `gh -R` spec straight from `git remote` (its `REMOTE_PREFERENCE`
+ * tries the remote literally named `github` first, and its `WRONG_FAMILY_HOST`
+ * guard discards a cross-family match). That makes the probe SELF-DISABLING: a
+ * repo without a GitHub mirror resolves to `undefined` → `null` → no spawn, no
+ * network call. A config key would be a second SSOT drifting against
+ * `git remote`.
+ *
+ * Plain-JS — no Zod dependency. Never throws.
+ *
+ * Mirrors the Phase 4 banner contract documented in
+ * `scripts/lib/loop-readiness-banner.mjs:23-26`: a single `checkXxx()` entry
+ * point returning `null` or `{ severity, message, ... }`.
+ *
+ * Cross-references:
+ *  - `scripts/lib/ci-status-banner.mjs` — the sibling project-facing probe
+ *    (whose `null`-collapsing this module deliberately does NOT copy, see below).
+ *  - `scripts/lib/reconcile-nudge-banner.mjs:183-186` — the same
+ *    absence-preserving discipline applied to a count.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ */
+
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveRepoSpec as _resolveRepoSpec } from './vcs-repo-spec.mjs';
+
+const execFileAsync = promisify(_execFile);
+
+/** Default timeout in ms for the `gh` invocation. Mirrors `ci-status-banner.mjs:20`. */
+export const DEFAULT_TIMEOUT_MS = 8000;
+
+/** Default `--limit` passed to `gh issue list`. */
+export const DEFAULT_LIMIT = 20;
+
+/**
+ * The VCS family this probe queries. Deliberately a module constant, not a
+ * parameter: querying the auto-detected platform would make this probe a no-op
+ * in exactly the repos it exists for.
+ */
+const MIRROR_VCS = 'github';
+
+/** How many issue numbers the banner message names before summarising. */
+const MESSAGE_ISSUE_CAP = 5;
+
+/**
+ * Closed set of `degraded` reasons. A degraded result means "the mirror was
+ * NOT successfully read" — never "the mirror is clean".
+ *
+ * `query-failed` is the residual bucket for a `gh` that ran and exited
+ * non-zero for a reason that is neither missing-CLI, timeout, nor auth
+ * (network down, repo renamed, rate limit). It is a deliberate fifth member
+ * beyond the four originally specified: folding those into `parse-error`
+ * would mislabel a network failure as malformed output, reintroducing the
+ * dishonest-state class this module was built to remove.
+ *
+ * @type {readonly ['cli-missing','timeout','parse-error','auth-error','query-failed']}
+ */
+export const DEGRADED_REASONS = Object.freeze([
+  'cli-missing',
+  'timeout',
+  'parse-error',
+  'auth-error',
+  'query-failed',
+]);
+
+/**
+ * Run `cmd` with a timeout race. Mirrors `ci-status-banner.mjs:30-38`.
+ *
+ * The timer is cleared and `unref`ed so a fast success does not hold the event
+ * loop open for the full budget (`.claude/rules/testing.md` § Async & Timeout
+ * Patterns). KNOWN LIMIT, inherited from the shared pattern and NOT fixed
+ * here: losing the race abandons the `gh` child process rather than killing
+ * it — a hung `gh` is left orphaned.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, timeoutMs?: number, execFile?: Function }} [opts]
+ * @returns {Promise<{ stdout?: string, stderr?: string }>}
+ */
+async function execWithTimeout(cmd, args, opts = {}) {
+  const { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, execFile = execFileAsync } = opts;
+  /** @type {NodeJS.Timeout | undefined} */
+  let timer;
+  try {
+    return await Promise.race([
+      execFile(cmd, args, { cwd, env: process.env }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Map a failed `gh` invocation onto a {@link DEGRADED_REASONS} member.
+ *
+ * @param {unknown} err
+ * @returns {'cli-missing'|'timeout'|'auth-error'|'query-failed'}
+ */
+function classifyFailure(err) {
+  const code = err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  if (code === 'ENOENT') return 'cli-missing';
+
+  const message = err instanceof Error ? err.message : String(err ?? '');
+  if (message === 'timeout') return 'timeout';
+
+  const stderr = err && typeof err === 'object' ? String(/** @type {any} */ (err).stderr ?? '') : '';
+  const haystack = `${message}\n${stderr}`.toLowerCase();
+  if (
+    haystack.includes('gh auth login') ||
+    haystack.includes('not logged in') ||
+    haystack.includes('authentication') ||
+    haystack.includes('http 401') ||
+    haystack.includes('http 403')
+  ) {
+    return 'auth-error';
+  }
+  return 'query-failed';
+}
+
+/**
+ * Build the degraded result. Distinct from `null` on purpose: `null` in the
+ * banner contract reads as "all clear", which a failed query has NOT
+ * established.
+ *
+ * @param {string} repoSpec
+ * @param {string} reason
+ * @returns {{ severity: 'warn', message: string, repoSpec: string, degraded: string }}
+ */
+function degradedResult(repoSpec, reason) {
+  return {
+    severity: 'warn',
+    message:
+      `⚠ mirror-issues: Mirror ${repoSpec} konnte nicht abgefragt werden (${reason}) ` +
+      `— Zustand unbekannt, nicht "sauber".`,
+    repoSpec,
+    degraded: reason,
+  };
+}
+
+/**
+ * Render the found-issues banner message, naming issue numbers up to
+ * {@link MESSAGE_ISSUE_CAP} and summarising any remainder.
+ *
+ * @param {string} repoSpec
+ * @param {Array<{ number: number, title: string }>} issues
+ * @returns {string}
+ */
+function formatMessage(repoSpec, issues) {
+  const named = issues.slice(0, MESSAGE_ISSUE_CAP).map((i) => `#${i.number}`).join(', ');
+  const rest = issues.length - Math.min(issues.length, MESSAGE_ISSUE_CAP);
+  const tail = rest > 0 ? ` (+${rest} weitere)` : '';
+  const plural = issues.length === 1 ? 'offenes Issue' : 'offene Issues';
+  return (
+    `⚠ mirror-issues: ${issues.length} ${plural} im Mirror ${repoSpec}: ${named}${tail} ` +
+    `— kein anderer Codepfad dieser Session liest sie.`
+  );
+}
+
+/**
+ * Check the GitHub mirror for open issues and produce a session-start banner.
+ *
+ * Return contract — three states, not two:
+ *  - `null` when the mirror remote does not resolve (repo genuinely has no
+ *    mirror; NO subprocess is spawned) or when the query SUCCEEDED and found
+ *    zero open issues (measured and clean).
+ *  - `{ severity:'warn', message, count, repoSpec, issues }` when N > 0.
+ *  - `{ severity:'warn', message, repoSpec, degraded }` when the query did not
+ *    succeed. `degraded` is present ONLY in this case, so its absence proves
+ *    the mirror was actually read — the distinction `ci-status-banner.mjs`
+ *    collapses (CLI-missing, bad JSON and no-remote all return `null` there,
+ *    which is why the mirror gap went unseen for months).
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string, timeoutMs?: number, limit?: number }} [opts]
+ * @param {{ execFile?: Function, resolveRepoSpec?: Function }} [deps] DI for tests only.
+ * @returns {Promise<null | { severity: 'warn', message: string, repoSpec: string, count?: number, issues?: Array<{number:number,title:string}>, degraded?: string }>}
+ */
+export async function checkMirrorIssues(opts = {}, deps = {}) {
+  try {
+    const { repoRoot, timeoutMs = DEFAULT_TIMEOUT_MS, limit = DEFAULT_LIMIT } = opts ?? {};
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const { execFile = execFileAsync, resolveRepoSpec = _resolveRepoSpec } = deps ?? {};
+
+    // Step 1 — resolve the mirror spec from `git remote`. `undefined` here is
+    // the self-disabling path: no mirror, no spawn, no network cost.
+    let repoSpec;
+    try {
+      repoSpec = resolveRepoSpec({ repoRoot, vcs: MIRROR_VCS });
+    } catch {
+      return null;
+    }
+    if (!repoSpec || typeof repoSpec !== 'string') return null;
+
+    // Step 2 — query. Args array, never a shell string.
+    let stdout;
+    try {
+      const result = await execWithTimeout(
+        'gh',
+        [
+          'issue',
+          'list',
+          '-R',
+          repoSpec,
+          '--state',
+          'open',
+          '--limit',
+          String(limit),
+          '--json',
+          'number,title',
+        ],
+        { cwd: repoRoot, timeoutMs, execFile },
+      );
+      stdout = String(result?.stdout ?? '');
+    } catch (err) {
+      return degradedResult(repoSpec, classifyFailure(err));
+    }
+
+    // Step 3 — parse. A CLI that exited 0 with unusable output is degraded,
+    // NOT clean.
+    let issues;
+    try {
+      const parsed = JSON.parse(stdout);
+      if (!Array.isArray(parsed)) return degradedResult(repoSpec, 'parse-error');
+      issues = parsed
+        .filter((entry) => entry && typeof entry === 'object' && Number.isFinite(Number(entry.number)))
+        .map((entry) => ({ number: Number(entry.number), title: String(entry.title ?? '') }));
+    } catch {
+      return degradedResult(repoSpec, 'parse-error');
+    }
+
+    // Step 4 — measured and clean.
+    if (issues.length === 0) return null;
+
+    return {
+      severity: 'warn',
+      message: formatMessage(repoSpec, issues),
+      count: issues.length,
+      repoSpec,
+      issues,
+    };
+  } catch {
+    // Defensive catch-all: a banner must never break session-start.
+    return null;
+  }
+}
+
+export default checkMirrorIssues;