session-orchestrator 5.2.0 → 5.4.0

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

@@ -11,6 +11,10 @@
  *     records that between them said nothing happened (#1151). Its count is
  *     carried by the run event's `skipped` total and `action_breakdown`, so the
  *     class stays measured — only its per-line locators are gone.
+ *     `skipped-duplicate-session` (#1291) is one of these per-entry records:
+ *     a `--kind session` line whose `session_id` a later line in the same
+ *     source superseded, so it was never dispatched. It carries `record_id`
+ *     and `line` and never `path` — no target file exists for it.
  *   - `orchestrator.vault.mirror_run_completed` — ONE record per CLI run,
  *     carrying the DENOMINATOR (`total` plus the per-class counts).
  *
@@ -162,7 +166,10 @@ export async function emitMirrorEvent({
  * @param {number} opts.updated — entries whose action was `updated`.
  * @param {number} opts.skipped — entries skipped for a NON-failure reason
  *   (`skipped-noop`, `skipped-handwritten`, `skipped-quality-low`,
- *   `skipped-collision-resolved`, `skipped-abandoned`).
+ *   `skipped-collision-resolved`, `skipped-abandoned`,
+ *   `skipped-duplicate-session`). The last one (#1291) is what keeps
+ *   `created + updated + skipped + failed === total` true for a `--kind
+ *   session` run whose dedup pass collapsed a duplicate `session_id` line.
  * @param {number} opts.failed — entries that produced `skipped-invalid`
  *   (validation error or mapper crash). Split out from `skipped` because these
  *   are the runs where a session silently ends up WITHOUT its vault note.

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

@@ -12,8 +12,9 @@
  *
  * Telemetry: every {@link mirrorBoard} call — and therefore every
  * {@link sweepBoard} call — emits exactly ONE {@link BOARD_EVENT} record,
- * including the no-op paths (`skipped-vault-disabled`, `skipped-handwritten`,
- * `skipped-noop`, `skipped-write-failed`). Those are the states that previously
+ * including the no-op paths (`skipped-vault-disabled`,
+ * `skipped-vault-not-canonical`, `skipped-handwritten`, `skipped-noop`,
+ * `skipped-write-failed`). Those are the states that previously
  * looked identical to a healthy write from outside the process. Emission is
  * best-effort and can never fail a board write.
  *
@@ -43,7 +44,8 @@
  *   2. Defense-in-depth: writeBoard hard-refuses to touch `_overview.md`
  *      (sven-owned, must NEVER be written by this generator).
  *
- * No console noise — library code. Plain Node ESM. No external deps.
+ * No console noise — library code — except the one stderr line on a
+ * canonical-vault refusal (#1450). Plain Node ESM. No external deps.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
@@ -60,6 +62,8 @@ import { enumerateCandidates } from '../dispatcher/enumerate.mjs';
 import { atomicWriteWithBackup } from '../io.mjs';
 import { withBoardLock } from './board-lock.mjs';
 import { expandTilde } from '../common.mjs';
+import { checkCanonicalVault, describeOriginForLog } from '../named-vault-resolver.mjs';
+import { loadHostPaths } from '../config/host-paths.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned board files. */
 export const GENERATOR_MARKER = 'session-orchestrator-active-sessions@1';
@@ -825,6 +829,8 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
  * Vault path assertion (Epic #673 safety): the resolved vault dir MUST live
  * under $HOME — a vault outside the home tree is refused as `skipped-vault-disabled`
  * so a misconfigured path can never drive a write into an arbitrary location.
+ * It must also be a canonical Meta-Vault ({@link checkCanonicalVault}, #1450):
+ * otherwise `skipped-vault-not-canonical`, nothing written, no lock, dry-run included.
  *
  * @param {object} opts
  * @param {string} opts.repoRoot — the repo whose row is being updated.
@@ -840,11 +846,14 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
  * @param {Date} [opts.now]
  * @param {boolean} [opts.dryRun]
  * @param {object} [opts.fs] — injectable fs for tests.
- * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [opts.hostPaths]
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object,
+ *   readOriginUrl?: (vaultDir: string) => string }} [opts.hostPaths]
  *   — forwarded verbatim to {@link parseSessionConfig}'s `hostPaths` DI seam (issue #653).
+ *   The same ctx feeds {@link checkCanonicalVault}; `readOriginUrl` replaces its
+ *   `git remote get-url origin` read (tests only — tmp vaults have no origin).
  *   Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig: undefined }`) when
  *   asserting a fixture's committed `vault-dir` — omitting it reads the REAL host
- *   `owner.yaml`, whose `paths.vault-dir` override (if set) wins over the fixture value
+ *   `owner.yaml`, whose `vault-dirs:` cwd match or `paths.vault-dir` override (if set) wins over the fixture value
  *   and bleeds into the assertion (issue #783). Production callers omit this — the
  *   default (real owner.yaml resolution) is the correct host-local behavior there.
  * @returns {Promise<{ result: { action: string, path?: string }, rows?: number,
@@ -861,10 +870,19 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
   }
 
   // Read + parse Session Config. Any failure → silent no-op.
+  // The host context is resolved ONCE here and reused by the canonical-vault
+  // guard below: loadOwnerConfig() has no cache and its section-drop WARNs are
+  // not rate-limited, so a second load would print every WARN of a broken
+  // owner.yaml twice per board write (#1450 follow-up). The config file is read
+  // BEFORE owner.yaml — the order narrative-mirror.mjs shares (#1479); vault-dir
+  // precedence is applied in parseSessionConfig, so the order changes only
+  // whether a repo without a config file reads owner.yaml at all.
   let config;
+  let hostCtx;
   try {
     const text = await readConfigFile(repoRoot);
-    config = parseSessionConfig(text, { hostPaths });
+    hostCtx = hostPaths ?? loadHostPaths();
+    config = parseSessionConfig(text, { hostPaths: hostCtx });
   } catch {
     return { result: { action: 'skipped-vault-disabled' } };
   }
@@ -886,6 +904,24 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
     return { result: { action: 'skipped-vault-disabled' } };
   }
 
+  // Safety: the vault must be a canonical Meta-Vault (#1450) — the same guard
+  // vault-mirror applies, so a vault-dir that resolved to a FOREIGN vault can
+  // never receive the board. Reuses the `hostCtx` the config parse used, so a
+  // hermetic ctx never reads the real owner.yaml and owner.yaml is loaded at
+  // most once. Runs before the dry-run branch and the lock: fail-closed.
+  const canonical = checkCanonicalVault({
+    vaultDir: expandedVault,
+    ownerConfig: hostCtx.ownerConfig,
+    env: hostCtx.env ?? process.env,
+    readOriginUrl: hostCtx.readOriginUrl,
+  });
+  if (!canonical.ok) {
+    process.stderr.write(
+      `vault-status board: refusing to write — vault is not the canonical Meta-Vault (expected git origin ending in one of: ${canonical.expected.join(', ')}; got ${describeOriginForLog(canonical.got) || 'no git origin'})\n`,
+    );
+    return { result: { action: 'skipped-vault-not-canonical' } };
+  }
+
   // `vault-name` (#660) overrides the git-derived repo slug for per-project
   // vault namespacing. Without it `collectRows` falls back to
   // `path.basename(repoRoot)`, so a repo whose directory name differs from its
@@ -1112,10 +1148,10 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
  * Public {@link mirrorBoardInner} wrapper that emits exactly ONE
  * {@link BOARD_EVENT} per call — on EVERY path, no-ops included.
  *
- * The wrapper exists so the emit cannot be forgotten: the six return points
- * inside {@link mirrorBoardInner} (five `skipped-vault-disabled` guards plus
- * whatever {@link writeBoard} decides) all funnel through here, and so does the
- * seventh someone adds next. Emitting per-return instead would leave each new
+ * The wrapper exists so the emit cannot be forgotten: the seven return points
+ * inside {@link mirrorBoardInner} (five `skipped-vault-disabled` guards, the
+ * `skipped-vault-not-canonical` guard, plus whatever {@link writeBoard}
+ * decides) all funnel through here, and so does the eighth someone adds next. Emitting per-return instead would leave each new
  * early return silent by default — which is the exact defect being fixed.
  *
  * A THROW from the inner function is deliberately NOT converted into an event:
@@ -1276,7 +1312,8 @@ export function buildSweepRepos(candidates, { thisRepoRoot } = {}) {
  * @param {object} [opts.deps] — injectable deps for {@link enumerateCandidates}
  *   (test seam: `readdirSync`, `existsSync`, `readLock`, `isLockLive`,
  *   `getCrossRepoProjects`, `validatePathInsideProject`, `now`).
- * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [opts.hostPaths]
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object,
+ *   readOriginUrl?: (vaultDir: string) => string }} [opts.hostPaths]
  *   — forwarded verbatim to every {@link mirrorBoard} call below (both the happy-path
  *   and the enumeration-failure-fallback path), which in turn forwards it to
  *   {@link parseSessionConfig}'s `hostPaths` DI seam (issue #653/#783). See

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

@@ -43,6 +43,9 @@ import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { createSecretValueMasker } from '../secret-masker.mjs';
 import { expandTilde } from '../common.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
+import { checkCanonicalVault, describeOriginForLog } from '../named-vault-resolver.mjs';
+import { loadHostPaths } from '../config/host-paths.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned narrative files. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-status-narrative@1';
@@ -762,9 +765,10 @@ async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
  * before any write.
  *
  * THIS FUNCTION WRITES TO THE OPERATOR'S REAL VAULT UNLESS YOU STOP IT. `vault-dir`
- * resolves HOST-LOCALLY — `SO_VAULT_DIR` > `owner.yaml` `paths.vault-dir` >
- * committed Session Config (`scripts/lib/config/host-paths.mjs`) — so the literal
- * value in a CLAUDE.md you just wrote into a tmp dir LOSES to both overrides. A
+ * resolves HOST-LOCALLY — `SO_VAULT_DIR` > `owner.yaml` `vault-dirs:` cwd match >
+ * `owner.yaml` `paths.vault-dir` > committed Session Config (`resolveVaultDir` in
+ * `scripts/lib/config.mjs`) — so the literal value in a CLAUDE.md you just wrote
+ * into a tmp dir LOSES to every override. A
  * probe that passes a synthetic `repoRoot` and nothing else has already written
  * into the live vault once (#1025 review). Any caller that must not touch the real
  * vault passes `hostPaths: { env: {}, ownerConfig: undefined }` (see below),
@@ -776,13 +780,16 @@ async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
  *   now?: Date,
  *   dryRun?: boolean,
  *   fs?: object,
- *   hostPaths?: { env?: Record<string, string|undefined>, ownerConfig?: object },
+ *   hostPaths?: { env?: Record<string, string|undefined>, ownerConfig?: object,
+ *     readOriginUrl?: (vaultDir: string) => string },
  * }} opts
  *   `hostPaths` is forwarded verbatim to {@link parseSessionConfig}'s `hostPaths` DI
- *   seam (issue #653). Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig:
+ *   seam (issue #653). The same ctx feeds {@link checkCanonicalVault} (#1450);
+ *   `readOriginUrl` replaces its `git remote get-url origin` read (tests only —
+ *   tmp vaults have no origin). Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig:
  *   undefined }`) when asserting a fixture's committed `vault-dir` — omitting it reads
- *   the REAL host `owner.yaml`, whose `paths.vault-dir` override (if set) wins over the
- *   fixture value and bleeds into the assertion (issue #783). Production callers omit
+ *   the REAL host `owner.yaml`, whose `vault-dirs:` cwd match or `paths.vault-dir`
+ *   override (if set) wins over the fixture value and bleeds into the assertion (issue #783). Production callers omit
  *   this — the default (real owner.yaml resolution) is the correct host-local behavior.
  * @returns {Promise<{ action: string, path?: string }>}
  */
@@ -828,7 +835,7 @@ export async function mirrorNarrative(opts) {
  * Split out so that the two emit sites in `mirrorNarrative` (the narrative
  * event AND, since #1028, the masker event) each cover EVERY outcome from
  * ONE call: a future early return added inside this function is telemetered
- * by construction, whereas hand-placing an emit beside each of the seven
+ * by construction, whereas hand-placing an emit beside each of the eight
  * `return`s makes "forgot the new one" the default failure. The `chars` companion travels beside the result
  * rather than inside it because the returned object is a PUBLIC shape that
  * callers (and tests) compare with `toEqual` — adding a key there would be an
@@ -854,10 +861,19 @@ async function runNarrativeMirror(opts) {
   const masker = createSecretValueMasker(process.env);
 
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
+  // The host context is loaded ONCE and shared by the Session Config parse and
+  // the canonical-vault guard below, so owner.yaml is read a single time per run.
+  // Order (#1479, same as board-writer.mjs): config file first, owner.yaml
+  // second. The `vault-dir` precedence (SO_VAULT_DIR > owner.yaml > committed)
+  // is applied inside parseSessionConfig, after both are in hand, so the order
+  // cannot change the resolved dir; it only spares a repo without a config file
+  // the owner.yaml read and its section-drop WARNs on a run that skips anyway.
   let config;
+  let hostCtx;
   try {
     const configText = await readConfigFile(repoRoot);
-    config = parseSessionConfig(configText, { hostPaths });
+    hostCtx = hostPaths ?? loadHostPaths();
+    config = parseSessionConfig(configText, { hostPaths: hostCtx });
   } catch {
     return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
@@ -869,15 +885,29 @@ async function runNarrativeMirror(opts) {
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
   // it from the operator-configured `vault-name` override (#660/#832) when set,
-  // else the repoRoot basename — never silently mis-file under 'unknown' (#675
-  // review). Precedence: explicit `repo` opt > `vault-name` > basename.
+  // else the `.vault.yaml` slug (#1131), else the repoRoot basename — never
+  // silently mis-file under 'unknown' (#675 review).
   const vaultNameOverride =
     typeof vaultIntegration['vault-name'] === 'string' && vaultIntegration['vault-name'].trim()
       ? vaultIntegration['vault-name'].trim()
       : null;
-  const repoName = (typeof repo === 'string' && repo.trim().length > 0)
+  const explicitName = (typeof repo === 'string' && repo.trim().length > 0)
     ? repo
-    : vaultNameOverride ?? path.basename(path.resolve(repoRoot));
+    : vaultNameOverride;
+
+  // #1131: with NO explicit override, the repo's own `.vault.yaml`
+  // `metadata.slug` — the CANONICAL vault registration — outranks the
+  // directory basename. Precedence: explicit `repo` opt > `vault-name` >
+  // `.vault.yaml` slug > basename.
+  //
+  // WHY the two overrides still win: both are things a CALLER/operator states
+  // for THIS call (`repo` is only ever passed to override the derived name —
+  // the sole production caller, `skills/session-end/session-metrics-write.md`,
+  // passes `repoRoot` alone), so honouring the file over them would make an
+  // explicit override unhonourable. The file wins over the basename, which is
+  // a guess nobody stated.
+  const vaultYamlSlug = explicitName ? null : readVaultSlug(repoRoot);
+  const repoName = explicitName ?? vaultYamlSlug ?? path.basename(path.resolve(repoRoot));
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
@@ -885,11 +915,36 @@ async function runNarrativeMirror(opts) {
   }
 
   const vaultDir = path.resolve(expandTilde(rawVaultDir));
+
+  // #1450: same shared guard as board-writer.mjs and scripts/vault-mirror.mjs —
+  // refuse a vault-dir whose git origin is not a canonical Meta-Vault. The
+  // stderr line names the expected suffixes and the origin, never the vault
+  // path itself.
+  const canonical = checkCanonicalVault({
+    vaultDir,
+    ownerConfig: hostCtx.ownerConfig,
+    env: hostCtx.env ?? process.env,
+    readOriginUrl: hostCtx.readOriginUrl,
+  });
+  if (!canonical.ok) {
+    process.stderr.write(`narrative-mirror: refusing to write — vault is not the canonical Meta-Vault (expected git origin ending in one of: ${canonical.expected.join(', ')}; got ${describeOriginForLog(canonical.got) || 'no git origin'})\n`);
+    return { result: { action: 'skipped-vault-not-canonical' }, needleCount: masker.needleCount, hits: 0, dryRun };
+  }
+
   const candidateSlug = subjectToSlug(repoName) || 'unknown';
-  // Loose-match against existing 01-projects/ folders before minting a new
-  // slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
+  // A declared `.vault.yaml` slug needs no healing — it IS the canonical folder
+  // name, so resolveLooseSlug is SKIPPED for it. Running the healer over it
+  // would re-open the bug this fixes: a vault that also carries an unhealed
+  // legacy folder (e.g. `foobarapp` beside the declared `foo-bar-app`) makes
+  // the loose match ambiguous, and ambiguity falls back to the candidate —
+  // which is how a duplicate pair, once created, keeps being written to.
+  //
+  // Otherwise: loose-match against existing 01-projects/ folders before minting
+  // a new slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
   // rules. Falls through to `candidateSlug` unchanged on any read failure.
-  const repoSlug = resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
+  const repoSlug = vaultYamlSlug
+    ? candidateSlug
+    : resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
   const outputPath = resolveNarrativePath(vaultDir, repoSlug);
 
   // Defense-in-depth: ensure the resolved file stays inside the vault root.

package/scripts/lib/vault-yaml.mjs

@@ -0,0 +1,118 @@
+/**
+ * vault-yaml.mjs — Reader for a repo's `.vault.yaml` registration slug (#1131).
+ *
+ * A repo registered in the Meta-Vault carries `.vault.yaml` at its root, whose
+ * `metadata.slug` is the CANONICAL vault slug for that project — the name of
+ * its `01-projects/<slug>/` folder. Until #1131 nothing READ that key: every
+ * vault writer derived the slug from the checkout DIRECTORY name instead
+ * (`scripts/lib/vault-status/narrative-mirror.mjs` via `subjectToSlug`,
+ * `scripts/lib/vault-mirror/namespace.mjs` via `basename(process.cwd())`), so a
+ * repo whose directory name differs lexically from its registered slug had its
+ * narrative and its learnings/sessions filed under a second, wrong folder — and
+ * the loose-slug healer in narrative-mirror (#829) only repairs case and
+ * punctuation drift, never a genuinely different name.
+ *
+ * Exports:
+ *   VAULT_YAML_FILE — the basename this module reads
+ *   readVaultSlug   — repoRoot → validated `metadata.slug` string, or null
+ *
+ * Contract: NEVER throws. Absent file, unreadable file, malformed YAML, missing
+ * key, non-string value, or a value that fails the repo's slug predicate all
+ * return `null`, leaving every caller on its pre-#1131 derivation chain.
+ *
+ * Import closure is deliberately tiny (`node:fs`, `node:path`, `node:module`,
+ * `./vault-mirror/utils.mjs`) — `namespace.mjs` is documented as a leaf-ward
+ * module and must stay one.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+import { isValidSlug } from './vault-mirror/utils.mjs';
+
+/** Basename of the per-repo vault registration file. */
+export const VAULT_YAML_FILE = '.vault.yaml';
+
+// ── Lazy js-yaml resolution ──────────────────────────────────────────────────
+//
+// Same shape (and same reason) as `getYaml()` in scripts/lib/owner-yaml.mjs:
+// a static `import yaml from 'js-yaml'` crashes any consumer running without
+// `node_modules`, at MODULE LOAD, where the failure is not catchable. Both
+// consumers of this reader are synchronous, so `createRequire` — not
+// `await import()` — is the resolution mechanism.
+
+/** @type {null | false | { load: Function }} */
+let _yaml = null;
+let _yamlWarned = false;
+
+function getYaml() {
+  if (_yaml !== null) return _yaml === false ? null : _yaml;
+  try {
+    _yaml = createRequire(import.meta.url)('js-yaml');
+  } catch {
+    _yaml = false;
+  }
+  return _yaml === false ? null : _yaml;
+}
+
+/**
+ * One-per-process actionable WARN, emitted ONLY when a `.vault.yaml` actually
+ * exists and could therefore have changed the resolved slug. A repo without the
+ * file loses nothing by the parser being absent, so it stays silent.
+ */
+function warnYamlMissing() {
+  if (_yamlWarned) return;
+  _yamlWarned = true;
+  process.stderr.write(
+    "WARN vault-yaml: 'js-yaml' is not installed — .vault.yaml cannot be parsed; " +
+      'the vault slug falls back to the directory-derived name (run \'npm install\' in the plugin directory)\n',
+  );
+}
+
+/**
+ * Read the canonical vault slug declared at `metadata.slug` in
+ * `<repoRoot>/.vault.yaml`.
+ *
+ * The value becomes a FILESYSTEM PATH SEGMENT under the operator's vault, so it
+ * is validated with the repo's existing slug predicate ({@link isValidSlug},
+ * `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`) rather than trusted. That rejects `/`, `..`,
+ * leading dots, whitespace and uppercase — this validation is a trust-boundary
+ * control, not hygiene: `.vault.yaml` is repo-supplied data, and a slug such as
+ * `../../etc` would otherwise escape the vault root.
+ *
+ * @param {string} repoRoot - absolute or relative path to the repository root.
+ * @returns {string|null} the validated slug, or `null` when it cannot be read.
+ */
+export function readVaultSlug(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') return null;
+
+  let text;
+  try {
+    text = readFileSync(path.join(repoRoot, VAULT_YAML_FILE), 'utf8');
+  } catch {
+    // Absent, unreadable, a directory, … — all "no declared slug".
+    return null;
+  }
+
+  const yaml = getYaml();
+  if (!yaml) {
+    warnYamlMissing();
+    return null;
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(text);
+  } catch {
+    // Malformed YAML must never break a vault write.
+    return null;
+  }
+
+  if (!doc || typeof doc !== 'object') return null;
+  const metadata = doc.metadata;
+  if (!metadata || typeof metadata !== 'object') return null;
+
+  const slug = metadata.slug;
+  return isValidSlug(slug) ? slug : null;
+}

package/scripts/lib/wave-executor/dispatch-common.mjs

@@ -21,6 +21,14 @@
  * exists to be.
  */
 
+/**
+ * Re-exported, not re-declared: the value lives in `process-group.mjs` since
+ * 773a994b, but this module exported it in 5.3.x and the package ships
+ * `scripts/` with no `exports` map — so a deep importer still links against
+ * this name. One definition, two import paths.
+ */
+export { DEFAULT_KILL_GRACE_MS } from '../process-group.mjs';
+
 /**
  * Roles that may NEVER run on a foreign model. Copied verbatim from
  * account-switch `tools/routing/routing.yaml` § never_foreign (read 2026-08-25).
@@ -44,22 +52,6 @@ export const NEVER_FOREIGN_ROLES = Object.freeze([
  * manufactures timeouts and reads as model failure. */
 export const DEFAULT_TIMEOUT_SEC = 900;
 
-/**
- * Grace period between SIGTERM and SIGKILL, in ms.
- *
- * `child.kill('SIGTERM')` is a REQUEST: a child that installs a handler and
- * ignores it never emits `close`, and this module's only resolve paths are
- * `close` and `error` — so without escalation a wedged `cursor-agent` hangs
- * `dispatchForeign` forever and takes the whole wave with it. SIGKILL is not
- * catchable, so the escalation always terminates.
- *
- * Named ceiling (BV-004): 10 s is enough for a cooperative child to flush its
- * stream-json tail and exit. Revisit if a well-behaved `cursor-agent` is ever
- * measured needing longer than that to shut down — raise the constant, never
- * drop the escalation.
- */
-export const DEFAULT_KILL_GRACE_MS = 10_000;
-
 /** A runId names a directory and a log file. Anything outside this alphabet —
  * or the two relative-path literals the alphabet happens to admit — can escape
  * the parent it is joined to. */
@@ -90,8 +82,8 @@ export function isNeverForeignRole(role) {
  *
  * The escalation is the difference between a bounded dispatch and a hung wave:
  * this function's only resolve paths are the child's `close` and `error`
- * events, so a child that ignores SIGTERM never lets the promise settle. See
- * {@link DEFAULT_KILL_GRACE_MS}.
+ * events, so a child that ignores SIGTERM never lets the promise settle. The
+ * callers pass `DEFAULT_KILL_GRACE_MS` from `process-group.mjs`.
  *
  * @returns {Promise<{capture: string, exitCode: number|null, signal: string|null,
  *   timerFired: boolean, killSignals: string[], errorCode: string|null}>}

package/scripts/lib/wave-executor/foreign-dispatch.mjs

@@ -54,8 +54,8 @@ import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isPathInside } from '../path-utils.mjs';
+import { DEFAULT_KILL_GRACE_MS } from '../process-group.mjs';
 import {
-  DEFAULT_KILL_GRACE_MS,
   DEFAULT_TIMEOUT_SEC,
   isNeverForeignRole,
   isSafeRunId,

package/scripts/lib/wave-executor/remote-dispatch.mjs

@@ -34,8 +34,8 @@ import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isPathInside } from '../path-utils.mjs';
+import { DEFAULT_KILL_GRACE_MS } from '../process-group.mjs';
 import {
-  DEFAULT_KILL_GRACE_MS,
   DEFAULT_TIMEOUT_SEC,
   isNeverForeignRole,
   isSafeRunId,

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

@@ -123,6 +123,14 @@ async function applyDecisionRules(measurements, opts) {
  * declares a remote host that accepts this wave role, route the wave to that
  * host at its full planned agent count instead of shrinking it.
  *
+ * `offload-first: true` in Session Config (#1465) widens that trigger to a
+ * `proceed` verdict too: an offloadable wave role goes to a ready host even when
+ * the local host has headroom. Host selection, the witness contract and the
+ * HR-004 cap below are identical on both paths. With the switch on, a wave that
+ * stays local anyway (no host declared, none ready) carries a named
+ * `offload-first:` reason, so the switch never fails silently; a role absent
+ * from OFFLOADABLE_WAVE_ROLES stays local without one.
+ *
  * The gate does NOT probe the network — a placement decision must stay a pure
  * function of its inputs. The caller supplies a readiness WITNESS:
  *   - `opts.remoteReady` — `{ [alias]: boolean }`, e.g. built from the
@@ -140,13 +148,24 @@ async function applyDecisionRules(measurements, opts) {
  * @returns {Promise<{decision: string, agents: number, reasons: string[], measurements: object, host?: string}>}
  */
 async function applyOffloadDecision(result, opts) {
-  if (result.decision !== 'reduce' && result.decision !== 'coordinator-direct') return result;
+  const offloadFirst = opts.config?.['offload-first'] === true;
+  if (!offloadFirst && result.decision !== 'reduce' && result.decision !== 'coordinator-direct') {
+    return result;
+  }
 
   const { config, plannedAgents, waveRole, remoteReady, probeFn = null } = opts;
+  const role = String(waveRole ?? '').trim().toLowerCase();
   const hosts = config?.['remote-hosts'];
-  if (!Array.isArray(hosts) || hosts.length === 0) return result;
+  if (!Array.isArray(hosts) || hosts.length === 0) {
+    // Only an offloadable role could have been placed, so only it gets the note.
+    return offloadFirst && OFFLOADABLE_WAVE_ROLES[role] !== undefined
+      ? {
+          ...result,
+          reasons: [...result.reasons, 'offload-first: true but no remote-hosts declared — staying local'],
+        }
+      : result;
+  }
 
-  const role = String(waveRole ?? '').trim().toLowerCase();
   // No isNeverForeignRole() check here (D8 #1204 LOW-1): the invariant is
   // enforced STRUCTURALLY by this mapping table, not by an extra guard.
   // NEVER_FOREIGN_ROLES {impl-core, security-review, migration, release,
@@ -186,9 +205,10 @@ async function applyOffloadDecision(result, opts) {
     }
   }
   if (host === undefined) {
-    return probeFailures.length === 0
-      ? result
-      : { ...result, reasons: [...result.reasons, ...probeFailures] };
+    const notes = offloadFirst
+      ? [...probeFailures, `offload-first: no ready host for '${role}' — staying local`]
+      : probeFailures;
+    return notes.length === 0 ? result : { ...result, reasons: [...result.reasons, ...notes] };
   }
 
   // The wave runs at its planned size again — but never above the HR-004 static
@@ -207,7 +227,9 @@ async function applyOffloadDecision(result, opts) {
     host: host.alias,
     reasons: [
       ...result.reasons,
-      `offload: ${role} routed to host '${host.alias}' instead of reducing to ${result.agents}`,
+      result.decision === 'proceed'
+        ? `offload-first: ${role} routed to host '${host.alias}' (verdict was proceed)`
+        : `offload: ${role} routed to host '${host.alias}' instead of reducing to ${result.agents}`,
     ],
     measurements: result.measurements,
   };
@@ -383,14 +405,18 @@ export async function evaluateWaveResourceGate(opts) {
   }
 
   // Rule 2: probe the system (or use override for tests).
+  // A failed probe yields `proceed`. Under `offload-first: true` (#1465) that
+  // result still goes through placement: routing to a witnessed-ready host needs
+  // no local measurement, so a broken probe must not silently disable the switch.
   const measured = await extractMeasurements(opts);
   if ('probeFailed' in measured) {
-    return {
+    const failed = {
       decision: 'proceed',
       agents: plannedAgents,
       reasons: ['probe failed (ignored)'],
       measurements: {},
     };
+    return config['offload-first'] === true ? applyOffloadDecision(failed, opts) : failed;
   }
 
   // Rules 3-8: apply decision rule sequence.