session-orchestrator 5.3.0 → 5.5.0

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

@@ -22,9 +22,14 @@
  * Here `src` is defined by NEGATION, so a new top-level directory joins the
  * denominator the moment it is committed, with no rule edit and no re-derivation.
  *
- *   universe     `git ls-files`, filtered to CODE_EXTENSIONS
- *   numerator    tracked code under `tests/`
+ *   universe     `git ls-files`, filtered to CODE_EXTENSIONS, minus declaration
+ *                files (`*.d.ts`, `*.d.mts`, `*.d.cts` — types, not executable code)
+ *   numerator    tracked code under a top-level `tests/`, plus co-located tests
+ *                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
  *
@@ -37,8 +42,8 @@
  *   Only git-tracked?                     YES — reproducible at a SHA, and it is
  *                                         what keeps node_modules/, coverage/ and
  *                                         untracked scratch out without an ignore list.
- *   Do `tests/fixtures/` count as test LOC? YES when they are code (`.mjs`/`.js`/
- *                                         `.cjs`). A code fixture is maintained
+ *   Do `tests/fixtures/` count as test LOC? YES when they are code (any of
+ *                                         CODE_EXTENSIONS). A code fixture is maintained
  *                                         code that exists only to serve the suite —
  *                                         that is test-corpus cost. Non-code
  *                                         fixtures (`.json`, `.jsonl`, `.md`) are
