session-orchestrator 5.4.0 → 5.5.0

package/scripts/lib/tail-window.mjs

@@ -16,6 +16,18 @@
 
 import fs from 'node:fs';
 
+/**
+ * `open(2)` flags of a `noFollow` read. `O_NOFOLLOW` refuses a symlink as the
+ * last path component (ELOOP) in the open itself; `O_NONBLOCK` makes the
+ * read-side open of a FIFO return at once instead of blocking until a writer
+ * appears (a plain `'r'` open of a planted FIFO blocked a detached scan child
+ * for good — reproduced 2026-10-02, #1487). On a regular file `O_NONBLOCK`
+ * changes nothing. Both are POSIX-only; Node leaves them undefined on Windows,
+ * where the read degrades to a plain open.
+ */
+const NO_FOLLOW_READ_FLAGS = fs.constants.O_RDONLY
+  | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+
 /**
  * Read the last `maxBytes` of `file` as UTF-8.
  *
@@ -28,14 +40,26 @@ import fs from 'node:fs';
  * THROWS on any fs error (ENOENT, EACCES, …) — mapping the failure is the
  * caller's decision.
  *
+ * `opts.noFollow` is for a file a hostile local writer may have replaced: it
+ * opens with {@link NO_FOLLOW_READ_FLAGS} and then refuses anything the
+ * descriptor's `fstat` does not call a regular file (FIFO, directory, device),
+ * so a symlink throws ELOOP and every other non-regular file throws
+ * `ERR_NOT_REGULAR_FILE` — never a blocked open, never a read of a link
+ * target. The default (`false`) is the plain `'r'` open every other caller uses.
+ *
  * @param {string} file
  * @param {number} maxBytes  window size in bytes (> 0)
+ * @param {{noFollow?: boolean}} [opts]
  * @returns {{ text: string, cut: boolean, size: number }}  `size` is the file size at open time
  */
