session-orchestrator 4.0.0 → 4.0.1

package/scripts/lib/owner-config-banner.mjs

@@ -36,14 +36,12 @@
  *  - Issue #820.
  */
 
-import { loadOwnerConfig, resolveOwnerYamlPath, getDefaults } from './owner-yaml.mjs';
-
-/**
- * OPTIONAL object sections (mirrors `owner-yaml.mjs`'s internal, unexported
- * `OPTIONAL_OBJECT_SECTIONS`) — the only sections the #1244 discard-branch
- * merge rule can carry through a whole-file discard.
- */
-const OPTIONAL_OBJECT_SECTION_NAMES = /** @type {const} */ (['paths', 'dispatcher']);
+import {
+  loadOwnerConfig,
+  resolveOwnerYamlPath,
+  getDefaults,
+  OPTIONAL_OBJECT_SECTIONS,
+} from './owner-yaml.mjs';
 
 /**
  * Format a `{ section, errors }` entry into a short `"name" (first error)` tag.
@@ -111,7 +109,7 @@ export function checkOwnerConfig({ loader = loadOwnerConfig } = {}) {
       const survivedSections = [];
       if (result.config && typeof result.config === 'object') {
         const defaults = getDefaults();
-        for (const name of OPTIONAL_OBJECT_SECTION_NAMES) {
+        for (const name of OPTIONAL_OBJECT_SECTIONS) {
           if (JSON.stringify(result.config[name]) !== JSON.stringify(defaults[name])) {
             survivedSections.push(name);
           }

package/scripts/lib/owner-yaml.mjs

@@ -196,8 +196,15 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * OPTIONAL object sections (#820) — a malformed entry is replaced by its
  * `getDefaults()` value and reported via `droppedSections` + a stderr WARN,
  * but does NOT discard the rest of the file.
+ *
+ * Exported (#1262.4) as the SSOT for consumers that must iterate exactly these
+ * sections — currently `scripts/lib/owner-config-banner.mjs`, which derived the
+ * #1244 "survived a whole-file discard" set from a hand-mirrored local copy.
+ * Frozen so a consumer cannot mutate the shared array.
  */