@@ -62,7 +67,9 @@
  *   <repo-root>    defaults to process.cwd()
  *   --json         emit a single JSON object on stdout, nothing else
  *   --check        exit 1 when the ratio exceeds the ceiling (consolidation
- *                  wave required); exit 0 when inside the corridor
+ *                  wave required); exit 3 when the ratio is not measurable
+ *                  (`reason: 'no-tests-found'`, #1451); exit 0 when inside
+ *                  the corridor
  *   --ceiling <n>  override the TV-003 ceiling (default 1.60)
  *   --stdin        take newline-separated paths from stdin instead of
  *                  enumerating via `git ls-files` (test seam / staged-only mode)
@@ -71,6 +78,12 @@
  *   0 — measurement completed (and, under --check, ratio is within the corridor)
  *   1 — --check only: ratio exceeds the ceiling
  *   2 — tool error (missing/unreadable root, bad argv)
+ *   3 — --check only: ratio not measurable — 0 test files counted while test-like
+ *       files ARE tracked (`reason: 'no-tests-found'`, e.g. a Python repo whose
+ *       `tests/test_*.py` sit outside CODE_EXTENSIONS). Fail-closed since #1451:
+ *       before, such a repo read `ratio 0, withinCorridor true` — "not found"
+ *       reported as "in corridor". TypeScript tests count since the 2026-10-01
+ *       owner decision on #1451; other stacks still get "not measurable".
  */
 
 import { readFileSync, existsSync, statSync } from 'node:fs';
@@ -90,23 +103,85 @@ import { isMainModule } from './is-main-module.mjs';
  * Applied symmetrically to numerator and denominator by construction — a file
  * type can never inflate one side while being invisible to the other.
  */
-export const CODE_EXTENSIONS = Object.freeze(['.mjs', '.js', '.cjs']);
+export const CODE_EXTENSIONS = Object.freeze([
+  '.mjs',
+  '.js',
+  '.cjs',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+]);
 
-/** Path prefix that makes a tracked code file part of the TEST corpus. */
+/**
+ * TypeScript declaration files end in a CODE_EXTENSION but carry only types —
+ * no executable line a test could exercise. Excluded from BOTH sides, so a
+ * generated `.d.ts` can never move the ratio.
+ */
+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/`
+ * regardless of extension. Used only to tell "this repo has no tests" apart from
+ * "this repo has tests the recipe cannot see" (#1451) — e.g. `tests/test_x.py`.
+ */
+const TEST_LIKE_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * @param {string} relPath repo-relative path
+ * @returns {boolean}
+ */
+export function isTestLikePath(relPath) {
+  const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
+  return TEST_LIKE_RE.test(p) || p.startsWith(TEST_PREFIX) || /(^|\/)__tests__\//.test(p);
+}
+
 /** The TV-003 ceiling. Exceeding it switches the consolidation rule on. */
 export const DEFAULT_CEILING = 1.6;
 
 /** Machine-readable schema tag for the --json envelope. */
-export const SCHEMA = 'tests-src-ratio/1';
+export const SCHEMA = 'tests-src-ratio/2';
 
 /**
  * Which bucket a repo-relative path belongs to.
  *
- * `src` is defined by NEGATION — every tracked code file that is not under
- * `tests/`. That is what makes the two buckets a partition rather than two
- * globs that can overlap or leave a gap.
+ * `src` is defined by NEGATION — every tracked code file that is not a test
+ * (under `tests/`, or co-located per COLOCATED_TEST_RE). That is what makes the
+ * two buckets a partition rather than two globs that can overlap or leave a gap.
+ *
+ * Known blind spot: a nested `pkg/tests/helper.ts` that is not itself named
+ * `*.test.*` counts as src — only the TOP-LEVEL `tests/` is a test directory.
  *
  * @param {string} relPath repo-relative path, `/`-separated
  * @returns {'test'|'src'|null} null = outside the metric entirely
@@ -114,7 +189,22 @@ export const SCHEMA = 'tests-src-ratio/1';
 export function classifyPath(relPath) {
   const p = String(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
   if (!CODE_EXTENSIONS.some((ext) => p.endsWith(ext))) return null;
-  return p === TEST_PREFIX.slice(0, -1) || p.startsWith(TEST_PREFIX) ? 'test' : 'src';
+  if (DECLARATION_SUFFIXES.some((ext) => p.endsWith(ext))) return null;
+  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';
 }
 
 /**
@@ -154,7 +244,10 @@ export function countPhysicalLines(content) {
  * @param {(relPath: string) => string|null} opts.readFile returns content, or null when unreadable
  * @param {number} [opts.ceiling]
  * @returns {{testFiles:number,testLoc:number,srcFiles:number,srcLoc:number,ratio:number|null,
- *            ceiling:number,withinCorridor:boolean,consolidationWaveRequired:boolean,skipped:number}}
+ *            ceiling:number,withinCorridor:boolean|null,consolidationWaveRequired:boolean|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;
@@ -162,8 +255,32 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
   let srcFiles = 0;
   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);
@@ -183,6 +300,27 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
 
   // A repo with no src code has an undefined ratio, not an infinite one. Saying
   // `null` keeps the consumer from reading Infinity as a corridor breach.
+  // Fail closed (#1451): a zero numerator next to tracked test-like files means
+  // the recipe cannot SEE this repo's tests (e.g. `tests/test_x.py`), not that
+  // there are none. Reporting ratio 0 / withinCorridor true there turned "not found"
+  // into "green". The verdict is unknown, so every verdict field is null.
+  if (testFiles === 0 && testLikeFilesSeen > 0) {
+    return {
+      testFiles,
+      testLoc,
+      srcFiles,
+      srcLoc,
+      ratio: null,
+      ceiling,
+      withinCorridor: null,
+      consolidationWaveRequired: null,
+      skipped,
+      testLikeFilesSeen,
+      reason: 'no-tests-found',
+      excludedScope: { shell },
+    };
+  }
+
   const ratio = srcLoc === 0 ? null : Number((testLoc / srcLoc).toFixed(4));
   const withinCorridor = ratio === null ? true : ratio <= ceiling;
 
@@ -196,6 +334,9 @@ export function measure({ files, readFile, ceiling = DEFAULT_CEILING }) {
     withinCorridor,
     consolidationWaveRequired: !withinCorridor,
     skipped,
+    testLikeFilesSeen,
+    reason: null,
+    excludedScope: { shell },
   };
 }
 
@@ -208,11 +349,21 @@ export function definitionOf(source) {
   return {
     source: source === 'stdin' ? 'stdin path list' : 'git ls-files (tracked files only)',
     codeExtensions: [...CODE_EXTENSIONS],
-    numerator: `tracked code files under ${TEST_PREFIX}`,
+    declarationsExcluded: [...DECLARATION_SUFFIXES],
+    numerator:
+      `tracked code files under a top-level ${TEST_PREFIX}, plus co-located tests anywhere: ` +
+      'basename *.test.<ext> / *.spec.<ext>, or any file under a __tests__/ directory',
     denominator: `every OTHER tracked code file (src defined by negation, not by a directory list)`,
     lineRule: 'physical lines; blank + comment lines counted; EOF-newline-insensitive',
     excluded:
-      'non-code extensions (.md, .json, .jsonl, .yml) on BOTH sides; untracked files (node_modules/, coverage/, scratch)',
+      `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.',
   };
 }
 