-export function readTailWindow(file, maxBytes) {
-  const fd = fs.openSync(file, 'r');
+export function readTailWindow(file, maxBytes, { noFollow = false } = {}) {
+  const fd = fs.openSync(file, noFollow ? NO_FOLLOW_READ_FLAGS : 'r');
   try {
-    const size = fs.fstatSync(fd).size;
+    const stats = fs.fstatSync(fd);
+    if (noFollow && !stats.isFile()) {
+      throw Object.assign(new Error('not a regular file'), { code: 'ERR_NOT_REGULAR_FILE' });
+    }
+    const size = stats.size;
     const want = Math.min(size, maxBytes);
     const start = size - want;
     const buf = Buffer.allocUnsafe(want);

package/scripts/lib/telemetry/pricing.mjs

@@ -122,9 +122,12 @@ export const PRICING_TABLE = Object.freeze({
   //
   // Ceiling: a model absent from this table prices as null, never at a neighbour's rate, so the
   // rollup reports `total_cost_usd: null` and `cost_records_priced < cost_records_total` — the
-  // intended way missing evidence shows up. That ratio also drops below 1 for records no row can
+  // intended way missing evidence shows up. That ratio also drops below 1 for agents no row can
   // fix: a token-less record (transcript over the hook's size cap, without usage turns, or
-  // unreadable) and a record with a token-bearing turn that names no model (#1475). Revisit when
+  // unreadable), a record with a token-bearing turn that names no model (#1475), a started agent
+  // whose stop found no transcript of its own, and an agent seen only in schema_version 1 records
+  // (#1487 Pkt 1). The one complete list is the `session-token-rollup.mjs` module doc — the code
+  // that decides; this comment and `emit-session.mjs` only point at it (#1498). Revisit when
   // an unpriced record names a model id absent from this table: add that model as its own
   // evidenced row, never as a family prefix or an alias to another generation.
   'claude-fable-5-1': usd({ input: 10.0, cache_read: 0.25, cache_creation: 12.5, output: 50.0 }),

package/scripts/lib/telemetry/sync.mjs

@@ -312,6 +312,23 @@ export function readSessionProfileForMetricsDir(metricsDir) {
   }
 }
 
+/**
+ * Events window this reader needs retained (#1401 part 3), in days — a CHOSEN
+ * ceiling, not a derived value. `deriveSessionFromEvents` loads the whole
+ * rotated ledger (no time filter) and keeps the LATEST
+ * `orchestrator.session.started`, so what it needs retained is that one
+ * record; 1 day is the assumed maximum age of that record when a flush reads
+ * it. Nothing in this module bounds that age: `buildBatch`'s
+ * `[now - DAILY_FLUSH_MS, now]` cutoff filters `skill-invocations.jsonl`, not
+ * the events ledger. CEILING (BV-004): a latest `session.started` older than a
+ * day at flush time (a session running longer than that) is found only if
+ * retention happens to reach it; revisit if that becomes common. Read by
+ * `scripts/lib/events-retention-banner.mjs`.
+ *
+ * @type {number}
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = 1;
+
 /**
  * Reconstruct the session facts a ping needs (`session_type`, `started_at`,
  * `completed_at`) from `<metricsDir>/events.jsonl` when `sessions.jsonl` has no

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

@@ -28,6 +28,8 @@
  *                anywhere: basename `*.test.<ext>` / `*.spec.<ext>`, or any file
  *                under a `__tests__/` directory
  *   denominator  every OTHER tracked code file
+ *   reported     tracked shell (EXCLUDED_SHELL_EXTENSIONS) — in NEITHER bucket,
+ *                its volume shipped as `excludedScope.shell` (#1488, variant B)
  *
  * ## The four questions, answered in code rather than left open
  *
@@ -122,12 +124,32 @@ export const DECLARATION_SUFFIXES = Object.freeze(['.d.ts', '.d.mts', '.d.cts'])
 /** Top-level path prefix that makes a tracked code file part of the TEST corpus. */
 export const TEST_PREFIX = 'tests/';
 
+/**
+ * Shell extensions the ratio deliberately does NOT count (#1488, owner decision
+ * 2026-10-02, variant B): they stay out of numerator and denominator, but their
+ * volume is MEASURED and reported under `excludedScope.shell`, so "this repo has
+ * no shell" and "this repo has 2.5k unmeasured shell lines" stop looking alike.
+ * Detection is by extension only — an extensionless shebang script (`.husky/*`)
+ * is not seen; sniffing shebangs would mean reading every extensionless tracked
+ * file inside a synchronous session-start probe.
+ */
+export const EXCLUDED_SHELL_EXTENSIONS = Object.freeze(['.sh', '.bash', '.bats']);
+
 /**
  * Co-located test files, wherever they sit: a `*.test.<ext>` / `*.spec.<ext>`
  * basename (the vitest/jest default include shape) or a `__tests__/` segment.
  */
 const COLOCATED_TEST_RE = /\.(test|spec)\.[^./]+$|(^|\/)__tests__\//;
 
+/**
+ * The one test-corpus rule, shared by the counted code buckets and the reported
+ * shell scope so the two can never split a path differently.
+ * @param {string} p normalised repo-relative path
+ */
+function isTestCorpusPath(p) {
+  return p.startsWith(TEST_PREFIX) || COLOCATED_TEST_RE.test(p);
+}
+
 /**
  * A tracked path that LOOKS like a test, counted or not: a `*.test.*` / `*.spec.*`
  * JS/TS file, anything under a `__tests__/` segment, or any file under `tests/`
@@ -168,7 +190,21 @@ export function classifyPath(relPath) {
   const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
   if (!CODE_EXTENSIONS.some((ext) => p.endsWith(ext))) return null;
   if (DECLARATION_SUFFIXES.some((ext) => p.endsWith(ext))) return null;
-  return p.startsWith(TEST_PREFIX) || COLOCATED_TEST_RE.test(p) ? 'test' : 'src';
+  return isTestCorpusPath(p) ? 'test' : 'src';
+}
+
+/**
+ * Which half of the EXCLUDED shell scope a path falls into — reported, never
+ * counted in the ratio. `.bats` is a test framework's own extension, so it is
+ * test-shell anywhere; any other shell file follows the code rule above.
+ *
+ * @param {string} relPath repo-relative path
+ * @returns {'test'|'src'|null} null = not shell
+ */
+function classifyShellPath(relPath) {
+  const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!EXCLUDED_SHELL_EXTENSIONS.some((ext) => p.endsWith(ext))) return null;
+  return p.endsWith('.bats') || isTestCorpusPath(p) ? 'test' : 'src';
 }
 
 /**
@@ -209,7 +245,9 @@ export function countPhysicalLines(content) {
  * @param {number} [opts.ceiling]
  * @returns {{testFiles:number,testLoc:number,srcFiles:number,srcLoc:number,ratio:number|null,
  *            ceiling:number,withinCorridor:boolean|null,consolidationWaveRequired:boolean|null,
- *            skipped:number,testLikeFilesSeen:number,reason:'no-tests-found'|null}}
+ *            skipped:number,testLikeFilesSeen:number,reason:'no-tests-found'|null,
+ *            excludedScope:{shell:{files:number,loc:number,testFiles:number,testLoc:number,
+ *                                  srcFiles:number,srcLoc:number,skipped:number}}}}
  */
 export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
   let testFiles = 0;
@@ -218,9 +256,31 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
   let srcLoc = 0;
   let skipped = 0;
   let testLikeFilesSeen = 0;
+  // Reported only — never added to testLoc/srcLoc (#1488 variant B). Always
+  // present, zeros included: a measured zero, not an absent measurement.
+  const shell = { files: 0, loc: 0, testFiles: 0, testLoc: 0, srcFiles: 0, srcLoc: 0, skipped: 0 };
 
   for (const rel of files) {
     if (isTestLikePath(rel)) testLikeFilesSeen++;
+    const shellBucket = classifyShellPath(rel);
+    if (shellBucket !== null) {
+      const content = readFile(rel);
+      if (content === null || content === undefined) {
+        shell.skipped++;
+        continue;
+      }
+      const lines = countPhysicalLines(content);
+      shell.files++;
+      shell.loc += lines;
+      if (shellBucket === 'test') {
+        shell.testFiles++;
+        shell.testLoc += lines;
+      } else {
+        shell.srcFiles++;
+        shell.srcLoc += lines;
+      }
+      continue;
+    }
     const bucket = classifyPath(rel);
     if (bucket === null) continue;
     const content = readFile(rel);
@@ -257,6 +317,7 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
       skipped,
       testLikeFilesSeen,
       reason: 'no-tests-found',
+      excludedScope: { shell },
     };
   }
 
@@ -275,6 +336,7 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
     skipped,
     testLikeFilesSeen,
     reason: null,
+    excludedScope: { shell },
   };
 }
 
