session-orchestrator 3.21.0 → 3.22.0

package/scripts/lib/peer-discovery.mjs

@@ -67,6 +67,7 @@ import { discoverActiveSessions } from './session-discovery.mjs';
 import { readLock, isLockLive, LOCK_PATH } from './session-lock.mjs';
 import { checkPeerStateMd } from './state-md-peer-guard.mjs';
 import { listWorktreesChecked } from './worktree/listing.mjs';
+import { parseSessionId } from './session-id.mjs';
 
 /** Closed enum of provenance sources. */
 const SOURCE_DISCOVERED = 'discovered'; // lock + registry unified (irreversibly merged upstream)
@@ -120,24 +121,64 @@ function _peerFromDiscovered(s, nowMs) {
   return peer;
 }
 
+/**
+ * Resolve a semantic hint to the concrete local raw ID for discovered surfaces.
+ *
+ * Semantic labels are attribution, not ownership. A mapping is usable only when
+ * current-session.json names the hint and its raw id exactly matches the local
+ * readable session.lock. Otherwise return null so a potentially foreign record
+ * stays visible. Raw caller ids retain the legacy direct comparison unchanged.
+ *
+ * This is a consistency check on two repo-global files, NOT a proof of ownership;
+ * a colliding semantic label from a foreign live session satisfies it. See the
+ * call site in findPeers for the measured case and why it is not closed here.
+ *
+ * @param {string|null} mySessionId
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function _discoveredSelfSessionId(mySessionId, repoRoot) {
+  if (typeof mySessionId !== 'string' || mySessionId.length === 0) return null;
+  if (parseSessionId(mySessionId)?.format !== 'semantic') return mySessionId;
+
+  try {
+    const raw = fs.readFileSync(
+      path.join(repoRoot, '.orchestrator', 'current-session.json'),
+      'utf8',
+    );
+    const current = JSON.parse(raw);
+    const lock = readLock({ repoRoot });
+    if (
+      current &&
+      typeof current === 'object' &&
+      !Array.isArray(current) &&
+      typeof current.session_id === 'string' &&
+      current.session_id.length > 0 &&
+      current.semantic_session_id === mySessionId &&
+      lock !== null &&
+      typeof lock.session_id === 'string' &&
+      lock.session_id === current.session_id
+    ) {
+      return lock.session_id;
+    }
+  } catch {
+    // Missing or malformed local state cannot prove a semantic alias.
+  }
+  return null;
+}
+
 /**
  * findPeers — union of all 3 peer-discovery surfaces, fail-open per surface.
  *
  * @param {string} repoRoot  Absolute path to the repository root.
  * @param {object} [opts] passthrough seams shared with the underlying surfaces.
- * @param {string|null} [opts.mySessionId]      Current session id, used for
- *   self-exclusion on BOTH surfaces — but the two surfaces read different
- *   id-spaces. Surface A+B (discoverActiveSessions) compares against
- *   `session_id` from session.lock / the host registry, which is ALWAYS the
- *   UUID (never `semantic_session_id` — see session-lock.mjs). Surface C
- *   (checkPeerStateMd) compares against STATE.md's `session:` frontmatter
- *   field, which callers may populate with either id-space as long as it is
- *   the SAME id-space `mySessionId` was derived from (see the PRECONDITION
- *   note in state-md-peer-guard.mjs). Passing a semantic id here self-excludes
- *   correctly on Surface C but NOT on Surface A+B (the UUID lock/registry
- *   entry for the same session will still surface as a 'discovered' peer of
- *   itself) — callers that need both surfaces to self-exclude MUST pass the
- *   UUID.
+ * @param {string|null} [opts.mySessionId]      Current session id hint. Raw
+ *   ids self-exclude directly on Surface A+B. A semantic hint maps to a raw
+ *   discovered-surface id only after the local current-session.json semantic
+ *   label matches it AND that file's raw id exactly equals local
+ *   session.lock.session_id. Missing, malformed, or mismatched local state
+ *   maps nothing, leaving discovered entries visible. Surface C receives this
+ *   original hint unchanged and compares it to STATE.md's `session:` field.
  * @param {number}      [opts.now]              ms-since-epoch (test seam for freshness/age).
  * @param {number}      [opts.freshnessMin]     Registry-entry freshness threshold (minutes).
  * @param {number}      [opts.maxAgeHours]      STATE.md abandonment threshold (hours).
@@ -155,6 +196,7 @@ function _peerFromDiscovered(s, nowMs) {
 export async function findPeers(repoRoot, opts = {}) {
   const nowMs = typeof opts.now === 'number' ? opts.now : Date.now();
   const mySessionId = opts.mySessionId ?? null;
+  const discoveredSelfSessionId = _discoveredSelfSessionId(mySessionId, repoRoot);
 
   const peers = [];
 
@@ -172,15 +214,24 @@ export async function findPeers(repoRoot, opts = {}) {
     });
     if (Array.isArray(discovered)) {
       for (const s of discovered) {
-        // Self-exclusion (#798): discoverActiveSessions has no notion of "my
-        // session" — it returns every live lock/registry entry, including the
-        // caller's own SessionStart-hook heartbeat. Exclude it here so it
-        // never surfaces as a source:'discovered' peer of itself. Mirrors the
-        // same guard in session-registry.mjs detectPeers() and
-        // hooks/on-session-start.mjs. `mySessionId === null` needs no special
-        // case: `!==` against a string sessionId is always true when
-        // mySessionId is null, so a foreign entry is never filtered.
-        if (s && typeof s.sessionId === 'string' && s.sessionId !== mySessionId) {
+        // Self-exclusion (#798, #1085): discovered entries carry raw ids. A
+        // semantic caller hint filters one such id only after the local raw
+        // binding was verified above.
+        //
+        // The binding proves CONSISTENCY of the two local files, not OWNERSHIP.
+        // Both are repo-global, so if a foreign live session wrote them last and
+        // its semantic label collides with this hint (labels like
+        // `main-2026-08-21-session-2` are routinely shared — see
+        // hooks/on-session-start.mjs), that foreign raw id is filtered and the
+        // peer PSA-002 exists to surface goes missing. Measured 2026-08-21:
+        // null hint -> peer visible, colliding semantic hint -> peers: [].
+        // Closing it needs a per-process ownership proof, not a stronger read
+        // of the same two files.
+        if (
+          s &&
+          typeof s.sessionId === 'string' &&
+          s.sessionId !== discoveredSelfSessionId
+        ) {
           peers.push(_peerFromDiscovered(s, nowMs));
         }
       }

package/scripts/lib/project-hygiene.mjs

@@ -212,6 +212,21 @@ function duBytes(absPath) {
   }
 }
 
+/**
+ * Human-readable byte size. Sub-megabyte totals are the common case once the
+ * aged subset is sized correctly, and `Math.round(bytes / MB)` renders every
+ * one of them as "0 MB" — which is why the unit is chosen, not fixed.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  const mb = bytes / (1024 * 1024);
+  if (mb >= 10) return `${Math.round(mb)} MB`;
+  if (mb >= 1) return `${mb.toFixed(2)} MB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${bytes} B`;
+}
+
 /**
  * H3 — Aged orchestrator artifacts.
  *
@@ -219,17 +234,48 @@ function duBytes(absPath) {
  * 147 MB were Playwright test-run captures dating back seven weeks, plus
  * 592 files older than 30 days.
  *
+ * Counts and sizes ONLY untracked aged files. Two properties are load-bearing
+ * and were both defects until 2026-08-22:
+ *
+ *   1. The byte total describes the set the sentence names — the aged files —
+ *      not the whole directory. Sizing the directory overstated the reachable
+ *      win by a factor of ~18 in this repo (11 MB claimed, 0.68 MB real).
+ *   2. Version-tracked paths are excluded. `.orchestrator/policy/*.json` and
+ *      `.orchestrator/steering/*.md` are read at runtime by hooks and skills;
+ *      their age is a sign of stability, not decay. Proposing them for
+ *      "pruning" is proposing to delete source.
+ *
  * @param {string} repoRoot
  * @param {number} ageDays
  * @param {number} now
- * @returns {object|null}
+ * @returns {{check: string, fixable: boolean, agedFiles: number, agedBytes: number, message: string}|null}
  */
 export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAYS, now = Date.now()) {
   const dir = join(repoRoot, '.orchestrator');
   if (!existsSync(dir)) return null;
 
+  // Resolve the tracked set ONCE per call — `git ls-files --error-unmatch` per
+  // file would cost one process per candidate for the same answer.
+  //
+  // FAIL-SAFE, NOT FAIL-OPEN: when git cannot answer (no repo, git absent,
+  // non-zero exit) source and artifact are indistinguishable, so the probe
+  // stays SILENT rather than falling back to "nothing is tracked" — that
+  // fallback IS the defect this exclusion closes, and it would return
+  // invisibly. Losing an advisory finding costs nothing; proposing to delete
+  // versioned files costs a restore. `-z` suppresses git's path quoting, so
+  // non-ASCII and space-bearing paths compare byte-exactly.
+  const trackedRaw = git(['ls-files', '-z', '--', '.orchestrator'], repoRoot);
+  if (trackedRaw === null) return null;
+  const tracked = new Set(
+    trackedRaw
+      .split('\0')
+      .filter(Boolean)
+      .map((p) => join(repoRoot, p)),
+  );
+
   const cutoff = now - ageDays * 24 * 60 * 60 * 1000;
   let aged = 0;
+  let agedBytes = 0;
   let scanned = 0;
 
   /** @param {string} d @param {number} depth */
@@ -248,9 +294,16 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
       if (e.isDirectory()) {
         walk(full, depth + 1);
       } else if (e.isFile()) {
+        // Counted before the tracked-skip so the 20k bound still measures the
+        // walk, not the reportable subset.
         scanned++;
+        if (tracked.has(full)) continue;
         try {
-          if (statSync(full).mtimeMs < cutoff) aged++;
+          const st = statSync(full);
+          if (st.mtimeMs < cutoff) {
+            aged++;
+            agedBytes += st.size;
+          }
         } catch {
           /* vanished mid-scan — ignore */
         }
@@ -261,11 +314,18 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
 
   if (aged === 0) return null;
 
-  const mb = Math.round((duBytes(dir) ?? 0) / (1024 * 1024));
+  // `fixable: true` stays. The only consumer is skills/session-start/SKILL.md
+  // (Phase 4), which routes fixable findings to "safe batch work" instead of
+  // the operator Q&A — prose guidance to the coordinator, not an automatic
+  // deletion run; `grep -rn "fixable" scripts/ skills/ hooks/` finds no other
+  // reader than the `mechanical` count below. With tracked paths excluded the
+  // claim is now true: every reported path is an untracked artifact.
   return {
     check: 'stale-artifacts',
     fixable: true,
-    message: `${aged} file(s) under .orchestrator/ older than ${ageDays}d${mb > 0 ? ` (${mb} MB total)` : ''} — candidates for pruning`,
+    agedFiles: aged,
+    agedBytes,
+    message: `${aged} untracked file(s) under .orchestrator/ older than ${ageDays}d${agedBytes > 0 ? ` (${formatBytes(agedBytes)} total)` : ''} — candidates for pruning`,
   };
 }
 

package/scripts/lib/reconcile/renderer.mjs

@@ -262,10 +262,23 @@ export function renderRule(learning, metadata) {
   // purely by `host-class:` (loads only on a matching host) — the intended
   // behavior, and still never always-on (host-class IS an activation axis).
   if (globs.length > 0) {
-    fm.push('globs:');
-    for (const glob of globs) {
-      // Always double-quote — keeps `*`/`[`/`{` safe; loader strips quotes.
-      fm.push(`  - "${glob}"`);
+    // TWO keys, same list, on purpose (#1108). `globs:` is what THIS repo's
+    // `rule-loader.mjs` and Cursor read; `paths:` is the ONLY key Claude Code's
+    // own loader honours, and a rule without it is loaded UNCONDITIONALLY into
+    // every agent (https://code.claude.com/docs/en/memory § Path-specific
+    // rules). Emitting `globs:` alone therefore produced a rule that LOOKS
+    // scoped, IS scoped for us, and is always-on for the harness — measured
+    // 2026-08-22: 16 such rules put 72_195 bytes (~18_300 tokens) into every
+    // single dispatch. `check-rules.mjs` now hard-FAILs that shape, so a
+    // globs-only rule emitted here would be rejected by the gate the moment it
+    // lands. Keep the two lists IDENTICAL: divergence is its own FAIL class,
+    // because it would scope Claude Code and Cursor to different rule sets.
+    for (const key of ['globs', 'paths']) {
+      fm.push(`${key}:`);
+      for (const glob of globs) {
+        // Always double-quote — keeps `*`/`[`/`{` safe; loader strips quotes.
+        fm.push(`  - "${glob}"`);
+      }
     }
   }
   if (hostClass !== undefined) {