@@ -322,7 +473,11 @@ const USAGE =
  * because a measurement problem must not block a session start.
  *
  * @param {{ repoRoot?: string, ceiling?: number }} [opts]
- * @returns {{ severity: 'warn', message: string, ratio: number, ceiling: number } | null}
+ * The one non-null path besides a breach is `reason: 'no-tests-found'` (#1451):
+ * a repo whose tests the recipe cannot see gets a WARN, never silence — silence
+ * is what made the unmeasurable ratio read as green fleet-wide.
+ *
+ * @returns {{ severity: 'warn', message: string, ratio: number|null, ceiling: number, reason?: string } | null}
  */
 export function checkTestsSrcRatio({ repoRoot, ceiling = DEFAULT_CEILING } = {}) {
   try {
@@ -342,6 +497,18 @@ export function checkTestsSrcRatio({ repoRoot, ceiling = DEFAULT_CEILING } = {})
     };
 
     const result = measure({ files, readFile, ceiling });
+    if (result.reason === 'no-tests-found') {
+      return {
+        severity: 'warn',
+        ratio: null,
+        ceiling: result.ceiling,
+        reason: result.reason,
+        message:
+          `⚠ tests:src ratio nicht messbar — 0 Testdateien gezählt, ` +
+          `${result.testLikeFilesSeen} test-artige Dateien getrackt (#1451). ` +
+          `Detail: node scripts/lib/tests-src-ratio.mjs --json`,
+      };
+    }
     if (result.ratio === null || result.withinCorridor) return null;
 
     const dirty = isDirty(root);
@@ -402,17 +569,23 @@ function main() {
     console.log(USAGE);
     console.log('');
     console.log('The canonical tests:src LOC measurement for TV-003 (test-value.md).');
-    console.log('  numerator    tracked code under tests/');
+    console.log('  numerator    tracked code under tests/, plus *.test.* / *.spec.* / __tests__/ anywhere');
     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');
-    console.log('  --check        exit 1 when the ratio exceeds the ceiling');
+    console.log('  --check        exit 1 when the ratio exceeds the ceiling, 3 when not measurable');
     console.log(`  --ceiling <n>  override the TV-003 ceiling (default ${DEFAULT_CEILING})`);
     console.log('  --stdin        read newline-separated paths instead of git ls-files');
     console.log('');
-    console.log('Exit: 0 ok / within corridor · 1 (--check) ceiling exceeded · 2 tool error');
+    console.log(
+      'Exit: 0 ok / within corridor · 1 (--check) ceiling exceeded · 2 tool error · 3 (--check) not measurable',
+    );
     process.exit(0);
   }
 
@@ -460,18 +633,37 @@ function main() {
     // fail-open class is not worth re-litigating per payload size.
     writeStdoutLineSync(JSON.stringify(envelope, null, 2));
   } else {
-    const r = result.ratio === null ? 'n/a (no src code)' : result.ratio.toFixed(4);
-    const verdict = result.withinCorridor
-      ? 'within corridor'
-      : `ABOVE ceiling ${result.ceiling} — TV-003 consolidation wave required`;
+    const notMeasurable = result.reason === 'no-tests-found';
+    const r = notMeasurable
+      ? 'n/a (no tests found)'
+      : result.ratio === null
+        ? 'n/a (no src code)'
+        : result.ratio.toFixed(4);
+    const verdict = notMeasurable
+      ? `NOT MEASURABLE — ${result.testLikeFilesSeen} test-like files tracked but 0 counted (#1451)`
+      : result.withinCorridor
+        ? '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' : ''),
     );
   }
 
