session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/hardware-pattern-detector.mjs

@@ -9,8 +9,10 @@
  *   1. oom-kill      — stop events with exitCode 137 or "Out of memory" marker
  *   2. heartbeat-gap — registry sweep.log entries for the same host
  *                      (session disappeared without a clean stop — freeze proxy)
- *   3. concurrent-session-pressure — session events where peer_count crossed
- *                      the configured concurrent-sessions-warn threshold
+ *   3. concurrent-session-pressure — session-start events inside a start wave:
+ *                      `recent_starts_count` (foreign starts in the last 5 min,
+ *                      emitted since #1650) >= startWaveMin. Re-aimed in #1654
+ *                      off `peer_count`, a standing state (see the detector).
  *   4. disk-full     — events with ENOSPC / "no space left" markers
  *   5. thermal-throttle — sustained high CPU load + unexpected slow-wave marker
  *
@@ -28,8 +30,14 @@
 export const DEFAULT_THRESHOLDS = Object.freeze({
   /** Minimum recurrence for a candidate to be emitted (same host_class). */
   minOccurrences: 2,
-  /** Minimum peer_count to count as concurrent-session pressure. */
-  concurrentSessionsWarn: 5,
+  /**
+   * Minimum `recent_starts_count` (foreign session starts in the 5 min before
+   * this start) to count as concurrent-session pressure. Mirrors START_WAVE_MIN
+   * in hooks/on-session-start.mjs (#1650). Replaces `concurrentSessionsWarn`
+   * (#1654), which was compared against `peer_count`; a caller still passing
+   * that key is ignored on purpose rather than silently fed the old meaning.
+   */
+  startWaveMin: 5,
   /** CPU load percentage that marks a thermal-throttle signal. */
   thermalCpuLoadPct: 85,
   /** Heartbeat gap threshold in minutes above which a session is "frozen". */
@@ -93,15 +101,97 @@ function detectHeartbeatGap(sweepLogEntries, thresholdMin) {
     }));
 }
 
