session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/claude-md-budget-lint.mjs

@@ -63,7 +63,8 @@
 
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { basename, resolve } from 'node:path';
+import { basename, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
 import { resolveInstructionFile } from './common.mjs';
 import { isSessionConfigHeading } from './config/section-extractor.mjs';
 
@@ -317,6 +318,36 @@ export function lintClaudeMd(opts = {}) {
  * @param {number} [opts.maxLineChars] forwarded to lintClaudeMd (default DEFAULT_MAX_LINE_CHARS).
  * @returns {{ severity: 'warn', message: string } | null}
  */
+/**
+ * Replace a leading home-directory prefix with the literal `$HOME`.
+ *
+ * Why `$HOME` and not `~`: the banner emits the path inside DOUBLE QUOTES, and
+ * no POSIX shell expands a tilde inside double quotes — `node "~/x.mjs"` fails,
+ * `node "$HOME/x.mjs"` works. Why not `path.relative(repoRoot, __filename)`
+ * (the first proposal): measured 2026-09-11, it only redacts when the repo and
+ * the plugin share a home ancestor —
+ *   repoRoot `~/Projects/bewerbungs-assistent`, plugin under `~/.claude/plugins`
+ *     → `../../.claude/plugins/…` (private, 98 chars)
+ *   repoRoot on a tmp/other volume, plugin under the home dir
+ *     → `../../../../Users/<name>/.claude/…` (LEAKS, and longer)
+ * and it is cwd-bound, which contradicts the `--repo-root` echo whose whole
+ * purpose is cwd-independence. `$HOME` collapse is unconditional, cwd-free, and
+ * leaks nothing in either case.
+ *
+ * A path OUTSIDE the home directory is returned unchanged — it carries no
+ * username to redact, and rewriting it would break the command.
+ *
+ * @param {string} p absolute path
+ * @returns {string} `p` with a leading `homedir()` replaced by `$HOME`
+ */
+function homeCollapsed(p) {
+  const home = homedir();
+  if (typeof p !== 'string' || home.length === 0) return p;
+  if (p === home) return '$HOME';
+  if (p.startsWith(home + sep)) return '$HOME' + p.slice(home.length);
+  return p;
+}
+
 export function checkClaudeMdBudgetLint(opts = {}) {
   const repoRoot = opts.repoRoot ?? process.cwd();
 
@@ -343,9 +374,28 @@ export function checkClaudeMdBudgetLint(opts = {}) {
   if (!result || result.violations.length === 0) return null;
 
   const ruleNames = [...new Set(result.violations.map((v) => v.rule))].join(', ');
+  // The hint MUST name a path the operator can actually run — `scripts/lib/…`
+  // repo-root-relative is only valid inside THIS repo's own checkout. A
+  // consumer repo has no such file: it either has no `scripts/lib/` at all,
+  // or a foreign one. `__filename` (module-scope, see the CLI section below)
+  // is the absolute path of the module that is EXECUTING RIGHT NOW — it is
+  // never wrong, because we could not be inside this function otherwise, and
+  // it needs no plugin-root lookup at all (no env var, no marketplace-cache
+  // scan, no "not resolvable" case to handle — see plugin-update-banner.mjs's
+  // module docstring for why guessing a plugin root from an env var is the
+  // WRONG move here: `$CLAUDE_PLUGIN_ROOT` can name a checkout that differs
+  // from the code that is actually loaded and running). `repoRoot` is echoed
+  // back too, so the copied command re-lints the exact file this banner
+  // reports on regardless of the operator's cwd when they paste it.
+  // PRIVACY (2026-09-11): the same message line already redacts `filePath` via
+  // `basename()`, while `__filename` and `repoRoot` went out verbatim — both
+  // CP1-shaped (`/Users/<name>/…`) on a personal host. The banner's route into
+  // public view is copy-paste into an issue or an agent report, the documented
+  // "agent reports carry private slugs" class. `homeCollapsed()` keeps the
+  // command EXECUTABLE (so #1302 stays closed) while dropping the username.
   const message =
     `⚠ CLAUDE.md budget lint: ${result.violations.length} violation(s) (${ruleNames}) in ${basename(filePath)} — ` +
-    `run \`node scripts/lib/claude-md-budget-lint.mjs --mode warn\` for details.`;
+    `run \`node "${homeCollapsed(__filename)}" --repo-root "${homeCollapsed(repoRoot)}" --mode warn\` for details.`;
 
   return { severity: 'warn', message };
 }

package/scripts/lib/config/issue-budget.mjs

@@ -1,5 +1,6 @@
 import { matchBlockHeader } from './block-header.mjs';
 import { preprocessBlockLines } from './block-preprocess.mjs';
+import { _coerceInteger } from './coercers.mjs';
 
 /**
  * issue-budget.mjs — Parser for the `issue-budget:` block-style Session Config key.
@@ -17,10 +18,13 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  * `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), both via
  * `scripts/lib/issue-budget.mjs`.
  *
- * Returns `{ "max-per-session", mode, overflow }`.
- * Tolerant parser: malformed values silently fall back to defaults (the
+ * Returns `{ "max-per-session", "max-per-session-raw", mode, overflow }`.
+ * Tolerant parser: malformed values fall back to defaults (the
  * `reconcile.min-rule-days` posture, NOT the noisier handover-gate WARN) —
- * a hook must never spam stderr on every single Bash call.
+ * a hook must never spam stderr on every single Bash call. ONE exception, and
+ * it is a safety one: a malformed per-session OVERRIDE with a valid base number
+ * (`7 (feature: x)`) keeps the base 7 and WARNs on stderr, because falling back
+ * to the built-in 12 there would silently LOOSEN a cap the operator tightened.
  *
  * Consumers: `scripts/lib/config.mjs`, `scripts/lib/issue-budget.mjs`,
  * `hooks/pre-bash-issue-budget.mjs`, `skills/session-end/SKILL.md` Phase 5.
@@ -44,7 +48,9 @@ const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
  * Defaults:
  *   max-per-session: 12        integer >= 0; 0 means "no issue may be created"
  *                              (a valid, deliberately harsh setting). Malformed
- *                              or negative input falls back to 12.
+ *                              or negative input falls back to 12 — EXCEPT a
+ *                              malformed override over a valid base (`7 (x: y)`),
+ *                              which keeps 7 and WARNs.
  *   mode:            strict    strict | warn | off
  *   overflow:        collect-issue   collect-issue | vault-note
  *
@@ -54,12 +60,29 @@ const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
  *     mode: strict
  *     overflow: collect-issue
  *
+ * NEW POLICY (not a restatement of an existing rule): `max-per-session` accepts
+ * the SAME per-session-type override syntax `agents-per-wave` already uses —
+ * `12 (feature: 6)` parses via `_coerceInteger` into
+ * `{ default: 12, feature: 6 }`. The key set is OPEN (any session-type label
+ * the operator writes), because the session-type vocabulary lives in
+ * session-start, not here.
+ *
+ * The parsed override object is returned under `"max-per-session-raw"`, while
+ * `"max-per-session"` stays STRICTLY NUMERIC (the `.default`). That split is
+ * load-bearing: three consumers read the key as a number
+ * (`scripts/lib/issue-budget.mjs` `chargeIssueBudget`,
+ * `hooks/pre-bash-issue-budget.mjs`, and the config-parity docs), and handing
+ * any of them an object would surface as `[object Object]` in a cap comparison
+ * rather than as an error. Resolution against the CURRENT session type is
+ * `resolveMaxPerSession()` in `scripts/lib/issue-budget.mjs`.
+ *
  * @param {string} content — full file contents
- * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ * @returns {{ "max-per-session": number, "max-per-session-raw": number|{default: number, [k: string]: number}, mode: string, overflow: string }}
  */
 export function _parseIssueBudget(content) {
   const defaults = {
     'max-per-session': 12,
+    'max-per-session-raw': 12,
     mode: 'strict',
     overflow: 'collect-issue',
   };
@@ -84,6 +107,7 @@ export function _parseIssueBudget(content) {
   if (blockLines.length === 0) return { ...defaults };
 
   let maxPerSession = defaults['max-per-session'];
+  let maxPerSessionRaw = defaults['max-per-session-raw'];
   let mode = defaults.mode;
   let overflow = defaults.overflow;
 
@@ -101,10 +125,45 @@ export function _parseIssueBudget(content) {
     else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
 
     switch (k) {
-      case 'max-per-session':
-        // Non-negative integer only; a leading '-' fails \d+ → default.
-        if (/^\d+$/.test(v)) maxPerSession = parseInt(v, 10);
+      case 'max-per-session': {
+        // Non-negative integer, or the `N (type: M)` override form. A leading
+        // '-' fails \d+ inside `_coerceInteger`, which throws → default.
+        // Tolerant by contract: this parser runs on every Bash call via the
+        // hook, so a malformed value must fall back silently, never throw.
+        let coerced;
+        try {
+          coerced = _coerceInteger(new Map([['max-per-session', v]]), 'max-per-session', 12);
+        } catch {
+          // A malformed OVERRIDE (`7 (feature: x)`) must never restore the
+          // built-in 12: the operator wrote a base cap of 7, and discarding the
+          // whole value because the parenthesised part is unparseable LOOSENS
+          // the cap by three on one typo — silently, in the direction nobody
+          // would choose. Keep the base number, drop the override, and say so
+          // once (this branch is reachable only on a malformed value, so it
+          // cannot become per-Bash-call stderr spam).
+          const base = v.match(/^(\d+)\s*\(/);
+          if (base) {
+            const n = Number.parseInt(base[1], 10);
+            if (Number.isInteger(n) && n >= 0) {
+              maxPerSession = n;
+              maxPerSessionRaw = n;
+              process.stderr.write(
+                `⚠ issue-budget: malformed per-session override in 'max-per-session': '${v}' — ` +
+                  `kept the base cap ${n} and dropped the override.\n`,
+              );
+            }
+          }
+          break;
+        }
+        if (typeof coerced === 'number') {
+          maxPerSession = coerced;
+          maxPerSessionRaw = coerced;
+        } else if (Number.isInteger(coerced?.default) && coerced.default >= 0) {
+          maxPerSession = coerced.default;
+          maxPerSessionRaw = coerced;
+        }
         break;
+      }
 
       case 'mode':
         if (MODES.includes(v.toLowerCase())) mode = v.toLowerCase();
@@ -118,6 +177,7 @@ export function _parseIssueBudget(content) {
 
   return {
     'max-per-session': maxPerSession,
+    'max-per-session-raw': maxPerSessionRaw,
     mode,
     overflow,
   };

package/scripts/lib/config/private-config-dir.mjs

@@ -5,8 +5,9 @@
  * `owner.yaml`, the self-alias ledger) moves with it, so the precedence has to
  * live in exactly ONE place. Before #1223 three copies with three different
  * precedences existed: `owner-yaml.mjs`'s import-time homedir-only
- * `OWNER_YAML_PATH`, `owner-config-loader.mjs`'s XDG-only + untrimmed
- * `resolveOwnerConfigPath()`, and `host-identity.mjs`'s `_privateDir()`. The
+ * `OWNER_YAML_PATH`, the now-removed `owner-config-loader.mjs`'s XDG-only +
+ * untrimmed `resolveOwnerConfigPath()`, and `host-identity.mjs`'s
+ * `_privateDir()`. The
  * live consequence: `SO_CONFIG_HOME=<sandbox>` moved the alias ledger but NOT
  * owner.yaml, which kept being read from the operator's REAL home — the
  * CLAUDE.md (Codex CLI alias: AGENTS.md) "vault-dir resolves HOST-LOCALLY"

package/scripts/lib/config/remote-hosts.mjs

@@ -40,8 +40,8 @@ export const REMOTE_HOST_DEFAULTS = Object.freeze({
  * scripts/lib/config.mjs — impl / db / security / compliance / docs stay local.
  *
  * NOT the wave-role enum ("Impl-Core", "Quality", …): those are two different
- * enums and conflating them is the documented trap (see resolveApwCap's docstring
- * in wave-resource-gate.mjs). The wave→agent-mapping-role translation is
+ * enums and conflating them is the documented trap (see the MODE_BLIND_SESSION_TYPE
+ * note in wave-resource-gate.mjs). The wave→agent-mapping-role translation is
  * `OFFLOADABLE_WAVE_ROLES` in that same module.
  *
  * @type {readonly string[]}

package/scripts/lib/config-schema.mjs

@@ -86,6 +86,8 @@ export function validateSessionConfig(config) {
     });
   }
 
+  validateIssueBudget(config['issue-budget'], errors);
+
   validateVaultIntegration(config['vault-integration'], errors);
   validateVaultSync(config['vault-sync'], errors);
 
@@ -124,6 +126,83 @@ export function validateSessionConfig(config) {
   return { ok: true, config, warnings };
 }
 
+/**
+ * Validate the `issue-budget` block's cap, including the per-session-type
+ * override form (#session-shape) — `12 (feature: 6)` parses to
+ * `{ default: 12, feature: 6 }` and lands on `max-per-session-raw`, while
+ * `max-per-session` stays the resolved NUMBER every consumer reads.
+ *
+ * Mirrors `validateAgentsPerWave` in shape, with two deliberate differences:
+ * the floor is 0 (`max-per-session: 0` is a valid "no issue may be created"
+ * setting) and the override key set is free-form, because the session-type
+ * vocabulary is owned by session-start, not by this schema.
+ *
+ * @param {unknown} block — `config['issue-budget']`
+ * @param {Array<{path: string, rule: string, message: string}>} errors
+ */
+function validateIssueBudget(block, errors) {
+  if (block === undefined || block === null) return;
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    errors.push({
+      path: 'issue-budget',
+      rule: 'object',
+      message: `issue-budget must be an object (got ${JSON.stringify(block)})`,
+    });
+    return;
+  }
+
+  const resolved = block['max-per-session'];
+  if (resolved !== undefined && (!Number.isInteger(resolved) || resolved < 0)) {
+    errors.push({
+      path: 'issue-budget.max-per-session',
+      rule: 'integer>=0',
+      message: `issue-budget.max-per-session must be an integer >= 0 (got ${JSON.stringify(resolved)})`,
+    });
+  }
+
+  const raw = block['max-per-session-raw'];
+  if (raw === undefined || raw === null) return;
+
+  if (Number.isInteger(raw)) {
+    if (raw < 0) {
+      errors.push({
+        path: 'issue-budget.max-per-session-raw',
+        rule: 'integer>=0',
+        message: `issue-budget.max-per-session-raw must be an integer >= 0 (got ${raw})`,
+      });
+    }
+    return;
+  }
+
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    const defaultVal = raw['default'];
+    if (!Number.isInteger(defaultVal) || defaultVal < 0) {
+      errors.push({
+        path: 'issue-budget.max-per-session-raw.default',
+        rule: 'integer>=0',
+        message: `issue-budget.max-per-session-raw.default must be an integer >= 0 (got ${JSON.stringify(defaultVal)})`,
+      });
+    }
+    for (const [k, v] of Object.entries(raw)) {
+      if (k === 'default') continue;
+      if (!Number.isInteger(v) || v < 0) {
+        errors.push({
+          path: `issue-budget.max-per-session-raw.${k}`,
+          rule: 'integer>=0',
+          message: `issue-budget.max-per-session-raw.${k} must be an integer >= 0 (got ${JSON.stringify(v)})`,
+        });
+      }
+    }
+    return;
+  }
+
+  errors.push({
+    path: 'issue-budget.max-per-session-raw',
+    rule: 'integer-or-object',
+    message: `issue-budget.max-per-session-raw must be an integer >= 0 or an object with numeric entries (got ${JSON.stringify(raw)})`,
+  });
+}
+
 function validateAgentsPerWave(value, errors) {
   if (Number.isInteger(value)) {
     if (value < 2) {

package/scripts/lib/config.mjs

@@ -208,7 +208,18 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     _getVal(kv, 'ecosystem-health', undefined) !== undefined
       ? _coerceBoolean(kv, 'ecosystem-health', false)
       : (_parseEcosystemHealthBlockEnabled(mdContent) ?? false);
-  const discoveryOnClose = _coerceBoolean(kv, 'discovery-on-close', false);
+  // discovery-on-close alone accepts `auto` (= true) and defaults to true when
+  // absent: the template recommends `auto` and the 2026-07-29 doc decision made
+  // close-time discovery the default. Other booleans stay strict (#1340).
+  // Ceiling (BV-004): a one-key tri-state kept inline; revisit (move into
+  // coercers.mjs as a shared auto-boolean coercer) when a second key accepts `auto`.
+  const discoveryOnCloseRaw = (_getVal(kv, 'discovery-on-close', 'auto')).toLowerCase();
+  if (!['true', 'false', 'auto'].includes(discoveryOnCloseRaw)) {
+    throw new Error(
+      `config.mjs: invalid boolean for 'discovery-on-close': '${_getVal(kv, 'discovery-on-close', '')}' (expected true, false or auto)`,
+    );
+  }
+  const discoveryOnClose = discoveryOnCloseRaw !== 'false';
   const reasoningOutput = _coerceBoolean(kv, 'reasoning-output', false);
   const groundingCheck = _coerceBoolean(kv, 'grounding-check', true);
   const allowDestructiveOps = _coerceBoolean(kv, 'allow-destructive-ops', false);

package/scripts/lib/eval/engine.mjs

@@ -37,6 +37,7 @@ import path from 'node:path';
 import { resolvePluginRoot } from '../common.mjs';
 import { readJsonlFile } from '../io.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
+import { isCoordinatorDirectHousekeeping } from '../session-schema/filters.mjs';
 import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './schema.mjs';
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
 
@@ -250,7 +251,12 @@ function scoreGateHealth(ctx) {
     const totalWaves = typeof ctx.record.total_waves === 'number' ? ctx.record.total_waves : null;
     const wavesEmpty =
       totalWaves === 0 || !Array.isArray(ctx.record.waves) || ctx.record.waves.length === 0;
-    if (wavesEmpty) {
+    // Since the metrics-collection writer rule (#1321), a session with no
+    // dispatched waves is recorded as ONE coordinator-direct Housekeeping wave
+    // with total_waves 1 — still "no waves ran" per rubric-v1's clarification.
+    // Only that wave SHAPE counts, never session_type: a housekeeping session
+    // that ran real waves stays cannot-determine (the pre-registered formula).
+    if (wavesEmpty || isCoordinatorDirectHousekeeping(ctx.record)) {
       return {
         id,
         method,

package/scripts/lib/file-lock.mjs

@@ -6,11 +6,12 @@
  * and the state-lock / staging-fence / session-lock blocks of session-lock.mjs).
  * Each copy independently re-implemented the same skeleton:
  *
- *   1. atomic create-or-fail via `linkSync(tmp, lock)` (POSIX mutex);
- *   2. on EEXIST → read + parse the existing body;
- *   3. same-host + dead-PID (or unparseable) → atomic override + WARN;
- *   4. live holder OR cross-host → poll until a deadline;
- *   5. owner-guarded release.
+ *   1. exclusive acquisition guard via `linkSync(tmp, lock + '.acquire')`;
+ *   2. atomic create-or-fail via `linkSync(tmp, lock)` (POSIX mutex);
+ *   3. on EEXIST → read + parse the existing body;
+ *   4. same-host + dead-PID (or unparseable) → guarded override + WARN;
+ *   5. release the acquisition guard; live/cross-host holders wait until a deadline;
+ *   6. owner-guarded primary-lock release.
  *
  * This module is the single home for that skeleton. It is a near-PURE primitive:
  * it imports ONLY scripts/lib/io.mjs (for writeJsonAtomicSync), the two host
@@ -27,6 +28,20 @@
  *     opinion of its own — every divergence between the five copies is a knob.
  *   - Cross-host locks are NEVER auto-overridden (PSA-003 hard invariant).
  *   - Overrides always go through writeJsonAtomicSync (tmp + renameSync).
+ *   - #1284 serializes acquisition and takeover: a stale observation must not
+ *     replace a different process's newly acquired lock.
+ *   - #1285 serializes owner-guarded release with takeover: release runs its
+ *     read → owner-match → unlink under the same `${lock}.acquire` guard, so an
+ *     old holder's delayed release can never delete the lock a successor took
+ *     over after the old lease expired.
+ *
+ * Lease semantics (`staleCheck: 'mtime' | 'heartbeat'`): lease expiry prevents
+ * a STUCK lock; it does NOT protect the critical section. After `staleMs` the
+ * next acquirer takes over whether or not the old holder is still running, and
+ * neither mode renews the lease (`heartbeat` ages from `acquiredAt`, `mtime`
+ * from the file's last write). A `not-owner` release under a lease mode means
+ * YOUR lease expired during your critical section and a successor may have run
+ * concurrently — keep critical sections well below `staleMs`.
  *
  * No external dependencies — Node 20+ stdlib + io.mjs only.
  */
@@ -246,6 +261,25 @@ function serializeBody(body, indent) {
   return JSON.stringify(body, null, indent) + '\n';
 }
 
+/**
+ * Create the exclusive `${lockPath}.acquire` sibling guard that serializes every
+ * acquisition, takeover and owner-guarded release pass on `lockPath` (#1284,
+ * #1285). The caller owns the guard only when `ok` is true and must unlink it
+ * in a `finally`; an existing guard is NEVER replaced (see tryAcquireFileLock).
+ *
+ * @param {string} lockPath
+ * @param {string} tmpPrefix — tmp-file prefix; `.acquire` is appended.
+ * @returns {{ ok: true } | { ok: false, reason: 'exists' } | { ok: false, reason: 'fs-error', error: string }}
+ */
+function createAcquireGuard(lockPath, tmpPrefix) {
+  return createExclusive(`${lockPath}.acquire`, {
+    pid: process.pid,
+    host: os.hostname(),
+    acquiredAt: new Date().toISOString(),
+    kind: 'acquisition-guard',
+  }, { indent: 2, tmpPrefix: `${tmpPrefix}.acquire` });
+}
+
 // ---------------------------------------------------------------------------
 // Exported primitive
 // ---------------------------------------------------------------------------
@@ -258,6 +292,26 @@ function serializeBody(body, indent) {
  * overridden via writeJsonAtomicSync and a WARN is emitted. A live holder or a
  * cross-host body returns `{ acquired: false, reason: 'held' }`.
  *
+ * Every acquisition pass owns the exclusive sibling `${lockPath}.acquire`
+ * from before create/read through any takeover. This prevents a waiter from
+ * reading an old holder, observing its exit, then replacing a newer holder.
+ * Owner-guarded releases (releaseFileLock) take the SAME guard for their
+ * read → owner-match → unlink pass (#1285), so a release can never unlink a
+ * lock that a takeover replaced after the releaser read its own body.
+ * All contenders must use this guarded implementation; legacy writers that
+ * ignore the sibling guard cannot participate safely in the same protocol.
+ *
+ * Crash-liveness tradeoff: the guard is held only for one synchronous pass
+ * (acquire or release), not for the caller's critical section. If its owner
+ * dies during a pass or cleanup fails, the guard remains: acquire attempts
+ * return `held` immediately (withFileLock's normal deadline bounds polling) and
+ * owner-guarded releases return `busy` after their bounded retry, leaving the
+ * primary lock to its stale policy. Even a dead-PID or malformed
+ * guard is NEVER stolen, because stale-guard replacement would repeat the same
+ * race. Recovery requires quiescing every process that can acquire this lock,
+ * verifying the guard is abandoned, then explicitly removing only that sibling.
+ * The primary lock retains its existing stale/host/owner protections.
+ *
  * The `signalVanished` knob reproduces memory-proposals/store.mjs's distinct
  * third state: when the lock file disappears between the EEXIST and the read
  * (concurrent release race), `{ acquired: false, reason: 'vanished' }` is
@@ -284,6 +338,25 @@ function serializeBody(body, indent) {
  *   | { acquired: false, reason: 'held'|'vanished'|'fs-error', existing?: object|null, error?: string }}
  */
 export function tryAcquireFileLock(lockPath, opts = {}) {
+  const guardPath = `${lockPath}.acquire`;
+  const guard = createAcquireGuard(lockPath, opts.tmpPrefix ?? '.file.lock');
+  if (!guard.ok) {
+    return guard.reason === 'exists'
+      ? { acquired: false, reason: 'held', existing: null }
+      : { acquired: false, reason: 'fs-error', error: guard.error };
+  }
+
+  try {
+    return tryAcquireGuardedFileLock(lockPath, opts);
+  } finally {
+    // Only this pass can own/remove this guard; no acquisition path replaces
+    // it. An unlink failure deliberately leaves subsequent attempts blocked.
+    try { fs.unlinkSync(guardPath); } catch { /* fail closed; see recovery above */ }
+  }
+}
+
+/** Caller must hold the acquisition guard throughout this synchronous pass. */
+function tryAcquireGuardedFileLock(lockPath, opts) {
   const {
     staleCheck = 'pid',
     staleMs,
@@ -376,21 +449,35 @@ export function tryAcquireFileLock(lockPath, opts = {}) {
  * match. This reproduces the agent-status / state-lock / staging-fence owner
  * guard (PSA-003: never delete a lock another holder owns).
  *
+ * Guaranteed (#1285): the owner-guarded read → owner-match → unlink runs under
+ * the same `${lockPath}.acquire` guard as acquisition and takeover, so an old
+ * holder's release can never delete a replacement's lock. Without the guard, a
+ * holder that read its own body, then paused while its lease expired and a
+ * successor took over, unlinked the successor's lock and let a third process
+ * acquire beside a live holder. Under `staleCheck: 'mtime' | 'heartbeat'`, a
+ * `not-owner` answer means your lease expired during your critical section —
+ * see the module header § Lease semantics. The guard is never stolen: when it
+ * stays taken past the budget the release returns `busy` and leaves the lock
+ * untouched for its stale policy to reclaim.
+ *
  * With `ownerGuard: false` the file is unlinked unconditionally, ENOENT
  * ignored — reproducing memory-proposals/store.mjs's `releaseProposalsLock`.
+ * That path takes no guard (its callers never run a takeover).
  *
  * @param {string} lockPath
  * @param {object} [opts]
  * @param {string} [opts.holder]            — expected holder for the owner guard.
  * @param {boolean} [opts.ownerGuard=true]
+ * @param {number} [opts.guardTimeoutMs=1000] — owner-guarded path only: how long
+ *        to retry for the `.acquire` guard before answering `busy`.
  * @param {(errToken: string) => void} [opts.warn] — sink for unexpected fs
  *        errors on the ownerGuard:false path. Receives the raw
  *        `err.code ?? err.message` token; the call-site formats the message.
  * @returns {{ ok: true }
- *   | { ok: false, reason: 'not-found'|'not-owner'|'fs-error', error?: string }}
+ *   | { ok: false, reason: 'not-found'|'not-owner'|'busy'|'fs-error', error?: string }}
  */
 export function releaseFileLock(lockPath, opts = {}) {
-  const { holder, ownerGuard = true, warn } = opts;
+  const { holder, ownerGuard = true, warn, guardTimeoutMs } = opts;
 
   if (ownerGuard === false) {
     // Unconditional unlink; ENOENT ignored. Other fs errors surfaced via warn.
@@ -406,6 +493,53 @@ export function releaseFileLock(lockPath, opts = {}) {
     }
   }
 
+  // Nothing to release → answer without the guard. Taking it would create the
+  // lock's directory (createExclusive mkdirs) and contend with live acquirers
+  // for a pass that can never unlink anything. Only ENOENT short-cuts; every
+  // other stat error falls through to the guarded read, which reports it.
+  try {
+    fs.statSync(lockPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: false, reason: 'not-found' };
+  }
+
+  const budget = typeof guardTimeoutMs === 'number' && guardTimeoutMs >= 0
+    ? guardTimeoutMs
+    : DEFAULT_RELEASE_GUARD_MS;
+  const deadline = Date.now() + budget;
+  for (;;) {
+    const guard = createAcquireGuard(lockPath, '.file.lock');
+    if (guard.ok) break;
+    if (guard.reason === 'fs-error') return { ok: false, reason: 'fs-error', error: guard.error };
+    // Never steal the guard (same rule as acquisition): wait, then give up.
+    if (Date.now() >= deadline) return { ok: false, reason: 'busy' };
+    sleepSync(RELEASE_GUARD_POLL_MS);
+  }
+
+  try {
+    return releaseGuardedFileLock(lockPath, holder);
+  } finally {
+    // Only this pass owns the guard; an unlink failure fails closed exactly
+    // like the acquisition path (see tryAcquireFileLock § recovery).
+    try { fs.unlinkSync(`${lockPath}.acquire`); } catch { /* fail closed */ }
+  }
+}
+
+/**
+ * Budget for an owner-guarded release to obtain the `.acquire` guard.
+ *
+ * CEILING (BV-004): a live contender holds the guard for one synchronous pass
+ * (a handful of fs syscalls), so the wait is normally sub-millisecond; the full
+ * 1000 ms is only spent on an ABANDONED guard (owner crashed mid-pass), where
+ * waiting longer cannot help. REVISIT if a `busy` release is ever observed on a
+ * host without a crash.
+ */
+const DEFAULT_RELEASE_GUARD_MS = 1000;
+/** Poll cadence while a release waits for the `.acquire` guard. */
+const RELEASE_GUARD_POLL_MS = 5;
+
+/** Caller must hold the acquisition guard throughout this synchronous pass. */
+function releaseGuardedFileLock(lockPath, holder) {
   let raw;
   try {
     raw = fs.readFileSync(lockPath, 'utf8');
@@ -481,6 +615,11 @@ function delay(ms) {
  * @param {boolean} [opts.sync=false]  — true → synchronous busy-wait poll +
  *        synchronous fn (agent-status variant). false → async poll.
  * @param {boolean} [opts.ownerGuard=true]  — passed to releaseFileLock.
+ * @param {(release: ReturnType<typeof releaseFileLock>) => void} [opts.onRelease]
+ *        — receives the releaseFileLock result from the finally (#1336). The
+ *        only reader of `busy` / `not-owner` (a lease that expired mid-`fn`);
+ *        the return value of withFileLock is unchanged. A throwing callback is
+ *        swallowed so it can mask neither `value` nor an error thrown by `fn`.
  * @param {...*} [opts.acquireOpts]  — remaining keys forwarded to tryAcquireFileLock.
  * @returns {Promise<{ ok: true, value: T }
  *   | { ok: false, reason: 'timeout'|'fs-error', error?: string, existing?: object|null }>}
@@ -492,6 +631,7 @@ export async function withFileLock(lockPath, fn, opts = {}) {
     pollMs = 100,
     sync = false,
     ownerGuard = true,
+    onRelease,
     ...acquireOpts
   } = opts;
 
@@ -525,6 +665,9 @@ export async function withFileLock(lockPath, fn, opts = {}) {
     const value = await fn(acquired.body);
     return { ok: true, value };
   } finally {
-    releaseFileLock(lockPath, { holder: releaseHolder, ownerGuard });
+    const released = releaseFileLock(lockPath, { holder: releaseHolder, ownerGuard });
+    if (typeof onRelease === 'function') {
+      try { onRelease(released); } catch { /* diagnostic sink — never masks fn */ }
+    }
   }
 }