session-orchestrator 5.3.0 → 5.5.0

package/hooks/subagent-telemetry.mjs

@@ -133,7 +133,16 @@ function jsonlPath() {
  * Defense-in-depth byte ceiling for transcript reads (#624). The transcript path
  * is harness-trusted, so this is not an exploitable vector — but the repo follows
  * a bounded-read discipline: a pathologically large transcript is skipped (yields
- * the empty/zero-usage result) rather than read whole into memory.
+ * the null-usage result) rather than read whole into memory.
+ *
+ * CEILING: a skipped transcript yields a stop record with found=true but null
+ * tokens and model; the session rollup counts it as an unpriced cost candidate
+ * (#1474) instead of reading it. Frequency per issue #1474 (2026-09-29): 2 of
+ * 10,482 subagent transcripts exceeded this size. REVISIT when oversized
+ * transcripts exceed ~0.1% of found stop records — count them from transcript
+ * sizes, because the ledger writes the same token-less record for an oversized,
+ * a usage-free and an unreadable transcript — then read large transcripts
+ * streamed instead of skipping them.
  */
 const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // ~50 MB
 
@@ -423,13 +432,23 @@ function readStdinJson() {
  * Four buckets, not two (#1244 / schema_version 2): `input_tokens`,
  * `cache_read_input_tokens`, `cache_creation_input_tokens` and `output_tokens`
  * are accumulated SEPARATELY per deduped turn, because they are billed at three
- * different rates. `model` is captured from `message.model` of the last kept
- * block that carries one (null when absent) — it is what makes a cost estimate
- * possible at all downstream.
+ * different rates. `model` is what makes a cost estimate possible at all
+ * downstream, so it names only a model that actually carried tokens (#1470): a
+ * kept turn is token-bearing when its four clamped buckets sum to > 0. Exactly
+ * one distinct `message.model` across the token-bearing turns → that model;
+ * zero-token turns of another model (a trailing `<synthetic>` turn) are ignored.
+ * Two or more, or a token-bearing turn that names no model → null, an honest
+ * unknown, with the token sums unchanged. No token-bearing turn at all → the
+ * last kept block that carries one (null when absent). Two or more models with
+ * every token-bearing turn named → `modelsUsage` carries the four buckets per
+ * model, so the session rollup can price each part; otherwise it is null.
  *
  * @param {string|undefined|null} transcriptPath — absolute path from stdin
  * @returns {{ tokenInputUncached: number|null, tokenCacheRead: number|null,
- *   tokenCacheCreation: number|null, tokenOutput: number|null, model: string|null }}
+ *   tokenCacheCreation: number|null, tokenOutput: number|null, model: string|null,
+ *   modelsUsage: Array<{ model: string, token_input_uncached: number,
+ *     token_cache_read: number, token_cache_creation: number,
+ *     token_output: number }>|null }}
  */
 function extractTranscriptUsage(transcriptPath) {
   const nullResult = {
@@ -438,6 +457,7 @@ function extractTranscriptUsage(transcriptPath) {
     tokenCacheCreation: null,
     tokenOutput: null,
     model: null,
+    modelsUsage: null,
   };
   try {
     if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return nullResult;
@@ -523,22 +543,73 @@ function extractTranscriptUsage(transcriptPath) {
     let tokenCacheRead = 0;
     let tokenCacheCreation = 0;
     let tokenOutput = 0;
+    /** Last non-null model over ALL kept turns — the zero-token fallback. */
     let model = null;
+    /** Per-model bucket sums of the token-bearing kept turns (#1470). */
+    const billedModels = new Map();
+    /** A token-bearing turn that names no model: its price is unknowable. */
+    let unattributed = false;
+    // Per-turn clamp (#624): a turn's value counts ONLY when it is a non-negative
+    // integer. A poisoned value (negative, NaN, float like 10.5) contributes 0 so
+    // the good turns survive. An absent side contributes 0, not null.
+    const clamp = (value) => (Number.isInteger(value) && value >= 0 ? value : 0);
     for (const { usage, model: turnModel } of kept) {
-      // Per-turn clamp (#624): add a turn's value ONLY when it is a non-negative
-      // integer. A poisoned value (negative, NaN, float like 10.5) is skipped so
-      // the good turns survive. An absent side contributes 0, not null.
-      const inTok = usage.input_tokens;
-      const cacheRead = usage.cache_read_input_tokens;
-      const cacheCreation = usage.cache_creation_input_tokens;
-      const outTok = usage.output_tokens;
-      if (Number.isInteger(inTok) && inTok >= 0) tokenInputUncached += inTok;
-      if (Number.isInteger(cacheRead) && cacheRead >= 0) tokenCacheRead += cacheRead;
-      if (Number.isInteger(cacheCreation) && cacheCreation >= 0) tokenCacheCreation += cacheCreation;
-      if (Number.isInteger(outTok) && outTok >= 0) tokenOutput += outTok;
-      if (turnModel !== null) model = turnModel;
+      const inTok = clamp(usage.input_tokens);
+      const cacheRead = clamp(usage.cache_read_input_tokens);
+      const cacheCreation = clamp(usage.cache_creation_input_tokens);
+      const outTok = clamp(usage.output_tokens);
+      tokenInputUncached += inTok;
+      tokenCacheRead += cacheRead;
+      tokenCacheCreation += cacheCreation;
+      tokenOutput += outTok;
+      const billed = inTok + cacheRead + cacheCreation + outTok > 0;
+      if (turnModel === null) {
+        if (billed) unattributed = true;
+        continue;
+      }
+      model = turnModel;
+      if (!billed) continue;
+      let part = billedModels.get(turnModel);
+      if (part === undefined) {
+        part = {
+          model: turnModel,
+          token_input_uncached: 0,
+          token_cache_read: 0,
+          token_cache_creation: 0,
+          token_output: 0,
+        };
+        billedModels.set(turnModel, part);
+      }
+      part.token_input_uncached += inTok;
+      part.token_cache_read += cacheRead;
+      part.token_cache_creation += cacheCreation;
+      part.token_output += outTok;
     }
 
+    // Model attribution (#1470): only a token-bearing turn is an observation of
+    // its model; one distinct model → that model, two or more → null, none →
+    // the fallback above. A token-bearing turn that names no model also gives
+    // null: its tokens must not be priced at whichever other model was named.
+    // A mixed-model record carries its per-model sums as `modelsUsage`, which
+    // the session rollup prices part by part (#1470). Measured 2026-09-29 over
+    // 10,745 subagent transcripts under `~/.claude/projects`: 17 (0.16%)
+    // contained more than one model on token-bearing turns (0 of 917 in this
+    // repo), while 273 contained more than one model id only through zero-token
+    // `<synthetic>` turns, which this rule ignores. A model-less token-bearing
+    // turn gets no breakdown: its tokens belong to no part, so the record stays
+    // unpriced. The ledger now tells a mixed-model null (`models_usage`
+    // present) from a missing model (absent). The fallback also names the LAST
+    // model of a transcript whose turns all carry 0 tokens — measured 2026-09-29,
+    // 31 of 10,479 records, all `<synthetic>`; the session rollup prices a record
+    // whose four buckets are all 0 at $0 regardless of its model (#1474), so that
+    // name is harmless.
+    let modelsUsage = null;
+    if (unattributed) model = null;
+    else if (billedModels.size > 1) {
+      model = null;
+      modelsUsage = [...billedModels.values()];
+    } else if (billedModels.size === 1) [model] = billedModels.keys();
+
     // The aggregates are guaranteed non-negative integers by per-turn clamping
     // above (Σ of non-negative integers), so emit them directly.
     return {
@@ -547,6 +618,7 @@ function extractTranscriptUsage(transcriptPath) {
       tokenCacheCreation,
       tokenOutput,
       model,
+      modelsUsage,
     };
   } catch {
     return nullResult;
@@ -752,7 +824,7 @@ async function main() {
     // NO fallback to input.transcript_path: that path is the parent session
     // transcript, and reading it is the #949 defect (every stop inherited the
     // parent's running totals). A phantom stop gets null — the honest value.
-    const { tokenInputUncached, tokenCacheRead, tokenCacheCreation, tokenOutput, model } =
+    const { tokenInputUncached, tokenCacheRead, tokenCacheCreation, tokenOutput, model, modelsUsage } =
       subagentTranscriptFound
         ? extractTranscriptUsage(subagentTranscriptPath)
         : {
@@ -761,6 +833,7 @@ async function main() {
             tokenCacheCreation: null,
             tokenOutput: null,
             model: null,
+            modelsUsage: null,
           };
 
     // schema_version 2 (#1244): `token_input` is now BILLABLE PROMPT VOLUME —
@@ -776,11 +849,15 @@ async function main() {
     }
     if (tokenOutput !== null) record.token_output = tokenOutput;
 
-    // Model id (#1244) — null when the transcript exposes none. Cost is NOT
+    // Model id (#1244) — null when the transcript exposes none, or when its
+    // token-bearing turns are not attributable to one model (#1470). Cost is NOT
     // computed here: pricing lives in scripts/lib/telemetry/pricing.mjs and is
     // applied by the session rollup, so this hot-path hook keeps its import
     // graph unchanged.
     record.model = model;
+    // Per-model breakdown (#1470) — written only for a mixed-model record, so
+    // the rollup can price it part by part; absent on every other record.
+    if (modelsUsage !== null) record.models_usage = modelsUsage;
 
     // Cost is best-effort / forward-compat (#624): the native transcript does
     // NOT expose total_cost_usd today, so this is null in practice. No rate

package/hooks/wave-scope-commit-guard.mjs

@@ -22,26 +22,48 @@
 //   agent's fence — i.e. another agent's intent to stage that path.
 //
 // Behavior summary
-//   - No .orchestrator/wave-scope.json → exit 0 (no active wave; sub-mode B
-//     short-circuits). Sub-mode C still runs if a fence directory exists.
-//   - Allowed paths violation → exit 1 with restore hint.
+//   - No wave-scope.json → exit 0 (no active wave; sub-mode B short-circuits).
+//     Sub-mode C still runs if a fence directory exists.
+//   - Sub-mode B, in order (#1493.1): a manifest bound to ANOTHER session is
+//     not this commit's scope (stand down, one stderr note); `enforcement:
+//     "off"` skips.
+//   - Non-empty allowedPaths: a staged path outside it BLOCKS (exit 1) under
+//     every enforcement level, `warn` included. Deliberately not tied to
+//     `enforcement`: in a warn-mode wave enforce-scope lets out-of-scope writes
+//     through, so this guard is the only hard PSA-004 stop left for a
+//     lint-staged sweep — softening it would weaken detection for the very
+//     class it exists to catch.
+//   - EMPTY allowedPaths is no longer a silent pass: a Discovery (read-only)
+//     manifest means no agent is committing, i.e. a coordinator commit between
+//     waves → allow with a note; a manifest older than the newest session
+//     clock may be a leftover or a parallel session's live one → report,
+//     never block; any other role means the `--union` step never completed →
+//     `strict` (the default when the field is absent, as in enforce-scope)
+//     blocks, `warn` reports and lets the commit through. Only this new
+//     verdict follows `enforcement`: it judges the coordinator's own
+//     bookkeeping, not a staged foreign file.
 //   - Cross-agent fence overlap → exit 1 with "staging-fence: cross-agent
 //     overlap" stderr.
 //   - --no-verify bypass: this hook is invoked as a git pre-commit hook;
 //     `git commit --no-verify` skips it entirely (operator opts out by name).
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
 
 // Re-use existing helpers from scripts/lib/hardening.mjs.
 // IMPORTANT: import is resolved relative to THIS file's location (the hook
 // ships with the session-orchestrator package), NOT relative to the git
 // repo it is protecting. The two diverge when the hook is invoked from a
 // consumer repo or a test tmp-dir.
-import { pathMatchesPattern, findScopeFile } from '../scripts/lib/hardening.mjs';
+import { pathMatchesPattern } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
+import { classifyEmptyScope, findOwnScopeFile, sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 
 // Resolve the "current" agent id from SO_WAVE_AGENT_ID (when set by the
 // caller) or fall back to a PID-derived marker. The fence files themselves
@@ -56,19 +78,6 @@ const ownAgentId = process.env.SO_WAVE_AGENT_ID ?? null;
  */
 const ALL_PATHS_MARKER = '*';
 
-/**
- * Build a regex that finds a staged path inside a `git add` command string.
- * Word-boundary on both sides so `src/foo.ts` does not match `src/foo.ts.bak`.
- * The path is escaped so glob metacharacters (`*`, `?`) and shell metas
- * cannot be reinterpreted.
- *
- * LEGACY PATH ONLY since #1404 — see the fallback branch in findOverlaps.
- */
-function pathRegex(p) {
-  const escaped = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(`(?:^|[\\s'"])${escaped}(?:$|[\\s'"])`);
-}
-
 /**
  * Normalise a path token so reader and writer compare the same spelling.
  *
@@ -107,19 +116,13 @@ function pathsOverlap(fencePath, ourPath) {
  * Walk a single sibling fence file and return the staged paths a sibling
  * agent also recorded an intent to stage.
  *
- * Two entry shapes are accepted:
- *  - #1404 shape `{ paths, command_hash, timestamp }` — path LISTS compared
- *    against our staged set.
- *  - LEGACY shape `{ command, timestamp }` — a fence file written by a
- *    pre-#1404 hook version. Live sessions on this host may hold such files
- *    RIGHT NOW, and dropping them would read as "no overlap" — silently
- *    weaker than before the change. So the old raw-command regex still runs
- *    for an entry that has `command` and no `paths`.
- *    NAMED CEILING (BV-004): this fallback exists only to span the sessions
- *    running across the upgrade. REVISIT TRIGGER — remove it one minor
- *    release after 5.3.0 (i.e. in 5.4.0), by which point no process started
- *    before the upgrade can still be writing fence files. The command text it
- *    reads is never PRINTED (issue #1404) — only the fact of the match is.
+ * One entry shape is read: the #1404 `{ paths, command_hash, timestamp }`,
+ * whose path LIST is compared against our staged set. An entry without a
+ * `paths` array is skipped — that includes the pre-#1404 `{ command }` shape,
+ * whose raw-command regex fallback was removed in 5.4.x as its own revisit
+ * trigger demanded (#1487 point 16): the only fence writer,
+ * hooks/pre-bash-staging-fence.mjs, has written `paths` + `command_hash` and
+ * never `command` since 5.3.0, and no other hook or bridge writes fence files.
  */
 function findOverlaps(fenceJsonPath, ourStaged) {
   let body;
@@ -135,36 +138,126 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   const siblingAgent = body.agent_id ?? '<unknown>';
   const matches = [];
   for (const entry of body.staged_paths) {
-    if (Array.isArray(entry?.paths)) {
-      const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
-      for (const raw of entry.paths) {
-        if (typeof raw !== 'string') continue;
-        const fencePath = normalizeStagedPath(raw);
-        for (const ours of ourStaged) {
-          if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
-            matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
-          }
+    if (!Array.isArray(entry?.paths)) continue;
+    const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
+    for (const raw of entry.paths) {
+      if (typeof raw !== 'string') continue;
+      const fencePath = normalizeStagedPath(raw);
+      for (const ours of ourStaged) {
+        if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
+          matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
         }
       }
-      continue;
-    }
-
-    const cmd = entry?.command;
-    if (typeof cmd !== 'string') continue;
-    for (const ours of ourStaged) {
-      if (pathRegex(ours).test(cmd)) {
-        matches.push({
-          ourPath: ours,
-          siblingAgent,
-          fencePath: '<legacy entry, pre-#1404>',
-          hash: '<legacy entry, pre-#1404>',
-        });
-      }
     }
   }
   return matches;
 }
 
+/** mtime of a file in ms, or `null` when it cannot be stat'ed. */
+function mtimeMsOf(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sub-mode B's decision, pure: which lines to print and whether to block.
+ *
+ * Until #1493.1 an empty `allowedPaths` skipped the check outright, the
+ * manifest's `role` and `enforcement: "off"` were never read, and a PEER
+ * session's manifest governed this session's commits. Each rung below closes
+ * one of those; the order is load-bearing — ownership first (a foreign
+ * manifest's enforcement level is not ours to honour), then `off`, then the
+ * verdict. `warn` softens ONLY the empty-union verdict; a non-empty violation
+ * blocks at every level (header § Behavior summary).
+ *
+ * @param {object} p
+ * @param {Record<string, unknown>} p.scope parsed manifest
+ * @param {string[]} p.stagedFiles
+ * @param {string} p.scopeRel manifest path for messages, repo-relative
+ * @param {Set<string>} p.ownIds this process's session ids
+ * @param {number|null} p.scopeMtimeMs
+ * @param {number|null} p.sessionAge ms since the newest session clock
+ * @returns {{action: 'pass'|'report'|'block', lines: string[]}}
+ */
+function scopeCommitVerdict({ scope, stagedFiles, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
+  if (stagedFiles.length === 0) return { action: 'pass', lines: [] };
+
+  // Same classifier and same disposition as enforce-scope Gate 3b: only a
+  // PROVABLY foreign manifest stands down; unknown ownership enforces.
+  if (classifyManifestSession(scope, ownIds).verdict === 'foreign') {
+    return {
+      action: 'pass',
+      lines: [`wave-scope-commit-guard: ${scopeRel} belongs to another session — its allowedPaths do not apply to this commit.`],
+    };
+  }
+
+  const enforcement = scope.enforcement ?? 'strict';
+  if (enforcement === 'off') return { action: 'pass', lines: [] };
+
+  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  if (allowedPaths.length > 0) {
+    const violations = stagedFiles.filter(
+      (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
+    );
+    if (violations.length === 0) return { action: 'pass', lines: [] };
+    // Blocks under `warn` too — see the header: in a warn-mode wave this is
+    // the only hard stop a lint-staged sweep meets before the commit exists.
+    return {
+      action: 'block',
+      lines: [
+        '✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:',
+        ...violations.map((v) => `  - ${v}`),
+        '',
+        'These files were likely added by lint-staged eslint --fix / prettier --write.',
+        'To proceed:',
+        '  1) git restore --staged <path>   # for each foreign path',
+        '  2) git commit                    # retry',
+      ],
+    };
+  }
+
+  // From here on the verdict judges the coordinator's own bookkeeping (an empty
+  // union), not a staged foreign file — only this part follows `enforcement`.
+  const failAction = enforcement === 'strict' ? 'block' : 'report';
+
+  const role = typeof scope.role === 'string' ? scope.role.trim() : '';
+  const reason = classifyEmptyScope({
+    role,
+    parseOk: true,
+    scopeMtimeMs,
+    sessionStartMs: typeof sessionAge === 'number' ? Date.now() - sessionAge : null,
+  });
+  if (reason === 'read-only-role') {
+    // No wave agent commits (PSA-007), so a commit under a read-only manifest
+    // is the coordinator's own, between waves.
+    return {
+      action: 'pass',
+      lines: [`wave-scope-commit-guard: ${scopeRel} is a ${role} (read-only) manifest — treated as a coordinator commit between waves; allowedPaths not checked.`],
+    };
+  }
+  if (reason === 'stale-manifest') {
+    // Older than the newest session clock of this working copy: a leftover OR a
+    // parallel session's live manifest, which the clocks cannot tell apart
+    // (scope-gate.mjs § "…and the reader may not be the OWNER") — so it is
+    // never grounds to block this commit.
+    return {
+      action: 'report',
+      lines: [`⚠ wave-scope-commit-guard: ${scopeRel} grants no paths and predates the newest session start in this working copy — a leftover or a parallel session's live manifest; allowedPaths not checked for this commit.`],
+    };
+  }
+  return {
+    action: failAction,
+    lines: [
+      `${failAction === 'block' ? '✗' : '⚠'} wave-scope-commit-guard: ${scopeRel} grants no paths${role ? ` for role \`${role}\`` : ''} — the coordinator's \`--union\` step did not complete, so none of the ${stagedFiles.length} staged path(s) can be checked against this wave's scope.`,
+      'Re-run the union step (skills/wave-executor/references/wave-loop-scope-manifest.md § 3.3), then retry the commit; do not hand-edit allowedPaths.',
+      ...(failAction === 'block' ? [] : ['(enforcement: warn — reported, the commit proceeds)']),
+    ],
+  };
+}
+
 /**
  * Both sub-modes, in the order the pre-commit hook needs them. Every statement
  * here used to sit at module top level, which meant a bare `import()` of this
@@ -181,7 +274,16 @@ async function main() {
   // skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
   // returns null when no scope file exists at any precedence dir, preserving
   // the "no active wave → exit 0" semantics below.
-  const scopePath = findScopeFile(repoRoot);
+  //
+  // #1504 point 6: the first manifest that is not provably a peer's, so a
+  // peer's higher-precedence manifest no longer hides this session's own one;
+  // when every candidate is foreign the first comes back and
+  // `scopeCommitVerdict` passes it as before. The git process inherits the
+  // committing session's env; there is no hook payload here, so the env tier is
+  // the only process-local identity.
+  const ownIds = new Set(readProcessLocalSessionIds());
+  const located = findOwnScopeFile(repoRoot, ownIds, classifyManifestSession);
+  const scopePath = located.path ?? located.foreignPath;
   const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
 
   // -------------------------------------------------------------------------
@@ -200,22 +302,16 @@ async function main() {
       process.exit(1);
     }
 
-    const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
-    if (allowedPaths.length > 0) {
-      const violations = stagedFiles.filter(
-        (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
-      );
-
-      if (violations.length > 0) {
-        process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
-        for (const v of violations) process.stderr.write(`  - ${v}\n`);
-        process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
-        process.stderr.write('To proceed:\n');
-        process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
-        process.stderr.write('  2) git commit                    # retry\n');
-        process.exit(1);
-      }
-    }
+    const verdict = scopeCommitVerdict({
+      scope: scope !== null && typeof scope === 'object' ? scope : {},
+      stagedFiles,
+      scopeRel: relative(repoRoot, scopePath) || scopePath,
+      ownIds,
+      scopeMtimeMs: mtimeMsOf(scopePath),
+      sessionAge: sessionAgeMs(repoRoot),
+    });
+    for (const line of verdict.lines) process.stderr.write(`${line}\n`);
+    if (verdict.action === 'block') process.exit(1);
   }
 
   // -------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -54,6 +54,7 @@
     "!**/.DS_Store"
   ],
   "scripts": {
+    "update:local": "node scripts/self-update.mjs",
     "test": "node scripts/check-package-manager.mjs && vitest --run",
     "test:coverage": "node scripts/check-package-manager.mjs && vitest --run --coverage",
     "test:watch": "node scripts/check-package-manager.mjs && vitest",
@@ -92,11 +93,6 @@
     "prettier": "^3.0.0",
     "vitest": "^4.1.11"
   },
-  "overrides": {
-    "vite": "^8.0.16",
-    "fast-uri": "^3.1.5",
-    "brace-expansion": "^5.0.9"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/pi/prompts/test-audit.md

@@ -0,0 +1,12 @@
+---
+description: "Use when writing, reviewing, or pruning tests. Three modes, one value bar: a four-question gate before any new test is written, a focused audit of one scope, and a campaign over a whole repo or subsystem that removes the least useful tests under a coverage guard. Every delete, merge, or repair carries written evidence and a caught mutation. Triggered by \"audit the tests\", \"prune the test suite\", \"remove low-value tests\", \"test diet\", \"is this test worth adding\", /test-audit."
+argument-hint: "[gate|audit|campaign] [scope] [--goal \\\"<goal>\\\"]"
+---
+
+# /test-audit
+
+Use the Session Orchestrator skill definition at `skills/test-audit/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/rules/README.md

@@ -11,7 +11,12 @@ It is **not** the always-on rule set of *this* repository — those live in
 
 Every rule file here carries a
 `<!-- source: session-orchestrator plugin (canonical: rules/<path>) -->` header.
-On sync, plugin-sourced files are overwritten in the consumer while its
+In a rule with frontmatter it stands on the first line directly after the
+closing `---` — the frontmatter itself must open on line 1, because Claude Code
+reads a rule's frontmatter only there. A rule without frontmatter carries the
+header on line 1. A path-scoped rule declares its file patterns twice, as
+`globs:` and `paths:` with identical lists: `paths:` is the only key Claude Code
+reads, `globs:` is what `rule-loader.mjs` reads first (#1449). On sync, plugin-sourced files are overwritten in the consumer while its
 locally-authored rules are preserved (copy-on-write). The canonical manifest of
 what vendors where is [`_index.md`](./_index.md).
 

package/rules/_index.md

@@ -40,7 +40,7 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 - `always-on/build-value.md` — BV-001..004: the seven-rung build ladder, the four protections never simplified away
 - `always-on/cross-session-messaging.md` — CSM-001..005: messaging is transport, not shared state; no permission laundering
 - `always-on/loop-and-monitor.md` — LM-001..008: routing between `/goal`, Workflows, Channels, Monitor, `/loop`, and Routines
-- `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via its own `globs:`/`paths:` frontmatter)
+- `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via `globs:` + `paths:` frontmatter carrying identical lists — `paths:` is what Claude Code reads, `globs:` what `rule-loader.mjs` reads first; #1449)
 
 ## opt-in-stack (vendored on match)
 
@@ -52,8 +52,8 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 
 ## opt-in-domain (vendored on match)
 
-- `opt-in-domain/prompt-caching.md` — Anthropic prompt caching (breakpoint placement, TTL selection, pre-warming, verification) [archetypes: nextjs-saas, express-service, docker-service, monorepo-oss, cli-tool]
+- `opt-in-domain/prompt-caching.md` — Anthropic prompt caching (breakpoint placement, TTL selection, pre-warming, verification) [archetypes: nextjs-saas, express-service, docker-service, monorepo-oss]
 
 ## Sync mechanism
 
-Consumer repos receive these files via `/bootstrap --sync-rules`. Re-running the command syncs every manifest category that has entries: universal entries always vendor, and archetype-tagged entries vendor only when the consumer repo's resolved archetype matches. Plugin-sourced files are overwritten while local rules are preserved (copy-on-write via the `<!-- source: session-orchestrator plugin ... -->` header on plugin files). Category entries must not share a basename, because all synced files flatten into `.claude/rules/`.
+Consumer repos receive these files via `/bootstrap --sync-rules`. Re-running the command syncs every manifest category that has entries: universal entries always vendor, and archetype-tagged entries vendor only when the consumer repo's resolved archetype matches. Plugin-sourced files are overwritten while local rules are preserved (copy-on-write via the `<!-- source: session-orchestrator plugin ... -->` header on plugin files). That header stands on the first line directly after the closing `---` of a rule's frontmatter, because Claude Code reads frontmatter only when it opens on line 1; only a rule without frontmatter carries it on line 1 (#1449). A consumer copy written in the older format (header on line 1, frontmatter after it) still counts as plugin-owned and is rewritten into the current format on the next sync. Category entries must not share a basename, because all synced files flatten into `.claude/rules/`.

package/rules/always-on/bash-harness-pitfalls.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/always-on/bash-harness-pitfalls.md) -->
 ---
 globs:
   - "**/*.sh"
@@ -6,8 +5,15 @@ globs:
   - scripts/**
   - tests/**
   - .husky/**
+paths:
+  - "**/*.sh"
+  - "**/*.bash"
+  - scripts/**
+  - tests/**
+  - .husky/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/always-on/bash-harness-pitfalls.md) -->
 # Bash / Shell-Harness Pitfalls (Path-scoped)
 
 Six recurring bash-harness failure classes, each surfaced by a live run rather

package/rules/opt-in-domain/prompt-caching.md

@@ -1,11 +1,15 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-domain/prompt-caching.md) -->
 ---
 globs:
   - "**/lib/ai/**"
   - "**/lib/llm/**"
   - "**/providers/**"
+paths:
+  - "**/lib/ai/**"
+  - "**/lib/llm/**"
+  - "**/providers/**"
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-domain/prompt-caching.md) -->
 # Prompt Caching Rules (Path-scoped — repos using `@anthropic-ai/sdk` or `@ai-sdk/anthropic`)
 
 > Path-scoped — applies anywhere a project imports `@anthropic-ai/sdk` or uses the `@ai-sdk/anthropic` provider. Out of scope: `session-orchestrator` itself (no SDK use; `backend.md` § "AI Provider Abstraction" already forbids direct SDK imports in business logic, and the orchestrator runs inside Claude Code's harness which manages caching at the platform layer).

package/rules/opt-in-stack/backend-data.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend-data.md) -->
 ---
 globs:
   - src/lib/db/**
@@ -8,8 +7,17 @@ globs:
   - migrations/**
   - src/lib/redis/**
   - src/lib/queue/**
+paths:
+  - src/lib/db/**
+  - src/lib/cache/**
+  - src/services/db/**
+  - supabase/**
+  - migrations/**
+  - src/lib/redis/**
+  - src/lib/queue/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend-data.md) -->
 # Backend Data Rules (Path-scoped)
 
 ## Database (Supabase)

package/rules/opt-in-stack/backend.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend.md) -->
 ---
 globs:
   - src/app/**
@@ -6,8 +5,15 @@ globs:
   - src/lib/api/**
   - src/routes/**
   - src/app/api/**
+paths:
+  - src/app/**
+  - src/services/**
+  - src/lib/api/**
+  - src/routes/**
+  - src/app/api/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend.md) -->
 # Backend Rules (Path-scoped)
 
 ## Server Actions (Next.js)