session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/telemetry/schema.mjs

@@ -93,6 +93,7 @@ export const USAGE_PING_OPTIONAL_FIELDS = Object.freeze([
   'fleet_self_declared',
   'session_record',
   'session_profile',
+  'ledger_complete',
 ]);
 
 /**
@@ -117,6 +118,29 @@ const USAGE_PING_PROJECTED_FIELDS = Object.freeze([...USAGE_PING_FIELDS, ...USAG
  */
 export const SESSION_RECORD_SOURCES = Object.freeze(['ledger', 'derived', 'absent']);
 
+/*
+ * `ledger_complete` — a SECOND, ORTHOGONAL axis beside `session_record`
+ * (GitLab #1416), deliberately NOT a fourth provenance token.
+ *
+ * `deriveSessionFromEvents` (telemetry/sync.mjs) returns a three-state verdict on
+ * the events ledger it read FROM: `true` (every rotation archive present),
+ * `false` (at least one measured gap — a deleted/missing archive), and `null`
+ * (no verdict was produced at all: the read threw, or there was no source). That
+ * verdict decided nothing on the wire, so a derived record reconstructed from a
+ * holey ledger was indistinguishable from one reconstructed from a whole one.
+ *
+ * Why a boolean and not a `derived-partial` token: `SESSION_RECORD_SOURCES` is a
+ * frozen enum mirrored in prose and in the server's `raw_json` consumers, and
+ * completeness is a property of the SOURCE READ, not of WHICH source was used —
+ * widening the provenance enum would make the two facts inseparable and force
+ * every reader of `session_record === 'derived'` to learn a second spelling.
+ *
+ * THE THIRD STATE IS OMISSION: only a real boolean is written. `null` (nothing
+ * measured) omits the key, exactly like `session_profile` — "we did not look" is
+ * never sent as a measured `false`. On the `ledger` branch the field is not set
+ * at ALL: that path never reads the events ledger, so it has no verdict to give.
+ */
+
 /** Exact duration-bucket tokens (ASCII, stable wire values). */
 export const DURATION_BUCKETS = Object.freeze(['<15m', '15-60m', '1-3h', '>3h']);
 