+  if (args.check && result.reason === 'no-tests-found') {
+    console.error(
+      `tests:src ratio not measurable — 0 test files counted but ${result.testLikeFilesSeen} ` +
+        `test-like files tracked (no-tests-found); see #1451`,
+    );
+    process.exit(3);
+  }
   process.exit(args.check && !result.withinCorridor ? 1 : 0);
 }
 

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

@@ -25,6 +25,7 @@
 
 import path from 'node:path';
 import { resolveStateDir } from '../platform.mjs';
+import { shellQuote } from '../sh-quote.mjs';
 import { detectVcsCommand } from './vcs-detector.mjs';
 import { isSessionCollision } from './tmux-shell.mjs';
 
@@ -48,17 +49,6 @@ try {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Single-quote a shell command string for use as a tmux send-keys argument.
- * Escapes embedded single-quotes using the POSIX `'...' '\'' '...'` pattern.
- *
- * @param {string} s
- * @returns {string}  e.g. 'tail -F /path/to/STATE.md'
- */
-function shellQuote(s) {
-  return "'" + String(s).replace(/'/g, "'\\''") + "'";
-}
-
 /** Poll interval (seconds) of the agent-status pane loop. */
 const STATUS_PANE_POLL_SECONDS = 2;
 

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.

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

@@ -6,6 +6,8 @@
 
 import { execSync } from 'node:child_process';
 
+import { shellQuote } from '../sh-quote.mjs';
+
 const MIN_MAJOR = 3;
 const MIN_MINOR = 0;
 
@@ -69,14 +71,3 @@ export function isSessionCollision(sessionName) {
     return { exists: false, error: `tmux has-session failed: ${err.message}` };
   }
 }
-
-/**
- * Shell-quote a string for safe interpolation into a shell command.
- * Uses single-quote wrapping with embedded single-quote escaping.
- *
- * @param {string} s
- * @returns {string}
- */
-function shellQuote(s) {
-  return "'" + String(s).replace(/'/g, "'\\''") + "'";
-}

package/scripts/lib/ux-grill/reconcile.mjs

@@ -187,7 +187,7 @@ export function buildIssueBody(finding, context) {
   if (!buildIssueBodyDeprecationWarned) {
     buildIssueBodyDeprecationWarned = true;
     console.warn(
-      '[deprecated] buildIssueBody from scripts/lib/ux-grill/reconcile.mjs is deprecated since 5.3.0 ' +
+      '[deprecated] buildIssueBody from scripts/lib/ux-grill/reconcile.mjs is deprecated since the 5.3 line ' +
         'and will be removed in 6.0.0 — use buildUxGrillIssueBody instead.',
     );
   }

package/scripts/lib/validate/check-agents.mjs

@@ -327,7 +327,7 @@ if (mdFiles.length === 0) {
       if (modelVal === null || (!ALLOWED_MODEL_ALIASES.has(modelVal) && !MODEL_ID_RE.test(modelVal))) {
         const got = modelVal ?? '';
         const aliasList = [...ALLOWED_MODEL_ALIASES].join('|');
-        fail(`${agentName}: model must be ${aliasList} or a full model ID like 'claude-opus-4-7' or 'claude-sonnet-5' (got: '${got}')`);
+        fail(`${agentName}: model must be ${aliasList} or a full model ID like 'claude-opus-5-5' or 'claude-sonnet-5' (got: '${got}')`);
       }
     }
 

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -113,6 +113,11 @@ const DOCUMENTED_ASYMMETRIES = {
         'skill-invocation-telemetry.mjs',
         'enforce-scope.mjs',
         'config-protection.mjs',
+        // pre-edit-sessions-ledger-guard (#1443): same Edit/Write/MultiEdit tool-name
+        // gate as enforce-scope/config-protection above — Codex writes files through
+        // `apply_patch`, a name this hook never matches. Wired, it would run and allow
+        // everything: a silent no-op, not enforcement. Gap registered, not faked.
+        'pre-edit-sessions-ledger-guard.mjs',
         'pre-bash-destructive-guard.mjs',
         'pre-bash-staging-fence.mjs',
         'pre-bash-memory-propose-audit.mjs',