session-orchestrator 5.6.0 → 5.8.0

package/scripts/lib/session-id.mjs

@@ -42,6 +42,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { readTailWindow } from './tail-window.mjs';
 import { withStateMdLock } from './session-lock.mjs';
@@ -207,7 +208,7 @@ const EVENTS_MAX_AGE_MS = 2 * 24 * 60 * 60 * 1000;
  * @returns {Promise<string[]>}  Array of semantic_session_id strings (may include duplicates).
  */
 async function readSessionIdsFromEvents(repoRoot) {
-  const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  const filePath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
 
   let window;
   try {

package/scripts/lib/session-record-repair.mjs

@@ -68,6 +68,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { atomicWriteWithBackup, envelopeToError } from './io.mjs';
 import { validateSession as defaultValidateSession } from './session-schema/validator.mjs';
 import { serializeSessionLineChecked as defaultSerialize } from './session-schema.mjs';
 import { checkSessionsIntegrity as defaultCheckIntegrity } from './sessions-integrity-banner.mjs';
@@ -716,7 +717,6 @@ export function repairLedger({ file, repoRoot = null, apply = false, backup = tr
     renameSync = fs.renameSync,
     copyFileSync = fs.copyFileSync,
     unlinkSync = fs.unlinkSync,
-    existsSync = fs.existsSync,
   } = deps;
 
   const { checkIntegrity = defaultCheckIntegrity } = deps;
@@ -751,18 +751,14 @@ export function repairLedger({ file, repoRoot = null, apply = false, backup = tr
   }
 
   // -- atomic swap ----------------------------------------------------------
-  const tmpPath = `${file}.tmp-${process.pid}`;
-  try {
-    writeFileSync(tmpPath, text, 'utf8');
-    renameSync(tmpPath, file);
-  } catch (err) {
-    try {
-      if (existsSync(tmpPath)) unlinkSync(tmpPath);
-    } catch {
-      /* best-effort cleanup */
-    }
-    throw err;
-  }
+  // The helper unlinks its tmp on failure; the backup above keeps its own
+  // `.bak-<compact stamp>` schema, so the helper takes none. The injected fs
+  // seams (`deps`) are threaded through so a test fake still sees the write.
+  const res = atomicWriteWithBackup(file, text, {
+    tmpPrefix: `.${path.basename(file)}.tmp`,
+    fs: { writeFileSync, renameSync, unlinkSync },
+  });
+  if (!res.ok) throw envelopeToError(res);
 
   // -- post-verification ----------------------------------------------------
   const verdict = verifyWritten({

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

@@ -162,11 +162,11 @@ export const AGENT_SUMMARY_FIELDS = Object.freeze(['complete', 'partial', 'faile
  * #964). These are NOT in REQUIRED_FIELDS — older entries lacking them validate
  * cleanly. Validator: see `_validateOptionalFields` in validator.mjs.
  *
- * NOT YET EXHAUSTIVE. `_validateOptionalFields` additionally shape-checks
- * `discovery_stats`, `review_stats`, `platform`, `branch`, `base_branch`,
- * `notes`, `duration_seconds`, `issues_closed` and `issues_created` without
- * listing them here. Treat membership as "declared optional", never absence as
- * "not a known field" — see the #964 follow-up note in the session report.
+ * Exhaustive since #986: every optional key `validateSession` inspects is
+ * declared here. tests/lib/session-schema/constants.test.mjs takes that census
+ * from the validator itself (a Proxy records the keys it reads) and also pins
+ * the declared-but-unchecked remainder (`session_start_ref`, `raw_session_id`,
+ * `_repair_source`).
  */
 export const OPTIONAL_FIELDS = Object.freeze([
   'agent_identity',
@@ -252,4 +252,19 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // 2026-10-01), so the counters say which of the two it is.
   'cost_records_priced',
   'cost_records_total',
+  // #986 — shape-checked by `_validateOptionalFields` since before this list
+  // existed, never declared until the census test made the gap visible.
+  'discovery_stats',
+  'review_stats',
+  'platform',
+  'branch',
+  'base_branch',
+  'notes',
+  'duration_seconds',
+  'issues_closed',
+  'issues_created',
+  // `express_path` (canonical boolean, legacy {activated} object tolerated) and
+  // its forensic sidecar `_express_path_detail` written by `normalizeSession`.
+  'express_path',
+  '_express_path_detail',
 ]);

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

@@ -50,7 +50,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
 
-import { emitEvent } from './events.mjs';
+import { emitEvent, eventsFilePath } from './events.mjs';
 import { ARCHIVE_DIR_NAME, ARCHIVE_NAME_RE } from './events-schema.mjs';
 
 /**
@@ -762,7 +762,7 @@ export const PROBES = [
     fn: 'checkEventsRetention',
     network: false,
     precondition: ({ repoRoot }) => {
-      const metrics = path.join(repoRoot, '.orchestrator', 'metrics');
+      const metrics = path.dirname(eventsFilePath(repoRoot)); // #1514: the ledger checkEventsRetention reads
       return existsSync(path.join(metrics, 'events.jsonl')) || hasRotationArchive(metrics)
         ? null
         : 'no-events-ledger';

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

@@ -143,6 +143,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { isRealSession } from './session-schema/filters.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
@@ -150,8 +151,6 @@ import { readCanonicalSessions } from './sessions-canonical.mjs';
 /** Repo-relative path to the session ledger (one record per closed session). */
 const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
 
-/** Repo-relative path to the generic telemetry stream (one line per event). */
-const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
 /** warn threshold: 2x the session-lock default TTL (8h) — imported, not duplicated. */
 export const WARN_THRESHOLD_HOURS = DEFAULT_TTL_HOURS * 2;
@@ -527,7 +526,7 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
     const ledger = lastLedgerEntry(sessionRecords);
     if (ledger === null) return null;
 
-    const eventLines = readJsonlLines(path.join(repoRoot, EVENTS_PATH));
+    const eventLines = readJsonlLines(eventsFilePath(repoRoot)); // #1514: the repo's one ledger
     if (eventLines === null || eventLines.length === 0) return null;
 
     const { cutoffMs, ownSessionId } = resolveCutoff(repoRoot, nowMs);

package/scripts/lib/skill-evolution/engine.mjs

@@ -49,9 +49,9 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
-import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 import { extractCandidates as realExtractCandidates } from './candidate-intake.mjs';
 import {
@@ -281,13 +281,10 @@ async function defaultApplyConfigRepair(candidate, repoRoot) {
     return { ok: true, applied: false, reason: 'already-current (no-op)' };
   }
 
-  try {
-    const dir = path.dirname(abs);
-    const tmpFile = path.join(dir, `.${path.basename(abs)}.${randomBytes(6).toString('hex')}.tmp`);
-    writeFileSync(tmpFile, next, { encoding: 'utf8' });
-    renameSync(tmpFile, abs);
-  } catch (err) {
-    return { ok: true, applied: false, reason: `write failed: ${err?.message ?? String(err)}` };
+  // The helper's mkdir -p is a no-op here: `abs` was just read, so its dir exists.
+  const written = atomicWriteWithBackup(abs, next, { tmpPrefix: `.${path.basename(abs)}.tmp` });
+  if (!written.ok) {
+    return { ok: true, applied: false, reason: `write failed: ${written.error}` };
   }
 
   return { ok: true, applied: true };

package/scripts/lib/skill-evolution/idempotency.mjs

@@ -45,9 +45,9 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 /**
  * @typedef {import('./candidate-intake.mjs').RepairCandidate} RepairCandidate
@@ -202,18 +202,16 @@ function readStore(absPath) {
  * @returns {{ ok: true, lines: number } | { ok: false, reason: 'fs-error', error: string }}
  */
 function writeStore(absPath, records) {
+  let content;
   try {
-    const dir = dirname(absPath);
-    mkdirSync(dir, { recursive: true });
     const body = records.map((r) => JSON.stringify(r)).join('\n');
-    const content = records.length > 0 ? body + '\n' : '';
-    const tmpFile = join(dir, `.repair-candidates.${randomBytes(6).toString('hex')}.tmp`);
-    writeFileSync(tmpFile, content, { encoding: 'utf8' });
-    renameSync(tmpFile, absPath);
-    return { ok: true, lines: records.length };
+    content = records.length > 0 ? body + '\n' : '';
   } catch (err) {
     return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
   }
+  // mkdir -p + tmp + rename; its failure envelope is this function's own.
+  const res = atomicWriteWithBackup(absPath, content, { tmpPrefix: '.repair-candidates.tmp' });
+  return res.ok ? { ok: true, lines: records.length } : res;
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/slopcheck.mjs

@@ -43,6 +43,7 @@
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { atomicWriteWithBackup } from './io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -164,15 +165,16 @@ function ensureCacheLoaded(repoRoot) {
 function persistCache(repoRoot) {
   if (_cache === null) return;
   const file = cachePathFor(repoRoot);
-  const dir = path.dirname(file);
+  let body;
   try {
-    fs.mkdirSync(dir, { recursive: true });
-    const obj = Object.fromEntries(_cache.entries());
-    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, file);
+    body = JSON.stringify(Object.fromEntries(_cache.entries()), null, 2) + '\n';
   } catch (err) {
-    console.warn(`slopcheck: cache write failed (${err.code ?? 'unknown'}): ${err.message}`);
+    console.warn(`slopcheck: cache write failed (serialize): ${err.message}`);
+    return;
+  }
+  const res = atomicWriteWithBackup(file, body, { tmpPrefix: `.${path.basename(file)}.tmp` });
+  if (!res.ok) {
+    console.warn(`slopcheck: cache write failed (${res.code ?? 'unknown'}): ${res.error}`);
   }
 }
 

package/scripts/lib/sunset/walker.mjs

@@ -606,8 +606,8 @@ export function staticReferenceScan(repoRoot, { kind, name }) {
  * NOTE since the 2026-09-16 command→skill fold (#1370): this linkage now covers
  * almost nothing. `commands/` holds two files (`session`, `templates-ack`), so
  * `skillToCommands` is near-empty by construction — the operator entry point for
- * every other slash command is an explicit `user-invocable: true` in the skill's
- * own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
+ * every other slash command is a skill whose `user-invocable` is `true` or absent
+ * (Claude Code picker semantics, #1515) in its own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
  * threads that flag alongside this linkage, and `classifyItem` treats the two as
  * equivalent evidence of "an operator can invoke this directly". Without that, 26
  * live slash commands would have been demoted the day their command file was
@@ -783,7 +783,7 @@ export function classifyItem({
   const strictRefs = staticRefs.strictRefs;
   const nonBoilerplateRefs = staticRefs.nonBoilerplateRefs;
   const invokedByCommands = linkage?.invokedByCommands ?? [];
-  // #1370 fold: an explicit `user-invocable: true` in SKILL.md frontmatter is the
+  // #1370 fold: a picker-visible skill (`user-invocable` true or absent, #1515) is the
   // post-fold form of "an operator invokes this directly" — the same evidence a
   // command file used to carry. Default false so older callers/tests that do not
   // thread it behave exactly as before.

package/scripts/lib/telemetry/sync.mjs

@@ -42,6 +42,7 @@ 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 { resolveEventsLedgerRoot } from '../platform.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
@@ -382,7 +383,8 @@ export function deriveSessionFromEvents(metricsDir) {
     // 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'),
+      // #1514: the repo's one ledger (identity unless metricsDir is in a linked worktree).
+      filePath: path.join(resolveEventsLedgerRoot(metricsDir), 'events.jsonl'),
     });
     const events = ledger.events;
     // A missing archive is a GAP, never an empty window (#1407 AC-3). Carried

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

@@ -32,8 +32,8 @@
  */
 
 import { existsSync } from 'node:fs';
-import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readTailWindow } from './tail-window.mjs';
 
 /**
@@ -122,7 +122,7 @@ export function checkTelemetryFlushHealth({ repoRoot } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
-    const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+    const file = eventsFilePath(repoRoot); // #1514: the repo's one ledger
     if (!existsSync(file)) return null;
 
     const tail = readTail(file);

package/scripts/lib/test-sibling-coverage.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * test-sibling-coverage.mjs — THE measurement behind the Test-Sibling Expansion
+ * figures (#970) in skills/wave-executor/references/wave-loop-scope-manifest.md.
+ *
+ * ## Why this file exists
+ *
+ * The expansion grants a GLOB (`tests/**\/{basename}*.test.mjs`) instead of a
+ * computed path, and the manifest justified that with three hand-measured counts
+ * (439 / 375 / 272 at `730ee9d`). Those numbers lived in prose, went stale, and a
+ * second contradicting copy appeared in a code comment (#1026.5, #1030 P3). Same
+ * cure as `tests-src-ratio.mjs`: the recipe is code, the `--json` envelope
+ * carries its own definition, and the docs point here instead of restating it.
+ *
+ * ## The recipe
+ *
+ *   universe     `git ls-files` (the index — tracked paths only)
+ *   tests        tracked files matching DEFAULT_TEST_PATH_PATTERNS (scope-gate)
+ *   production   tracked files matching a DEFAULT_TEST_SIBLING_RULES `source`
+ *                that are NOT tests — defined by negation, so a new top-level
+ *                directory is counted the moment it is committed
+ *   glob         production files where a sibling glob from `testSiblingsFor()`
+ *                matches a test via `pathMatchesPattern()` — the exact matcher
+ *                the scope gate grants with, reused rather than re-derived
+ *   exact        production files with a test under `tests/` whose basename is
+ *                exactly `<stem>.test<ext>`
+ *   mirror       production files whose 1:1 mirror exists: `tests/` + the path
+ *                with a leading `scripts/` dropped, `<ext>` → `.test<ext>`
+ *
+ * By construction mirror ⊆ exact ⊆ glob ⊆ production, so the counts must obey
+ * mirror ≤ exact ≤ glob ≤ total; a violation means a broken definition.
+ *
+ * Usage: test-sibling-coverage.mjs [<repo-root>] [--json]
+ * Exit:  0 measured · 2 tool error (not a git repo, bad argument)
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+import {
+  DEFAULT_TEST_PATH_PATTERNS,
+  DEFAULT_TEST_SIBLING_RULES,
+  pathMatchesPattern,
+  testSiblingsFor,
+} from './scope-gate.mjs';
+import { isMainModule } from './is-main-module.mjs';
+
+/** Machine-readable schema tag for the --json envelope. */
+export const SCHEMA = 'test-sibling-coverage/1';
+
+const isTest = (p) => DEFAULT_TEST_PATH_PATTERNS.some((pat) => pathMatchesPattern(p, pat));
+const isProduction = (p) =>
+  !isTest(p) && DEFAULT_TEST_SIBLING_RULES.some((r) => pathMatchesPattern(p, r.source));
+
+/** `scripts/lib/x.mjs` → { stem: 'x', ext: '.mjs' } */
+function stemOf(p) {
+  const ext = path.posix.extname(p);
+  return { stem: path.posix.basename(p, ext), ext };
+}
+
+/** The 1:1 mirror path the manifest's "naive mirror" figure counts. */
+export function mirrorPathOf(p) {
+  const { ext } = stemOf(p);
+  const rel = p.startsWith('scripts/') ? p.slice('scripts/'.length) : p;
+  return `tests/${rel.slice(0, rel.length - ext.length)}.test${ext}`;
+}
+
+/**
+ * Measure the three coverage counts over a path list. Pure.
+ * @param {string[]} files — repo-relative POSIX paths
+ * @returns {{total: number, glob: number, exact: number, mirror: number, uncovered: string[]}}
+ */
+export function measure(files) {
+  const tests = files.filter(isTest);
+  const testSet = new Set(tests);
+  const testBasenames = new Set(tests.filter((t) => t.startsWith('tests/')).map((t) => path.posix.basename(t)));
+  const production = files.filter(isProduction);
+  let glob = 0;
+  let exact = 0;
+  let mirror = 0;
+  const uncovered = [];
+  for (const p of production) {
+    const globs = testSiblingsFor([p]);
+    // Linear scan of every test per glob — 0.3 s wall for the whole CLI at 571
+    // production files (2026-10-03); revisit if the tracked test count passes ~5000.
+    if (globs.some((g) => tests.some((t) => pathMatchesPattern(t, g)))) glob += 1;
+    else uncovered.push(p);
+    const { stem, ext } = stemOf(p);
+    if (testBasenames.has(`${stem}.test${ext}`)) exact += 1;
+    if (testSet.has(mirrorPathOf(p))) mirror += 1;
+  }
+  return { total: production.length, glob, exact, mirror, uncovered };
+}
+
+/** The self-describing definition block shipped inside every --json envelope. */
+export function definition() {
+  return {
+    source: 'git ls-files (tracked paths only)',
+    tests: `tracked paths matching scope-gate DEFAULT_TEST_PATH_PATTERNS: ${DEFAULT_TEST_PATH_PATTERNS.join(', ')}`,
+    total: `production files: tracked paths matching a sibling-rule source (${DEFAULT_TEST_SIBLING_RULES.map((r) => r.source).join(', ')}) that are not tests`,
+    glob: `production files where a scope-gate testSiblingsFor() glob (${DEFAULT_TEST_SIBLING_RULES.map((r) => r.sibling).join(', ')}) matches a test via pathMatchesPattern`,
+    exact: 'production files with a test under tests/ whose basename is exactly <stem>.test<ext>',
+    mirror: 'production files whose mirror tests/<path minus leading scripts/, <ext> -> .test<ext>> is tracked',
+    invariant: 'mirror <= exact <= glob <= total',
+  };
+}
+
+function git(root, args) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+const pct = (n, d) => (d === 0 ? null : Math.round((n / d) * 1000) / 10);
+
+function main(argv) {
+  let json = false;
+  let root = process.cwd();
+  for (const a of argv) {
+    if (a === '--json') json = true;
+    else if (a.startsWith('--')) {
+      process.stderr.write(`Unknown argument '${a}'. Usage: test-sibling-coverage.mjs [<repo-root>] [--json]\n`);
+      return 2;
+    } else root = path.resolve(a);
+  }
+  let files;
+  let ref;
+  let dirty;
+  try {
+    files = git(root, ['ls-files']).split('\n').filter(Boolean);
+    ref = git(root, ['rev-parse', '--short', 'HEAD']).trim();
+    // The index IS the measured population: only a staged add/delete/rename
+    // makes (ref, counts) unreproducible. --no-optional-locks: no index refresh
+    // under a parallel session (PSA-007).
+    dirty = git(root, ['--no-optional-locks', 'diff', '--cached', '--name-only', '--diff-filter=ADR']).trim() !== '';
+  } catch (error) {
+    process.stderr.write(`ERROR: git failed in ${root}: ${error.message}\n`);
+    return 2;
+  }
+  const r = measure(files);
+  const envelope = {
+    schema: SCHEMA,
+    ref,
+    dirty,
+    measuredAt: new Date().toISOString().slice(0, 10),
+    total: r.total,
+    glob: r.glob,
+    exact: r.exact,
+    mirror: r.mirror,
+    percent: { glob: pct(r.glob, r.total), exact: pct(r.exact, r.total), mirror: pct(r.mirror, r.total) },
+    uncovered: r.uncovered,
+    definition: definition(),
+  };
+  if (json) {
+    process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    const line = (k) => `  ${k.padEnd(7)} ${String(r[k]).padStart(5)} / ${r.total}  (${envelope.percent[k]} %)`;
+    process.stdout.write(
+      `test-sibling coverage at ${ref}${dirty ? ' (index differs from HEAD)' : ''}, ${envelope.measuredAt}\n`
+      + `${line('glob')}\n${line('exact')}\n${line('mirror')}\n`
+      + `  uncovered by the glob: ${r.uncovered.length} (list: --json)\n`,
+    );
+  }
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}

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

@@ -15,11 +15,9 @@
  */
 
 import path from 'node:path';
-import { readEventsWithRotations } from '../events.mjs';
+import { eventsFilePath, 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.';
 
@@ -58,11 +56,11 @@ export const REQUIRED_EVENTS_WINDOW_DAYS = null;
  * 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]
+ * @param {string} [eventsPath=eventsFilePath()]  the repo's one ledger (#1514)
  * @returns {{events: Array<object>, complete: boolean|null, gaps: Array<object>,
  *            notices: Array<object>}}
  */
-export function readTmuxEventsEnvelope(eventsPath = EVENTS_PATH) {
+export function readTmuxEventsEnvelope(eventsPath = eventsFilePath()) {
   const { events, gaps, complete, notices } = readEventsWithRotations(undefined, {
     filePath: eventsPath,
   });
@@ -83,10 +81,10 @@ export function readTmuxEventsEnvelope(eventsPath = EVENTS_PATH) {
  * existing caller expects. Use the envelope when the completeness of the read
  * matters to the answer.
  *
- * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
+ * @param {string} [eventsPath=eventsFilePath()]  the repo's one ledger (#1514)
  * @returns {Array<object>}  parsed event records (filtered to tmux-layout.* events)
  */
-export function readTmuxEvents(eventsPath = EVENTS_PATH) {
+export function readTmuxEvents(eventsPath = eventsFilePath()) {
   return readTmuxEventsEnvelope(eventsPath).events;
 }
 

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

@@ -19,17 +19,15 @@ import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { findProjectRoot } from '../common.mjs';
+import { eventsFilePath } from '../events.mjs';
 import { stampEventSchemaVersion, validateEventRecord } from '../events-schema.mjs';
 
-/**
- * Path FRAGMENT joined against a resolved repo root at write time — NOT a
- * relative path constant. A relative constant resolves against process.cwd(),
- * which is how ~8k test-emitted tmux events landed in the real ledger: the
- * suite spawns scripts/tmux-layout.mjs with cwd = repo root, so every
- * telemetry write went straight into production telemetry.
- * Same shape as scripts/lib/session-close-backfill.mjs § EVENTS_REL.
- */
-const EVENTS_REL = ['.orchestrator', 'metrics', 'events.jsonl'];
+// The ledger path is resolved against a repo root at write time — NEVER a
+// relative path constant. A relative constant resolves against process.cwd(),
+// which is how ~8k test-emitted tmux events landed in the real ledger: the
+// suite spawns scripts/tmux-layout.mjs with cwd = repo root, so every
+// telemetry write went straight into production telemetry. The path is
+// `eventsFilePath(<root>)` (#1514: the repo's one ledger).
 
 /**
  * True when this process is a vitest run, or a child spawned by one
@@ -56,7 +54,7 @@ function isTestRunner() {
 export function emit(eventType, payload = {}, { repoRoot } = {}) {
   try {
     if (!repoRoot && isTestRunner()) return;
-    const eventsPath = path.join(repoRoot || findProjectRoot(), ...EVENTS_REL);
+    const eventsPath = eventsFilePath(repoRoot || findProjectRoot()); // #1514: the repo's one ledger
     const dir = path.dirname(eventsPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     // `stampEventSchemaVersion()` rather than an inline `schema_version:` —

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

@@ -6,11 +6,13 @@
  * 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
+ * mechanism). Every other slash command IS a skill. Claude Code lists a skill in
+ * the `/` picker unless its frontmatter says `user-invocable: false` — a MISSING
+ * key counts as `true` (#1515, measured 2026-10-03: 37 picker entries against a
+ * documented 27, because 10 skills carried no key). Consumers that used to
  * count or link `commands/*.md` therefore need the union:
  *
- *   commands/*.md  ∪  skills with explicit `user-invocable: true`
+ *   commands/*.md  ∪  skills whose `user-invocable` is absent or `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
@@ -29,6 +31,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { parseAgentFrontmatter } from './agent-frontmatter.mjs';
+import { isHiddenSourceName } from './plugin-surface.mjs';
 
 /**
  * YAML 1.1 boolean lookalikes that YAML 1.2 / js-yaml's CORE_SCHEMA (what
@@ -85,9 +88,10 @@ function normaliseScalar(text) {
  * 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.
+ * Judges a PRESENT value only: `undefined` returns `false`. Whether an ABSENT
+ * `user-invocable` key makes a skill a slash command is a question about the
+ * whole frontmatter, answered by {@link isUserInvocableSkill} (absent = true,
+ * as Claude Code reads it — #1515).
  *
  * Accepted: the boolean `true`, and a string that normalises to `true`
  * case-insensitively — so `"true"`, `'true'`, `True`, `true # note` and
@@ -155,7 +159,30 @@ export function parseSkillFrontmatter(content) {
 }
 
 /**
- * Names of skills carrying an explicit `user-invocable: true`, sorted.
+ * Claude Code's picker semantics for one parsed SKILL.md frontmatter: the key
+ * ABSENT means invocable; a present key goes through
+ * {@link isUserInvocableValue}. Kept apart from that predicate on purpose —
+ * the sibling marker `disable-model-invocation` shares the value normaliser
+ * but defaults to `false` when absent.
+ *
+ * Every generator (Cursor, Pi, Codex, agents surface) and every counter routes
+ * the skill-level question through here, so an absent key cannot be a slash
+ * command for the census and a non-command for the adapters (#1515 MED-2).
+ * `check-skills` additionally requires the key to be written down, so the
+ * absent branch is the harness-parity fallback, not the expected path.
+ *
+ * @param {Record<string, unknown>|null|undefined} frontmatter
+ * @param {string} [file] path named in a lookalike WARN
+ * @returns {boolean} `false` for a missing/non-object frontmatter (fail-closed)
+ */
+export function isUserInvocableSkill(frontmatter, file) {
+  if (!frontmatter || typeof frontmatter !== 'object') return false;
+  if (!Object.hasOwn(frontmatter, 'user-invocable')) return true;
+  return isUserInvocableValue(frontmatter['user-invocable'], file);
+}
+
+/**
+ * Names of skills that appear in the `/` picker (key absent or `true`), sorted.
  *
  * @param {string} repoRoot plugin root (the directory holding `skills/`)
  * @returns {string[]}
@@ -165,7 +192,7 @@ export function userInvocableSkills(repoRoot) {
   if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
   const names = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory() || isHiddenSourceName(entry.name)) continue;
     const file = path.join(dir, entry.name, 'SKILL.md');
     if (!existsSync(file) || !statSync(file).isFile()) continue;
     let fm;
@@ -174,7 +201,7 @@ export function userInvocableSkills(repoRoot) {
     } catch {
       continue;
     }
-    if (fm && isUserInvocableValue(fm['user-invocable'], file)) names.push(entry.name);
+    if (fm && isUserInvocableSkill(fm, file)) names.push(entry.name);
   }
   return names.sort();
 }
@@ -184,7 +211,7 @@ 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('.'))
+    .filter((f) => f.endsWith('.md') && !isHiddenSourceName(f))
     .map((f) => f.replace(/\.md$/, ''))
     .sort();
 }