session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/issue-budget.mjs

@@ -29,11 +29,14 @@
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
 import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 
 import { writeJsonAtomicSync } from './io.mjs';
 import { resolveInstructionFile } from './common.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
+import { parseStateMd } from './state-md/yaml-parser.mjs';
+import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 
 /**
  * Legacy single-slot counter file, relative to the repo root.
@@ -148,24 +151,95 @@ export function classifyExemption(command) {
   return { exempt: false, reason: null };
 }
 
+/**
+ * Resolve the effective cap for one session type out of a parsed config.
+ *
+ * Precedence is `raw[sessionType] ?? raw.default ?? cfg['max-per-session']` —
+ * an unknown or absent session type falls through to the default, never to a
+ * hard-coded number, and a config parsed before the override syntax existed
+ * (no `max-per-session-raw` key at all) still resolves via the last term.
+ *
+ * @param {{ "max-per-session"?: number, "max-per-session-raw"?: number|Record<string, number> }} cfg
+ * @param {string|null|undefined} sessionType — e.g. `feature`, `deep`, `housekeeping`
+ * @returns {number} non-negative integer cap
+ */
+export function resolveMaxPerSession(cfg, sessionType) {
+  const fallback =
+    Number.isInteger(cfg?.['max-per-session']) && cfg['max-per-session'] >= 0
+      ? cfg['max-per-session']
+      : 12;
+  const raw = cfg?.['max-per-session-raw'];
+  if (Number.isInteger(raw) && raw >= 0) return raw;
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const key = typeof sessionType === 'string' ? sessionType.trim().toLowerCase() : '';
+    const override = key === '' ? undefined : raw[key];
+    if (Number.isInteger(override) && override >= 0) return override;
+    if (Number.isInteger(raw.default) && raw.default >= 0) return raw.default;
+  }
+  return fallback;
+}
+
+/**
+ * Read `session-type:` from the active STATE.md frontmatter.
+ *
+ * Never throws: a missing STATE.md, unparseable frontmatter, or an absent /
+ * non-string `session-type` all yield `null`, which `resolveMaxPerSession`
+ * reads as "use the default". The hook path runs on every Bash call, so a
+ * broken STATE.md must degrade to today's behaviour rather than fail.
+ *
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+export function readSessionTypeFromStateMd(repoRoot) {
+  try {
+    const filePath = resolveStateMdPath(repoRoot);
+    if (!existsSync(filePath)) return null;
+    const parsed = parseStateMd(readFileSync(filePath, 'utf8'));
+    const value = parsed?.frontmatter?.['session-type'];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Load the `issue-budget` config from the repo's instruction file
  * (CLAUDE.md / AGENTS.md). Reads only that one file and only that one block —
  * `parseSessionConfig()` is deliberately NOT used here so the hook path does
  * not pay for host-path resolution and owner.yaml I/O on every Bash call.
  *
+ * `max-per-session` is returned ALREADY RESOLVED for the current session type
+ * (read from the active STATE.md frontmatter), so every existing consumer that
+ * treats it as a plain number keeps working and automatically gains the
+ * per-session-type override. The unresolved value stays available under
+ * `max-per-session-raw`, and `session-type-resolved` records which type the
+ * resolution used (`null` when STATE.md is absent or carries no session-type).
+ *
  * @param {string} repoRoot
- * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ * @returns {{ "max-per-session": number, "max-per-session-raw": number|Record<string, number>, "session-type-resolved": string|null, mode: string, overflow: string }}
  */
 export function loadIssueBudgetConfig(repoRoot) {
-  const defaults = { 'max-per-session': 12, mode: 'strict', overflow: 'collect-issue' };
+  const defaults = {
+    'max-per-session': 12,
+    'max-per-session-raw': 12,
+    'session-type-resolved': null,
+    mode: 'strict',
+    overflow: 'collect-issue',
+  };
+  let parsed;
   try {
     const resolved = resolveInstructionFile(repoRoot);
     if (!resolved) return defaults;
-    return _parseIssueBudget(readFileSync(resolved.path, 'utf8'));
+    parsed = _parseIssueBudget(readFileSync(resolved.path, 'utf8'));
   } catch {
     return defaults;
   }
+  const sessionType = readSessionTypeFromStateMd(repoRoot);
+  return {
+    ...parsed,
+    'max-per-session': resolveMaxPerSession(parsed, sessionType),
+    'session-type-resolved': sessionType,
+  };
 }
 
 /**
@@ -180,6 +254,27 @@ export function budgetStatePath(repoRoot, sessionId = null) {
   return path.join(repoRoot, budgetStateRel(sessionId));
 }
 
+/**
+ * Is this a well-formed charge record (#1347)?
+ *
+ * A record that fails this test is DROPPED rather than repaired: it can no
+ * longer prove which unit it was charged to, and a refund against an
+ * unclassifiable record is exactly the drain this ledger exists to prevent.
+ *
+ * @param {unknown} r
+ * @returns {boolean}
+ */
+function _isChargeRecord(r) {
+  return (
+    !!r &&
+    typeof r === 'object' &&
+    !Array.isArray(r) &&
+    typeof r.key === 'string' &&
+    r.key.length > 0 &&
+    (r.unit === 'count' || r.unit === 'exempt')
+  );
+}
+
 /**
  * Coerce a parsed counter file into a state object, or `null` when it does not
  * belong to `accountingSessionId`.
@@ -200,6 +295,10 @@ function _coerceState(data, accountingSessionId) {
     count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
     exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
     overflow: Array.isArray(data.overflow) ? data.overflow : [],
+    // #1347 CHARGE ledger — PROOF OF CHARGE, the thing a refund must present.
+    // Coerced here and NOT elsewhere: this function is the only reader, so a key
+    // it drops is a key that does not survive a round trip.
+    charged: Array.isArray(data.charged) ? data.charged.filter(_isChargeRecord) : [],
   };
 }
 
@@ -250,7 +349,7 @@ function _readStateFile(file, accountingSessionId) {
 export function readBudgetState(repoRoot, sessionId) {
   const accountingSessionId =
     typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
-  const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [] };
+  const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [], charged: [] };
   if (accountingSessionId === null) return fresh;
 
   const ownFile = budgetStatePath(repoRoot, accountingSessionId);
@@ -285,6 +384,100 @@ export function writeBudgetState(repoRoot, state) {
   return res.ok === true;
 }
 
+/**
+ * Named ceilings for a parked overflow record (#1314, BV-004). GitLab accepts
+ * descriptions up to ~1 MB; 16 KiB covers every real issue body this repo files,
+ * and the record lives in a per-session JSON file that session-end folds into
+ * ONE collector issue. Revisit if `truncated: true` shows up in a fold.
+ * Measured in UTF-16 code units (≈ bytes for ASCII bodies).
+ */
+export const OVERFLOW_DESCRIPTION_MAX = 16 * 1024;
+export const OVERFLOW_COMMAND_MAX = 2 * 1024;
+/** A description file above GitLab's own ~1 MB limit is not read at all. */
+const OVERFLOW_DESCRIPTION_FILE_MAX_BYTES = 1024 * 1024;
+
+/**
+ * Build the structured overflow record BOTH park sites write (#1314) — the
+ * hook's chain pre-flight and `chargeIssueBudget`'s strict branch. Before this
+ * both parked only the raw command, so a body passed as `$(cat /tmp/x.md)` was
+ * lost once the temp file was gone. The description file is read NOW, at block
+ * time; any read failure yields `description: null`, silently — the park itself
+ * must never fail. Old records (`title/command/at` only) stay readable: every
+ * added key is optional.
+ *
+ * Path resolution: a leading `~` / `~/` expands to the home directory; an
+ * absolute path is used as is; a relative path resolves against `cwd` (the
+ * PreToolUse input's working directory) when that is absolute, else against
+ * `repoRoot`. When `cwdChanged` (a `cd` earlier in the same chain) a relative
+ * path is NOT resolved — the record says `descriptionUnresolved: 'cwd-changed'`
+ * instead of parking whichever file happens to sit at the guessed location.
+ * NAMED CEILING (BV-004): `~user/` is not expanded. Revisit if it shows up.
+ *
+ * @param {{ repoRoot: string, title?: string|null, description?: string|null,
+ *           descriptionFile?: string|null, repo?: string|null,
+ *           cwd?: string|null, cwdChanged?: boolean,
+ *           command: string, at: string }} opts
+ * @returns {{ title: string|null, description: string|null, repo: string|null,
+ *             command: string, at: string, truncated: boolean,
+ *             descriptionUnresolved?: 'cwd-changed' }}
+ */
+export function buildOverflowRecord({
+  repoRoot,
+  title = null,
+  description = null,
+  descriptionFile = null,
+  repo = null,
+  cwd = null,
+  cwdChanged = false,
+  command,
+  at,
+}) {
+  let body = typeof description === 'string' ? description : null;
+  let truncated = false;
+  let unresolved = null;
+  if (body === null && typeof descriptionFile === 'string' && descriptionFile.length > 0) {
+    try {
+      let file = descriptionFile;
+      if (file === '~' || file.startsWith('~/')) file = path.join(homedir(), file.slice(1));
+      if (!path.isAbsolute(file)) {
+        if (cwdChanged) {
+          unresolved = 'cwd-changed';
+          throw new Error('cwd-changed');
+        }
+        const base = typeof cwd === 'string' && path.isAbsolute(cwd) ? cwd : repoRoot;
+        file = path.resolve(base, file);
+      }
+      const st = statSync(file);
+      if (st.isFile() && st.size <= OVERFLOW_DESCRIPTION_FILE_MAX_BYTES) {
+        body = readFileSync(file, 'utf8');
+      } else if (st.isFile()) {
+        truncated = true;
+      }
+    } catch {
+      body = null;
+    }
+  }
+  if (body !== null && body.length > OVERFLOW_DESCRIPTION_MAX) {
+    body = body.slice(0, OVERFLOW_DESCRIPTION_MAX);
+    // Never end on half a surrogate pair — a lone high surrogate is not text.
+    const last = body.charCodeAt(body.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff) body = body.slice(0, -1);
+    truncated = true;
+  }
+  const raw = String(command);
+  if (raw.length > OVERFLOW_COMMAND_MAX) truncated = true;
+  const record = {
+    title: title ?? null,
+    description: body,
+    repo: typeof repo === 'string' && repo.length > 0 ? repo : null,
+    command: raw.slice(0, OVERFLOW_COMMAND_MAX),
+    at,
+    truncated,
+  };
+  if (unresolved !== null) record.descriptionUnresolved = unresolved;
+  return record;
+}
+
 /**
  * Charge one issue creation against the session budget and return the verdict.
  *
@@ -304,6 +497,11 @@ export function writeBudgetState(repoRoot, state) {
  *   sessionId?: string|null,
  *   command: string,
  *   title?: string|null,
+ *   description?: string|null,
+ *   descriptionFile?: string|null,
+ *   repo?: string|null,
+ *   cwd?: string|null,
+ *   cwdChanged?: boolean,
  *   config?: { "max-per-session": number, mode: string, overflow: string },
  *   now?: string,
  * }} opts
@@ -323,6 +521,13 @@ export function chargeIssueBudget({
   sessionId = null,
   command,
   title = null,
+  description = null,
+  descriptionFile = null,
+  repo = null,
+  cwd = null,
+  cwdChanged = false,
+  toolCallId = null,
+  statementIndex = 0,
   config,
   now = new Date().toISOString(),
 }) {
@@ -354,9 +559,26 @@ export function chargeIssueBudget({
   const persist = (next) =>
     accountingSessionId === null ? false : writeBudgetState(repoRoot, next);
 
+  // The charge RECORD is the only thing a later refund may act on (#1347). It is
+  // written on every branch that actually increments a counter, and on NO branch
+  // that does not — which is what makes a parked (blocked) creation unrefundable
+  // by construction rather than by a heuristic in the refund hook.
+  const record = (unit) => {
+    state.charged = [
+      ...state.charged,
+      {
+        id: bookingId({ toolCallId, statementIndex }),
+        key: bookingKey({ sessionId: accountingSessionId, command: String(command ?? ''), statementIndex }),
+        unit,
+        at: now,
+      },
+    ].slice(-CHARGED_LEDGER_MAX);
+  };
+
   const { exempt, reason } = classifyExemption(command);
   if (exempt) {
     state.exempt += 1;
+    record('exempt');
     persist(state);
     return {
       ...base,
@@ -369,22 +591,24 @@ export function chargeIssueBudget({
 
   if (state.count < max) {
     state.count += 1;
+    record('count');
     persist(state);
     return { ...base, decision: 'allow', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
   if (mode === 'warn') {
     state.count += 1;
+    record('count');
     persist(state);
     return { ...base, decision: 'warn', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
   // strict — park the request, do not count it.
-  state.overflow.push({
-    title: title ?? null,
-    command: String(command).slice(0, 500),
-    at: now,
-  });
+  state.overflow.push(
+    buildOverflowRecord({
+      repoRoot, title, description, descriptionFile, repo, cwd, cwdChanged, command, at: now,
+    }),
+  );
   persist(state);
   return {
     ...base,
@@ -395,6 +619,185 @@ export function chargeIssueBudget({
   };
 }
 
+/**
+ * How many CHARGE records one session's counter file remembers (#1347, BV-004).
+ *
+ * A record is REMOVED only when its refund is honoured; the record of a create
+ * that SUCCEEDED stays for the rest of the session (nothing else prunes it), so
+ * the ledger holds every charge of the session, not only the outstanding ones.
+ * 64 covers a cap of 12 plus the uncapped exempt creates of a long deep
+ * session (measured this repo: ≤ 12 per session so far) and keeps the file in
+ * the low-kilobyte class. Eviction is fail-CLOSED: an evicted record
+ * makes its refund `not-charged`, i.e. the slot stays spent (the cap ends up
+ * slightly tighter), never refundable twice. Revisit if a session legitimately
+ * exceeds 64 outstanding charges — then the bound, not the direction, is wrong.
+ */
+export const CHARGED_LEDGER_MAX = 64;
+
+/**
+ * The EXACT id of one charged statement, when the harness publishes a tool-call
+ * id for the invocation.
+ *
+ * `<tool_use_id>#<statementIndex>` — instance-unique per statement, so a chain
+ * of two creates yields two ids and a re-delivered failure of the same call
+ * yields the same one.
+ *
+ * @param {{ toolCallId?: string|null, statementIndex?: number }} opts
+ * @returns {string|null} `null` when the harness published no id
+ */
+export function bookingId({ toolCallId = null, statementIndex = 0 } = {}) {
+  if (typeof toolCallId !== 'string' || toolCallId.length === 0) return null;
+  return `${toolCallId}#${Number.isInteger(statementIndex) ? statementIndex : 0}`;
+}
+
+/**
+ * The deterministic fallback key of one charged statement.
+ *
+ * Deliberately session + command text + statement index and NOTHING ELSE — in
+ * particular NOT the counter value at charge time (`countBefore`, the #1347
+ * first-cut key). That value made every retry of the same create mint a FRESH
+ * key: measured against a cap of 3, three retries of a create that was PARKED
+ * (never charged) refunded three slots and drove `count` to 0 while the parked
+ * record still sat in `overflow[]` — i.e. `max-per-session` was unbounded by
+ * retrying a denied create. The key is now stable across retries, and proof of
+ * charge comes from the record's PRESENCE rather than from the key's shape.
+ *
+ * @param {{ sessionId: string|null, command: string, statementIndex?: number }} opts
+ * @returns {string}
+ */
+export function bookingKey({ sessionId, command, statementIndex = 0 }) {
+  const idx = Number.isInteger(statementIndex) ? statementIndex : 0;
+  return digestSha256Short(`cmd:${sessionId ?? ''}|${command}|${idx}`, { length: 16 });
+}
+
+/**
+ * Give one booking back to the session budget (#1347) — ONLY against a recorded
+ * CHARGE.
+ *
+ * WHY THIS EXISTS: `chargeIssueBudget` books the slot in PreToolUse — BEFORE the
+ * command runs. When `glab issue create` then fails (network, rejected label,
+ * expired auth) and the coordinator retries, the SAME issue consumed two slots,
+ * and under `max-per-session: 12` + `mode: strict` that pushes a legitimate
+ * issue into overflow parking. This is the compensating half of the charge.
+ *
+ * WHY IT IS LEDGER-BASED AND NOT INFERRED: the first cut decremented whenever a
+ * failure signal arrived for an issue-create command. It could not tell a CHARGE
+ * from a NON-charge, and at `count === max` the pre-hook PARKS the create and
+ * denies WITHOUT charging while the failure event still fires — so retrying a
+ * DENIED create refunded a slot that was never spent. Presenting the charge
+ * record is the only form of proof that closes that class; every "was this
+ * really charged?" heuristic is a guess about state this module already knows.
+ *
+ * Matching: the exact `<tool_use_id>#<index>` id when both sides have one,
+ * otherwise the deterministic `bookingKey`. Both routes are consulted because
+ * the charging and refunding payloads are separate harness events and only one
+ * of them may carry a tool-call id.
+ *
+ * Decision table:
+ *   mode `off`                  → `{ decision: 'off' }`, nothing written
+ *   no accounting session id    → `{ decision: 'no-session' }`, nothing written
+ *   no matching charge record   → `{ decision: 'noop', reason: 'not-charged' }`
+ *   record with `unit: exempt`  → `{ decision: 'refunded-exempt' }`, `exempt`--
+ *   record with `unit: count`   → `{ decision: 'refunded' }`, `count`--
+ *
+ * Three invariants:
+ *   - The matched record is REMOVED, so a re-delivered failure of the same call
+ *     finds nothing and is `not-charged`. Dedupe is the removal, not a second
+ *     ledger.
+ *   - The refund lands on the SAME counter the charge did (`count` vs `exempt`),
+ *     read off the record — never re-classified from the command text, which a
+ *     retry can have edited.
+ *   - `overflow[]` is NEVER touched. A parked record means the creation was
+ *     BLOCKED, so it was never charged and there is nothing to give back;
+ *     removing it would drop the item session-end promises to file.
+ *
+ * Fail-open like every other function here: an unwritable ledger means the
+ * refund is lost (the cap stays a little tighter), never an exception.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   sessionId?: string|null,
+ *   command: string,
+ *   toolCallId?: string|null,
+ *   statementIndex?: number,
+ *   config?: { "max-per-session": number, mode: string, overflow: string },
+ * }} opts
+ * @returns {{
+ *   decision: 'off'|'no-session'|'noop'|'refunded'|'refunded-exempt',
+ *   count: number,
+ *   exempt: number,
+ *   max: number,
+ *   mode: string,
+ *   overflowCount: number,
+ *   bookingId: string|null,
+ *   reason: string|null,
+ * }}
+ */
+export function refundBooking({
+  repoRoot,
+  sessionId = null,
+  command,
+  toolCallId = null,
+  statementIndex = 0,
+  config,
+}) {
+  const cfg = config ?? loadIssueBudgetConfig(repoRoot);
+  const base = { max: cfg['max-per-session'], mode: cfg.mode };
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+
+  if (cfg.mode === 'off') {
+    return { ...base, decision: 'off', count: 0, exempt: 0, overflowCount: 0, bookingId: null, reason: null };
+  }
+  // Identity-less: `chargeIssueBudget` never PERSISTED such a charge, so there
+  // is provably nothing to refund — and writing here would hit the shared legacy
+  // slot and reset a live session's count (the #1141 hazard).
+  if (accountingSessionId === null) {
+    return { ...base, decision: 'no-session', count: 0, exempt: 0, overflowCount: 0, bookingId: null, reason: null };
+  }
+
+  const state = readBudgetState(repoRoot, accountingSessionId);
+  state.sessionId = accountingSessionId;
+  const exactId = bookingId({ toolCallId, statementIndex });
+  const key = bookingKey({
+    sessionId: accountingSessionId,
+    command: String(command ?? ''),
+    statementIndex,
+  });
+  const verdict = (decision, reason = null, matchedId = null) => ({
+    ...base,
+    decision,
+    count: state.count,
+    exempt: state.exempt,
+    overflowCount: state.overflow.length,
+    bookingId: matchedId ?? exactId ?? key,
+    reason,
+  });
+
+  // Match order (review MED-1, measured): the deterministic key is shared by
+  // EVERY charge of the same command text in this session, so a refund that
+  // carries a tool_use_id must match by id first and may fall back to the key
+  // only among records charged WITHOUT an id (the id-less harness / a
+  // one-sided id). Falling back onto an id-bearing record would hand the
+  // refund to an OLDER charge that may have SUCCEEDED — two charges, one
+  // delivery each, and the second delivery drained the successful create's slot.
+  let at = exactId !== null ? state.charged.findIndex((r) => r.id === exactId) : -1;
+  if (at === -1) {
+    at = state.charged.findIndex((r) => r.key === key && (exactId === null || r.id === null || r.id === undefined));
+  }
+  if (at === -1) return verdict('noop', 'not-charged');
+
+  const rec = state.charged[at];
+  state.charged = [...state.charged.slice(0, at), ...state.charged.slice(at + 1)];
+  if (rec.unit === 'exempt') {
+    if (state.exempt > 0) state.exempt -= 1;
+  } else if (state.count > 0) {
+    state.count -= 1;
+  }
+  writeBudgetState(repoRoot, state);
+  return verdict(rec.unit === 'exempt' ? 'refunded-exempt' : 'refunded', null, rec.id ?? rec.key);
+}
+
 /**
  * Human-readable block message. Shared by the hook (stderr + deny JSON) and the
  * programmatic path so an agent sees the same instruction either way.

package/scripts/lib/learnings/evolve-telemetry.mjs

@@ -20,8 +20,7 @@
  * pipeline).
  *
  * Both emitters are best-effort and try/catch-wrapped — same posture as
- * `emitReconcileCompleted` in `scripts/lib/reconcile/engine.mjs` and
- * `decideAndRecordAutoDialectic` in `scripts/lib/auto-dialectic.mjs` — because
+ * `emitReconcileCompleted` in `scripts/lib/reconcile/engine.mjs` — because
  * `emitEvent()` THROWS `EventValidationError` on a malformed record, and a
  * telemetry failure must never break the `/evolve` pipeline itself.
  *

package/scripts/lib/learnings/sizing-subject.mjs

@@ -0,0 +1,44 @@
+/**
+ * learnings/sizing-subject.mjs — the one derivation of an `effective-sizing`
+ * learning's `subject`, keyed on `(session_type, session_profile)`.
+ *
+ * GitLab #1247. `ultradeep` is a PROFILE layered on top of an unchanged
+ * `session_type: deep` (STATE.md frontmatter key `session-profile`; see
+ * `scripts/lib/state-md.mjs` `SESSION_PROFILE_FIELD`, PRD
+ * `docs/prd/2026-09-06-ultradeep-session-profile.md`) — 7 waves vs. deep's
+ * 4-5. Before this module, the `effective-sizing` analyzer
+ * (`skills/evolve/references/evolve-analyze-mode.md`) keyed its subject on
+ * `session_type` alone (e.g. `deep-session-sizing`), so a 7-wave ultradeep
+ * session and a 5-wave deep session landed on the SAME row — the over-delivery
+ * median for one profile silently absorbed the other's.
+ *
+ * Pure, stdlib-only, no imports, no clock, no fs.
+ *
+ * ## Subject literal (chosen form, justified)
+ *
+ * `${session_type}-session-sizing` when `session_profile` is absent/null —
+ * BYTE-IDENTICAL to the pre-#1247 literal (`deep-session-sizing`,
+ * `feature-session-sizing`, per the existing `skills/evolve/SKILL.md` example
+ * row), so learnings keyed before this change still match on re-run.
+ * `${session_type}-${session_profile}-session-sizing` when a profile is
+ * present — e.g. `deep-ultradeep-session-sizing`. The profile slots BETWEEN
+ * type and the `-session-sizing` suffix (rather than, say, prefixing or
+ * appending after the suffix) so every subject stays readable as
+ * `<type>[-<profile>]-session-sizing` and a reader can strip the trailing
+ * `-session-sizing` to recover `type[-profile]` unambiguously — the same
+ * shape `session-profile` frontmatter documents ("a wave-shape variant on
+ * top of an unchanged session_type").
+ *
+ * @param {{session_type?: unknown, session_profile?: unknown}} params
+ * @returns {string} The canonical `effective-sizing` subject.
+ */
+export function sizingSubject({ session_type, session_profile } = {}) {
+  const type = typeof session_type === 'string' && session_type.trim().length > 0
+    ? session_type.trim()
+    : 'unknown';
+  const profile =
+    typeof session_profile === 'string' && session_profile.trim().length > 0
+      ? session_profile.trim()
+      : null;
+  return profile === null ? `${type}-session-sizing` : `${type}-${profile}-session-sizing`;
+}

