session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/vcs-repo-spec.mjs

@@ -0,0 +1,362 @@
+/**
+ * vcs-repo-spec.mjs — resolve a glab/gh `-R`/`--repo` host-pinning spec from
+ * the local git remotes (#839).
+ *
+ * Why this exists: a bare `glab`/`gh` spawn (no shell wrapper, no `-R`) falls
+ * back to the ambient `GITLAB_HOST`/`GH_HOST` env var to pick a host. On a
+ * multi-GitLab-instance host that can resolve to the WRONG instance and fail
+ * silently — the root cause of #839.
+ *
+ * Injecting `GITLAB_HOST` into the spawn env is NOT the fix — it was tested
+ * live and FAILS whenever `~/.ssh/config` maps the GitLab hostname to a
+ * `HostName` IP alias: glab then reports "none of the git remotes configured
+ * for this repository correspond to the GITLAB_HOST environment variable"
+ * because the remote it sees is the IP, not the hostname. The only mechanism
+ * verified to survive that mismatch is passing the raw remote URL (or a
+ * HOST/OWNER/REPO spec) via `-R`/`--repo`.
+ *
+ * Preference order:
+ *   - vcs === 'github': remote `github` → `origin`
+ *   - vcs === 'gitlab' (default): remote `gitlab` → `origin`
+ *
+ * Returns `undefined` when no matching remote resolves — callers MUST treat
+ * this as "could not auto-detect" and omit the `-R`/`--repo` flag entirely
+ * (never emit `-R undefined`).
+ *
+ * Spec format (#872 follow-up): `resolveRepoSpec` returns the RAW remote URL
+ * for `vcs: 'gitlab'`, but a NORMALIZED `HOST/OWNER/REPO` string for
+ * `vcs: 'github'` — `gh -R`/`--repo` documents only `[HOST/]OWNER/REPO` as
+ * its accepted spec shape, unlike `glab -R` which explicitly accepts a full
+ * URL. See `resolveRepoSpec`'s own docblock for the full rationale. This
+ * module also exports `resolveRepoHost` for the `glab api`/`gh api`
+ * call sites, which accept neither `-R` nor a URL — only `--hostname`.
+ *
+ * Credential safety (#907, CWE-214): every value returned by `resolveRepoSpec`
+ * / `resolveRepoHost` has any embedded userinfo credential
+ * (`https://user:token@host/...`, the GitLab-CI checkout pattern) stripped at
+ * the source, so a credential can never reach a `-R`/`--repo`/`--hostname`
+ * argv position (visible via `ps` / `/proc/<pid>/cmdline`). A scp-like SSH
+ * login (`git@host:path`) is NOT a credential and is preserved verbatim. The
+ * exported `redactUrlCredentials` is the log-line defense-in-depth counterpart
+ * for values that bypass the source strip (e.g. a `--repo` override). See
+ * `stripUrlCredentials` / `userinfoIsCredential`.
+ *
+ * Lifted out of `scripts/archive-closed-prds.mjs::defaultGlabRepo` (that
+ * script's docblock described this exact problem months before #839 was
+ * filed) into a shared `scripts/lib/` module so
+ * `scripts/lib/issue-close-strip-labels.mjs` and
+ * `scripts/lib/spiral-carryover.mjs` can reuse the same, single
+ * implementation instead of each re-deriving it.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * argv-boundary guard (#872 follow-up, Q3-LOW centralization). A well-formed
+ * git remote URL or bare hostname never legitimately contains whitespace or a
+ * C0 control character — if a resolved value does, treat it as `undefined`
+ * ("could not auto-detect") rather than let it flow into a `-R`/`--repo`/
+ * `--hostname` argv position. This is the CENTRAL defense for both
+ * `resolveRepoSpec` and `resolveRepoHost`: the ~9 call sites across the repo
+ * that do a bare `if (spec) args.push('-R', spec)` do not re-check the value
+ * themselves, so they inherit this guard for free by going through either
+ * exported function here rather than reading a git remote URL directly.
+ */
+// eslint-disable-next-line no-control-regex -- deliberate: the argv-boundary guard must catch ALL C0 control characters, not only the \s subset
+const UNSAFE_ARGV_CHARS_RE = /[\s\x00-\x1f]/;
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true when `value` is a string containing whitespace or a
+ *   C0 control character — unsafe to forward as a single argv token.
+ */
+function isUnsafeForArgv(value) {
+  return typeof value === 'string' && UNSAFE_ARGV_CHARS_RE.test(value);
+}
+
+/**
+ * Embedded-credential guard (#907, CWE-214). A `scheme://userinfo@host/...`
+ * remote URL carries its userinfo (`user:password`, or a bare `token`) in the
+ * clear. The GitLab-CI checkout pattern
+ * `https://gitlab-ci-token:<MASKED>@host/group/project.git` is the canonical
+ * source. If that raw URL reaches a `-R`/`--repo` argv position it is visible
+ * via `ps` / `/proc/<pid>/cmdline`, and if it reaches a `--verbose` log line
+ * it is written to CI job output — either way the credential leaks. The
+ * 2026-07-26 argv-boundary guard ({@link UNSAFE_ARGV_CHARS_RE}) does NOT catch
+ * this: an embedded credential contains no whitespace or control character.
+ *
+ * Matches ONLY the `scheme://` URL forms (`https://`, `http://`, `ssh://`,
+ * `git+ssh://`, …). The scp-like SSH form `git@host:path` has no `://` and is
+ * therefore never matched — a bare SSH login user is not a credential. The
+ * userinfo class `[^/\s]+` stops at the first `/`, so an `@` that appears in a
+ * PATH (e.g. `.../path@ref`) is never mistaken for userinfo. Because `@` is NOT
+ * excluded from the class, a greedy match binds `@` to the LAST `@` before the
+ * authority ends — the real userinfo/host separator per RFC 3986 (and how
+ * glab/gh parse it). This closes the residual-credential leak where a raw `@`
+ * inside the token/password (`user:gl@token@host`, or nested `a:b@c:d@host`)
+ * previously left a partial secret after a first-`@`-only match (#907 MED-1).
+ */
+const URL_WITH_USERINFO_RE = /([a-z][a-z0-9+.-]*:\/\/)([^/\s]+)@/gi;
+
+/**
+ * Decide whether a matched `scheme://userinfo@` is a CREDENTIAL (strip/redact)
+ * or a legitimate login username (leave untouched).
+ *
+ * A credential is either:
+ *   - any userinfo carrying a password component (`user:pass`, a `:` present) —
+ *     for ANY scheme, including `ssh://user:pass@host`; or
+ *   - a bare userinfo on an `http`/`https` scheme (`https://token@host`) — HTTPS
+ *     git auth passes tokens/PATs through the userinfo slot, so a bare userinfo
+ *     there is a token, never a plain username.
+ *
+ * A bare userinfo on a non-HTTP scheme (`ssh://git@host`) is a login username,
+ * NOT a credential — SSH authenticates with keys, never a URL-embedded secret —
+ * so it is left untouched, consistent with the scp-like `git@host:path` case.
+ *
+ * @param {string} scheme e.g. `https://` (includes the trailing `://`)
+ * @param {string} userinfo the substring between `scheme` and `@`
+ * @returns {boolean}
+ */
+function userinfoIsCredential(scheme, userinfo) {
+  if (userinfo.includes(':')) return true;
+  return /^https?:\/\/$/i.test(scheme);
+}
+
+/**
+ * Strip credential userinfo from a single remote URL, returning the URL with
+ * host/path/project-spec EXACTLY preserved. A credential-free URL (and the
+ * scp-like `git@host:path` SSH form) is returned BYTE-IDENTICAL — the strip is
+ * a no-op unless {@link userinfoIsCredential} classifies the userinfo as a
+ * secret. Never throws; a non-string returns unchanged.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function stripUrlCredentials(url) {
+  if (typeof url !== 'string') return url;
+  return url.replace(URL_WITH_USERINFO_RE, (match, scheme, userinfo) =>
+    userinfoIsCredential(scheme, userinfo) ? scheme : match,
+  );
+}
+
+/**
+ * Defense-in-depth redactor for LOG output: replace any credential userinfo in
+ * an arbitrary text string (e.g. a verbose `glab … -R <spec>` line) with a
+ * `***` marker, leaving the surrounding text and the URL host/path intact. Used
+ * by `scripts/vault-integration-watcher.mjs`'s `verbose()` to cover the
+ * `--repo <spec>` override path, which bypasses the source-level strip in
+ * {@link resolveRawRemoteUrl}. Never throws; a non-string returns unchanged.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function redactUrlCredentials(text) {
+  if (typeof text !== 'string') return text;
+  return text.replace(URL_WITH_USERINFO_RE, (match, scheme, userinfo) =>
+    userinfoIsCredential(scheme, userinfo) ? `${scheme}***@` : match,
+  );
+}
+
+/**
+ * Default git-remote runner: `git -C <repoRoot> remote get-url <name>`.
+ * Never throws — returns `{ ok:false, stdout:'', stderr }` on any failure
+ * (missing remote, not a git repo, git not on PATH, ...).
+ *
+ * @param {string[]} gitArgs
+ * @returns {{ ok: boolean, stdout: string, stderr: string }}
+ */
+function defaultGitRun(gitArgs) {
+  try {
+    const stdout = execFileSync('git', gitArgs, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, stdout: String(stdout ?? ''), stderr: '' };
+  } catch (err) {
+    const stderr =
+      err && err.stderr ? String(err.stderr) : err && err.message ? String(err.message) : 'unknown error';
+    return { ok: false, stdout: '', stderr };
+  }
+}
+
+/** Remote-name preference order, per VCS. */
+const REMOTE_PREFERENCE = {
+  gitlab: ['gitlab', 'origin'],
+  github: ['github', 'origin'],
+};
+
+/**
+ * The OTHER platform's well-known public host, per requested vcs — the one
+ * case a resolved remote URL can be PROVEN to belong to the wrong VCS family
+ * without any repo-specific host configuration (self-hosted GitLab/GitHub
+ * Enterprise instances can live at ANY domain, so this deliberately checks
+ * only the unambiguous public-host case, not a general host allow-list).
+ */
+const WRONG_FAMILY_HOST = {
+  gitlab: 'github.com',
+  github: 'gitlab.com',
+};
+
+/**
+ * Extract the bare hostname from a git remote URL, handling both the HTTPS
+ * (`https://host/owner/repo.git`) and SSH (`git@host:owner/repo.git`) forms.
+ * Returns `null` for an unrecognized shape (never throws).
+ *
+ * @param {string} url
+ * @returns {string|null}
+ */
+function extractHost(url) {
+  const httpsMatch = /^https?:\/\/([^/]+)/i.exec(url);
+  if (httpsMatch) return httpsMatch[1].toLowerCase();
+  const sshMatch = /^[^@\s]+@([^:\s]+):/i.exec(url);
+  if (sshMatch) return sshMatch[1].toLowerCase();
+  return null;
+}
+
+/**
+ * Normalize a github remote URL (HTTPS or SSH) into the `HOST/OWNER/REPO`
+ * shape `gh -R`/`--repo` documents as its accepted spec format. gh does NOT
+ * accept a raw remote URL the way `glab -R` does — only `[HOST/]OWNER/REPO`.
+ * Strips a trailing `.git` suffix and any trailing slash.
+ *
+ * Falls back to returning `url` unchanged when it does not match the
+ * expected `host/owner/repo` shape (never throws) — a raw URL is still
+ * strictly better than omitting `-R` entirely.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function normalizeGithubSpec(url) {
+  const httpsMatch = /^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i.exec(url);
+  if (httpsMatch) {
+    const [, host, owner, repo] = httpsMatch;
+    return `${host.toLowerCase()}/${owner}/${repo}`;
+  }
+  const sshMatch = /^[^@\s]+@([^:\s]+):([^/]+)\/([^/]+?)(?:\.git)?\/?$/i.exec(url);
+  if (sshMatch) {
+    const [, host, owner, repo] = sshMatch;
+    return `${host.toLowerCase()}/${owner}/${repo}`;
+  }
+  return url;
+}
+
+/**
+ * Resolve the raw remote URL for the requested vcs — shared by
+ * `resolveRepoSpec` and `resolveRepoHost` so both apply the identical
+ * remote-preference-order + cross-family-guard resolution.
+ *
+ * Cross-family guard (#839 follow-up): a candidate URL whose host is the
+ * OTHER platform's well-known public host (`github.com` under vcs:'gitlab',
+ * `gitlab.com` under vcs:'github') is skipped rather than returned — passing
+ * it to `glab`/`gh -R` would be a guaranteed hard failure, strictly worse
+ * than the ambient-resolution fallback #839 replaced. This is a narrow,
+ * unambiguous check only; it does not attempt to validate self-hosted
+ * domains, which cannot be distinguished from a URL string alone.
+ *
+ * Credential guard (#907, CWE-214): the raw `git remote get-url` output can
+ * be `https://user:token@host/...` (GitLab-CI checkout pattern). The userinfo
+ * is stripped HERE, at the single source both `resolveRepoSpec` and
+ * `resolveRepoHost` flow through, BEFORE the cross-family host check and
+ * before the value can reach any `-R`/`--repo`/`--hostname` argv position —
+ * see {@link stripUrlCredentials}. A credential-free URL is unchanged
+ * (byte-identical), so #839/#872 behaviour is preserved.
+ *
+ * @param {{
+ *   repoRoot?: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} [opts]
+ * @returns {string|undefined}
+ */
+function resolveRawRemoteUrl({ repoRoot, vcs = 'gitlab', gitRun = defaultGitRun } = {}) {
+  const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
+  const root = repoRoot ?? process.cwd();
+  const wrongFamilyHost = WRONG_FAMILY_HOST[vcsResolved];
+
+  for (const remote of REMOTE_PREFERENCE[vcsResolved]) {
+    const { ok, stdout } = gitRun(['-C', root, 'remote', 'get-url', remote]);
+    const url = ok ? stripUrlCredentials(stdout.trim()) : '';
+    if (!url) continue;
+    if (extractHost(url) === wrongFamilyHost) continue;
+    return url;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the glab/gh `-R`/`--repo` host-pinning spec.
+ *
+ * Format contract differs by vcs, because `glab -R` and `gh -R` accept
+ * different spec shapes:
+ *   - `vcs: 'gitlab'` (default): the RAW remote URL, verbatim. `glab -R`
+ *     explicitly accepts a full URL, and GitLab group namespaces can nest
+ *     arbitrarily deep (`group/subgroup/project`), which makes a reliable
+ *     `OWNER/REPO` derivation impossible from the URL alone — so the raw URL
+ *     is the only unambiguous spec here.
+ *   - `vcs: 'github'`: the NORMALIZED `HOST/OWNER/REPO` form (see
+ *     `normalizeGithubSpec`). `gh -R`/`--repo` documents ONLY
+ *     `[HOST/]OWNER/REPO` as accepted input — a raw URL is not guaranteed to
+ *     parse the same way, and GitHub repos are always exactly two path
+ *     segments (owner/repo), so the derivation is unambiguous.
+ *
+ * Returns `undefined` when no matching remote resolves — callers MUST treat
+ * this as "could not auto-detect" and omit the `-R`/`--repo` flag entirely
+ * (never emit `-R undefined`). Also returns `undefined` when the resolved
+ * spec contains whitespace or a control character — see the module-level
+ * argv-boundary guard ({@link isUnsafeForArgv}), which this function applies
+ * to the FINAL spec value (post `normalizeGithubSpec`, when applicable).
+ *
+ * @param {{
+ *   repoRoot?: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} [opts]
+ * @returns {string|undefined}
+ */
+export function resolveRepoSpec({ repoRoot, vcs = 'gitlab', gitRun = defaultGitRun } = {}) {
+  const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
+  const url = resolveRawRemoteUrl({ repoRoot, vcs: vcsResolved, gitRun });
+  if (!url) return undefined;
+  const spec = vcsResolved === 'github' ? normalizeGithubSpec(url) : url;
+  return isUnsafeForArgv(spec) ? undefined : spec;
+}
+
+/**
+ * Resolve the bare hostname of the matching remote, for use with
+ * `glab api --hostname`/`gh api --hostname` — the `api` subcommand of both
+ * CLIs does NOT accept `-R`/`--repo` (it has no repo concept), only a
+ * `--hostname` flag to pin which instance the request targets. This is the
+ * host-pinning counterpart to `resolveRepoSpec` for those api-only call
+ * sites.
+ *
+ * Applies the identical remote-preference-order + cross-family-guard
+ * resolution as `resolveRepoSpec`, just returning the host instead of the
+ * full spec — same contract: `undefined` ⇒ caller omits the flag entirely.
+ * Also applies the same argv-boundary guard ({@link isUnsafeForArgv}) to the
+ * resolved host before returning it.
+ *
+ * @param {{
+ *   repoRoot?: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} [opts]
+ * @returns {string|undefined}
+ */
+export function resolveRepoHost({ repoRoot, vcs, gitRun } = {}) {
+  const url = resolveRawRemoteUrl({ repoRoot, vcs, gitRun });
+  const host = url ? (extractHost(url) ?? undefined) : undefined;
+  return isUnsafeForArgv(host) ? undefined : host;
+}
+
+/**
+ * @deprecated Back-compat alias for `archive-closed-prds.mjs`'s original
+ * `defaultGlabRepo(repoRoot, gitRunFn)` positional signature (gitlab-only).
+ * New callers should use `resolveRepoSpec`.
+ *
+ * @param {string} repoRoot
+ * @param {(args: string[]) => { ok: boolean, stdout: string, stderr: string }} gitRunFn
+ * @returns {string|undefined}
+ */
+export function defaultGlabRepo(repoRoot, gitRunFn) {
+  return resolveRepoSpec({ repoRoot, vcs: 'gitlab', gitRun: gitRunFn });
+}

package/scripts/lib/wave-resource-gate.mjs

@@ -20,7 +20,7 @@ import { probe } from './resource-probe.mjs';
  * "proceed" decision.
  *
  * @param {object} opts - Same opts shape as evaluateWaveResourceGate
- * @returns {Promise<{ramFreeGb: number, ramAvailableGb: number|null, cpuLoadPct: number, concurrentSessions: number} | {probeFailed: true}>}
+ * @returns {Promise<{ramFreeGb: number, ramAvailableGb: number|null, cpuLoadPct: number, cpuLoad5mPct: number|null, concurrentSessions: number} | {probeFailed: true}>}
  */
 async function extractMeasurements(opts) {
   const { probeOverride } = opts;
@@ -31,6 +31,8 @@ async function extractMeasurements(opts) {
       // Tests may supply ramAvailableGb to exercise the macOS path; absent → null.
       ramAvailableGb: probeOverride.ramAvailableGb ?? null,
       cpuLoadPct: probeOverride.cpuLoadPct,
+      // 5m-average CPU pct (#943); absent → null (legacy overrides → 1m-only judging).
+      cpuLoad5mPct: probeOverride.cpuLoad5mPct ?? null,
       concurrentSessions: probeOverride.concurrentSessions,
     };
   }
@@ -47,6 +49,9 @@ async function extractMeasurements(opts) {
     // os.freemem() is already accurate. (#667)
     ramAvailableGb: snapshot.ram_available_gb ?? null,
     cpuLoadPct: snapshot.cpu_load_pct,
+    // 5m load-average as pct-of-cores (#943). null on Windows/zero-load, where
+    // the gate falls back to judging the 1m-derived cpu_load_pct alone.
+    cpuLoad5mPct: snapshot.cpu_load_5m_pct ?? null,
     // concurrent sessions: number of claude processes found by the probe.
     concurrentSessions: snapshot.claude_processes_count ?? 0,
   };
@@ -54,15 +59,89 @@ async function extractMeasurements(opts) {
 
 /**
  * Apply the gate decision rule sequence (rules 3-8) given measurements and
- * config. Returns the full gate result.
+ * config, then apply the HR-004 heavy-repo preflight ceiling on top. Returns
+ * the full gate result.
  *
- * @param {{ramFreeGb: number, cpuLoadPct: number, concurrentSessions: number}} measurements
+ * @param {{ramFreeGb: number, ramAvailableGb?: number|null, cpuLoadPct: number, cpuLoad5mPct?: number|null, concurrentSessions: number}} measurements
  * @param {object} opts - Same opts shape as evaluateWaveResourceGate
  * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
  */
 function applyDecisionRules(measurements, opts) {
+  const result = computeResourceDecision(measurements, opts);
+  return applyHeavyRepoCap(result, opts);
+}
+
+/**
+ * Resolve an `agents-per-wave` config value into a plain numeric cap, or
+ * `null` when no cap should apply.
+ *
+ * `_coerceInteger()` (scripts/lib/config/coercers.mjs) parses the documented
+ * HR-003 parenthetical-override syntax — `agents-per-wave: 4 (deep: 18)` —
+ * into an OBJECT `{ default: 4, deep: 18 }`, not a plain number. Feeding that
+ * object straight into a `typeof cap !== 'number'` guard makes the heavy-repo
+ * cap silently no-op for every repo using the override syntax, which defeats
+ * HR-004 exactly where it matters most (a heavy repo that also runs deep
+ * sessions).
+ *
+ * `evaluateWaveResourceGate()` has no session-mode input in scope — `waveRole`
+ * is a wave role (e.g. "Impl-Core"), not a session mode (e.g. "deep") — so the
+ * object shape resolves to `cap.default` here. That is the conservative
+ * choice: the documented HR-003 convention writes the override as
+ * `<default> (mode: <higher-ceiling>)`, i.e. `default` is the MORE
+ * restrictive of the pair. Falling back to it can only under-apply a looser
+ * mode-specific ceiling; it never lets a heavy repo exceed its base cap.
+ *
+ * @param {number|{default: number, [mode: string]: number}|*} cap
+ * @returns {number|null}
+ */
+function resolveApwCap(cap) {
+  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
+  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
+    const def = cap.default;
+    return typeof def === 'number' && Number.isFinite(def) ? def : null;
+  }
+  return null;
+}
+
+/**
+ * HR-003/HR-004 heavy-repo preflight ceiling (baseline #60). A STATIC cap
+ * independent of the live resource-probe verdict: when `config['heavy-repo']`
+ * is `true`, `agents` is clamped to at most `config['agents-per-wave']`
+ * (resolved via {@link resolveApwCap} to handle the object-override shape).
+ * More-restrictive-wins — this only ever LOWERS `agents`, never raises it
+ * above what the resource-driven rules already decided (e.g. a
+ * coordinator-direct 0 stays 0).
+ *
+ * @param {{decision: string, agents: number, reasons: string[], measurements: object}} result
+ * @param {object} opts - Same opts shape as evaluateWaveResourceGate
+ * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
+ */
+function applyHeavyRepoCap(result, opts) {
+  const { config } = opts;
+  if (!config || config['heavy-repo'] !== true) return result;
+  const cap = resolveApwCap(config['agents-per-wave']);
+  if (cap === null) return result;
+  if (result.agents <= cap) return result; // already within the ceiling — never raise
+  return {
+    ...result,
+    decision: result.decision === 'coordinator-direct' ? 'coordinator-direct' : 'reduce',
+    agents: cap,
+    reasons: [...result.reasons, `heavy-repo: true caps agents-per-wave to ${cap} (HR-004)`],
+  };
+}
+
+/**
+ * Rules 3-8: resource-driven decision sequence (RAM/CPU/concurrent-sessions).
+ * Extracted so `applyDecisionRules` can layer the HR-004 heavy-repo cap on
+ * top without duplicating this sequence.
+ *
+ * @param {{ramFreeGb: number, ramAvailableGb?: number|null, cpuLoadPct: number, cpuLoad5mPct?: number|null, concurrentSessions: number}} measurements
+ * @param {object} opts - Same opts shape as evaluateWaveResourceGate
+ * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
+ */
+function computeResourceDecision(measurements, opts) {
   const { config, plannedAgents } = opts;
-  const { ramFreeGb, ramAvailableGb, cpuLoadPct, concurrentSessions } = measurements;
+  const { ramFreeGb, ramAvailableGb, cpuLoadPct, cpuLoad5mPct, concurrentSessions } = measurements;
   const T = config['resource-thresholds'];
 
   // macOS fix (#667): os.freemem() reports only `Pages free`, which reads
@@ -111,24 +190,41 @@ function applyDecisionRules(measurements, opts) {
     };
   }
 
-  // Rule 6: CPU overloaded → reduce.
-  if (cpuLoadPct > T['cpu-load-max-pct']) {
+  // Rule 6: CPU overloaded → reduce. #943: this gate runs, by construction,
+  // right after the coordinator's own CPU-saturating quality-gate run — the 1m
+  // load average still carries that decaying tail (observed 2026-07-30:
+  // 96% → 91% → 78% → 75% within 36s), so a 1m-only reading systematically
+  // over-reports and halves waves without a real bottleneck. When the probe
+  // supplied a numeric 5m percentage, judge on min(1m, 5m): only-1m-high is a
+  // decaying transient (informational, no reduce), both-high is genuine
+  // sustained load. `cpuLoad5mPct` null (legacy overrides, Windows) → 1m-only.
+  const has5mCpu = typeof cpuLoad5mPct === 'number' && Number.isFinite(cpuLoad5mPct);
+  const effectiveCpuLoadPct = has5mCpu ? Math.min(cpuLoadPct, cpuLoad5mPct) : cpuLoadPct;
+  if (effectiveCpuLoadPct > T['cpu-load-max-pct']) {
+    const detail = has5mCpu ? ` (min of 1m ${cpuLoadPct}% / 5m ${cpuLoad5mPct}%)` : '';
     return {
       decision: 'reduce',
       agents: Math.max(1, Math.floor(plannedAgents / 2)),
       reasons: [
-        `CPU load ${cpuLoadPct}% > max ${T['cpu-load-max-pct']}% — reducing agent count`,
+        `CPU load ${effectiveCpuLoadPct}%${detail} > max ${T['cpu-load-max-pct']}% — reducing agent count`,
       ],
       measurements,
     };
   }
+  const cpuTransientNote =
+    has5mCpu && cpuLoadPct > T['cpu-load-max-pct']
+      ? `info: CPU 1m load ${cpuLoadPct}% > max ${T['cpu-load-max-pct']}% but 5m load ${cpuLoad5mPct}% is below — decaying transient (typically the coordinator's own just-finished gate run), not reducing (#943)`
+      : null;
 
   // Rule 7: concurrent sessions above warn → proceed with warning.
   if (concurrentSessions > T['concurrent-sessions-warn']) {
     return {
       decision: 'proceed',
       agents: plannedAgents,
-      reasons: [`warn: ${concurrentSessions} concurrent sessions`],
+      reasons: [
+        ...(cpuTransientNote ? [cpuTransientNote] : []),
+        `warn: ${concurrentSessions} concurrent sessions`,
+      ],
       measurements,
     };
   }
@@ -137,7 +233,10 @@ function applyDecisionRules(measurements, opts) {
   return {
     decision: 'proceed',
     agents: plannedAgents,
-    reasons: ['all thresholds within bounds'],
+    reasons: [
+      ...(cpuTransientNote ? [cpuTransientNote] : []),
+      'all thresholds within bounds',
+    ],
     measurements,
   };
 }
@@ -148,14 +247,19 @@ function applyDecisionRules(measurements, opts) {
  * @param {object} opts.config - Parsed Session Config (from parse-config.sh output)
  * @param {number} opts.plannedAgents - Number of agents the session-plan wants to dispatch
  * @param {string} opts.waveRole - e.g. "Impl-Core", "Quality"
- * @param {object} [opts.probeOverride] - {ramFreeGb, cpuLoadPct, concurrentSessions} for
- *   testing; when omitted, calls resource-probe
+ * @param {object} [opts.probeOverride] - {ramFreeGb, cpuLoadPct, cpuLoad5mPct?, concurrentSessions}
+ *   for testing; when omitted, calls resource-probe
  * @returns {Promise<{decision: "proceed"|"reduce"|"coordinator-direct", agents: number, reasons: string[], measurements: object}>}
  */
 export async function evaluateWaveResourceGate(opts) {
   const { config, plannedAgents } = opts;
 
   // Rule 1: resource-awareness disabled — skip all probing.
+  // `resource-awareness: false` is a FULL opt-out, INCLUDING the HR-004
+  // heavy-repo static cap below (applyHeavyRepoCap runs only inside
+  // applyDecisionRules, which this early return bypasses entirely). The
+  // static cap only applies on the resource-aware path — deliberate,
+  // reviewed 2026-07-23, baseline #60.
   if (config['resource-awareness'] === false) {
     return {
       decision: 'proceed',

package/scripts/lib/worktree/listing.mjs

@@ -2,7 +2,8 @@
  * worktree/listing.mjs — list and filter worktrees.
  *
  * Exports:
- *   listWorktrees()                            — list all git worktrees
+ *   listWorktrees()                            — list all git worktrees (bare array; swallows git failure)
+ *   listWorktreesChecked()                     — same listing WITH a "git actually ran" signal (#919.3)
  *   applyWorktreeExcludes(wtPath, patterns)    — remove top-level dirs from worktree
  *
  * No imports from lifecycle.mjs — this module is intentionally a leaf of the
@@ -18,23 +19,39 @@ import path from 'node:path';
 // ---------------------------------------------------------------------------
 
 /**
- * List all git worktrees in the current repository.
+ * List all git worktrees WITH an explicit "git actually ran" signal (#919.3).
+ *
+ * The bare `listWorktrees()` below swallows a failing `git worktree list` into
+ * an empty array — indistinguishable from "git ran, repo has no extra
+ * worktrees". That collapse is the last fail-open gap in the
+ * `checkLiveForeignSession` full path (peer-discovery.mjs, #906/#908 residual):
+ * a total surface failure read as "nobody home". This variant keeps the listing
+ * contract but makes the failure DISTINGUISHABLE, so callers that need the
+ * distinction can make the fail-safe call themselves.
  *
  * @param {object} [opts]
  * @param {Function} [opts.$]  Optional zx-compatible executor. Defaults to real zx.$.
  *   Tests pass a mock here to avoid vi.mock('zx') under fork pool.
- * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
- *   Array of worktree descriptors; empty array if none or on parse error.
+ * @returns {Promise<{ok: boolean, worktrees: Array<{path: string, branch: string, head: string}>, error?: string}>}
+ *   `ok: true`  — `git worktree list` ran; `worktrees` is the (possibly empty)
+ *                 parsed listing. An empty list here is a MEASUREMENT.
+ *   `ok: false` — the git invocation itself failed (spawn error, non-zero
+ *                 exit, not a repo, …); `worktrees` is `[]` and `error` carries
+ *                 the failure message. An empty list here is NOT a measurement.
  */
-export async function listWorktrees(opts = {}) {
+export async function listWorktreesChecked(opts = {}) {
   const dollar = opts.$ ?? defaultDollar;
   const git = dollar({ cwd: process.cwd() });
   let output;
   try {
     const result = await git`git worktree list --porcelain`;
     output = result.stdout;
-  } catch {
-    return [];
+  } catch (err) {
+    return {
+      ok: false,
+      worktrees: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 
   const worktrees = [];
@@ -67,6 +84,26 @@ export async function listWorktrees(opts = {}) {
     worktrees.push(current);
   }
 
+  return { ok: true, worktrees };
+}
+
+/**
+ * List all git worktrees in the current repository.
+ *
+ * Thin backward-compatible wrapper over `listWorktreesChecked()`: existing
+ * callers get the bare array they always got, INCLUDING the historical
+ * swallow-to-`[]` on git failure. Callers that must distinguish "git ran,
+ * empty" from "git failed" use `listWorktreesChecked()` instead (#919.3).
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.$]  Optional zx-compatible executor. Defaults to real zx.$.
+ *   Tests pass a mock here to avoid vi.mock('zx') under fork pool.
+ * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
+ *   Array of worktree descriptors; empty array if none OR on git failure
+ *   (the two are indistinguishable here — by design, see wrapper note).
+ */
+export async function listWorktrees(opts = {}) {
+  const { worktrees } = await listWorktreesChecked(opts);
   return worktrees;
 }
 

package/scripts/mcp-server.sh

@@ -128,9 +128,23 @@ tool_session_config() {
     return
   fi
 
-  # Extract everything from "## Session Config" to the next heading or EOF
-  local config
-  config=$(sed -n '/^## Session Config$/,/^## /{/^## Session Config$/d;/^## /d;p;}' "$instr_file" 2>/dev/null) || true
+  # Extract everything from "## Session Config" to the next heading or EOF.
+  #
+  # The address matches isSessionConfigHeading() in
+  # scripts/lib/config/section-extractor.mjs (the SSOT) exactly: the literal
+  # heading, plus an optional CR so a CRLF checkout is read the same way. Shell
+  # cannot import the JS predicate, so the alignment is by hand and this
+  # comment names the authority. Before #968 this was the only STRICTER site in
+  # the repo — a bare `$` anchors before the CR in a BRE, so on a CRLF checkout
+  # (this plugin ships to Windows-side Codex/Cursor users) the tool reported
+  # "no Session Config section" for a file the runtime parses fine.
+  #
+  # `\r` is not portable inside a BRE (GNU sed only), so the CR is injected as
+  # a literal byte via printf.
+  local cr config sc_re
+  cr=$(printf '\r')
+  sc_re="^## Session Config${cr}\{0,1\}\$"
+  config=$(sed -n "/$sc_re/,/^## /{/$sc_re/d;/^## /d;p;}" "$instr_file" 2>/dev/null) || true
 
   if [[ -z "$config" ]]; then
     respond "$id" "$(text_content "No '## Session Config' section found in $instr_file")"