session-orchestrator 3.16.0

package/scripts/lib/reconcile/writer.mjs

@@ -0,0 +1,293 @@
+/**
+ * writer.mjs — FA3 writer seam for the Reconciliation Engine (Epic #693, issue #696).
+ *
+ * Persists APPROVED reconciliation rule proposals to `.claude/rules/` AFTER
+ * operator approval. This is the one and only module that writes `.claude/rules/`
+ * on behalf of the engine — the FA2 engine/renderer NEVER touch the filesystem
+ * for rule files.
+ *
+ * Responsibilities:
+ *  - Acquire a per-write file lock (`.orchestrator/rules.lock`) to serialise
+ *    concurrent writers — mirrors PSA-005 (withStateMdLock) pattern.
+ *  - For each approved proposal: path-safety guard → mkdirSync → atomic tmp+rename write.
+ *  - For each rejected proposal: JSONL-append to `.orchestrator/reconcile.rejected.log`.
+ *  - Never throws — all failures are collected into errors[] and returned.
+ *
+ * Path-safety:
+ *  - `validatePathInsideProject(item.path, repoRoot, {canonicalizeRoot:true})` is
+ *    the primary guard (two-phase lexical + realpath, CWE-22 defence).
+ *  - Additional assertion: resolved path must be inside `<repoRoot>/.claude/rules/`.
+ *  - Both guards must pass; failure skips the record and pushes an error string.
+ *
+ * Atomic write strategy (rule files):
+ *  - Write content to `<target>.XXXXXXXX.tmp` via `writeFileSync`, then
+ *    `renameSync` over the final path. Same-filesystem rename is atomic on POSIX,
+ *    so the rule file is never partially visible. Mirrors idempotency.mjs pattern.
+ *
+ * JSONL append strategy (rejected log):
+ *  - `appendFileSync` for the rejected log — each record is a self-contained line,
+ *    and POSIX append (O_APPEND) is atomic for writes < PIPE_BUF (4096 bytes),
+ *    which every JSONL record satisfies. Mirrors memory-proposals/sink.mjs pattern.
+ *
+ * DI-friendly: accepts repoRoot as a parameter; no global cwd assumptions.
+ *
+ * Plain Node ESM, no external deps — Node 20+ stdlib + sibling scripts/lib only.
+ *
+ * Part of Epic #693 → issue #696 (FA3 Advisory Delivery).
+ *
+ * @module reconcile/writer
+ */
+
+import { mkdirSync, writeFileSync, renameSync, appendFileSync, realpathSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+
+import { withFileLock } from '../file-lock.mjs';
+import { validatePathInsideProject } from '../path-utils.mjs';
+
+// ---------------------------------------------------------------------------
+// Path constants (relative to repoRoot)
+// ---------------------------------------------------------------------------
+
+/** Lock file that serialises concurrent rule-write operations. */
+const RULES_LOCK_REL = path.join('.orchestrator', 'rules.lock');
+
+/** Directory where auto-generated rule files are written (repo-relative). */
+const RULES_DIR_REL = path.join('.claude', 'rules');
+
+/** Rejected-proposals log for rules declined by the operator (repo-relative). */
+const REJECTED_LOG_REL = path.join('.orchestrator', 'reconcile.rejected.log');
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute rules directory for the given repoRoot. Used both for
+ * the per-proposal assertion and for mkdirSync.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function rulesAbsDir(repoRoot) {
+  return path.resolve(repoRoot, RULES_DIR_REL);
+}
+
+/**
+ * Write `content` to `destPath` atomically via tmp+rename.
+ *
+ * Uses a random 8-hex-char suffix for the tmp file to avoid collisions when
+ * multiple proposals write to the same directory concurrently (defensive;
+ * under the lock this should not happen, but the pattern is cheap).
+ *
+ * Throws on filesystem errors — callers must catch.
+ *
+ * @param {string} destPath - absolute path of the target rule file.
+ * @param {string} content  - UTF-8 text content to write.
+ */
+function writeTextAtomic(destPath, content) {
+  const dir = path.dirname(destPath);
+  mkdirSync(dir, { recursive: true });
+  const suffix = randomBytes(4).toString('hex');
+  const tmpPath = `${destPath}.${suffix}.tmp`;
+  writeFileSync(tmpPath, content, 'utf8');
+  renameSync(tmpPath, destPath);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} WriterApprovedItem
+ * @property {string} slug     - kebab-case slug (from renderer.mjs / engine.mjs).
+ * @property {string} path     - repo-relative rule path (`.claude/rules/<slug>.md`).
+ * @property {string} content  - full rendered markdown content.
+ * @property {string} [learningKey]
+ * @property {number} [confidence]
+ * @property {string} [candidateId]
+ * @property {string} [status]
+ */
+
+/**
+ * @typedef {Object} WriterRejectedItem
+ * @property {string} [learningKey]
+ * @property {string} [type]
+ * @property {string} [reason]
+ * @property {string} [status]
+ */
+
+/**
+ * @typedef {Object} WriteApprovedRulesResult
+ * @property {number}   written   - number of rule files successfully written.
+ * @property {number}   archived  - number of rejected records appended to the log.
+ * @property {string[]} errors    - per-item error strings (never fatal).
+ */
+
+/**
+ * Persist approved reconciliation rule proposals to `.claude/rules/` and
+ * archive rejected proposals to the rejected log.
+ *
+ * NEVER throws — all per-item failures are collected into `errors[]`.
+ *
+ * @param {Object}                opts
+ * @param {WriterApprovedItem[]}  opts.approved   - proposals approved by the operator.
+ * @param {WriterRejectedItem[]}  [opts.rejected]  - proposals declined by the operator.
+ * @param {string}                opts.repoRoot   - absolute repo root path.
+ * @param {string}                [opts.sessionId] - current session id (informational; unused in v1).
+ * @returns {Promise<WriteApprovedRulesResult>}
+ */
+export async function writeApprovedRules({ approved, rejected = [], repoRoot, sessionId: _sessionId }) {
+  // Defensive: coerce inputs
+  const approvedItems = Array.isArray(approved) ? approved : [];
+  const rejectedItems = Array.isArray(rejected) ? rejected : [];
+
+  if (approvedItems.length === 0 && rejectedItems.length === 0) {
+    return { written: 0, archived: 0, errors: [] };
+  }
+
+  const lockPath = path.join(repoRoot, RULES_LOCK_REL);
+
+  // Ensure .orchestrator dir exists so lock acquisition can create the lock file.
+  try {
+    mkdirSync(path.dirname(lockPath), { recursive: true });
+  } catch {
+    // Non-fatal: withFileLock will surface the fs-error if the lock cannot be created.
+  }
+
+  // Acquire the rules lock — serialises concurrent rule writes.
+  const lockResult = await withFileLock(
+    lockPath,
+    async () => {
+      /** @type {string[]} */
+      const errors = [];
+      let written = 0;
+      let archived = 0;
+
+      const rulesDir = rulesAbsDir(repoRoot);
+
+      // Parent-directory symlink hardening (#697 security follow-up): if
+      // `.claude/rules/` is itself a pre-planted symlink to a directory outside
+      // the repo, a lexically-safe leaf path would still be written through it.
+      // Resolve the directory's realpath once and refuse all writes if it
+      // escapes the canonical repo root. Requires local FS write access to
+      // exploit (below the VCS trust boundary) but the guard is one cheap call.
+      let rulesDirSafe = true;
+      try {
+        mkdirSync(rulesDir, { recursive: true });
+        let canonRoot = repoRoot;
+        try { canonRoot = realpathSync(repoRoot); } catch { /* fall back to lexical */ }
+        const expectedRulesDir = path.resolve(canonRoot, RULES_DIR_REL);
+        const realRulesDir = realpathSync(rulesDir);
+        if (realRulesDir !== expectedRulesDir && !realRulesDir.startsWith(expectedRulesDir + path.sep)) {
+          errors.push('path-confinement: .claude/rules/ resolves outside the repo (symlinked dir) — all approved writes skipped');
+          rulesDirSafe = false;
+        }
+      } catch { /* mkdir/realpath failure — per-item writes will surface errors normally */ }
+
+      // ── Step 1: write approved rule files ──────────────────────────────────
+      for (const item of approvedItems) {
+        if (!rulesDirSafe) break;
+        // Guard: item must have a path string
+        if (!item || typeof item.path !== 'string' || item.path.length === 0) {
+          errors.push(`approved item missing path: ${JSON.stringify(item)}`);
+          continue;
+        }
+
+        // Primary path-safety guard (two-phase lexical + realpath, CWE-22 defence)
+        const pathResult = validatePathInsideProject(item.path, repoRoot, { canonicalizeRoot: true });
+        if (!pathResult.ok) {
+          errors.push(`path-safety (${pathResult.reason}): "${item.path}" — skipped`);
+          continue;
+        }
+
+        // Resolve the absolute write target from the validated lexical path
+        const absPath = pathResult.realPath ?? pathResult.lexicalPath;
+
+        // Defense-in-depth: assert the resolved path is inside .claude/rules/.
+        // Canonicalize repoRoot the same way validatePathInsideProject does
+        // (opts.canonicalizeRoot:true) so the prefix check is consistent on
+        // platforms where os.tmpdir() has a symlink (e.g. macOS /var → /private/var).
+        let canonRoot = repoRoot;
+        try { canonRoot = realpathSync(repoRoot); } catch { /* ENOENT/EACCES: fall back to lexical */ }
+        const resolvedRulesDir = path.resolve(canonRoot, RULES_DIR_REL);
+        if (!absPath.startsWith(resolvedRulesDir + path.sep) && absPath !== resolvedRulesDir) {
+          errors.push(`path-confinement: "${item.path}" resolves outside .claude/rules/ — skipped`);
+          continue;
+        }
+
+        // Guard: content must be a string
+        if (typeof item.content !== 'string') {
+          errors.push(`approved item "${item.path}" has non-string content — skipped`);
+          continue;
+        }
+
+        // Ensure .claude/rules/ exists and write atomically
+        try {
+          mkdirSync(rulesDir, { recursive: true });
+          writeTextAtomic(absPath, item.content);
+          written++;
+        } catch (err) {
+          const msg = err && err.message ? err.message : String(err);
+          errors.push(`write failed "${item.path}": ${msg}`);
+        }
+      }
+
+      // ── Step 2: archive rejected proposals to the rejected log ─────────────
+      if (rejectedItems.length > 0) {
+        const rejectedLogRelPath = REJECTED_LOG_REL;
+        const logResult = validatePathInsideProject(rejectedLogRelPath, repoRoot, { canonicalizeRoot: true });
+
+        if (!logResult.ok) {
+          errors.push(`path-safety (rejected log): ${logResult.reason} (${rejectedLogRelPath})`);
+        } else {
+          const rejectedLogPath = logResult.realPath ?? logResult.lexicalPath;
+
+          // Ensure parent directory exists
+          try {
+            mkdirSync(path.dirname(rejectedLogPath), { recursive: true });
+          } catch (err) {
+            const msg = err && err.message ? err.message : String(err);
+            errors.push(`mkdir failed (rejected log): ${msg}`);
+          }
+
+          const rejectedAt = new Date().toISOString();
+
+          for (const item of rejectedItems) {
+            try {
+              const archiveRecord = {
+                ...item,
+                _rejected_reason: (item && typeof item.reason === 'string' && item.reason !== '')
+                  ? item.reason
+                  : 'user-declined',
+                _rejected_at: rejectedAt,
+              };
+              const line = JSON.stringify(archiveRecord) + '\n';
+              appendFileSync(rejectedLogPath, line, 'utf8');
+              archived++;
+            } catch (err) {
+              const msg = err && err.message ? err.message : String(err);
+              const key = (item && item.learningKey) ? item.learningKey : '<unknown>';
+              errors.push(`archive failed "${key}": ${msg}`);
+            }
+          }
+        }
+      }
+
+      return { written, archived, errors };
+    },
+    { timeoutMs: 10000 },
+  );
+
+  // If lock acquisition failed, return a zeroed result with the lock error.
+  if (lockResult.ok === false) {
+    return {
+      written: 0,
+      archived: 0,
+      errors: [`lock-${lockResult.reason ?? 'unknown'}`],
+    };
+  }
+
+  // Unwrap the result returned from inside the lock body.
+  return lockResult.value;
+}

package/scripts/lib/reconcile-nudge-banner.mjs

@@ -0,0 +1,284 @@
+/**
+ * reconcile-nudge-banner.mjs — #723 (Epic #723 B1, Flaggschiff-Konvergenz 11).
+ *
+ * Deterministic session-start nudge for the Learning→Rule reconciliation
+ * pipeline. Fleet finding: `reconcile.enabled` defaults to `false` (silent
+ * no-op) and `/reconcile` is on-demand-only — repos with 131/123/101
+ * learnings on disk had ZERO reconcile runs, because nothing ever told the
+ * operator the corpus had accumulated enough evidence to be worth converting.
+ * This probe closes that gap the same way `loop-readiness-banner.mjs` (#633)
+ * closes the "no .claude/loop.md" gap: a single `checkXxx({repoRoot})` entry
+ * point that returns `null` (silent no-op) or `{severity:'warn', message}`.
+ *
+ * Deliberately introduces NO new Session Config key — per the #723 scope note,
+ * an advisory-only banner needs no on/off switch of its own (mirrors
+ * `ci-status-banner.mjs` / `qg-command-drift-banner.mjs` / `loop-readiness-banner.mjs`,
+ * none of which carry a dedicated enable flag). The EXISTING `reconcile.enabled`
+ * key is read only to decide whether to append an informational parenthetical —
+ * never to gate the probe itself.
+ *
+ * "Last reconcile run" provenance (researched, not guessed): the reconciliation
+ * engine (`scripts/lib/reconcile/engine.mjs` `runReconcile`) writes exactly ONE
+ * disk artifact per run — the idempotency sidecar at
+ * `.orchestrator/runtime/reconcile-candidates.jsonl` (owned by
+ * `scripts/lib/reconcile/idempotency.mjs`). Every learning present at a given
+ * run (eligible OR rejected) gets a candidate row, so:
+ *   - the MAX `created_at` across `loadCandidates({repoRoot})` is the most
+ *     recent reconcile run's timestamp (or `null` when the store is empty —
+ *     i.e. no run on record, matching the fleet finding above).
+ *   - the candidate COUNT is a reasonable proxy for "how many learnings had
+ *     been seen as of the last run" (dedup is by `learning_key`, so it is a
+ *     high-water mark across all runs to date), used for the "new learnings
+ *     since last run" delta heuristic.
+ * There is no separate `reconcile`-scoped event in `.orchestrator/metrics/events.jsonl`
+ * — the idempotency sidecar IS the durable run record, so this module reads
+ * that directly rather than re-deriving a signal from the generic event log.
+ *
+ * Reuses the existing learnings-corpus helpers rather than re-implementing
+ * filter logic:
+ *   - `readLearnings` (`./learnings/io.mjs`) — normalized entries (files→file_paths
+ *     dialect rename applied), used for the eligibility count.
+ *   - `surfaceTopN` (`./learnings/surface.mjs`) — the canonical active-learning
+ *     filter (confidence > floor, not expired); called with a large cap to get
+ *     the full active set rather than a top-N slice.
+ *   - `filterEligible` (`./reconcile/eligibility.mjs`) — the SAME type/file_paths
+ *     allow-list gate the reconcile engine itself uses (deliberately NOT
+ *     confidence-gated — mirrors `runReconcile`'s own posture, see
+ *     `skills/reconcile/SKILL.md` Phase 2.2).
+ *
+ * Plain-JS — no Zod dependency. Never throws. `computeReconcileNudge` always
+ * returns the full shape (never null); `checkReconcileNudge` returns the
+ * session-start banner object or null.
+ *
+ * Cross-references:
+ *  - `.claude/rules/verification-before-completion.md` — evidence-before-claims.
+ *  - `scripts/lib/loop-readiness-banner.mjs` — the banner-shape template.
+ *  - `scripts/lib/reconcile/engine.mjs` / `idempotency.mjs` / `eligibility.mjs`.
+ *  - `scripts/lib/learnings/io.mjs` / `surface.mjs`.
+ *  - `scripts/lib/config/reconcile.mjs` (`_parseReconcile`) — existing config key.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ *  - Issue #723.
+ */
+
+import { join } from 'node:path';
+
+import { readLearnings } from './learnings/io.mjs';
+import { surfaceTopN } from './learnings/surface.mjs';
+import { filterEligible } from './reconcile/eligibility.mjs';
+import { loadCandidates } from './reconcile/idempotency.mjs';
+import { readConfigFile } from './config/io.mjs';
+import { _parseReconcile } from './config/reconcile.mjs';
+
+/** Repo-relative location of the learnings corpus (mirrors engine.mjs's own constant — not exported there). */
+const LEARNINGS_PATH = '.orchestrator/metrics/learnings.jsonl';
+
+/** Nudge threshold (a): active-learning count with no reconcile run on record. */
+export const NUDGE_MIN_LEARNINGS = 20;
+
+/** Nudge threshold (b): new learnings accrued since the last determinable reconcile run. */
+export const NUDGE_MIN_DELTA = 15;
+
+/** Nudge threshold (c): rule-eligible learnings (type + file_paths allow-list), regardless of confidence. */
+export const NUDGE_MIN_ELIGIBLE = 3;
+
+/**
+ * Resolve the max `created_at` across reconcile-candidate sidecar records —
+ * the most recent reconcile run's timestamp, or `null` when no run is on
+ * record (empty store, missing file, or no parseable timestamp).
+ *
+ * @param {Array<{created_at?: unknown}>} candidates
+ * @returns {string|null} ISO 8601 timestamp, or null
+ */
+function _lastRunAt(candidates) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  let maxMs = -Infinity;
+  for (const c of candidates) {
+    const t = c && typeof c.created_at === 'string' ? Date.parse(c.created_at) : NaN;
+    if (Number.isFinite(t) && t > maxMs) maxMs = t;
+  }
+  return Number.isFinite(maxMs) && maxMs > -Infinity ? new Date(maxMs).toISOString() : null;
+}
+
+/**
+ * Pure computation — always returns the full shape (never null, never throws).
+ * Touches disk only via the injected/default learnings + candidates readers,
+ * all of which are themselves never-throwing.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — project root (defaults to process.cwd()).
+ * @param {Date|number} [opts.now] — injectable clock, forwarded to the active-learning filter.
+ * @returns {Promise<{
+ *   totalLearnings: number,
+ *   activeLearnings: number,
+ *   eligibleCount: number,
+ *   lastRunAt: string|null,
+ *   lastRunCandidateCount: number,
+ *   delta: number,
+ *   nudge: boolean,
+ *   reasons: string[],
+ * }>}
+ */
+export async function computeReconcileNudge(opts = {}) {
+  const empty = {
+    totalLearnings: 0,
+    activeLearnings: 0,
+    eligibleCount: 0,
+    lastRunAt: null,
+    lastRunCandidateCount: 0,
+    delta: 0,
+    nudge: false,
+    reasons: [],
+  };
+
+  const repoRoot = typeof opts.repoRoot === 'string' && opts.repoRoot.length > 0 ? opts.repoRoot : process.cwd();
+  const learningsPath = join(repoRoot, LEARNINGS_PATH);
+
+  /** @type {object[]} */
+  let entries;
+  try {
+    const result = await readLearnings(learningsPath);
+    entries = Array.isArray(result?.entries) ? result.entries : [];
+  } catch {
+    return empty; // fail-open — never throw out of the probe
+  }
+
+  // Silent no-op: missing file, empty file, or all-malformed lines all
+  // collapse to entries.length === 0 here.
+  if (entries.length === 0) return empty;
+
+  /** @type {object[]} */
+  let active;
+  try {
+    // Reuse surfaceTopN's active-filter (confidence > floor, not expired)
+    // uncapped — pass a large `n` to get the FULL active set, not a top slice.
+    active = await surfaceTopN(learningsPath, Number.MAX_SAFE_INTEGER, { now: opts.now });
+  } catch {
+    active = [];
+  }
+
+  if (active.length === 0) return empty;
+
+  let eligibleCount;
+  try {
+    eligibleCount = filterEligible(entries).eligible.length;
+  } catch {
+    eligibleCount = 0;
+  }
+
+  /** @type {Array<Record<string, unknown>>} */
+  let candidates;
+  try {
+    candidates = loadCandidates({ repoRoot });
+  } catch {
+    candidates = [];
+  }
+
+  const lastRunAt = _lastRunAt(candidates);
+  const lastRunCandidateCount = Array.isArray(candidates) ? candidates.length : 0;
+  const delta = entries.length - lastRunCandidateCount;
+
+  const reasons = [];
+  // (a) — plenty of active learnings, but no reconcile run has ever recorded them.
+  if (active.length >= NUDGE_MIN_LEARNINGS && lastRunAt === null) {
+    reasons.push(`${active.length} active learnings with no reconcile run on record`);
+  }
+  // (b) — a determinable prior run exists, and the corpus has grown meaningfully since.
+  if (lastRunAt !== null && delta > NUDGE_MIN_DELTA) {
+    reasons.push(`${delta} new learnings since the last reconcile run`);
+  }
+  // (c) — enough rule-eligible learnings to be worth a batch, independent of confidence.
+  if (eligibleCount >= NUDGE_MIN_ELIGIBLE) {
+    reasons.push(`${eligibleCount} rule-eligible learnings`);
+  }
+
+  return {
+    totalLearnings: entries.length,
+    activeLearnings: active.length,
+    eligibleCount,
+    lastRunAt,
+    lastRunCandidateCount,
+    delta,
+    nudge: reasons.length > 0,
+    reasons,
+  };
+}
+
+/**
+ * Best-effort extraction of `reconcile.enabled` from an already-parsed Session
+ * Config object (DI/test seam — avoids re-reading CLAUDE.md when the caller
+ * already has it). Returns `null` when unresolvable from `config` alone, in
+ * which case `checkReconcileNudge` falls back to reading CLAUDE.md/AGENTS.md.
+ *
+ * @param {unknown} config
+ * @returns {boolean|null}
+ */
+function _reconcileEnabledFromConfig(config) {
+  if (config && typeof config === 'object') {
+    const rc = /** @type {Record<string, unknown>} */ (config).reconcile;
+    if (rc && typeof rc === 'object' && typeof (/** @type {any} */ (rc).enabled) === 'boolean') {
+      return /** @type {any} */ (rc).enabled;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check reconcile-nudge readiness and produce a session-start banner.
+ *
+ * Silent (`null`) when: no learnings corpus (missing/empty/all-malformed),
+ * zero active learnings, or none of the three nudge thresholds are met.
+ * Never throws.
+ *
+ * @param {{repoRoot: string, config?: object, now?: Date|number}} opts
+ *   - `repoRoot`: REQUIRED absolute path to the repo root.
+ *   - `config`: optional already-parsed Session Config (DI seam; avoids a
+ *     second CLAUDE.md read when the caller already parsed it).
+ *   - `now`: optional injectable clock, forwarded to the active-learning filter.
+ * @returns {Promise<null | {severity:'warn', message:string}>}
+ */
+export async function checkReconcileNudge(opts = {}) {
+  try {
+    const { repoRoot, config, now } = opts;
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    let computed;
+    try {
+      computed = await computeReconcileNudge({ repoRoot, now });
+    } catch {
+      return null;
+    }
+    if (!computed || computed.nudge !== true) return null;
+
+    let reconcileEnabled = _reconcileEnabledFromConfig(config);
+    if (reconcileEnabled === null) {
+      try {
+        const content = await readConfigFile(repoRoot);
+        reconcileEnabled = _parseReconcile(content).enabled;
+      } catch {
+        // Config unreadable — fall back to the documented config default (false)
+        // so the informational parenthetical still renders conservatively.
+        reconcileEnabled = false;
+      }
+    }
+
+    const lastRunLabel =
+      typeof computed.lastRunAt === 'string' && computed.lastRunAt.length >= 10
+        ? computed.lastRunAt.slice(0, 10)
+        : 'never';
+
+    const lines = [
+      `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.eligibleCount} rule-eligible, ` +
+        `last reconcile run: ${lastRunLabel} — run /reconcile to convert learnings into rules.`,
+    ];
+    if (reconcileEnabled === false) {
+      lines.push(
+        '  (reconcile.enabled: false — banner is advisory only; /reconcile still runs on-demand.)'
+      );
+    }
+
+    return { severity: 'warn', message: lines.join('\n') };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}