+/**
+ * Fallback wave window for start events that predate the producer writing
+ * `recent_starts_window_min` beside `recent_starts_count`. Mirrors the default
+ * of `countRecentStarts()` in scripts/lib/session-registry.mjs; the producer's
+ * own constant (START_WAVE_WINDOW_MIN in hooks/on-session-start.mjs) is
+ * module-private to a hook script and arrives per event instead, so the event
+ * field always wins over this value.
+ */
+const FALLBACK_START_WAVE_WINDOW_MIN = 5;
+
+/**
+ * Start-wave detector (#1654). Keyed on `recent_starts_count`, NOT `peer_count`:
+ * `peer_count >= 5` held on 880/1305 = 67.4% of M4 and 255/991 = 25.7% of M5
+ * starts since 2026-08-24 (#1650) — a standing condition, so every learning
+ * derived from it was noise (HR-101). A start wave fired on 2.7% / 5.2%.
+ *
+ * Events without a numeric `recent_starts_count` (every pre-#1650 record) carry
+ * no value on this branch: they are skipped, never read as 0 and never as a hit.
+ * The signal name stays `concurrent-session-pressure` so existing learnings'
+ * subjects (`concurrent-session-pressure::<host_class>`) remain stable.
+ *
+ * One hit per WAVE, not per event (#1664): with >= 7 starts in one wave, the
+ * 6th and 7th start each see >= 5 foreign starts, so counting events let a
+ * single wave satisfy `minOccurrences: 2` on its own. See clusterStartWaves().
+ */
 function detectConcurrentSessionPressure(events, threshold) {
-  return events
-    .filter((e) => e.event === 'orchestrator.session.started' && typeof e.peer_count === 'number' && e.peer_count >= threshold)
-    .map((e) => ({
-      signal: 'concurrent-session-pressure',
-      host_class: e.host_class ?? null,
-      timestamp: e.timestamp,
-      raw: { peer_count: e.peer_count },
-    }));
+  const qualifying = events.filter(
+    (e) =>
+      e.event === 'orchestrator.session.started' &&
+      typeof e.recent_starts_count === 'number' &&
+      e.recent_starts_count >= threshold,
+  );
+  return clusterStartWaves(qualifying).map((wave) => ({
+    signal: 'concurrent-session-pressure',
+    host_class: wave[0].host_class ?? null,
+    timestamp: wave[0].timestamp,
+    // Peak count of the wave: same `{ recent_starts_count }` sample shape as
+    // the per-event hits this replaces.
+    raw: { recent_starts_count: Math.max(...wave.map((e) => e.recent_starts_count)) },
+  }));
+}
+
+/**
+ * Cluster qualifying start events into waves, per `host_class` (events without
+ * a host share one `null` bucket; aggregateCandidates() drops those hits later).
+ * Chain rule: sorted by time, an event joins the current wave when it lies
+ * less than the window after the PREVIOUS qualifying event — the window being
+ * the span `recent_starts_count` itself looks back over (event field
+ * `recent_starts_window_min`, else FALLBACK_START_WAVE_WINDOW_MIN). Events with
+ * an unparseable timestamp cannot be placed in any wave and are DROPPED:
+ * counting each as its own wave would re-open the per-event over-count.
+ *
+ * Each wave's hit carries the wave's FIRST timestamp, so downstream
+ * `last_seen` means "start of the last wave", not "last qualifying start".
+ *
+ * Ceiling (BV-004): chaining is unbounded, so qualifying starts that keep
+ * arriving less than one window apart for an hour merge into ONE occurrence —
+ * a sustained-pressure stretch undercounts rather than overcounts. Revisit if
+ * the ledger shows a chained wave on one host spanning more than 30 min, which
+ * would mean sustained load, not a burst, and deserves its own count.
+ *
+ * @param {object[]} qualifying — start events already past the threshold
+ * @returns {object[][]} waves, each a non-empty array of events in time order
+ */
+function clusterStartWaves(qualifying) {
+  const byHost = new Map();
+  for (const e of qualifying) {
+    const key = e.host_class ?? null;
+    if (!byHost.has(key)) byHost.set(key, []);
+    byHost.get(key).push({ e, ms: Date.parse(e.timestamp) });
+  }
+  const waves = [];
+  for (const list of byHost.values()) {
+    const timed = list.filter((x) => Number.isFinite(x.ms)).sort((a, b) => a.ms - b.ms);
+    let current = null;
+    let prevMs = 0;
+    for (const x of timed) {
+      const windowMin =
+        typeof x.e.recent_starts_window_min === 'number' && x.e.recent_starts_window_min > 0
+          ? x.e.recent_starts_window_min
+          : FALLBACK_START_WAVE_WINDOW_MIN;
+      if (current && x.ms - prevMs < windowMin * 60_000) {
+        current.push(x.e);
+      } else {
+        current = [x.e];
+        waves.push(current);
+      }
+      prevMs = x.ms;
+    }
+  }
+  return waves;
 }
 
 function detectDiskFull(events) {
@@ -210,7 +300,7 @@ export function detectHardwarePatterns({
   const hits = [
     ...detectOomKill(events),
     ...detectHeartbeatGap(sweepLogEntries, t.heartbeatGapMinutes),
-    ...detectConcurrentSessionPressure(events, t.concurrentSessionsWarn),
+    ...detectConcurrentSessionPressure(events, t.startWaveMin),
     ...detectDiskFull(events),
     ...detectThermalThrottle(events, t.thermalCpuLoadPct),
   ];

package/scripts/lib/harness-audit/categories/category1.mjs

@@ -5,13 +5,15 @@
  *         orchestrator-layout
  *
  * Stdlib + intra-repo helpers only (node:fs, node:path, ./helpers.mjs,
- * ../../sessions-canonical.mjs).
+ * ../../platform.mjs, ../../sessions-canonical.mjs).
  */
 
 import { existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 
 import { parseFrontmatter, safeRead, parseJsonl, pass, fail } from './helpers.mjs';
+import { resolveEventsLedgerRoot } from '../../platform.mjs';
+import { resolveLedgerPath } from '../../ledger-path.mjs';
 import { canonicalizeSessions } from '../../sessions-canonical.mjs';
 
 export function runCategory1(root) {
@@ -54,8 +56,12 @@ export function runCategory1(root) {
 
   // c1.2 sessions-jsonl-growth
   {
-    const p = join(root, '.orchestrator/metrics/sessions.jsonl');
+    // #1592: the repo's ONE sessions ledger, as c4.2 reads it — a linked
+    // worktree holds no ledger of its own since #1584, so `<root>/…` would
+    // report "missing" for a repo that records every session.
+    const p = join(resolveEventsLedgerRoot(root), '.orchestrator/metrics/sessions.jsonl');
     const text = safeRead(p);
+    // ledger-root: display relPath for the finding, the read above is resolved
     const relPath = '.orchestrator/metrics/sessions.jsonl';
     if (!text) {
       checks.push(fail('sessions-jsonl-growth', 3, relPath,
@@ -87,8 +93,9 @@ export function runCategory1(root) {
 
   // c1.3 learnings-jsonl-nonempty
   {
-    const p = join(root, '.orchestrator/metrics/learnings.jsonl');
+    const p = resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', root);
     const text = safeRead(p);
+    // ledger-root: display relPath for the finding, the read above is resolved
     const relPath = '.orchestrator/metrics/learnings.jsonl';
     if (!text) {
       checks.push(fail('learnings-jsonl-nonempty', 2, relPath,
@@ -115,9 +122,14 @@ export function runCategory1(root) {
       '.orchestrator',
       '.orchestrator/bootstrap.lock',
       '.orchestrator/policy',
+      // ledger-root: existence check only, resolved under resolveEventsLedgerRoot() below
       '.orchestrator/metrics',
     ];
-    const presentPaths = requiredPaths.filter((rp) => existsSync(join(root, rp)));
+    // #1722: a linked worktree of a repo that ignores its ledgers has no
+    // metrics dir of its own — they live in the main checkout.
+    const presentPaths = requiredPaths.filter((rp) =>
+      existsSync(rp === '.orchestrator/metrics' ? join(resolveEventsLedgerRoot(root), rp) : join(root, rp)),
+    );
     if (presentPaths.length === requiredPaths.length) {
       checks.push(pass('orchestrator-layout', 2, 2, '.orchestrator/',
         { presentPaths },

package/scripts/lib/harness-audit/categories/category4.mjs

@@ -5,7 +5,7 @@
  *         vault-sync-validator, orphaned-session-lock
  *
  * Stdlib + intra-repo helpers only (node:fs, node:path, ./helpers.mjs,
- * ../../session-schema/filters.mjs, ../../sessions-canonical.mjs,
+ * ../../platform.mjs, ../../sessions-canonical.mjs,
  * ../../config/section-extractor.mjs).
  */
 
@@ -13,8 +13,9 @@ import { existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 
 import { parseFrontmatter, safeRead, parseJsonl, pass, fail } from './helpers.mjs';
-import { isRealSession } from '../../session-schema/filters.mjs';
-import { canonicalizeSessions } from '../../sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from '../../platform.mjs';
+import { resolveLedgerPath } from '../../ledger-path.mjs';
+import { canonicalizeSessions, isMeasuredSession } from '../../sessions-canonical.mjs';
 import { findSessionConfigBlock } from '../../config/section-extractor.mjs';
 
 // Default session-lock TTL in hours — mirrors DEFAULT_TTL_HOURS in
@@ -86,8 +87,9 @@ export function runCategory4(root) {
 
   // c4.2 sessions-jsonl-recent
   {
-    const p = join(root, '.orchestrator/metrics/sessions.jsonl');
+    const p = join(resolveEventsLedgerRoot(root), '.orchestrator/metrics/sessions.jsonl');
     const text = safeRead(p);
+    // ledger-root: display relPath for the finding, the read above is resolved
     const relPath = '.orchestrator/metrics/sessions.jsonl';
     if (!text) {
       checks.push(fail('sessions-jsonl-recent', 3, relPath,
@@ -100,13 +102,13 @@ export function runCategory4(root) {
           { latestCompletedAt: null, ageInDays: null },
           'sessions.jsonl is empty'));
       } else {
-        // Most-recent REAL session by completed_at, over the CANONICAL record
+        // Most-recent MEASURED session by completed_at, over the CANONICAL record
         // set (#1209b) — canonicalizeSessions() already collapses duplicate
         // `session_id` lines to the newest occurrence, drops the systemic
         // double-stub twin, and removes any record a surviving one
         // `supersedes`. A raw backward-scan-to-last-real-LINE (the pre-#1209b
         // approach) cannot see this: a duplicate id whose LAST occurrence was
-        // retroactively corrected to `status: 'abandoned'` still let an
+        // retroactively corrected to a synthetic stub still let an
         // EARLIER, now-superseded raw line for the same identity count as
         // "recent". Max, not backward-scan, because canonical order is
         // first-appearance order per id, not completed_at order.
@@ -123,7 +125,7 @@ export function runCategory4(root) {
         let lastObj = null;
         let lastMs = -Infinity;
         for (const rec of records) {
-          if (!isRealSession(rec)) continue;
+          if (!isMeasuredSession(rec)) continue;
           const ms = Date.parse(rec?.completed_at);
           if (Number.isFinite(ms) && ms > lastMs) {
             lastMs = ms;
@@ -154,8 +156,9 @@ export function runCategory4(root) {
 
   // c4.3 learnings-prunable
   {
-    const p = join(root, '.orchestrator/metrics/learnings.jsonl');
+    const p = resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', root);
     const text = safeRead(p);
+    // ledger-root: display relPath for the finding, the read above is resolved
     const relPath = '.orchestrator/metrics/learnings.jsonl';
     if (!text) {
       checks.push(fail('learnings-prunable', 2, relPath,

package/scripts/lib/harness-audit/categories/category6.mjs

@@ -14,6 +14,8 @@ import { execFileSync } from 'node:child_process';
 import { safeRead, lineCount, pass, fail } from './helpers.mjs';
 import { resolveInstructionFile } from '../../common.mjs';
 import { listRemotes } from '../../vcs-repo-spec.mjs';
+import { _extractConfigSection, _parseKV } from '../../config/section-extractor.mjs';
+import { parseSourceCommitTrailer } from '../../github-export.mjs';
 
 export function runCategory6(root) {
   const checks = [];
@@ -231,14 +233,32 @@ export function runCategory6(root) {
         // git not honouring its own contract — equally unmeasurable, and
         // splitting it off would leave the identical fail-open standing behind a
         // smaller trigger. `aheadCountQuery` records which of the two occurred.
-        const revListOut = runGit(['rev-list', '--count', `github/${mirrorBranch}..HEAD`]);
+        // `mirror: curated` (#1631): the published commit is a snapshot, not an
+        // ancestor of HEAD, so `github/<branch>..HEAD` would count the whole private
+        // history. Count from the snapshot's `Source-Commit` trailer instead; a
+        // mirror that carries no trailer yet is still a plain ancestor (pre-export).
+        const instrText = instr ? safeRead(instrPath) : null;
+        const curated = instrText !== null && _parseKV(_extractConfigSection(instrText)).get('mirror') === 'curated';
+        let aheadBase = `github/${mirrorBranch}`;
+        let revListOut;
+        if (curated) {
+          const mirrorCommit = runGit(['cat-file', 'commit', `github/${mirrorBranch}`]);
+          aheadBase = (mirrorCommit !== null && parseSourceCommitTrailer(mirrorCommit)) || aheadBase;
+          revListOut = mirrorCommit === null ? null : runGit(['rev-list', '--count', `${aheadBase}..HEAD`]);
+        } else {
+          revListOut = runGit(['rev-list', '--count', `${aheadBase}..HEAD`]);
+        }
         const aheadCount = revListOut !== null ? Number.parseInt(revListOut, 10) : NaN;
+        const curatedEvidence = curated ? { mirrorMode: 'curated', aheadBase } : {};
+        const pushHint = curated
+          ? 'Run /close on main — session-end § 4.4 publishes the curated snapshot with its checks (never push the export by hand)'
+          : 'Run: git push github HEAD';
 
         if (Number.isNaN(aheadCount)) {
           const aheadCountQuery = revListOut === null ? 'git-error' : 'unparseable-output';
           checks.push(fail({
             checkId, maxPoints: 2, path: relPath,
-            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount: null, aheadCountQuery },
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount: null, aheadCountQuery, ...curatedEvidence },
             message:
               `unable to determine ahead-count vs github/${mirrorBranch} (${aheadCountQuery}) — ` +
               'mirror drift not measurable',
@@ -246,14 +266,14 @@ export function runCategory6(root) {
         } else if (aheadCount === 0) {
           checks.push(pass({
             checkId, points: 2, maxPoints: 2, path: relPath,
-            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount },
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount, ...curatedEvidence },
             message: `HEAD is fully mirrored to github/${mirrorBranch}`,
           }));
         } else {
           checks.push(pass({
             checkId, points: 1, maxPoints: 2, path: relPath,
-            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount },
-            message: `${aheadCount} local commit(s) not pushed to github mirror (github/${mirrorBranch}). Run: git push github HEAD`,
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount, ...curatedEvidence },
+            message: `${aheadCount} local commit(s) not pushed to github mirror (github/${mirrorBranch}). ${pushHint}`,
           }));
         }
       }

package/scripts/lib/harness-audit/categories/category9.mjs

@@ -21,7 +21,8 @@
  * status field is only 'pass' / 'fail' — partial tiers emit a reduced-points
  * pass() (there is no 'partial' constructor in helpers.mjs).
  *
- * Stdlib only: node:fs, node:path, node:child_process. The advisory tally in
+ * Stdlib (node:fs, node:path, node:child_process) plus the auditor's own
+ * ../../platform.mjs for the sessions-ledger root. The advisory tally in
  * c9.3 imports the AUDITOR's OWN (trusted) join/score modules in a short-lived
  * worker subprocess and runs them over the TARGET repo's telemetry DATA files —
  * it never imports code rooted at the audited repo (review N2b: RCE-on-audit).
@@ -34,6 +35,8 @@ import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 import { pass, fail } from './helpers.mjs';
+import { resolveEventsLedgerRoot } from '../../platform.mjs';
+import { resolveLedgerPath } from '../../ledger-path.mjs';
 
 const TELEMETRY_REL = '.orchestrator/metrics/skill-invocations.jsonl';
 const SESSIONS_REL = '.orchestrator/metrics/sessions.jsonl';
@@ -80,7 +83,7 @@ export function runCategory9(root) {
   // points (with a quoted malformed-line count) when some lines are malformed.
   {
     const checkId = 'skill-telemetry-hygiene';
-    const telemetryPath = join(root, TELEMETRY_REL);
+    const telemetryPath = resolveLedgerPath(TELEMETRY_REL, root);
     if (!existsSync(telemetryPath)) {
       checks.push(pass({
         checkId, points: 4, maxPoints: 4, path: TELEMETRY_REL,
@@ -186,7 +189,7 @@ function buildAdvisoryCheck(root) {
 
   const scorerPath = join(root, SCORER_REL);
   const joinPath = join(root, JOIN_REL);
-  const telemetryPath = join(root, TELEMETRY_REL);
+  const telemetryPath = resolveLedgerPath(TELEMETRY_REL, root);
 
   // No module(s) or no telemetry → advisory surface has nothing to say, but
   // that is a healthy "insufficient signal" state. Pass full points.
@@ -250,7 +253,10 @@ function buildAdvisoryCheck(root) {
 // for caller symmetry. The CODE imported here comes from the auditor's OWN modules
 // (derived from import.meta.url below), never from the audited target (review N2b).
 function computeAdvisoryTally(scorerPath, joinPath, telemetryPath, root) {
-  const sessionsPath = join(root, SESSIONS_REL);
+  // #1592: the repo's ONE sessions ledger (main checkout of a linked worktree),
+  // matching join.mjs's own default and c4.2 — telemetry stays at `root`, its
+  // hook writer is not mapped.
+  const sessionsPath = join(resolveEventsLedgerRoot(root), SESSIONS_REL);
   // Import the AUDITOR's OWN trusted modules — derived from THIS file's location,
   // NEVER from the audited `root`. The target's join.mjs/score.mjs are existence-
   // checked by the caller but never imported (would execute target code → N2b).

package/scripts/lib/host-identity.mjs

@@ -216,7 +216,9 @@ const HOST_ALIASES_MAX = 16;
  * @param {number} mode
  */
 function _writeJsonAtomicSync(filePath, data, mode) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
+  // 0o700: the ledger lives in the private config dir, which must not come out
+  // 0777 under umask 000 (#1629).
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
   const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
   try {
     // `flag: 'wx'` + `mode` on the CREATE, never a chmod after the rename.
@@ -486,10 +488,11 @@ async function _readJsonSafe(p) {
   }
 }
 
-async function _writeJsonAtomic(filePath, data, { mode } = {}) {
-  await mkdir(path.dirname(filePath), { recursive: true });
+async function _writeJsonAtomic(filePath, data, { mode, dirMode } = {}) {
+  await mkdir(path.dirname(filePath), dirMode === undefined ? { recursive: true } : { recursive: true, mode: dirMode });
   const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-  await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  // mode at creation closes the 0666 window before the chmod below (#1632).
+  await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', mode === undefined ? 'utf8' : { encoding: 'utf8', mode });
   const { rename } = await import('node:fs/promises');
   await rename(tmp, filePath);
   if (mode !== undefined) {
@@ -541,6 +544,7 @@ export async function getPrivateHostInfo(projectRoot) {
     return cached;
   }
   const fresh = collectPrivateInfo(projectRoot);
-  await _writeJsonAtomic(f, fresh, { mode: 0o600 });
+  // dirMode only here: the public twin goes to the repo's .orchestrator/ (#1629).
+  await _writeJsonAtomic(f, fresh, { mode: 0o600, dirMode: 0o700 });
   return fresh;
 }

package/scripts/lib/http-request.mjs

@@ -0,0 +1,64 @@
+/**
+ * Buffered HTTP response subset for hook networking (#1612). Stdlib requests
+ * avoid Undici async-handle teardown crashes on Windows at process.exit().
+ * Internal configured endpoints only; no redirects are followed (SEC-014).
+ */
+import http from 'node:http';
+import https from 'node:https';
+
+export async function httpRequest(url, {
+  method = 'GET', headers = {}, body, timeoutMs = 3000, maxBytes = 1024 * 1024,
+} = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new Error('invalid maxBytes');
+  const target = new URL(url);
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+    throw new Error('HTTP request requires http: or https:');
+  }
+  return new Promise((resolve, reject) => {
+    const transport = target.protocol === 'https:' ? https : http;
+    const req = transport.request(target, { method, headers, agent: false }, res => {
+      const chunks = [];
+      let bytes = 0;
+      let overflow = false;
+      res.on('data', chunk => {
+        if (overflow) return;
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          overflow = true;
+          chunks.length = 0;
+          const error = new Error(`HTTP response exceeded maxBytes (${maxBytes})`);
+          clearTimeout(timer);
+          reject(error);
+          res.destroy();
+          req.destroy(error);
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('error', reject);
+      res.on('end', () => {
+        clearTimeout(timer);
+        if (overflow) return;
+        const text = Buffer.concat(chunks).toString('utf8');
+        const status = res.statusCode;
+        resolve({
+          ok: status >= 200 && status < 300,
+          status,
+          text: async () => text,
+          json: async () => JSON.parse(text),
+        });
+      });
+    });
+    // Wall-clock ceiling includes DNS, connection and body, unlike a socket
+    // inactivity timeout. Destroying closes the socket even for a stalled body.
+    const timer = setTimeout(() => {
+      req.destroy(new Error('HTTP request timed out'));
+    }, timeoutMs);
+    req.on('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    req.on('close', () => clearTimeout(timer));
+    req.end(body);
+  });
+}

package/scripts/lib/instruction-budget-guard.mjs

@@ -3,10 +3,12 @@
  *
  * Lightweight directive-budget guard for always-on `.claude/rules/*.md`.
  *
- * Sums the always-on directive count across the rule files that the
- * rule-loader classifies as always-on (no `globs:` frontmatter, and no
- * `paths:` alias either — issue #795: `paths:`-scoped rules are NOT
- * always-on and must not inflate this count) and warns when the total
+ * Sums the always-on directive count across the rule files that Claude Code
+ * loads always-on: every rule WITHOUT a `paths:` frontmatter key (#1638).
+ * Claude Code reads `paths:` only and ignores `globs:` without an error, so a
+ * `globs:`-only rule is always-on there and counts here, even though the
+ * rule-loader's own wave injection scopes it. Measured through
+ * `loadApplicableRules({ scopeKey: 'paths' })`. It warns when the total
  * exceeds a ceiling. "Mechanism over discipline" — the #668 instruction-
  * budget audit recommends this as a silent-now growth ratchet that only
  * fires when NEW always-on directives are added.
@@ -66,11 +68,13 @@
  * - SISTER GUARD / KNOWN DIVERGENCE (#906.3): the projects-baseline repo
  *   (resolved via `plan-baseline-path` / owner.yaml `baseline-path`) ships
  *   `scripts/check-instruction-budget.sh` under rule CCU-009c. It measures the
- *   SAME `.claude/rules/*.md` corpus and its total is NOT comparable to ours —
- *   it diverges on BOTH axes, in OPPOSITE directions:
+ *   SAME `.claude/rules/*.md` corpus and its total is NOT comparable to ours.
+ *   As of 2026-07-30 it diverged on BOTH axes, in OPPOSITE directions:
  *     (a) MEMBERSHIP — it classifies a file as path-scoped only on a `paths:`
- *         frontmatter key, so this repo's `globs:`-scoped rules stay inside ITS
- *         always-on set: 26 files where `loadApplicableRules` yields 12 here.
+ *         frontmatter key, so this repo's then `globs:`-scoped rules stayed
+ *         inside ITS always-on set: 26 files where we counted 12. That was
+ *         Claude Code's semantics and ours was wrong; since #1638 this guard
+ *         also scopes on `paths:` only, so the membership axis is aligned.
  *     (b) HEURISTIC — it counts only rule-ID anchors and imperative-keyword
  *         BULLET lines outside code fences, where `countDirectives` below
  *         counts every bullet, ordered-list item and `##`-or-deeper heading.
@@ -957,15 +961,16 @@ export function listMachineGeneratedRules(opts = {}) {
  *     ({@link isMachineGeneratedRule}). This is the population
  *     {@link DEFAULT_GENERATED_BYTE_CEILING} is a ceiling FOR: the thing that
  *     grows on its own, without anyone deciding to add a rule.
- *   - `pathScoped` — every rule with `globs:` (or its `paths:` alias, #795),
- *     i.e. the complement of the always-on set the three tier surfaces measure.
+ *   - `pathScoped` — every rule with a `paths:` key (#1638: Claude Code's only
+ *     scope key; a `globs:`-only rule is always-on there), i.e. the complement
+ *     of the always-on set the three tier surfaces measure.
  *     A real quantity, and the one this axis USED to report under the name
  *     `generated` — see the ceiling's docblock for what that cost.
  *
  * The two overlap but neither contains the other by construction: a
  * hand-written rule can be path-scoped (3 of them are here), and a generated
  * rule could in principle carry a `host-class` activation axis instead of
- * `globs:`.
+ * `paths:`.
  *
  * Neither can reuse `loadApplicableRules`: that loader takes a `scopePaths`
  * list and returns the rules APPLICABLE to it, so with `scopePaths: []` it
@@ -1005,10 +1010,10 @@ function measureRuleCorpora(rulesDir) {
     } catch {
       continue; // unreadable file — skip, never throw
     }
-    let globs;
+    let paths;
     let meta;
     try {
-      ({ globs, meta } = parseGlobsFrontmatter(content));
+      ({ paths, meta } = parseGlobsFrontmatter(content));
     } catch {
       continue;
     }
@@ -1017,8 +1022,9 @@ function measureRuleCorpora(rulesDir) {
       generated.files += 1;
       generated.bytes += bytes;
     }
-    // `globs === null` → always-on, already counted by the tier surfaces.
-    if (globs !== null) {
+    // `paths === null` → always-on for Claude Code, already counted by the
+    // tier surfaces (which load with `scopeKey: 'paths'` — same split).
+    if (paths !== null) {
       pathScoped.files += 1;
       pathScoped.bytes += bytes;
     }
@@ -1130,8 +1136,8 @@ function measureRuleCorpora(rulesDir) {
  *       reconciliation PROVENANCE marker (`auto-generated: true` /
  *       `learning-key` / `expires-at`) — the corpus
  *       {@link DEFAULT_GENERATED_BYTE_CEILING} judges (#1297).
- *     bySurface.pathScoped === {bytes, files} of every rule with `globs:`
- *       (or its `paths:` alias) — the complement of the always-on set, and
+ *     bySurface.pathScoped === {bytes, files} of every rule with a `paths:`
+ *       key (#1638) — the complement of the always-on set, and
  *       the number an operator reproduces from `ls .claude/rules/` (HR-106).
  *       Judged against {@link DEFAULT_PATH_SCOPED_BYTE_CEILING} into
  *       `overPathScopedBudget`, an `overBudget` term since #1316 (see that
@@ -1207,10 +1213,12 @@ export function computeInstructionBudget(opts = {}) {
     // — reused, not reimplemented. All three lists are loaded unconditionally
     // (not just the one matching `opts.context`) because `bySurface` reports
     // all three surfaces regardless of which `context` was requested for the
-    // PRIMARY totals (see doc above).
-    allEntries = loadApplicableRules({ rulesDir, scopePaths: [] });
-    waveEntries = loadApplicableRules({ rulesDir, scopePaths: [], context: 'wave' });
-    coordinatorEntries = loadApplicableRules({ rulesDir, scopePaths: [], context: 'coordinator' });
+    // PRIMARY totals (see doc above). `scopeKey: 'paths'` (#1638): the budget
+    // measures what Claude Code loads, and Claude Code scopes on `paths:` only.
+    const scopeKey = 'paths';
+    allEntries = loadApplicableRules({ rulesDir, scopePaths: [], scopeKey });
+    waveEntries = loadApplicableRules({ rulesDir, scopePaths: [], context: 'wave', scopeKey });
+    coordinatorEntries = loadApplicableRules({ rulesDir, scopePaths: [], context: 'coordinator', scopeKey });
   } catch {
     return empty;
   }
@@ -1242,7 +1250,7 @@ export function computeInstructionBudget(opts = {}) {
     // `pathScoped` keeps the old measurement under its honest name. Both are
     // disjoint from `totalBytes`, which counts always-on rules exclusively —
     // except that a generated rule activated by `host-class` rather than
-    // `globs:` would be always-on and therefore counted in both.
+    // `paths:` would be always-on and therefore counted in both.
     ...measureRuleCorpora(rulesDir),
   };
 

package/scripts/lib/io.mjs

@@ -888,13 +888,14 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  * @param {object} [opts]
  * @param {number} [opts.indent=2]      JSON.stringify indent.
  * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {number} [opts.mode]  File mode of the tmp file, kept by the rename (#1632).
  * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string, code: string|null }}
  *   `code` is the failing call's `err.code` (`'ENOSPC'`, `'EACCES'`, …), or `null`
  *   when the error carried none (a serialization TypeError, the partial-adapter
  *   refusal). Additive (#1032): `error` keeps its exact text.
  */
 export function writeJsonAtomicSync(filePath, data, opts = {}) {
-  const { indent = 2, tmpPrefix = '.tmp' } = opts;
+  const { indent = 2, tmpPrefix = '.tmp', mode } = opts;
 
   let body;
   try {
@@ -903,7 +904,7 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
     return _fsErrorEnvelope(err);
   }
 
-  const res = atomicWriteWithBackup(filePath, body, { tmpPrefix });
+  const res = atomicWriteWithBackup(filePath, body, { tmpPrefix, mode });
   return res.ok ? { ok: true } : res;
 }
 
@@ -980,6 +981,7 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * @param {BufferEncoding} [opts.encoding='utf8']  Encoding for a string `body`.
  * @param {boolean} [opts.backup=false]  Snapshot the existing file to `.bak-<ISO>` first.
  * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {number} [opts.mode]  File mode of the tmp file, kept by the rename (#1632).
  * @param {Date} [opts.now]  Clock seam for the backup stamp (tests).
  * @param {{ mkdirSync?: Function, writeFileSync?: Function, renameSync?: Function,
  *   copyFileSync?: Function, existsSync?: Function, unlinkSync?: Function }} [opts.fs]
@@ -995,6 +997,7 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
     encoding = 'utf8',
     backup = false,
     tmpPrefix = '.tmp',
+    mode,
     now = new Date(),
     fs: injectedFs,
   } = opts;
@@ -1043,7 +1046,7 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
     }
 
     tmpFile = _tmpPathFor(dir, tmpPrefix);
-    fsWriteFile(tmpFile, body, encoding);
+    fsWriteFile(tmpFile, body, mode === undefined ? encoding : { encoding, mode });
     fsRename(tmpFile, filePath);
 
     return { ok: true, path: filePath, bytes: _byteLength(body, encoding), backupPath };