-const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (['paths', 'dispatcher']);
+export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
+  Object.freeze(['paths', 'dispatcher'])
+);
 
 /**
  * OPTIONAL list sections (#820) — malformed entries are passed through

package/scripts/lib/plugin-update-banner.mjs

@@ -346,7 +346,8 @@ function resolvePlatformFromEnv(env) {
  * @param {"claude"|"codex"|"cursor"|"pi"} [opts.platform]  The harness driving
  *   this session, when the caller already knows it (the SessionStart hook
  *   computes this once and could pass it straight through). Falls back to
- *   {@link resolvePlatformFromEnv} on `opts.env` when omitted — never throws,
+ *   {@link resolvePlatformFromEnv} on `opts.env` when omitted OR when the value
+ *   is not one of the four keys above — never throws,
  *   never leaves the instruction generic just because the caller didn't wire
  *   the parameter through yet.
  * @returns {Promise<{severity: 'warn', message: string, installed: string, latest: string}|null>}
@@ -391,8 +392,15 @@ export async function checkPluginUpdate({
     return null;
   }
 
+  // Allowlist, not "any non-empty string": only a value this table actually has
+  // a recipe for may pre-empt env resolution — a typo or a future harness name
+  // (`'CLAUDE'`, `'clade'`) falls through to the env signal instead of silently
+  // degrading to the generic instruction. `Object.hasOwn`, never `in`: `in`
+  // would accept prototype keys (`'toString'`) as platforms.
   const resolvedPlatform =
-    typeof platform === 'string' && platform.length > 0 ? platform : resolvePlatformFromEnv(env);
+    typeof platform === 'string' && Object.hasOwn(PLATFORM_UPDATE_INSTRUCTIONS, platform)
+      ? platform
+      : resolvePlatformFromEnv(env);
   const instruction = PLATFORM_UPDATE_INSTRUCTIONS[resolvedPlatform] ?? GENERIC_UPDATE_INSTRUCTION;
 
   return {

package/scripts/lib/reconcile/engine.mjs

@@ -389,6 +389,28 @@ const BODY_LEARNING_ID_RE = /-\s*learning-id:\s*`([^`]+)`/g;
  * on disk: re-proposing it is the issue #484 defect (9 of 10 proposals in one
  * run were learnings a `.claude/rules/` file already covered).
  *
+ * **This scan is the AUTHORITATIVE half of the dedupe contract** (#1242). The
+ * `.claude/rules/*.md` files it reads are TRACKED, so they survive a fresh
+ * clone, a wiped working copy, and any loss of `.orchestrator/runtime/` (which
+ * is gitignored — `.gitignore:114`). The idempotency sidecar consulted beside
+ * it is a CACHE that can only SHORT-CIRCUIT this scan, never replace it: on a
+ * fresh clone the sidecar is empty and correctness rests entirely on the
+ * markers below. Measured 2026-09-07 on this repo: with the sidecar emptied,
+ * the run produced the identical 10 proposals and 30 "already materialized"
+ * rejections; with this scan disabled instead, 5 already-consolidated
+ * learnings were re-proposed.
+ *
+ * Both marker forms are load-bearing. Frontmatter `learning-key:` is a YAML
+ * SCALAR and can name exactly ONE learning, so a CONSOLIDATED rule file (one
+ * file absorbing N learnings) carries the remaining N-1 identities ONLY as
+ * `## Provenance` body bullets. Breaking {@link BODY_LEARNING_KEY_RE} would
+ * therefore silently re-propose most of a consolidated corpus while every
+ * single-learning file still deduped correctly — pinned by the "fresh clone,
+ * consolidated shape" test in `tests/lib/reconcile/engine.test.mjs`.
+ *
+ * `rule-loader.mjs` only EXCLUDES expired rules from injection; it never
+ * deletes a file, so an expired rule keeps deduping through these markers.
+ *
  * Gated the same way as {@link defaultLoadCandidatesForDedupe}: an absent
  * `repoRoot` yields empty sets rather than falling back to `process.cwd()`.
  * Never throws — a missing `.claude/rules/` dir or an unreadable file
@@ -555,14 +577,23 @@ async function runReconcileInner(
     // new learning could use — the #484 defect measured on a real repo was
     // exactly this: 9 of 10 proposals in one run were learnings that already
     // had a `.claude/rules/` file on disk, crowding out the tenth new one.
-    // Two independent sources both count as terminal, either is sufficient:
-    //   - the idempotency sidecar already carries a `processed_at` stamp for
-    //     this `learning_key` (`isProcessed`, previously computed but NEVER
-    //     called from this module — the other half of #484);
-    //   - a `.claude/rules/*.md` file already carries a matching
+    // Two independent sources both count as terminal, either is sufficient —
+    // but they are NOT peers (#1242). Their contract is:
+    //   - AUTHORITATIVE: a `.claude/rules/*.md` file already carries a matching
     //     `learning-key`/`learning-id` provenance marker, discovered by
-    //     scanning disk directly (covers the case where a rule was written
-    //     without ever going through this sidecar, e.g. hand-authored).
+    //     scanning disk directly. Those files are TRACKED, so this source alone
+    //     is sufficient on a fresh clone and covers rules written without ever
+    //     going through the sidecar (hand-authored, or consolidated by hand).
+    //   - CACHE: the idempotency sidecar already carries a `processed_at` stamp
+    //     for this `learning_key` (`isProcessed`, previously computed but NEVER
+    //     called from this module — the other half of #484). It lives in the
+    //     GITIGNORED `.orchestrator/runtime/` (`.gitignore:114`), so it is
+    //     absent on a fresh clone. It only SHORT-CIRCUITS the scan above (and
+    //     carries forward verdicts the scan can no longer see, e.g. an operator
+    //     decline (#1042) or a rule file since removed) — it never replaces it.
+    // Consequence: an empty sidecar must never change the verdict for a
+    // learning whose rule file exists. Pinned by the "fresh clone, consolidated
+    // shape" test in `tests/lib/reconcile/engine.test.mjs`.
     const { records: existingCandidates } = loadCandidatesForDedupe(repoRoot) ?? { records: [] };
     const materialized = readMaterializedProvenance(repoRoot) ?? { keys: new Set(), ids: new Set() };
 

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

@@ -5,7 +5,8 @@
  * Leaf module — no imports from siblings or parent.
  *
  * Exports: CURRENT_SESSION_SCHEMA_VERSION, SESSION_KEY_ALIASES,
- *          VALID_SESSION_TYPES, REQUIRED_FIELDS, AGENT_SUMMARY_FIELDS
+ *          VALID_SESSION_TYPES, VALID_SESSION_PROFILES, REQUIRED_FIELDS,
+ *          AGENT_SUMMARY_FIELDS
  */
 
 // ---------------------------------------------------------------------------
