session-orchestrator 3.22.0 → 3.24.0

package/scripts/promote-vault-strict.mjs

@@ -23,6 +23,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { expandTilde } from './lib/common.mjs';
 
 const COMMIT_MSG = 'chore(orchestrator): Promote vault-integration to strict mode — refs #305';
 
@@ -53,18 +54,6 @@ const noBaseline = args.includes('--no-baseline');
 const repoIdx = args.indexOf('--repo');
 const singleRepo = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : null;
 
-// ---------------------------------------------------------------------------
-// Path resolution
-// ---------------------------------------------------------------------------
-
-/** Expand leading ~ to the user's home directory. */
-function expandHome(p) {
-  if (p.startsWith('~/')) {
-    return join(homedir(), p.slice(2));
-  }
-  return p;
-}
-
 // ---------------------------------------------------------------------------
 // Vault-integration mode replacement
 // ---------------------------------------------------------------------------
@@ -424,7 +413,7 @@ async function main() {
 
   if (singleRepo) {
     // Single-repo mode
-    const absRepo = expandHome(singleRepo);
+    const absRepo = expandTilde(singleRepo);
     const singleRoot = getConfinementRoot();
     const singleGuard = validatePathInsideProject(absRepo, singleRoot);
     if (!singleGuard.ok) {
@@ -449,7 +438,7 @@ async function main() {
 
     const batchRoot = getConfinementRoot();
     for (const rawPath of eligibleRepos) {
-      const absRepo = expandHome(rawPath);
+      const absRepo = expandTilde(rawPath);
       const guard = validatePathInsideProject(absRepo, batchRoot);
       if (!guard.ok) {
         process.stderr.write(
@@ -469,7 +458,7 @@ async function main() {
         (p) => p === 'projects-baseline' || p.endsWith('/projects-baseline')
       );
       if (baselineEntry) {
-        const baselineRepoDir = expandHome(
+        const baselineRepoDir = expandTilde(
           baselineEntry.startsWith('~') || baselineEntry.startsWith('/')
             ? baselineEntry
             : `~/Projects/${baselineEntry}`

package/scripts/site-numbers.mjs

@@ -79,6 +79,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -401,10 +402,31 @@ export const METRIC_DEFS = Object.freeze([
     // Gitignored ledger (`.gitignore`: local-only observability data) — absent
     // in every fresh clone, CI checkout and tarball build.
     snapshotFallback: true,
-    source: 'grep -c . .orchestrator/metrics/sessions.jsonl',
+    // #1186: `grep -c` over-counts — sessions.jsonl is append-only, so the same
+    // physical session can carry more than one line (crash-recovery re-appends,
+    // #1068 stub/supersede pairs). readCanonicalSessions collapses those to one
+    // record per session_id before the count; see scripts/lib/sessions-canonical.mjs
+    // for the three collapse rules. `learnings` below stays a raw line count —
+    // that ledger has no session_id-shaped identity to dedupe on.
+    // Measured on THIS repo's own ledger @ 2ccea0f2: raw line count 289 vs
+    // canonical (deduped) count 278 — an over-count of 11 records, which is the
+    // bug's magnitude this migration removes.
+    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186)',
     compute: (root) => {
-      const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', 'sessions.jsonl'));
-      return r === null ? null : fmtCount(r.entries);
+      const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+      // Same absent/non-file guard as countJsonlEntries, kept explicit here
+      // because readCanonicalSessions returns [] (not null) on a missing ledger
+      // — collapsing that into fmtCount(0) would silently defeat the
+      // snapshotFallback precedence above (a fresh clone would report "0
+      // sessions" instead of falling back to the tracked snapshot).
+      if (!existsSync(file) || !statSync(file).isFile()) return null;
+      // Same reader every other #1186 consumer uses (autopilot.mjs,
+      // build-live-signals.mjs, telemetry/sync.mjs) — a record with no
+      // `session_id` is dropped rather than counted, because it cannot be
+      // identified for dedup. Measured @ 2ccea0f2 on this repo's own ledger:
+      // 0 such rows (raw 289 lines == 289 identified), so the drop is inert
+      // here; it only matters for a future malformed/legacy row.
+      return fmtCount(readCanonicalSessions({ filePath: file }).length);
     },
   },
   {
@@ -623,7 +645,17 @@ export function collect(root) {
   ]) {
     const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', file));
     if (r && r.malformed > 0) {
-      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — the ${name} count includes them`);
+      // #1186: the two ledgers now disagree on what a malformed line DOES to
+      // the published count. `learnings` is still the raw countJsonlEntries
+      // total, which counts a malformed line as an entry regardless of its
+      // content. `sessions` is readCanonicalSessions, whose parse loop skips a
+      // line it cannot JSON.parse — so a malformed session line is silently
+      // ABSENT from the count rather than included in it.
+      const consequence =
+        name === 'sessions'
+          ? `they are DROPPED from the sessions count (readCanonicalSessions skips unparseable lines)`
+          : `the ${name} count includes them`;
+      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — ${consequence}`);
     }
   }
 

package/scripts/token-audit.sh

@@ -141,8 +141,15 @@ if [ -f "$CLAUDE_SETTINGS" ]; then
         fi
     fi
 
-    # Count enabled plugins
-    plugin_count=$(grep -c ': true' "$CLAUDE_SETTINGS" 2>/dev/null || echo "0")
+    # Count enabled plugins.
+    # `|| true` rather than `|| echo "0"`: grep -c ALREADY prints 0 on no-match and
+    # still exits 1, so an echo fallback appends a second line — the capture becomes
+    # "0\n0", which every numeric test downstream rejects (bash-harness-pitfalls.md §1).
+    plugin_count=$(grep -c ': true' "$CLAUDE_SETTINGS" 2>/dev/null || true)
+    # NOTE: after the :-0 default an unreadable file prints the same as "zero
+    # plugins" — accepted, the only consumer is the informational echo below.
+    # The #1077 fix here is the removed double-"0" line, not a failure sentinel.
+    plugin_count=${plugin_count:-0}
     echo "  Enabled plugins: $plugin_count"
 fi
 echo ""

package/scripts/validate-plugin.mjs

@@ -244,6 +244,9 @@ if (runCheck('check-pi-package.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-pi-prompts.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-cursor-adapter.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-session-plan-routing.mjs') !== 0) checkFailed = 1;
 
@@ -315,6 +318,16 @@ runCheck('check-vcs-repo-flag.mjs');
 process.stdout.write('\n');
 runCheck('check-doc-cli-commands.mjs');
 
+// BLOCKING (#1176): a `scripts/**.mjs` path cited in skills/, commands/ or
+// agents/ prose that does not exist. Unlike the WARN-only check above, the
+// oracle is this repository's own filesystem — no version skew of a foreign
+// binary can red an unrelated commit, so a finding is always a real defect.
+// A deliberately absent path is annotated in place:
+// `<!-- path-check: planned #<iid> | historical | example -->`, honoured on the
+// citation's own line or the line immediately above.
+process.stdout.write('\n');
+if (runCheck('check-skill-script-paths.mjs') !== 0) checkFailed = 1;
+
 // WARN-only: a state-mutating `git` call in tests/ that names no target resolves
 // its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19
 // incident, where fixture commits, a fixture remote and a fixture identity landed
@@ -334,6 +347,22 @@ runCheck('check-doc-cli-commands.mjs');
 process.stdout.write('\n');
 runCheck('check-test-git-config-target.mjs');
 
+// BLOCKING (#1183): every `emitEvent()` call site under hooks/**/*.mjs must be
+// try/catch-guarded (emitEvent() throws EventValidationError on a malformed
+// record — an unguarded call aborts the hook process). Five pre-existing
+// unguarded sites are baselined inside the checker itself and report WARN,
+// never FAIL, so this can be blocking-by-default without going red on
+// arrival; only a NEW unguarded site fails the build.
+process.stdout.write('\n');
+if (runCheck('check-hooks-emit-event-guard.mjs') !== 0) checkFailed = 1;
+
+// BLOCKING (#1184): every scripts/lib/validate/check-*.mjs must be referenced
+// by basename from this file, .husky/pre-commit, or .gitlab-ci.yml — or carry
+// a `// registration: standalone <reason>` header marker declaring itself
+// deliberately CLI-only. A checker nobody runs is built work with no effect.
+process.stdout.write('\n');
+if (runCheck('check-validator-registration.mjs') !== 0) checkFailed = 1;
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/scripts/validate-wave-scope.mjs

@@ -252,6 +252,72 @@ function validateRequired(obj, errors) {
   }
 }
 
+/**
+ * Shape-check ONE optional identifier field: present ⇒ a non-empty string.
+ *
+ * Returns whether the key was PRESENT at all (regardless of validity), so the
+ * caller can distinguish "absent" from "present but malformed" — the two need
+ * different treatment and only the first is a warning.
+ *
+ * An EMPTY string is an error rather than a second flavour of absent, for the
+ * reason `sessionAttribution()` (scripts/lib/events.mjs) already states about
+ * omitting the key: an empty id satisfies a truthiness check while attributing
+ * to nothing. A reader comparing `manifest.session === <own session id>` would
+ * then treat the manifest as FOREIGN (ignore it) where the writer meant
+ * UNBOUND (enforce it) — the two dispositions are opposites, so the ambiguity
+ * is not cosmetic. Absence is the only honest encoding of "not session-bound".
+ *
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @param {string[]} errors
+ * @returns {boolean} true when the key is present (valid or not)
+ */
+function validateOptionalSessionId(obj, key, errors) {
+  if (!(key in obj) || obj[key] === undefined) return false;
+  const value = obj[key];
+  const t = value === null ? 'null' : typeof value;
+  if (t !== 'string') {
+    errors.push(`${key} must be a non-empty string, got type: ${t}`);
+    return true;
+  }
+  if (/** @type {string} */ (value).length === 0) {
+    errors.push(
+      `${key} must be a non-empty string, got: "" — an empty id attributes to nothing; omit the key entirely to declare the manifest unbound`,
+    );
+  }
+  return true;
+}
+
+/**
+ * Validate the OPTIONAL session binding (#1123): `session` (the raw
+ * `session_id` of the session that WROTE this manifest) and its human-readable
+ * twin `semantic_session`. Both come from one `sessionAttribution(repoRoot)`
+ * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest.
+ *
+ * Deliberately NOT part of {@link validateRequired}, and that is a compatibility
+ * constraint rather than a preference: `wave-scope.json` is a shared
+ * working-copy artefact, every manifest written before #1123 lacks the field,
+ * and the pre-union skeleton of § Scope Manifest 3.3 is fed through this very
+ * validator before the union exists. Requiring it would reject manifests the
+ * documented procedure itself produces. The absent case therefore WARNS — the
+ * flip to an error belongs to a later release, once no legacy writer remains.
+ *
+ * @param {Record<string, unknown>} obj
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ */
+function validateSession(obj, errors, warnings) {
+  const present = validateOptionalSessionId(obj, 'session', errors);
+  validateOptionalSessionId(obj, 'semantic_session', errors);
+  if (!present) {
+    warnings.push(
+      'no session field — manifest is not session-bound (legacy, #1123), so every session sharing this ' +
+        'working copy is enforced against it. The writer derives it from sessionAttribution() — see ' +
+        'skills/wave-executor/wave-loop.md § Scope Manifest.',
+    );
+  }
+}
+
 /**
  * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
  * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
@@ -683,6 +749,7 @@ function validate(
   const warnings = [];
 
   validateRequired(obj, errors);
+  validateSession(obj, errors, warnings);
   validateAllowedPaths(obj, errors, warnings);
   validateBlockedCommands(obj, errors);
   validateGates(obj, errors);

package/scripts/vault-consolidate.mjs

@@ -84,10 +84,9 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { pathToFileURL } from 'node:url';
 
-import { die, utcTimestamp } from './lib/common.mjs';
+import { die, utcTimestamp, expandTilde } from './lib/common.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import {
   SCRIPT_NAME,
@@ -150,13 +149,6 @@ Exit codes:
   process.stderr.write(usage);
 }
 
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 async function isDir(p) {
   try {
     const st = await fs.stat(p);
@@ -222,8 +214,8 @@ async function main() {
   const isDryRun = !isApply;
   const isJson = parsed.values.json === true;
 
-  const sourceRoot = path.resolve(expandHome(parsed.values.source ?? DEFAULT_SOURCE));
-  const canonicalRoot = path.resolve(expandHome(parsed.values.canonical ?? DEFAULT_CANONICAL));
+  const sourceRoot = path.resolve(expandTilde(parsed.values.source ?? DEFAULT_SOURCE));
+  const canonicalRoot = path.resolve(expandTilde(parsed.values.canonical ?? DEFAULT_CANONICAL));
 
   // Parse --resolve flags into a Map<relPath, "src"|"dst"|"skip">
   const resolutions = new Map();

package/scripts/vault-integration-watcher.mjs

@@ -31,11 +31,10 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { resolveRepoSpec, redactUrlCredentials } from './lib/vcs-repo-spec.mjs';
+import { expandTilde } from './lib/common.mjs';
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
@@ -332,9 +331,8 @@ async function main() {
   // Load the config-driven repo list before doing any glab work
   const watcherRoot = getConfinementRoot();
   // Home-expand each entry before confinement, matching sibling scripts (W4-Q2 LOW).
-  const expandHome = (p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p);
   const flipRepos = (await getCrossRepoProjects()).filter((r) => {
-    const guard = validatePathInsideProject(expandHome(r), watcherRoot);
+    const guard = validatePathInsideProject(expandTilde(r), watcherRoot);
     if (!guard.ok) {
       process.stderr.write(
         `vault-integration-watcher: WARN rejecting confined-path violation for ${JSON.stringify(r)} (reason: ${guard.reason})\n`