session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/validate/check-skill-script-paths.mjs

@@ -3,11 +3,13 @@
  * Check: every `scripts/**.mjs` path cited in `skills/`, `commands/`,
  * `agents/` and `docs/` either EXISTS or is annotated as deliberately absent
  * (#1176). Extended (#1187) to also cite `scripts/**.sh` and `hooks/**.sh` —
- * see "## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" below for why that
+ * see "## Mode" below for why that
  * half is advisory, not blocking. `docs/` joined `SCAN_DIRS` in #1208, after
  * the 22 dead paths it carried at the time (9 `.mjs`, all ADR/reference
  * prose) were annotated — see that section below for the census and why
  * widening the scan root had to wait for the annotation pass, not precede it.
+ * #1241 adds blocking repo-rooted `.md` paths quoted as complete inline-code
+ * spans, with the same annotations and fence handling. Scan roots stay fixed.
  *
  * ## Why
  *
@@ -50,7 +52,7 @@
  * looking misplaced. A malformed marker (unknown class, or `planned` without a
  * `#<iid>`) is itself a finding for the same reason — it must never fail silent.
  *
- * ## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh` (#1187)
+ * ## Mode: BLOCKING for `.mjs` / `.md`, ADVISORY for `.sh` (#1187)
  *
  * Unlike `check-doc-cli-commands.mjs`, the oracle here is the repository's own
  * filesystem, not a locally installed third-party binary — there is no version
@@ -115,6 +117,22 @@ export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs'])
  */
 const CITATION_RE = /scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
 
+/**
+ * A complete inline-code span, including spans delimited by multiple backticks.
+ * Consume the outer span before judging its content, so a quoted command that
+ * contains backticks cannot donate a nested path-looking substring.
+ */
+const INLINE_CODE_RE = /(?<!`)(`+)(.+?)(?<!`)\1(?!`)/g;
+
+/**
+ * #1241's bounded grammar: a literal repo-rooted .md path, optionally followed
+ * by :line, :line:end / :line-end, and #anchor. Only the file is checked.
+ * URLs, commands, absolute paths, skill-relative references/, variables and
+ * globs are outside this grammar. Matching is line-local; revisit if the
+ * instruction corpus adopts multiline path spans or another target root.
+ */
+const MARKDOWN_CITATION_RE = /^((?:docs|skills|commands|agents|templates|rules|scripts|hooks|tests|\.(?:claude|codex|cursor|pi|orchestrator|gitlab|github))\/[a-zA-Z0-9_./-]+\.md)(?::\d+(?:[:-]\d+)?)?(?:#[^\s`]+)?$/;
+
 /**
  * Filename fragments that mark a citation as an ILLUSTRATIVE placeholder —
  * `scripts/example.sh`, `hooks/my-hook.sh`, `scripts/<name>.sh` — rather than
@@ -211,6 +229,10 @@ export function extractCitations(lines) {
     for (const hit of raw.matchAll(CITATION_RE)) {
       citations.push({ line: lineNumber, path: hit[0] });
     }
+    for (const span of raw.matchAll(INLINE_CODE_RE)) {
+      const hit = span[2].match(MARKDOWN_CITATION_RE);
+      if (hit) citations.push({ line: lineNumber, path: hit[1] });
+    }
   };
 
   // A blockquoted fence is still a fence — the shared tracker strips the `>`
@@ -234,12 +256,12 @@ export function extractCitations(lines) {
 
 /**
  * Census the documentation corpus for dead `scripts/**.mjs`/`.sh` and
- * `hooks/**.sh` citations.
+ * `hooks/**.sh` citations, plus repo-rooted `.md` inline-code paths.
  *
  * @param {{pluginRoot: string, dirs?: string[], strictSh?: boolean}} options
  *   `strictSh` (default `false`) promotes a dead `.sh` citation from
  *   `severity: 'warn'` to `severity: 'fail'` — see the module docblock
- *   "Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" for why the default stays
+ *   "Mode" for why the default stays
  *   advisory in this release.
  * @returns {{ok: boolean, summary: object, findings: {kind: string, file: string, line: number, path: string, annotation: string | null, message: string, severity: 'fail' | 'warn'}[], toolError: boolean}}
  */
@@ -344,10 +366,11 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
         summary.existing += 1;
         continue;
       }
-      // An illustrative placeholder name needs no marker — see
+      // A script placeholder name needs no marker — see
       // `isPlaceholderCitation`'s docblock for the closed fragment list and
-      // its named ceiling.
-      if (isPlaceholderCitation(citation.path)) {
+      // its named ceiling. Markdown examples require explicit annotations:
+      // a real missing docs/foobar.md must not disappear because of its name.
+      if (path.extname(citation.path) !== '.md' && isPlaceholderCitation(citation.path)) {
         summary.placeholders += 1;
         continue;
       }
@@ -366,7 +389,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
       }
       if (marker && !marker.ok) continue; // already reported as bad-annotation
 
-      // `.mjs` is blocking exactly as before this module grew a `.sh` half.
+      // `.mjs` and `.md` are blocking.
       // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
       const isSh = path.extname(citation.path) === '.sh';
       const severity = isSh && !strictSh ? 'warn' : 'fail';
@@ -405,7 +428,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
  * @returns {number} 0 = clean, 1 = findings, 2 = tool error
  */
 export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {}) {
-  console.log('--- Check: scripts/*.mjs (+ *.sh) paths cited in skills/commands/agents exist ---');
+  console.log('--- Check: script and Markdown paths cited in skills/commands/agents/docs exist ---');
   const inspection = scanSkillScriptPaths({ pluginRoot, strictSh });
 
   for (const item of inspection.findings) {
@@ -427,7 +450,7 @@ export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {})
   const blockingCount = inspection.findings.filter((f) => f.severity !== 'warn').length;
   if (inspection.ok) {
     console.log(
-      `  PASS: ${s.citations} script citation(s) in ${s.filesScanned} doc file(s) — ` +
+      `  PASS: ${s.citations} file citation(s) in ${s.filesScanned} doc file(s) — ` +
         `${s.existing} exist, ${s.annotated} annotated as deliberately absent, ` +
         `${s.placeholders} placeholder(s)` +
         (s.warnings > 0 ? `, ${s.warnings} advisory .sh warning(s) (see --strict-sh)` : ''),

package/scripts/lib/validate/check-untracked-test-deps.mjs

@@ -629,28 +629,42 @@ function importClosure(repoRoot, entry, readSource) {
  */
 function checkIgnoreBatch(repoRoot, specs, out) {
   if (specs.length === 0) return;
-  const ci = spawnSync('git', ['check-ignore', '--stdin'], {
-    cwd: repoRoot, input: specs.join('\n'), encoding: 'utf8',
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  // 0 = at least one ignored (listed on stdout); 1 = none ignored; else fatal.
-  if (ci.status === 0) {
-    for (const line of (ci.stdout || '').split('\n')) {
-      const p = line.trim();
-      if (p) out.add(p);
+  let pending = specs;
+  for (;;) {
+    const ci = spawnSync('git', ['check-ignore', '--stdin'], {
+      cwd: repoRoot, input: pending.join('\n'), encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    // 0 = at least one ignored (listed on stdout); 1 = none ignored; else fatal.
+    if (ci.status === 0) {
+      for (const line of (ci.stdout || '').split('\n')) {
+        const p = line.trim();
+        if (p) out.add(p);
+      }
+      return;
     }
+    if (ci.status === 1) return;
+    // Git identifies this refused candidate precisely. Retrying only the rest
+    // preserves the old dropped-candidate semantics without bisecting healthy
+    // paths (78 subprocesses for five symlink descendants in the tracked tree).
+    const rejected = /^fatal: pathspec '([^'\n]+)' is beyond a symbolic link\r?\n?$/.exec(ci.stderr || '')?.[1];
+    if (rejected && pending.includes(rejected)) {
+      process.stderr.write(`  WARN: git check-ignore rejected "${rejected}" — candidate dropped (${(ci.stderr || '').trim()})\n`);
+      pending = pending.filter((spec) => spec !== rejected);
+      if (pending.length === 0) return;
+      continue;
+    }
+    if (pending.length === 1) {
+      process.stderr.write(
+        `  WARN: git check-ignore rejected "${pending[0]}" — candidate dropped (${(ci.stderr || '').trim().split('\n')[0]})\n`,
+      );
+      return;
+    }
+    const mid = pending.length >> 1;
+    checkIgnoreBatch(repoRoot, pending.slice(0, mid), out);
+    checkIgnoreBatch(repoRoot, pending.slice(mid), out);
     return;
   }
-  if (ci.status === 1) return;
-  if (specs.length === 1) {
-    process.stderr.write(
-      `  WARN: git check-ignore rejected "${specs[0]}" — candidate dropped (${(ci.stderr || '').trim().split('\n')[0]})\n`,
-    );
-    return;
-  }
-  const mid = specs.length >> 1;
-  checkIgnoreBatch(repoRoot, specs.slice(0, mid), out);
-  checkIgnoreBatch(repoRoot, specs.slice(mid), out);
 }
 
 /**

package/scripts/lib/validate/check-unwired-features.mjs

@@ -114,8 +114,9 @@
  * `CHANGELOG.md` is excluded from the prose corpus for the same reason: it is an
  * append-only record of what a PAST release shipped, so it names the symbols of
  * code that may since have died. Counting it silenced a true positive
- * (`soul-resolve.mjs`, whose only live claim is in `.claude/rules/owner-persona.md`
- * but whose symbols appear in a 2026-06 changelog entry).
+ * (`soul-resolve.mjs` — since DELETED as dead: its only live claim was in
+ * `.claude/rules/owner-persona.md`, while its symbols appeared in a 2026-06
+ * changelog entry).
  *
  * ## S4 `unreachable-library-module` — the question the machine can answer
  *
@@ -777,11 +778,11 @@ function mentionedModuleTokens(lines) {
  * ## Cluster roots — one defect, one line
  *
  * Only the ROOT of each unreachable cluster is reported: a module no OTHER
- * unreachable module references. `scripts/lib/owner-config.mjs` has no importer
- * and drags its whole 7-file `owner-config/` subtree down with it; reporting the
- * six interior files would multiply one deletion into seven findings that all
- * disappear together. Measured on the live tree: 71 unreachable modules collapse
- * to 50 roots. This is category separation in the sense of
+ * unreachable module references. A drag-cluster looks like this: an unimported
+ * top-level module whose own subtree of interior files goes down with it —
+ * reporting the interior files too would multiply one deletion into N findings
+ * that all disappear together. Measured on the live tree: 71 unreachable modules
+ * collapse to 50 roots. This is category separation in the sense of
  * `.claude/rules/development.md` § Guard & Threshold Design — a structural split,
  * never a raised threshold.
  *
@@ -794,9 +795,18 @@ function mentionedModuleTokens(lines) {
  *    switched off. Revisit if a real module-resolver (import-specifier resolution
  *    relative to the importing file) becomes cheap, or if a collided basename is
  *    ever confirmed to mask a true positive. The `coordinator-invoked-module`
- *    DOWNGRADE is exempt: there a colliding basename must be named with its
- *    `dirname/base` suffix, because that match moves a module OUT of the
- *    reportable class and would otherwise hide a true unreachable sibling.
+ *    DOWNGRADE is exempt, and since #1293 so is the CLUSTER-ROOT filter: in both
+ *    a colliding basename must be named with its `dirname/base` suffix, because
+ *    those matches move a module OUT of the reportable class and would otherwise
+ *    hide a true unreachable sibling. Measured cost of leaving the root filter
+ *    on bare basenames: `locks/index.mjs` and `worktree/index.mjs` were both
+ *    suppressed by a third unreachable module that merely mentioned bare
+ *    `index.mjs`, and only resurfaced when that module was deleted for an
+ *    unrelated reason. Remaining ceiling: two ambiguous roots whose mentioning
+ *    module ALSO carries the qualified form (e.g. an unreachable module that
+ *    literally writes `locks/index.mjs`) are still suppressed — correct when it
+ *    is a real reference, a mask when it is prose. Revisit if a qualified
+ *    mention is ever confirmed to hide a root.
  *  - **Reachable ≠ executed.** A module imported by a hook that never takes that
  *    branch reads as wired here. Proving execution needs coverage data, not a graph.
  *  - **Reachable from SOME entrypoint is not reachable from the PROMISED one.**
@@ -839,6 +849,10 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       // module an operator flagged. Measured 2026-08-28 on the first S4
       // allowlist entry: 52 → 51 unreachable modules plus one bogus stale line.
       mentions: relative === SELF_REL ? new Set() : mentionedModuleTokens(lines),
+      // Raw text, kept for the QUALIFIED (`dirname/base`) re-check in the
+      // root filter below: `mentionedModuleTokens` strips the directory, so
+      // a colliding basename can only be disambiguated against the body.
+      rawBody: relative === SELF_REL ? '' : body,
     };
   });
 
@@ -876,10 +890,38 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     (module) => !reachable.has(module.relative) && !module.entrypoint && module.exports.length > 0,
   );
   const unreachableSet = new Set(unreachable.map((module) => module.relative));
-  const roots = unreachable.filter(
-    (module) =>
-      !unreachable.some((other) => other.relative !== module.relative && other.mentions.has(module.base)),
-  );
+  // Basename census, shared by the root filter below and the downgrade half
+  // further down. A bare basename is only a valid module reference when it is
+  // UNIQUE in the corpus: `writer.mjs` names both `peer-cards/writer.mjs` and
+  // `reconcile/writer.mjs` (measured 2026-09-07), so a doc naming ONE of them
+  // would otherwise downgrade BOTH out of the reportable class — a true
+  // unreachable silently moved into the advisory half. For a colliding basename
+  // the reference must therefore carry at least the `dirname/base` suffix
+  // (`reconcile/writer.mjs`); unique basenames keep the cheaper bare match.
+  // Direction matters in both consumers: this can only ever ADD findings back to
+  // the reportable class, never remove one.
+  /** @type {Map<string, number>} */
+  const basenameCount = new Map();
+  for (const module of modules) basenameCount.set(module.base, (basenameCount.get(module.base) ?? 0) + 1);
+
+  const roots = unreachable.filter((module) => {
+    // A bare-basename mention only suppresses when the basename is UNIQUE
+    // (see the census above). When it collides, the mentioning module must name
+    // the `dirname/base` form in its body — otherwise ONE unreachable module
+    // mentioning bare `index.mjs` masks EVERY differently-pathed `index.mjs`
+    // root at once (#1293: `locks/index.mjs` + `worktree/index.mjs` were masked
+    // by a third unreachable module until that module was deleted for an
+    // unrelated reason).
+    const ambiguous = (basenameCount.get(module.base) ?? 0) > 1;
+    const qualified = module.relative.split(path.sep).slice(-2).join('/');
+    const qualifiedRe = ambiguous ? tokenMatcher(qualified) : null;
+    return !unreachable.some(
+      (other) =>
+        other.relative !== module.relative &&
+        other.mentions.has(module.base) &&
+        (qualifiedRe === null || qualifiedRe.test(other.rawBody)),
+    );
+  });
 
   // Category split (see § Category split in the doc block above): an INSTRUCTION
   // document that names both the module AND one of its exported symbols is an
@@ -893,19 +935,6 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     .sort()
     .map((file) => ({ relative: path.relative(pluginRoot, file), body: readFileSync(file, 'utf8') }));
 
-  // Basename census for the downgrade half. A bare basename is only a valid
-  // module reference when it is UNIQUE in the corpus: `writer.mjs` names both
-  // `peer-cards/writer.mjs` and `reconcile/writer.mjs` (measured 2026-09-07),
-  // so a doc naming ONE of them would otherwise downgrade BOTH out of the
-  // reportable class — a true unreachable silently moved into the advisory
-  // half. For a colliding basename the doc must therefore carry at least the
-  // `dirname/base` suffix (`reconcile/writer.mjs`); unique basenames keep the
-  // cheaper bare match. Direction matters: this can only ever ADD findings back
-  // to the reportable class, never remove one.
-  /** @type {Map<string, number>} */
-  const basenameCount = new Map();
-  for (const module of modules) basenameCount.set(module.base, (basenameCount.get(module.base) ?? 0) + 1);
-
   let coordinatorInvoked = 0;
   const findings = roots.map((module) => {
     // Docs write POSIX separators regardless of host; `path.relative` does not.

package/scripts/lib/vault-mirror/process.mjs

@@ -879,7 +879,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // This is deliberately REDUNDANT with the renderer's status mapping (#909,
   // render-sessions.mjs) — see that module's header. The filter removes one
   // status from the vault; the mapping keeps every OTHER status honest, and
-  // guards the generators' other entry point (the render.mjs barrel).
+  // guards the generators' other entry point (this module imports
+  // render-learnings.mjs and render-sessions.mjs directly — no barrel).
   if (!isRealSession(entry)) {
     return emitEntryAction(_lineNum, ctx, {
       action: 'skipped-abandoned',

package/scripts/lib/vault-status/board-lock.mjs

@@ -60,6 +60,15 @@ const DEFAULT_POLL_MS = 50;
  * REVISIT when a board sweep is measured above 30 s (half the TTL — the point
  * at which a slow host crosses it), or when an `onLockOutcome` carrying
  * `staleOverride` is observed in the events ledger on a host that had no crash.
+ *
+ * What expiry does NOT do: protect the section it bounds — past 60 s the next
+ * writer takes over while this one may still run (see file-lock.mjs § Lease
+ * semantics). What IS guaranteed since #1285: the late writer's release can no
+ * longer delete the successor's lock, because release runs under the same
+ * `.acquire` guard as takeover. A `not-owner` release here therefore means THIS
+ * writer's lease expired mid-section — the lost-update case above, never a
+ * benign miss. Since #1336 that release result reaches callers through
+ * `onReleaseOutcome` (see withBoardLock).
  */
 const DEFAULT_STALE_MS = 60_000;
 
@@ -105,6 +114,11 @@ export function boardLockPathFor(vaultDir) {
  *   is present only when this acquire OVERRODE an aged lock, and carries
  *   `file-lock.mjs`'s own reason token — the observable behind the
  *   DEFAULT_STALE_MS revisit trigger.
+ * @param {(release: { ok: boolean, reason?: string }) => void} [opts.onReleaseOutcome]
+ *   — diagnostic sink for the release result, called at most once, AFTER `fn`
+ *   (only on the locked path). `{ ok: false, reason: 'not-owner' }` means this
+ *   writer's lease expired mid-section; `'busy'` means the release gave up on
+ *   the `.acquire` guard and left the lock in place.
  * @param {(lockPath: string, fn: Function, opts: object) => Promise<object>} [opts.lockImpl]
  *   — test seam; defaults to {@link withFileLock}. Must honour the same
  *   `{ ok: true, value } | { ok: false, reason }` contract.
@@ -123,6 +137,7 @@ export async function withBoardLock(vaultDir, fn, opts = {}) {
     staleMs = DEFAULT_STALE_MS,
     holder: holderOpt,
     onLockOutcome,
+    onReleaseOutcome,
     lockImpl = withFileLock,
     warn = (msg) => process.stderr.write(msg),
   } = opts;
@@ -167,6 +182,9 @@ export async function withBoardLock(vaultDir, fn, opts = {}) {
       indent: 2,
       tmpPrefix: '.board.lock',
       warn: warnAndWatch,
+      // Separate sink, not a second onLockOutcome call — that one stays
+      // "exactly once, before fn".
+      ...(typeof onReleaseOutcome === 'function' ? { onRelease: onReleaseOutcome } : {}),
     },
   );
 

package/scripts/lib/vault-status/board-writer.mjs

@@ -1095,6 +1095,14 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
         waited_ms: Date.now() - acquireStartedAt,
       };
     },
+    // #1336: the release runs in withFileLock's finally, i.e. before
+    // withBoardLock returns — so this lands on the SAME board_written event,
+    // which mirrorBoard emits only after this function returns.
+    onReleaseOutcome: (r) => {
+      if (lockOutcome && r && r.ok === false && typeof r.reason === 'string') {
+        lockOutcome.release = r.reason;
+      }
+    },
   });
 
   return lockOutcome === undefined ? inner : { ...inner, lock: lockOutcome };

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -1,7 +1,7 @@
 /**
  * narrative-mirror.mjs — Durable per-repo narrative mirror (Epic #673 Phase 1, #675).
  *
- * At session-end, extract from a repo's `.claude/STATE.md` the DURABLE narrative —
+ * At session-end, extract from a repo's active `STATE.md` the DURABLE narrative —
  * `## Wave History`, `## Deviations`, `## What Not To Retry`, plus the mission-status
  * rollup — and idempotently mirror it into a generator-owned per-repo vault file, so a
  * reviewer or stand-in can read PER REPO what was done, what failed, and what not to
@@ -31,7 +31,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
-import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
+import { parseStateMd, parseMissionStatus, resolveStateMdPath } from '../state-md.mjs';
 import {
   parseFrontmatter,
   toDate,
@@ -328,7 +328,7 @@ export function renderNarrative(opts) {
   lines.push(`# ${repo ?? 'unknown'} — Session Narrative`);
   lines.push('');
   lines.push(
-    '> Durable per-repo narrative mirrored from `.claude/STATE.md` (Epic #673). ' +
+    '> Durable per-repo narrative mirrored from the repo\'s active `STATE.md` (Epic #673). ' +
       'What was done, what failed, and what not to retry — readable without opening the repo.',
   );
   lines.push('');
@@ -909,7 +909,7 @@ async function runNarrativeMirror(opts) {
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
-  const stateMdPath = path.join(repoRoot, '.claude', 'STATE.md');
+  const stateMdPath = resolveStateMdPath(repoRoot);
   let stateContents;
   try {
     stateContents = await readFile(stateMdPath, 'utf8');

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

@@ -8,6 +8,7 @@
  */
 
 import { probe, evaluate } from './resource-probe.mjs';
+import { resolveAgentCap } from './session-shape.mjs';
 
 /**
  * Wave roles that may run on a declared remote host, mapped to the
@@ -194,7 +195,10 @@ async function applyOffloadDecision(result, opts) {
   // ceiling, which is a property of the REPO and holds wherever the wave runs.
   // Restoring plannedAgents unconditionally here would let a heavy repo exceed
   // its own cap by way of a remote host.
-  const cap = config?.['heavy-repo'] === true ? resolveApwCap(config['agents-per-wave']) : null;
+  const cap =
+    config?.['heavy-repo'] === true
+      ? resolveAgentCap(config['agents-per-wave'], MODE_BLIND_SESSION_TYPE)
+      : null;
   const agents = cap === null ? plannedAgents : Math.min(plannedAgents, cap);
 
   return {
@@ -210,42 +214,34 @@ async function applyOffloadDecision(result, opts) {
 }
 
 /**
- * Resolve an `agents-per-wave` config value into a plain numeric cap, or
- * `null` when no cap should apply.
+ * The session type this module resolves `agents-per-wave` FOR: none.
  *
  * `_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).
+ * into an OBJECT `{ default: 4, deep: 18 }`, not a plain number, so the cap
+ * must be resolved rather than type-guarded (a bare `typeof cap !== 'number'`
+ * check no-ops HR-004 for every repo using the override syntax).
  *
- * `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.
+ * This gate has NO session mode in scope — `waveRole` is a wave role (e.g.
+ * "Impl-Core"), never a session mode (e.g. "deep") — so it deliberately asks
+ * `resolveAgentCap` for no type and takes the `.default` fallback. That is the
+ * conservative reading: the HR-003 convention writes the override as
+ * `<default> (mode: <higher-ceiling>)`, i.e. `default` is the MORE restrictive
+ * of the pair. Under-applying a looser mode-specific ceiling is safe; passing a
+ * guessed `'deep'` here would silently RAISE a heavy repo's ceiling to the deep
+ * override, which is the bug this named constant exists to make un-writable.
  *
- * @param {number|{default: number, [mode: string]: number}|*} cap
- * @returns {number|null}
+ * @type {undefined}
  */
-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;
-}
+const MODE_BLIND_SESSION_TYPE = undefined;
 
 /**
  * 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).
+ * (resolved via `resolveAgentCap` from `./session-shape.mjs` — the ONE exported
+ * copy of that resolver — to handle the object-override shape; see
+ * {@link MODE_BLIND_SESSION_TYPE} for why no session type is passed).
  * 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).
@@ -257,7 +253,7 @@ function resolveApwCap(cap) {
 function applyHeavyRepoCap(result, opts) {
   const { config } = opts;
   if (!config || config['heavy-repo'] !== true) return result;
-  const cap = resolveApwCap(config['agents-per-wave']);
+  const cap = resolveAgentCap(config['agents-per-wave'], MODE_BLIND_SESSION_TYPE);
   if (cap === null) return result;
   if (result.agents <= cap) return result; // already within the ceiling — never raise
   return {

package/scripts/lib/wave-sizing.mjs

@@ -3,10 +3,17 @@
  * Learning: coordinator-over-worktree-on-shared-files caused back-to-back regressions.
  */
 
-// 'unknown' is accepted because scripts/lib/session-close-backfill.mjs writes it for records whose
+// SSOT for the session-type enum. It used to be RE-DECLARED here while this very comment named
+// constants.mjs as the source of truth — two literals that agreed only by luck (and already
+// differed in member order). The direction of the dependency is forced: constants.mjs declares
+// itself a leaf ("no imports from siblings or parent") and mentions wave-sizing.mjs only in prose,
+// so this module imports, never the reverse; no cycle exists in either direction.
+//
+// 'unknown' is a member because scripts/lib/session-close-backfill.mjs writes it for records whose
 // type it could not measure (4.0.0). It is NOT a mode anyone selects — isolation resolves as for
-// 'deep' (the conservative end). SSOT for the ledger enum: scripts/lib/session-schema/constants.mjs.
-const VALID_SESSION_TYPES = ['housekeeping', 'feature', 'deep', 'unknown'];
+// 'deep' (the conservative end).
+import { VALID_SESSION_TYPES } from './session-schema/constants.mjs';
+
 const VALID_COLLISION_RISKS = ['low', 'medium', 'high'];
 const VALID_CONFIG_ISOLATIONS = ['auto', 'worktree', 'none'];
 const VALID_ENFORCEMENTS = ['strict', 'warn', 'off'];