@@ -82,6 +83,38 @@ export const SESSION_KEY_ALIASES = Object.freeze({
  */
 export const VALID_SESSION_TYPES = Object.freeze(['feature', 'deep', 'housekeeping', 'unknown']);
 
+/**
+ * CLOSED set of valid `session_profile` values — the SSOT for this enum
+ * (GitLab #1252). `scripts/lib/telemetry/schema.mjs` re-exports this constant
+ * rather than defining a second literal; `server/ingest/validate.mjs`
+ * `SESSION_PROFILES` is a deliberate MIRROR (the server tree must not import
+ * from `scripts/`) held in lockstep by `tests/telemetry/parity.test.mjs`.
+ *
+ * A profile names a WAVE-SHAPE variant on top of an UNCHANGED `session_type`:
+ * an ultradeep session is `session_type: "deep"` PLUS
+ * `session_profile: "ultradeep"` — never `session_type: "ultradeep"`.
+ * PRD: docs/prd/2026-09-06-ultradeep-session-profile.md. Writer:
+ * `commands/session.md` § "Argument alias: ultradeep" → STATE.md frontmatter
+ * `session-profile`; wave shape: `skills/session-plan/SKILL.md`.
+ *
+ * DELIBERATELY NOT A MEMBER of VALID_SESSION_TYPES above: that set is consumed
+ * by `scripts/lib/telemetry/schema.mjs` (an unlisted type → 'other') and by
+ * `scripts/lib/wave-sizing.mjs` (an unlisted type → TypeError), where a new
+ * MODE would be MISLABELLED rather than rejected. That reasoning is unchanged
+ * by the `unknown` member: `unknown` is the absence of a measurement, not a
+ * mode, and nothing dispatches on it.
+ *
+ * WHY A WHITELIST AND NOT A REGEX: the value is copied from repo-authored
+ * STATE.md frontmatter, i.e. it is the only usage-ping field whose VALUE is
+ * free text. Two Wave-1 reviewers reproduced the leak end-to-end (2026-09-06):
+ * `session-profile: client-acme-private-repo` travelled verbatim to the ingest
+ * server's `raw_json`. A shape regex does not close it — that string already
+ * passes any lowercase-and-hyphens pattern. Only an enumeration of names that
+ * are public BY CONSTRUCTION does. Adding a profile therefore means a reviewed
+ * edit HERE and in the server mirror.
+ */
+export const VALID_SESSION_PROFILES = Object.freeze(['ultradeep']);
+
 /**
  * Required fields for a schema_version=1 record. Validated by validateSession
  * before any write reaches disk.
@@ -154,15 +187,9 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // into a note a human reads" ⊃ "schema-valid". A record missing it is a clean
   // vault-mirror skip, NOT a malformed record.
   'effectiveness',
-  // PRD docs/prd/2026-09-06-ultradeep-session-profile.md — `session_profile`
-  // names a WAVE-SHAPE variant on top of an unchanged `session_type`. It is
-  // additive and optional on purpose: `ultradeep` is deliberately NOT a member
-  // of VALID_SESSION_TYPES above, because that set is mirrored in
-  // scripts/lib/telemetry/schema.mjs (an unlisted type -> 'other') and in
-  // scripts/lib/wave-sizing.mjs (an unlisted type -> TypeError), where a new
-  // MODE would be MISLABELLED rather than rejected. That reasoning is unchanged
-  // by the `unknown` member added above: `unknown` is the absence of a
-  // measurement, not a mode, and nothing dispatches on it. Every historical
-  // record lacking the field validates unchanged.
+  // `session_profile` — a WAVE-SHAPE variant on top of an unchanged
+  // `session_type`. Additive and optional on purpose: every historical record
+  // lacking the field validates unchanged. Value set + the full rationale for
+  // why it is NOT a VALID_SESSION_TYPES member: VALID_SESSION_PROFILES above.
   'session_profile',
 ]);

package/scripts/lib/session-start-probes.mjs

@@ -168,6 +168,18 @@ export const PROBES = [
     // vault-staleness-banner.mjs's header for the "one vocabulary, not two"
     // rationale.
   },
+  {
+    id: 'telemetry-flush-health',
+    spec: local('./telemetry-flush-health-banner.mjs'),
+    fn: 'checkTelemetryFlushHealth',
+    network: false,
+    args: ({ repoRoot }) => ({ repoRoot }),
+    // No custom render/severityOf: the probe returns `{severity:'warn',
+    // message}` — exactly the shape the module-level defaults below read. It
+    // reports the LAST `orchestrator.telemetry.flush` record when that record
+    // is a `sandbox:*` refusal (#1255); the refusal reached the ledger and
+    // nothing else before this entry existed.
+  },
   {
     id: 'ci-status',
     spec: local('./ci-status-banner.mjs'),

package/scripts/lib/telemetry/schema.mjs

@@ -38,6 +38,7 @@
 import { getPlatform, getPluginRoot } from '../platform.mjs';
 import { enumerateSurface } from '../sunset/walker.mjs';
 import { readPluginVersionFromPackageJson } from '../bootstrap-lock-freshness.mjs';
+import { VALID_SESSION_PROFILES } from '../session-schema/constants.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -124,8 +125,31 @@ const ROSTER_OTHER = 'other';
 const MAX_NAME_LENGTH = 64;
 const MAX_NAMES = 100;
 
+/**
+ * The two list bounds that are genuinely SHARED with the ingest server
+ * (`server/ingest/validate.mjs` `INGEST_LIST_BOUNDS` — MAX_LIST_ITEMS /
+ * MAX_LIST_ITEM_LEN). Exported so `tests/telemetry/parity.test.mjs` can compare
+ * the two trees instead of trusting two hand-typed numbers: a client that caps
+ * higher than the server emits pings the server 400s.
+ *
+ * The server's other five bounds (MAX_ANON_ID, MAX_SENT_AT, MAX_PLUGIN_VERSION,
+ * MAX_SESSION_TYPE, MAX_SESSION_PROFILE) are SERVER-ONLY BY DESIGN — they bound
+ * inputs from any client, including foreign or tampered ones, and have no client
+ * counterpart to keep in lockstep. Do not mirror them here.
+ */
+export const SHARED_LIST_BOUNDS = Object.freeze({
+  maxItems: MAX_NAMES,
+  maxItemLength: MAX_NAME_LENGTH,
+});
+
 /** Enum fallbacks. */
 const VALID_PLATFORMS = Object.freeze(['claude', 'codex', 'cursor', 'pi']);
+// DELIBERATE ASYMMETRY, not a drift: this is the TELEMETRY type set and omits
+// `'unknown'`, which session-schema/constants.mjs VALID_SESSION_TYPES carries.
+// There `unknown` is a storable ledger value; here it is a NORMALIZER FALLBACK
+// (SESSION_TYPE_UNKNOWN below) that must never be reachable from the input set,
+// or "we could not tell" would be indistinguishable from a measured type. Not
+// unified with constants.mjs for exactly that reason.
 const VALID_SESSION_TYPES = Object.freeze(['housekeeping', 'feature', 'deep']);
 const PLATFORM_OTHER = 'other';
 const SESSION_TYPE_OTHER = 'other';
@@ -145,27 +169,24 @@ const SESSION_TYPE_UNKNOWN = 'unknown';
 /**
  * CLOSED whitelist of PUBLIC session-profile names that may reach the wire.
  *
- * WHY A WHITELIST AND NOT A REGEX: `session_profile` is copied from the STATE.md
- * frontmatter key `session-profile`, which is written per repo by whoever runs
- * `/session <alias>` — i.e. it is the only field on the usage-ping whose VALUE is
- * repo-authored free text. Two independent Wave-1 reviewers reproduced the leak
- * end-to-end (2026-09-06): `session-profile: client-acme-private-repo` travelled
- * verbatim through `buildUsagePing` → `projectUsagePing` → the ingest server's
- * `raw_json` column. A shape regex does NOT close it — that example string is
- * already lowercase-and-hyphens and passes any such pattern. Only an
- * enumeration of names that are public BY CONSTRUCTION does.
+ * RE-EXPORT, not a definition (GitLab #1252): the SSOT is
+ * `scripts/lib/session-schema/constants.mjs` `VALID_SESSION_PROFILES`, whose
+ * docblock carries the reproduced leak and the whitelist-over-regex rationale.
  *
- * Today exactly one profile exists: `ultradeep`, the 7-wave variant of a `deep`
- * session (writer: `commands/session.md` § "Argument alias: ultradeep" → STATE.md
- * frontmatter `session-profile`; wave shape: `skills/session-plan/SKILL.md`).
- * Adding a profile there means adding it HERE and in the server's mirror
- * (`server/ingest/validate.mjs` `SESSION_PROFILES`) — a deliberate two-line,
- * reviewed edit, the same contract `ACCEPTED_VERSIONS` already uses server-side.
+ * Kept as a pure COMPATIBILITY SHIM, and measured as one: since 2026-09-07 no
+ * module in this repo imports the name from here (`rg -n VALID_SESSION_PROFILES
+ * scripts server hooks skills tests` — the two telemetry tests that used to now
+ * address constants.mjs). It stays because removing an export is a MAJOR change
+ * and this is a patch line; a deep importer outside the repo may still hold it.
+ * `tests/telemetry/schema.test.mjs` pins it with an IDENTITY assertion
+ * (`toBe`, not `toEqual`) so the shim can never quietly become a second
+ * definition of the whitelist.
  *
- * NOT a member of VALID_SESSION_TYPES: the profile is a SECOND axis. An
- * ultradeep session is `session_type: "deep"` PLUS `session_profile: "ultradeep"`.
+ * Adding a profile is a reviewed edit in constants.mjs AND in the server's
+ * mirror (`server/ingest/validate.mjs` `SESSION_PROFILES`) — the same two-tree
+ * contract `ACCEPTED_VERSIONS` already uses server-side.
  */
-export const VALID_SESSION_PROFILES = Object.freeze(['ultradeep']);
+export { VALID_SESSION_PROFILES };
 
 /**
  * Closed sets for os/arch client-side normalization. A value outside the set —

package/scripts/lib/telemetry-flush-health-banner.mjs

@@ -0,0 +1,211 @@
+/**
+ * telemetry-flush-health-banner.mjs — #1255
+ *
+ * Surfaces the ONE telemetry-flush outcome nobody could see: a flush the
+ * sandbox guard refused.
+ *
+ * ## Why this module exists
+ *
+ * `scripts/lib/telemetry/sync.mjs` fails CLOSED since 4.0.0 — when its
+ * environment probe cannot complete its checks it returns
+ * `{ sandbox: true, reason: 'sandbox:probe-failed' }` and sends nothing. That
+ * is the right default, and `sync.mjs` stays deliberately SILENT about it (it
+ * runs inside the SessionEnd teardown budget, where a banner has no reader).
+ *
+ * The refusal therefore reaches exactly one sink: `hooks/on-session-end.mjs`
+ * emits `orchestrator.telemetry.flush` with `{ outcome, reason }` into
+ * `.orchestrator/metrics/events.jsonl`. Measured 2026-09-07 (W1-D6 census):
+ * NO consumer read that reason back out — a repo could refuse every flush for
+ * weeks and the only visible difference from a healthy repo was an absence.
+ * That is `.claude/rules/host-resources.md` § HR-105 ("a rule you cannot
+ * falsify is not a rule") applied to the flush path.
+ *
+ * This probe closes the loop on the NEXT session start, which is the first
+ * moment a human is actually looking: it reads the LAST flush record and warns
+ * when that record is a sandbox refusal. Newest-wins by construction — a later
+ * successful flush silently clears the warning, so the banner reports the
+ * CURRENT state of the channel, never its history.
+ *
+ * Never throws. Never mutates input. No network.
+ *
+ * @module scripts/lib/telemetry-flush-health-banner
+ */
+
+import { existsSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Bytes of `events.jsonl` read from the END of the file.
+ *
+ * The ledger is append-only and grows without bound (33k+ records in this repo
+ * alone), so a full `readFileSync` on a SessionStart hook's critical path is
+ * the wrong shape — this probe shares a 2s budget with ~18 siblings.
+ *
+ * NAMED CEILING (BV-004): a flush record older than the last 64 KB of the
+ * ledger is invisible to this probe and reads as "no flush recorded" → `null`
+ * (silent). At the observed record width (~120-400 bytes) that window holds
+ * roughly 150-500 events, and a flush is emitted once per session close — so
+ * the window covers the last flush unless ~150+ events landed after it without
+ * one, which cannot happen inside a single session's teardown.
+ * REVISIT TRIGGER: if the per-session event volume ever exceeds ~150 records
+ * between two session ends, raise this or index the ledger — do not silently
+ * accept the truncation.
+ */
+export const TAIL_BYTES = 64 * 1024;
+
+/** The event name `hooks/on-session-end.mjs` emits for every flush attempt. */
+const FLUSH_EVENT = 'orchestrator.telemetry.flush';
+
+/**
+ * Bound an untrusted ledger `reason` before it is interpolated into a terminal
+ * banner: strip C0/DEL control bytes (a record could carry an ANSI escape) and
+ * cap the length. Mirrors the sibling bound in
+ * `scripts/lib/session-start-probes.mjs` (`.slice(0, 200)` on a probe error).
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+function sanitizeReason(reason) {
+  // eslint-disable-next-line no-control-regex -- stripping control bytes IS the job
+  return String(reason).replace(/[\x00-\x1f\x7f]/g, '').slice(0, 120);
+}
+
+/**
+ * Read the last `TAIL_BYTES` of a file as UTF-8.
+ *
+ * Returns a DISCRIMINATED result rather than `string|null`, because "the
+ * ledger could not be read" and "the ledger holds nothing alarming" are the
+ * two states this probe exists to keep apart (HR-105): collapsing an EACCES
+ * onto `null` renders an unreadable channel as a healthy one.
+ *
+ * @param {string} file
+ * @returns {{text: string} | {missing: true} | {error: string}}
+ */
+function readTail(file) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const { size } = fstatSync(fd);
+    const length = Math.min(size, TAIL_BYTES);
+    const start = size - length;
+    const buf = Buffer.allocUnsafe(length);
+    let read = 0;
+    while (read < length) {
+      const n = readSync(fd, buf, read, length - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return { text: buf.subarray(0, read).toString('utf8') };
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { missing: true };
+    return { error: typeof err?.code === 'string' ? err.code : 'EUNKNOWN' };
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}
+
+/**
+ * Classify the telemetry-flush channel from the LAST recorded flush event.
+ *
+ * Scans the ledger tail BACKWARDS and stops at the first
+ * `orchestrator.telemetry.flush` record it can parse — newest wins, so an
+ * older refusal followed by a successful flush produces no banner.
+ *
+ * Returns `null` (silent) when: `repoRoot` is not a string, the ledger is
+ * ABSENT, no flush record sits in the tail window, or the newest flush
+ * record's `reason` does not start with `sandbox:`. A malformed line is
+ * SKIPPED (it is not a flush record we can read), never a throw — the ledger's
+ * last line is routinely a partial write when another process is appending.
+ *
+ * An UNREADABLE ledger (EACCES/EIO/…, i.e. anything other than "not there") is
+ * NOT silent: it returns a `ledger-unreadable` warning. "The guard state
+ * cannot be confirmed" must not display like "the last flush was fine" — that
+ * collapse is the exact HR-105 defect this module's header cites as its reason
+ * to exist, one layer down.
+ *
+ * This probe reports the LAST outcome regardless of its age (no clock seam):
+ * a refusal does not expire on its own — only a later successful flush clears
+ * it.
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {null | {severity: 'warn', reason: string, message: string}}
+ */
+export function checkTelemetryFlushHealth({ repoRoot } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+    if (!existsSync(file)) return null;
+
+    const tail = readTail(file);
+    if (tail.missing) return null;
+    if (tail.error) {
+      return {
+        severity: 'warn',
+        reason: 'ledger-unreadable',
+        message:
+          '⚠ Telemetry: flush-health unknown — .orchestrator/metrics/events.jsonl ' +
+          `could not be read (${sanitizeReason(tail.error)}); ` +
+          'the sandbox guard state cannot be confirmed.',
+      };
+    }
+    if (!tail.text) return null;
+
+    const lines = tail.text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        // Malformed (or a tail-truncated first line) — not readable as a flush
+        // record, so it cannot be the newest one. Keep scanning backwards.
+        continue;
+      }
+      if (!record || typeof record !== 'object') continue;
+      if (record.event !== FLUSH_EVENT) continue;
+
+      // First flush record found scanning backwards = the newest one.
+      const rawReason = record.reason;
+      if (typeof rawReason !== 'string' || !rawReason.startsWith('sandbox:')) return null;
+
+      // The ledger is an untrusted string source for banner purposes: bound the
+      // reason on BOTH surfaces (the field a consumer may render itself, and
+      // the message we render) rather than only on the one we happen to own.
+      const reason = sanitizeReason(rawReason);
+
+      return {
+        severity: 'warn',
+        reason,
+        message:
+          `⚠ Telemetry: last flush refused by the sandbox guard (${reason}) — ` +
+          'the guard could not complete its checks and failed closed; no ping was sent. ' +
+          'See docs/telemetry.md § Sandbox guard.',
+      };
+    }
+
+    return null;
+  } catch {
+    // Defensive catch-all — a banner probe must never throw (fail-open).
+    return null;
+  }
+}
+
+/**
+ * Convenience renderer: the banner message string, or `''` when silent.
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {string}
+ */
+export function renderBanner({ repoRoot } = {}) {
+  const result = checkTelemetryFlushHealth({ repoRoot });
+  return result ? result.message : '';
+}