package/scripts/lib/locks/staging-fence-lock.mjs

@@ -22,14 +22,13 @@
  * NEVER → session-lock.mjs, so there is no import cycle.
  */
 
-import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 
-import { tryAcquireFileLock } from '../file-lock.mjs';
-import { hostnamesMatch, lockHostCandidate, stableHostname } from '../host-identity.mjs';
-import { nowIso, delay, parseLockBody } from './lock-body.mjs';
+import { releaseFileLock, tryAcquireFileLock } from '../file-lock.mjs';
+import { stableHostname } from '../host-identity.mjs';
+import { nowIso, delay } from './lock-body.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -156,47 +155,23 @@ export async function acquireStagingFenceLock({
 /**
  * Release the staging-fence commit-lock IFF the holder matches.
  *
+ * `busy` (#1349) means the shared `${lockFile}.acquire` guard stayed taken past
+ * its budget; the lock file is left untouched for its stale policy.
+ *
  * @param {object} [opts]
  * @param {string} [opts.repoRoot]
  * @param {string} [opts.holder]
- * @returns {{ ok: true } | { ok: false, reason: 'not-found'|'not-owner'|'fs-error', error?: string }}
+ * @returns {{ ok: true } | { ok: false, reason: 'not-found'|'not-owner'|'busy'|'fs-error', error?: string }}
  */
 export function releaseStagingFenceLock({ repoRoot, holder } = {}) {
   const lockFile = stagingFenceLockPathFor(repoRoot);
 
-  let raw;
-  try {
-    raw = fs.readFileSync(lockFile, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      return { ok: false, reason: 'not-found' };
-    }
-    return { ok: false, reason: 'fs-error', error: err.message };
-  }
-
-  const lock = parseLockBody(raw);
-  if (lock === null) {
-    return { ok: false, reason: 'not-owner' };
-  }
-
-  const ownerMatch = typeof holder === 'string' && holder.length > 0
-    ? lock.holder === holder
-    // #1072: alias-aware host identity, not a raw os.hostname() comparison.
-    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
-
-  if (!ownerMatch) {
-    return { ok: false, reason: 'not-owner' };
-  }
-
-  try {
-    fs.unlinkSync(lockFile);
-    return { ok: true };
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      return { ok: false, reason: 'not-found' };
-    }
-    return { ok: false, reason: 'fs-error', error: err.message };
-  }
+  // Consolidated onto releaseFileLock (#1349); the `pid` staleCheck makes the
+  // takeover race unreachable today — if this lock ever moves to a lease mode,
+  // the shared guard is what keeps release safe.
+  // An empty holder falls through to releaseFileLock's PID + host owner check,
+  // exactly as the inline sequence did.
+  return releaseFileLock(lockFile, { holder });
 }
 
 /**
@@ -258,11 +233,17 @@ export async function withStagingFenceLock(repoRoot, fn, opts = {}) {
   } catch (err) {
     caughtError = err;
   } finally {
+    // WARN only where OUR lock is left behind: 'fs-error' and 'busy' (the
+    // shared guard stayed taken — #1349). 'not-found'/'not-owner' stay silent.
     const releaseResult = releaseStagingFenceLock({ repoRoot, holder });
     if (!releaseResult.ok && releaseResult.reason === 'fs-error') {
       console.warn(
         `withStagingFenceLock: release failed (fs-error: ${releaseResult.error ?? 'unknown'})`,
       );
+    } else if (!releaseResult.ok && releaseResult.reason === 'busy') {
+      console.warn(
+        'withStagingFenceLock: release failed (busy: acquire guard held) — .commit.lock left for its stale policy',
+      );
     }
   }