@@ -541,6 +565,7 @@ export function buildUsagePing({
   consentState,
   sessionRecordSource,
   sessionProfile,
+  ledgerComplete,
 } = {}) {
   const session = isPlainObject(sessionRecord) ? sessionRecord : {};
   const invocations = Array.isArray(skillInvocations) ? skillInvocations : [];
@@ -637,6 +662,11 @@ export function buildUsagePing({
     session_record: SESSION_RECORD_SOURCES.includes(sessionRecordSource)
       ? sessionRecordSource
       : 'absent',
+    // ONLY a real boolean travels (#1416). `null`/`undefined` — the read never
+    // happened, or this path never read the events ledger at all — OMITS the
+    // key, the same absent-is-not-empty contract `session_profile` uses above.
+    // Writing `false` there would turn "we did not look" into a measured gap.
+    ...(typeof ledgerComplete === 'boolean' ? { ledger_complete: ledgerComplete } : {}),
     skills: filterRosterNames(skillNames, rosterSkills),
     commands: filterRosterNames(commandNames, rosterCommands),
   };

package/scripts/lib/telemetry/sync.mjs

@@ -41,6 +41,7 @@ import { ensureAnonId } from './anon-id.mjs';
 import { peekAll, enqueue, clear, queueStats } from './queue.mjs';
 import { loadOwnerConfig } from '../owner-yaml.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { readEventsWithRotations } from '../events.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
@@ -338,12 +339,54 @@ export function readSessionProfileForMetricsDir(metricsDir) {
  * Never throws.
  *
  * @param {string} metricsDir
- * @returns {{ session: object, source: 'derived'|'absent' }}
+ * @returns {{ session: object, source: 'derived'|'absent',
+ *             ledger_complete: boolean|null, ledger_gaps: object[] }}
+ *   `ledger_complete` is `null` — never `false` — when the read produced no
+ *   verdict at all: an undetermined ledger is not a proven gap. TWO paths reach
+ *   that third state (#1423): this function throwing, and the reader finding NO
+ *   source (no active file, no archive, no legacy ring) — in the latter case
+ *   `events: []` is the absence of a ledger, not a measured quiet window.
+ *   `ledger_complete === false` additionally writes ONE stderr line naming the
+ *   gap kinds, because a verdict nothing surfaces is a verdict nobody acts on.
  */
 export function deriveSessionFromEvents(metricsDir) {
   try {
-    const events = readJsonlFile(path.join(metricsDir, 'events.jsonl'), { skipInvalid: true });
-    if (!Array.isArray(events) || events.length === 0) return { session: {}, source: 'absent' };
+    // #1407: read ACROSS rotation boundaries. This reconstruction is the ONLY
+    // source of session facts whenever `sessions.jsonl` has no usable record,
+    // and its sibling window is `DAILY_FLUSH_MS` (24 h) — so a rotation between
+    // a session's start and its flush silently truncated it.
+    //
+    // CEILING (BV-004): the reader loads the active file AND every archive
+    // fully into memory — up to ~60 MB transient at the default
+    // `max-size-mb: 10` / `max-backups: 5`. Measured 2026-09-20 A/B in ONE
+    // process on exactly that worst case (60 MB / 6 sources / 293,994 records,
+    // host loadavg 11.2): median 25.5 ms → 215.8 ms, i.e. +190 ms, which is
+    // 6.4 % of this path's `POST_TIMEOUT_MS` (3000). Acceptable for a
+    // once-per-flush cold read. Revisit if `max-size-mb` is raised past ~100,
+    // if `max-backups` grows, or if the flush budget drops below ~1 s.
+    const ledger = readEventsWithRotations(undefined, {
+      filePath: path.join(metricsDir, 'events.jsonl'),
+    });
+    const events = ledger.events;
+    // A missing archive is a GAP, never an empty window (#1407 AC-3). Carried
+    // on EVERY return below, including the empty ones — that is precisely where
+    // a deleted archive and a quiet period are otherwise indistinguishable.
+    const ledgerVerdict = { ledger_complete: ledger.complete, ledger_gaps: ledger.gaps };
+    // Visibility (#1423): the field had ZERO production consumers — a measured
+    // gap reached nobody. ONE stderr line, at the single point the verdict is
+    // formed, so every return below is covered by construction. Diagnostics on
+    // stderr, never stdout (cli-design.md); no new event, because the gap is a
+    // property of the LEDGER and an event about it would land in the same file.
+    if (ledger.complete === false) {
+      const kinds = [...new Set((ledger.gaps ?? []).map((g) => g?.kind ?? 'unknown'))].sort();
+      process.stderr.write(
+        `⚠ telemetry: events ledger INCOMPLETE — ${ledger.gaps.length} gap(s) ` +
+          `[${kinds.join(', ')}]; the session facts below are reconstructed from a PARTIAL read\n`,
+      );
+    }
+    if (!Array.isArray(events) || events.length === 0) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     let startedAt = null;
     let sessionType = null;
@@ -412,7 +455,9 @@ export function deriveSessionFromEvents(metricsDir) {
       profile = undatedShapeProfile;
     }
 
-    if (startedAt === null && sessionType === null && profile === null) return { session: {}, source: 'absent' };
+    if (startedAt === null && sessionType === null && profile === null) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     const session = {};
     if (sessionType !== null) session.session_type = sessionType;
@@ -422,9 +467,11 @@ export function deriveSessionFromEvents(metricsDir) {
     // omit-never-fabricate contract session-close-backfill.mjs uses (#914 R1).
     if (lastTs !== null && startedAt !== null && lastTs >= startedAt) session.completed_at = lastTs;
 
-    return { session, source: 'derived' };
+    return { session, source: 'derived', ...ledgerVerdict };
   } catch {
-    return { session: {}, source: 'absent' };
+    // No verdict was ever produced — `null`, not `false`: a measurement that
+    // did not happen is not a measured zero.
+    return { session: {}, source: 'absent', ledger_complete: null, ledger_gaps: [] };
   }
 }
 
@@ -483,6 +530,12 @@ export function buildBatch({
     let sessionForPing;
     /** @type {'ledger'|'derived'|'absent'} */
     let sessionRecordSource = 'ledger';
+    // #1416: the events-ledger completeness verdict, carried to the ping as its
+    // own optional boolean. Stays `null` on the LEDGER branch by construction —
+    // that branch never reads events.jsonl, so it has nothing to report, and
+    // `buildUsagePing` omits the key for anything that is not a real boolean.
+    /** @type {boolean|null} */
+    let ledgerComplete = null;
     if (sessionRecord && typeof sessionRecord.started_at === 'string' && !Number.isNaN(Date.parse(sessionRecord.started_at))) {
       const startMs = Date.parse(sessionRecord.started_at);
       windowInvocations = invocations.filter((rec) => {
@@ -500,6 +553,7 @@ export function buildBatch({
       const derived = deriveSessionFromEvents(dir);
       sessionForPing = derived.session;
       sessionRecordSource = derived.source;
+      ledgerComplete = derived.ledger_complete;
 
       const derivedStartMs = Date.parse(sessionForPing.started_at);
       const cutoff = (Number.isNaN(Date.parse(nowIso)) ? Date.now() : Date.parse(nowIso)) - DAILY_FLUSH_MS;
@@ -522,6 +576,7 @@ export function buildBatch({
       consentState,
       sessionRecordSource,
       sessionProfile: readSessionProfileForMetricsDir(dir),
+      ledgerComplete,
     });
 
     const target = statePath || TELEMETRY_JSON_PATH;

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

@@ -31,9 +31,11 @@
  * @module scripts/lib/telemetry-flush-health-banner
  */
 
-import { existsSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+import { readTailWindow } from './tail-window.mjs';
+
 /**
  * Bytes of `events.jsonl` read from the END of the file.
  *
@@ -82,31 +84,11 @@ function sanitizeReason(reason) {
  * @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') };
+    return { text: readTailWindow(file, TAIL_BYTES).text };
   } 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 */
-      }
-    }
   }
 }
 

package/scripts/lib/test-runner/issue-reconcile.mjs

@@ -22,10 +22,17 @@
  *   triageDecision(finding, candidates)
  *     → {action: 'create'|'update'|'ignore', target?, reason: string, confidence: number}
  *
+ *   buildIssueBody(finding, fp) → string
+ *
+ *   neutralizeFingerprintSentinel(text) → string
+ *   fingerprintSentinelLine(fp) → string
+ *     The one shared sentinel writer + neutraliser, also used by
+ *     ux-grill/reconcile.mjs (#1339 P6).
+ *
  *   ReconcileError
  *
  * Security:
- *   - #388 (SEC-IR-MED-1): sentinel injection hardening — sanitizeRecommendation()
+ *   - #388 (SEC-IR-MED-1): sentinel injection hardening — neutralizeFingerprintSentinel()
  *     strips **Fingerprint:** literals from free-text fields before they are
  *     embedded in the body (before the authoritative sentinel line is appended).
  *   - #389 (SEC-IR-LOW-1): maxBuffer set to 4 MB on every execFile call;
@@ -126,39 +133,64 @@ function validateFinding(finding) {
 // ---------------------------------------------------------------------------
 
 /**
- * Sanitize free-text recommendation fields before embedding in the issue body.
- * Replaces any literal `**Fingerprint:**` with `__Fingerprint__` to prevent
- * a crafted recommendation from spoofing the authoritative fingerprint sentinel
- * line that is appended by buildIssueBody().
+ * Neutralise every `**Fingerprint:**` literal in untrusted text by rewriting it
+ * to `__Fingerprint__`. The ONE copy of this neutralisation: this module's
+ * {@link buildIssueBody} and `ux-grill/reconcile.mjs` both route free text
+ * through it (#1339 P6), so a hardening added here reaches both producers.
  *
- * Context: glab parses issue bodies as Markdown. If `recommendation` contained
+ * Context: glab parses issue bodies as Markdown. If a free-text field contained
  * `**Fingerprint:** <attacker-hash>`, a grep for the fingerprint sentinel in
  * listExistingFindings() would match the spoofed value instead of the real one,
  * bypassing dedup. Replacing the literal prevents the attack without altering
- * the semantic meaning of the recommendation text.
+ * the semantic meaning of the text.
+ *
+ * @param {unknown} text - coerced with `String(text ?? '')`
+ * @returns {string}
+ */
+export function neutralizeFingerprintSentinel(text) {
+  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
+  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
+  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
+  return String(text ?? '').replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+}
+
+/**
+ * The authoritative dedup sentinel line, in the exact shape
+ * {@link extractFingerprintFromBody} reads. The caller passes an
+ * already-trusted value; this function does not sanitise it.
+ *
+ * @param {string} fp - 16-char hex fingerprint
+ * @returns {string}
+ */
+export function fingerprintSentinelLine(fp) {
+  return `**Fingerprint:** \`${fp}\``;
+}
+
+/**
+ * Sanitize free-text recommendation fields before embedding in the issue body
+ * (#388 SEC-IR-MED-1) — {@link neutralizeFingerprintSentinel} for a non-empty
+ * string, anything else returned unchanged (a `null` description is dropped by
+ * buildIssueBody's line filter rather than rendered as an empty line).
  *
  * @param {string|undefined|null} text
  * @returns {string|undefined|null}
  */
 function sanitizeRecommendation(text) {
   if (!text || typeof text !== 'string') return text;
-  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
-  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
-  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
-  return text.replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+  return neutralizeFingerprintSentinel(text);
 }
 
 /**
  * Render untrusted text as the content of ONE inline Markdown code span:
- * sentinel literals neutralised (sanitizeRecommendation), line breaks and NUL
- * folded to a space, backticks turned into `'` — so a page-controlled locator
- * can neither close its code span nor start a new body line.
+ * sentinel literals neutralised, line breaks and NUL folded to a space,
+ * backticks turned into `'` — so a page-controlled locator can neither close
+ * its code span nor start a new body line.
  *
  * @param {unknown} text
  * @returns {string}
  */
 function codeSpanContent(text) {
-  return sanitizeRecommendation(String(text ?? ''))
+  return neutralizeFingerprintSentinel(text)
     .replace(/[\r\n\0]+/g, ' ')
     .replace(/`/g, "'");
 }
@@ -218,7 +250,7 @@ export function buildIssueBody(finding, fp) {
     '',
     safeRecommendation ? `**Recommendation:** ${safeRecommendation}` : null,
     '',
-    `**Fingerprint:** \`${fp}\``,
+    fingerprintSentinelLine(fp),
     `**Severity:** ${finding.severity}`,
     `**Check:** ${finding.checkId}`,
     `**Locator:** \`${codeSpanContent(finding.locator)}\``,

package/scripts/lib/tests-src-ratio.mjs

@@ -76,9 +76,9 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, isAbsolute, relative, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync } from './io.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // The definition — the part that must never be re-derived by hand
@@ -475,10 +475,6 @@ function main() {
   process.exit(args.check && !result.withinCorridor ? 1 : 0);
 }
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) main();

package/scripts/lib/tmux-layout/telemetry-stats.mjs

@@ -2,7 +2,8 @@
  * scripts/lib/tmux-layout/telemetry-stats.mjs
  *
  * Aggregator stub for /tmux-layout telemetry promotion gate (#563).
- * Reads .orchestrator/metrics/events.jsonl and computes:
+ * Reads the events ledger — active file AND every rotated archive (#1407) —
+ * and computes:
  *   - invocation count (total + per layout)
  *   - completion rate (completed / invoked) — promotion gate threshold 80%
  *   - top-K degradation reasons
@@ -13,25 +14,68 @@
  *   - CLI: `node scripts/lib/tmux-layout/telemetry-stats.mjs` (emits JSON to stdout)
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { readEventsWithRotations } from '../events.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
+/** Every event this module reports on carries this prefix. */
+const TMUX_EVENT_PREFIX = 'tmux-layout.';
+
+/**
+ * Read the tmux-layout events ACROSS rotation boundaries, together with the
+ * honesty verdict of that read.
+ *
+ * WHY THE ENVELOPE (#1407 acceptance criterion 3): the stats below are an
+ * ALL-TIME rate. Reading only the active file silently redefines "all time" as
+ * "since the last rotation", and a genuinely missing archive would then look
+ * identical to a quiet week. `complete === false` says which of the two it is;
+ * the CLI prints it and never computes over a partial set in silence.
+ *
+ * THREE states (#1423): `complete === null` is a THIRD reading — no source
+ * existed at all, so `invocations: 0` is UNMEASURED, not a measured zero, and
+ * `meetsPromotionGate: false` below rests on nothing. The CLI names that case
+ * separately; folding it into `false` would report a gap nobody found, folding
+ * it into `true` would report a measurement nobody took.
+ *
+ * CEILING (BV-004): `readEventsWithRotations` loads the active file and every
+ * archive fully into memory — up to ~60 MB transient at the default
+ * `max-size-mb: 10` / `max-backups: 5`. Acceptable here because this is a COLD
+ * ops path: a hand-run CLI / promotion-gate check, never a hook and never on
+ * the session path. Revisit if this module gains a hot-path caller or if
+ * `max-size-mb` is raised past ~100.
+ *
+ * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
+ * @returns {{events: Array<object>, complete: boolean|null, gaps: Array<object>,
+ *            notices: Array<object>}}
+ */
+export function readTmuxEventsEnvelope(eventsPath = EVENTS_PATH) {
+  const { events, gaps, complete, notices } = readEventsWithRotations(undefined, {
+    filePath: eventsPath,
+  });
+  return {
+    events: events.filter(
+      (rec) => rec && typeof rec.event === 'string' && rec.event.startsWith(TMUX_EVENT_PREFIX),
+    ),
+    complete,
+    gaps,
+    notices: notices ?? [],
+  };
+}
+
 /**
- * Read events.jsonl and return tmux-layout-related events.
+ * Read the events ledger and return tmux-layout-related events.
+ *
+ * Thin array-returning view of {@link readTmuxEventsEnvelope} — the shape every
+ * existing caller expects. Use the envelope when the completeness of the read
+ * matters to the answer.
  *
  * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
  * @returns {Array<object>}  parsed event records (filtered to tmux-layout.* events)
  */
 export function readTmuxEvents(eventsPath = EVENTS_PATH) {
-  if (!existsSync(eventsPath)) return [];
-  const raw = readFileSync(eventsPath, 'utf-8');
-  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
-  return lines
-    .map((l) => {
-      try { return JSON.parse(l); } catch { return null; }
-    })
-    .filter((rec) => rec && typeof rec.event === 'string' && rec.event.startsWith('tmux-layout.'));
+  return readTmuxEventsEnvelope(eventsPath).events;
 }
 
 /**
@@ -93,8 +137,24 @@ export function computeStats(events) {
 }
 
 // CLI entry-point — emit stats as JSON to stdout when run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const events = readTmuxEvents();
+if (isMainModule(import.meta.url)) {
+  const { events, complete, gaps } = readTmuxEventsEnvelope();
   const stats = computeStats(events);
-  console.log(JSON.stringify(stats, null, 2));
+  if (complete === null) {
+    // NOT MEASURED — a different sentence from "incomplete" (#1423): no active
+    // file and no archive means the zeros below were never observed.
+    console.error(
+      'WARN: no events source was readable (no active file, no archive) — the stats below are UNMEASURED, not zero',
+    );
+  } else if (!complete) {
+    // A gap, never an empty window: diagnostics on stderr (cli-design.md),
+    // the machine-readable verdict in the JSON below.
+    const detail = gaps
+      .map((g) => `${g.kind}:${path.basename(String(g.archived_as ?? 'unknown'))}`)
+      .join(', ');
+    console.error(
+      `WARN: events ledger incomplete — the all-time rate below is computed over a PARTIAL set (${gaps.length} gap(s): ${detail})`,
+    );
+  }
+  console.log(JSON.stringify({ ...stats, ledgerComplete: complete, ledgerGaps: gaps }, null, 2));
 }

package/scripts/lib/user-invocable-skills.mjs

@@ -0,0 +1,205 @@
+/**
+ * scripts/lib/user-invocable-skills.mjs
+ *
+ * ONE definition of "this skill is an operator-facing slash command".
+ *
+ * Since the #1370 command→skill fold (2026-09-16) `commands/` holds only the two
+ * names that cannot be a skill (`session`, `templates-ack` — see
+ * `tests/commands/headless-bare-command-availability.test.mjs` for the measured
+ * mechanism). Every other slash command IS a skill, marked by an EXPLICIT
+ * `user-invocable: true` in its SKILL.md frontmatter. Consumers that used to
+ * count or link `commands/*.md` therefore need the union:
+ *
+ *   commands/*.md  ∪  skills with explicit `user-invocable: true`
+ *
+ * This module exists so that union has one implementation rather than one per
+ * consumer (site-numbers tile, sunset walker linkage, the guard tests). It is
+ * deliberately tiny and dependency-free: `scripts/lib/sunset/walker.mjs` imports it,
+ * and the walker sits in the hook import graph, which must load WITHOUT
+ * node_modules (GH#62/#63) — so no `js-yaml` here; the frontmatter parser is the
+ * repo's own `parseAgentFrontmatter`, already in that graph.
+ *
+ * PARSED, never line-matched: `.claude/rules/test-hygiene.md` records that a
+ * line-regex frontmatter reader is blind to unparseable YAML and mis-measures
+ * block scalars. A SKILL.md whose frontmatter does not parse is treated as NOT
+ * user-invocable — fail-closed, and loud where it matters because such a file
+ * already fails `check-skills`/`validate-plugin`.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseAgentFrontmatter } from './agent-frontmatter.mjs';
+
+/**
+ * YAML 1.1 boolean lookalikes that YAML 1.2 / js-yaml's CORE_SCHEMA (what
+ * `generate-codex-skills` parses with) reads as PLAIN STRINGS, not as `true`.
+ * They are therefore NOT user-invocable here either — but silently demoting a
+ * skill on one of them is the #1370 defect class, so each one gets a WARN.
+ */
+const TRUTHY_LOOKALIKE = /^(?:yes|y|on|t|1)$/i;
+
+/**
+ * Strip a trailing `#` comment, honouring quotes: `true # note` is the same
+ * declaration as `true`, but `"a # b"` carries the hash as content.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function stripTrailingComment(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    // A `#` opens a YAML comment only at the start or after whitespace.
+    if (ch === '#' && (i === 0 || /\s/.test(text[i - 1]))) return text.slice(0, i);
+  }
+  return text;
+}
+
+/**
+ * Normalise a raw frontmatter scalar to the token a YAML parser would see:
+ * trim, drop a trailing comment, drop one layer of matching surrounding quotes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function normaliseScalar(text) {
+  let out = stripTrailingComment(text).trim();
+  if (out.length >= 2 && (out[0] === '"' || out[0] === "'") && out[out.length - 1] === out[0]) {
+    out = out.slice(1, -1).trim();
+  }
+  return out;
+}
+
+/**
+ * THE one normaliser for `user-invocable` — the marker "this skill is an
+ * operator-facing slash command". Every generator (Cursor, Pi, Codex) and every
+ * counter (site-numbers tile, drift-check `command-count`, the guard tests) must
+ * route through this function; four private re-implementations disagreeing on a
+ * quoted value is the defect this replaces.
+ *
+ * Explicit-true only. `undefined` (flag absent) is NOT user-invocable: the whole
+ * point of the marker is that it is written down, so a skill that forgot it is a
+ * defect to surface, not a default to guess.
+ *
+ * Accepted: the boolean `true`, and a string that normalises to `true`
+ * case-insensitively — so `"true"`, `'true'`, `True`, `true # note` and
+ * `true ` (trailing space, invisible in an editor) all read as the same
+ * declaration. Trailing-whitespace tolerance is load-bearing rather than
+ * cosmetic: without it a stray space silently demotes a skill out of the
+ * generated adapters with no diagnostic anywhere.
+ *
+ * REJECTED: `yes` / `y` / `on` / `t` / `1`. Those are YAML 1.1 booleans; under
+ * YAML 1.2 — which is what js-yaml's CORE_SCHEMA in `generate-codex-skills`
+ * applies — they are plain strings, and this predicate follows the parser rather
+ * than inventing a fifth dialect. Because the demotion is the surprising half,
+ * each one emits exactly one stderr WARN naming the file.
+ *
+ * The same normalisation governs the SIBLING boolean marker
+ * `disable-model-invocation` (the Cursor and Codex adapters read it with this
+ * predicate). The WARN therefore names the key it was asked about rather than a
+ * hard-coded `user-invocable`: measured 2026-09-18, a `disable-model-invocation:
+ * yes` demotion reported `user-invocable: "yes"`, sending the operator to a
+ * line that does not exist in that file.
+ *
+ * The NOUN follows the key too (#1388 P10). Naming the key while hard-coding
+ * "is NOT a slash-command marker" told a `disable-model-invocation: yes` author
+ * that his value failed to be something it never was — a correct key with a
+ * wrong subject reads as a broken diagnostic. The default phrase is unchanged
+ * for `user-invocable`, so the four existing call sites see identical text.
+ *
+ * @param {unknown} value the raw frontmatter value
+ * @param {string} [file] path named in the WARN when a truthy-looking value is demoted
+ * @param {string} [key] frontmatter key named in the WARN (default `user-invocable`)
+ * @returns {boolean}
+ */
+const MARKER_NOUN = Object.freeze({
+  'user-invocable': 'a slash-command marker',
+  'disable-model-invocation': 'a model-invocation opt-out marker',
+});
+const DEFAULT_MARKER_NOUN = 'a boolean marker';
+
+export function isUserInvocableValue(value, file, key = 'user-invocable') {
+  if (value === true) return true;
+  if (typeof value !== 'string') return false;
+  const token = normaliseScalar(value);
+  if (token.toLowerCase() === 'true') return true;
+  if (TRUTHY_LOOKALIKE.test(token)) {
+    const where = file ? `${file}: ` : '';
+    process.stderr.write(
+      `WARN ${where}${key}: ${JSON.stringify(value)} is NOT ${MARKER_NOUN[key] ?? DEFAULT_MARKER_NOUN} — `
+        + `only \`true\` is (YAML 1.2 reads yes/on/1 as strings). Write \`${key}: true\`.\n`,
+    );
+  }
+  return false;
+}
+
+/**
+ * Parse a SKILL.md's YAML frontmatter. Returns `null` when there is no
+ * frontmatter block or it does not parse.
+ *
+ * @param {string} content
+ * @returns {Record<string, unknown>|null}
+ */
+export function parseSkillFrontmatter(content) {
+  if (typeof content !== 'string') return null;
+  const parsed = parseAgentFrontmatter(content);
+  return parsed.ok ? parsed.frontmatter : null;
+}
+
+/**
+ * Names of skills carrying an explicit `user-invocable: true`, sorted.
+ *
+ * @param {string} repoRoot plugin root (the directory holding `skills/`)
+ * @returns {string[]}
+ */
+export function userInvocableSkills(repoRoot) {
+  const dir = path.join(repoRoot, 'skills');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const names = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const file = path.join(dir, entry.name, 'SKILL.md');
+    if (!existsSync(file) || !statSync(file).isFile()) continue;
+    let fm;
+    try {
+      fm = parseSkillFrontmatter(readFileSync(file, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (fm && isUserInvocableValue(fm['user-invocable'], file)) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Names of `commands/*.md` files (without the extension), sorted. */
+export function commandFileNames(repoRoot) {
+  const dir = path.join(repoRoot, 'commands');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('.'))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+/**
+ * The product's "slash commands" set: `commands/*.md` ∪ explicitly
+ * user-invocable skills, deduplicated by NAME.
+ *
+ * Dedup is load-bearing rather than defensive: a name present as BOTH is the
+ * picker-duplicate bug (the body runs, and the entry lists twice), so it must
+ * count once here and go red in the guard test — never inflate the number.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} sorted unique names
+ */
+export function slashCommandNames(repoRoot) {
+  return [...new Set([...commandFileNames(repoRoot), ...userInvocableSkills(repoRoot)])].sort();
+}