@@ -297,6 +359,11 @@ export function definitionOf(source) {
       `declaration files (${DECLARATION_SUFFIXES.map((x) => `*${x}`).join(', ')}: types, not ` +
       'executable code) and non-code extensions (.md, .json, .jsonl, .yml) on BOTH sides; ' +
       'untracked files (node_modules/, coverage/, scratch)',
+    excludedScope:
+      `shell (${EXCLUDED_SHELL_EXTENSIONS.join(' ')}, by extension only — extensionless shebang ` +
+      'scripts such as .husky/ hooks are not seen): counted in NEITHER bucket, its volume ' +
+      'reported under excludedScope.shell (#1488). test-shell = .bats anywhere, or the ' +
+      'numerator path rule above; every other shell file is src-shell. Same line rule.',
   };
 }
 
@@ -506,6 +573,9 @@ function main() {
     console.log('  denominator  every other tracked code file (src by negation)');
     console.log(`  code exts    ${CODE_EXTENSIONS.join(' ')}   (.md / .json never counted)`);
     console.log(`  excluded     declaration files ${DECLARATION_SUFFIXES.join(' ')} on both sides`);
+    console.log(
+      `  shell        ${EXCLUDED_SHELL_EXTENSIONS.join(' ')} counted nowhere, volume reported (excludedScope.shell)`,
+    );
     console.log('  lines        physical; blanks + comments counted; EOF-newline-insensitive');
     console.log('');
     console.log('  --json         machine-readable envelope on stdout');
@@ -575,9 +645,14 @@ function main() {
         ? 'within corridor'
         : `ABOVE ceiling ${result.ceiling} — TV-003 consolidation wave required`;
     const at = envelope.ref ? ` @ ${envelope.ref}${dirty ? '+dirty' : ''}` : '';
+    const sh = result.excludedScope.shell;
     writeStdoutLineSync(
       `tests:src = ${r}  (${result.testLoc} test LOC / ${result.srcLoc} src LOC` +
         `; ${result.testFiles} test + ${result.srcFiles} src files${at}) — ${verdict}` +
+        (sh.files > 0
+          ? `\n  excluded: shell ${sh.files} files / ${sh.loc} lines ` +
+            `(${sh.testFiles} test + ${sh.srcFiles} src files) — in neither bucket (#1488)`
+          : '') +
         (dirty ? '\n  NOTE: working tree is dirty — this number is NOT reproducible at that SHA' : ''),
     );
   }

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

@@ -23,6 +23,18 @@ const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 /** Every event this module reports on carries this prefix. */
 const TMUX_EVENT_PREFIX = 'tmux-layout.';
 
+/**
+ * Events window this reader needs retained (#1401 part 3): UNBOUNDED, hence
+ * `null`. The stats are an ALL-TIME rate, so every record ever written is in
+ * scope and no finite `events-rotation` retention satisfies it — a number here
+ * could only be invented. Truncation is reported by the envelope's own
+ * `complete: false` (pruned archives leave rotation tombstones), not by a
+ * retention floor. Read by `scripts/lib/events-retention-banner.mjs`.
+ *
+ * @type {number|null}
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
 /**
  * Read the tmux-layout events ACROSS rotation boundaries, together with the
  * honesty verdict of that read.