session-orchestrator 5.2.0 → 5.3.0

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/worktree/lifecycle.mjs

@@ -46,6 +46,15 @@ async function _exists(p) {
   }
 }
 
+/**
+ * The one directory session-orchestrator worktrees may live in.
+ * Host-shared: several sessions run concurrently against the same base.
+ * @returns {string}
+ */
+function _worktreeBaseDir() {
+  return path.join(os.tmpdir(), 'so-worktrees');
+}
+
 /**
  * Compute the standard branch name and tmp path for a given suffix.
  * @param {string} suffix
@@ -53,10 +62,146 @@ async function _exists(p) {
  */
 function _worktreeInfo(suffix) {
   const branch = `so-worktree-${suffix}`;
-  const wtPath = path.join(os.tmpdir(), 'so-worktrees', branch);
+  const wtPath = path.join(_worktreeBaseDir(), branch);
   return { branch, wtPath };
 }
 
+/**
+ * Resolve symlinks, returning null when the path does not exist.
+ * @param {string} p
+ * @returns {Promise<string|null>}
+ */
+async function _realpathOrNull(p) {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `wtPath` is NOT a live working tree of any repository — i.e. either
+ * it carries no `.git` entry at all, or its `.git` file points at an
+ * administrative directory that no longer exists (the registration was dropped).
+ *
+ * A directory whose registration is intact is never an orphan: `git worktree
+ * remove --force` handles that case, so this predicate is what keeps a live
+ * worktree — including one owned by a PEER session, or by another repository —
+ * out of the delete path below.
+ *
+ * @param {string} wtPath
+ * @returns {Promise<boolean>}
+ */
+async function _isUnregisteredWorktreeDir(wtPath) {
+  const dotGit = path.join(wtPath, '.git');
+  let st;
+  try {
+    st = await fs.lstat(dotGit);
+  } catch {
+    return true; // No .git entry — not a working tree of anything.
+  }
+  // A real .git DIRECTORY means a full repository lives here; never ours to delete.
+  if (!st.isFile()) return false;
+
+  const content = await fs.readFile(dotGit, 'utf8').catch(() => '');
+  const match = /^gitdir:\s*(.+)$/m.exec(content);
+  if (!match) return false; // Unparseable — treat as live, refuse.
+
+  const adminDir = path.resolve(wtPath, match[1].trim());
+  // Admin dir still present → git knows this worktree → not an orphan.
+  return !(await _exists(adminDir));
+}
+
+/**
+ * Remove an ORPHAN worktree directory (issue #984).
+ *
+ * An interrupted `removeWorktree` drops the git registration first and can die
+ * before the directory is gone. `git worktree add` then fails with
+ * "'…' already exists" while `git worktree remove --force` fails with
+ * "'…' is not a working tree" (swallowed by nothrow) — the retry loops on the
+ * same error until someone deletes the directory by hand.
+ *
+ * SAFETY — this is a recursive delete inside library code, so every condition
+ * below is asserted in code before `fs.rm` runs. Any failed condition returns
+ * false and leaves the directory alone (the retry then fails with git's own
+ * error, which is the pre-#984 behaviour):
+ *   1. `wtPath` itself is a real directory and NOT a symlink — the LEAF is never
+ *      followed. (A symlink one level up is covered by condition 2.)
+ *   2. The literal base `<os.tmpdir()>/so-worktrees` is itself a real directory
+ *      and NOT a symlink. The base lives on a host-shared /tmp where a co-tenant
+ *      can pre-create it; without this check the realpath of a planted base
+ *      symlink BECOMES the delete root, so a `so-worktree-*` directory anywhere
+ *      on the filesystem would qualify.
+ *   3. The REALPATH of `wtPath` is a DIRECT child of the REALPATH of that base
+ *      — both sides resolved, because macOS resolves /tmp → /private/tmp and
+ *      os.tmpdir() itself may be a symlinked path.
+ *   4. The resolved basename starts with `so-worktree-`.
+ *   5. It is not a live working tree of ANY repository (see above).
+ * Note what is NOT asserted: an intermediate component of `wtPath` other than
+ * the base cannot exist — the path is `<base>/so-worktree-<suffix>`, computed by
+ * `_worktreeInfo`, never caller-supplied.
+ * `git worktree prune` is deliberately NOT used: it is repo-global and would
+ * drop a peer session's stale registration.
+ *
+ * CEILING (BV-004): the delete is bounded to one directory directly under the
+ * fixed base `<os.tmpdir()>/so-worktrees` whose name carries the `so-worktree-`
+ * prefix. Revisit when worktree paths become caller-supplied (the
+ * `validateWorkspacePath` follow-up noted above) or move out of os.tmpdir() —
+ * at that point the containment base is no longer a constant and must be passed
+ * in and validated by the caller.
+ *
+ * @param {string} wtPath
+ * @returns {Promise<boolean>} true when a directory was actually removed.
+ */
+async function _removeOrphanWorktreeDir(wtPath) {
+  let lst;
+  try {
+    lst = await fs.lstat(wtPath);
+  } catch {
+    return false; // Nothing there.
+  }
+  if (lst.isSymbolicLink() || !lst.isDirectory()) return false;
+
+  // The containment BASE must be a real directory too: on a host-shared /tmp a
+  // co-tenant can pre-create `<os.tmpdir()>/so-worktrees` as a symlink, and a
+  // realpath-resolved base would then relocate the delete root off-tmpdir.
+  const baseDir = _worktreeBaseDir();
+  let baseLst;
+  try {
+    baseLst = await fs.lstat(baseDir);
+  } catch {
+    return false; // No base directory — nothing under it to remove.
+  }
+  if (baseLst.isSymbolicLink() || !baseLst.isDirectory()) return false;
+
+  const realWt = await _realpathOrNull(wtPath);
+  const realBase = await _realpathOrNull(baseDir);
+  if (!realWt || !realBase) return false;
+  if (!isPathInside(realWt, realBase)) return false;
+  // Direct child only — matches the CEILING below; no nested path qualifies.
+  if (path.dirname(realWt) !== realBase) return false;
+  if (!path.basename(realWt).startsWith('so-worktree-')) return false;
+
+  if (!(await _isUnregisteredWorktreeDir(realWt))) return false;
+
+  // RACE WINDOW (accepted, #1390 P7): `_isUnregisteredWorktreeDir` above and
+  // `fs.rm` below are two separate syscalls, not one atomic check-then-act.
+  // Both plausible racers here are session-orchestrator sessions on the SAME
+  // host, contending over the same `<os.tmpdir()>/so-worktrees` base: one
+  // could register (`git worktree add`) or delete `realWt` in the gap between
+  // the two calls. No lock primitive guards this sub-millisecond window
+  // between our own sessions — the worst case is a benign retry (the caller's
+  // `git worktree add` above already retries once on failure), never data
+  // loss, because neither racer ever touches a path outside its own
+  // `so-worktree-*` name.
+  // REVISIT TRIGGER (BV-004): an UNRELATED process gains the ability to
+  // create or delete `so-worktree-*` directories under this base — at that
+  // point the race is no longer bounded to our own retry semantics and this
+  // window needs an actual lock, not an accepted gap.
+  await fs.rm(realWt, { recursive: true, force: true });
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // validateWorkspacePath
 // ---------------------------------------------------------------------------
@@ -136,6 +281,13 @@ export async function createWorktree(suffix, baseRef = 'HEAD', options = {}) {
     await nothrow(git`git worktree remove ${wtPath} --force`);
     await nothrow(git`git branch -D ${branch}`);
 
+    // Still on disk after the remove attempt → git has no registration for it
+    // (issue #984). Delete the orphan directory under the guards documented on
+    // _removeOrphanWorktreeDir; a live/registered worktree never reaches here.
+    if (await _exists(wtPath)) {
+      await _removeOrphanWorktreeDir(wtPath);
+    }
+
     try {
       await git`git worktree add -b ${branch} ${wtPath} ${baseRef}`;
     } catch (secondErr) {

package/scripts/release-session-lock.mjs

@@ -0,0 +1,305 @@
+/**
+ * release-session-lock.mjs — CLI: release THIS session's `session.lock`, emit the
+ * terminal `orchestrator.session.lock.released` breadcrumb, and PROVE the lock is
+ * gone before exiting 0.
+ *
+ * ## Why a CLI and not one more `release()` call site (#1395)
+ *
+ * Measured 2026-09-19: three of the four `release()` call sites already emit
+ * `orchestrator.session.lock.released` — `hooks/on-session-end.mjs`,
+ * `scripts/lib/autopilot/worktree-pipeline.mjs` and
+ * `scripts/lib/session-transition.mjs`. The silent one was never code at all: it
+ * is the PROSE step `skills/session-end/SKILL.md` § Phase 3.8, executed by hand
+ * by the coordinator LLM. It deletes the lock, so the SessionEnd hook later reads
+ * `status: 'absent'` and emits nothing — this repo recorded 5 `lock.acquired`
+ * against 0 `lock.released`. A prose "call X, then check Y" step is the shape
+ * that gets skipped (`.claude/rules/process-contracts.md`: 339 of 351 issues
+ * closed without the prose-mandated pre-step); the repair is ONE command that
+ * verifies its own effect and exits non-zero when it cannot.
+ *
+ * ## Why the emit is not inside `release()`
+ *
+ * Three structural reasons, none of them fixable here:
+ *   1. Import cycle — `scripts/lib/events.mjs` imports `session-lock.mjs`
+ *      (`sessionAttribution()` reads the lock), so `session-lock.mjs` cannot
+ *      import `events.mjs`.
+ *   2. `release()` is synchronous; `emitEvent()` is async.
+ *   3. After the unlink the event envelope can no longer read the lock for
+ *      correlation — which is exactly why this CLI captures `session_id` and
+ *      `semantic_session_id` from the lock BEFORE releasing and passes both
+ *      EXPLICITLY in the payload.
+ *
+ * ## Reuse note (BV-001.2)
+ *
+ * `leaveSourceRoot()` in `scripts/lib/session-transition.mjs` is the closest
+ * existing helper and is deliberately NOT reused: it also deregisters the
+ * host-wide registry entry, which a session closing in place must NOT do at
+ * Phase 3.8 (the SessionEnd hook owns deregistration, at the real end). Its
+ * `LOCK_RELEASED_EVENT` constant IS reused, so the event name has one writer.
+ *
+ * Exit codes: 0 verified · 1 user/input or ownership error · 2 system error.
+ *
+ * Exports (for tests): main.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { readLockDetailed, loadOwnerProof, release } from './lib/session-lock.mjs';
+import { LOCK_RELEASED_EVENT } from './lib/session-transition.mjs';
+import { emitEvent } from './lib/events.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+/**
+ * `caller` value stamped into the breadcrumb, so this fourth release site stays
+ * distinguishable from `on-session-end`, `session-transition` and the autopilot
+ * worktree pipeline in the single `orchestrator.session.lock.*` stream.
+ */
+export const PHASE_CALLER = 'session-end-phase-3-8';
+
+const HELP = `release-session-lock.mjs — release this session's lock and prove it is gone
+
+USAGE
+  node scripts/release-session-lock.mjs --session-id <raw-id> [--repo-root <path>] [--json]
+
+WHAT IT DOES
+  1. Reads <repo-root>/.orchestrator/session.lock.
+  2. Releases it IFF its raw session_id equals --session-id (owner-proof gated,
+     exactly as hooks/on-session-end.mjs gates it).
+  3. Emits orchestrator.session.lock.released with the ids read BEFORE the
+     delete, plus caller="${PHASE_CALLER}".
+  4. RE-READS the lock path and exits 0 only when our lock is provably gone.
+
+FLAGS
+  --session-id <id>   REQUIRED. The RAW (physical) session id that owns the lock
+                      — .orchestrator/session.lock "session_id", never STATE.md
+                      "session" and never the semantic id. A lock owned by a
+                      different id is NEVER released.
+  --repo-root <path>  Repo whose lock is released (default: cwd).
+  --json              Machine-readable result on stdout.
+  -h, --help          Show this help and exit 0.
+
+OUTCOMES
+  absent        no lock file — nothing released, NO event, exit 0.
+  deleted       our lock was removed and re-read as gone.
+  already-gone  ownership matched but the lock had already vanished; the event
+                is still written, because a lock removed by a third party while
+                we held it is the forensically interesting case.
+
+EXIT CODES
+  0 — the lock is provably absent (released now, or nothing to release)
+  1 — user/input or ownership error: missing/empty --session-id, unknown flag,
+      or a lock owned by a different session (nothing is touched)
+  2 — system error: unreadable/corrupt lock, filesystem error, owner-proof
+      mismatch, the lock still present after release, or the breadcrumb could
+      not be written
+`;
+
+/**
+ * Print the one-line human summary (stdout = data, stderr = diagnostics).
+ *
+ * @param {{outcome: string, verified: boolean, session_id: string, event_emitted: boolean}} result
+ */
+function printHuman(result) {
+  if (result.outcome === 'absent') {
+    process.stdout.write('session-lock: nothing to release — no lock file (no event written).\n');
+    return;
+  }
+  const verified = result.verified ? 'verified gone' : 'NOT verified — lock still present';
+  const event = result.event_emitted ? 'breadcrumb written' : 'breadcrumb FAILED';
+  process.stdout.write(
+    `session-lock ${result.outcome} for session ${result.session_id} — ${verified}, ${event}.\n`,
+  );
+}
+
+/**
+ * Did OUR lock really vanish?
+ *
+ * Computed from a FRESH read after `release()` returned, deliberately not from
+ * `release()`'s own `verified` field: that field is absent on the benign
+ * `no-lock` branch (so a caller copying it reports `verified: false` for a lock
+ * that IS gone), and it was computed before this process did anything else. The
+ * CLI's whole contract is "exit 0 proves absence", so it re-reads.
+ *
+ * A FOREIGN lock present at the re-read counts as verified — ours is gone and a
+ * sibling legitimately acquired the path in the race window (same rule as
+ * `release()`'s post-delete verify; PSA-005: never touch a lock we do not own).
+ *
+ * @param {string} repoRoot
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+function ourLockIsGone(repoRoot, sessionId) {
+  const after = readLockDetailed({ repoRoot });
+  if (after.status === 'absent') return true;
+  if (after.status === 'ok') return after.lock.session_id !== sessionId;
+  // unreadable / corrupt — absence cannot be confirmed, so it is not claimed.
+  return false;
+}
+
+/**
+ * CLI entry point.
+ *
+ * @param {{argv?: string[]}} [opts]
+ * @returns {Promise<number>} process exit code
+ */
+export async function main({ argv = process.argv.slice(2) } = {}) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        'repo-root': { type: 'string' },
+        'session-id': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    process.stderr.write(`release-session-lock: ${err?.message ?? 'bad arguments'}\n`);
+    process.stderr.write('Run with --help for usage.\n');
+    return 1;
+  }
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const sessionId = values['session-id'];
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    process.stderr.write('release-session-lock: --session-id <raw-id> is required.\n');
+    process.stderr.write('Run with --help for usage.\n');
+    return 1;
+  }
+
+  const repoRoot = values['repo-root'] ?? process.cwd();
+
+  const emitResult = async (result) => {
+    if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else printHuman(result);
+  };
+
+  // -- Step 1: read the lock, and capture the ids BEFORE anything is deleted --
+  const lockDetail = readLockDetailed({ repoRoot });
+
+  if (lockDetail.status === 'absent') {
+    // Nothing was released, so nothing terminal happened: NO event. Writing one
+    // here would put a fictional lifecycle end into the stream — the idempotent
+    // re-run case is not a release.
+    const result = { ok: true, outcome: 'absent', verified: true, session_id: sessionId, event_emitted: false };
+    await emitResult(result);
+    return 0;
+  }
+
+  if (lockDetail.status !== 'ok') {
+    process.stderr.write(`release-session-lock: lock is ${lockDetail.status} — ownership cannot be established; nothing touched.\n`);
+    await emitResult({
+      ok: false, outcome: `lock-${lockDetail.status}`, verified: false, session_id: sessionId, event_emitted: false,
+    });
+    return 2;
+  }
+
+  const lock = lockDetail.lock;
+  if (lock.session_id !== sessionId) {
+    // A raw-id mismatch never grants release ownership (same gate as
+    // hooks/on-session-end.mjs). Reconciliation of a foreign lease is the
+    // reaper's job, not this command's.
+    process.stderr.write(`release-session-lock: lock is owned by a different session — not released.\n`);
+    await emitResult({
+      ok: false, outcome: 'session-mismatch', verified: false, session_id: sessionId, event_emitted: false,
+    });
+    return 1;
+  }
+
+  const semanticSessionId = typeof lock.semantic_session_id === 'string' && lock.semantic_session_id.length > 0
+    ? lock.semantic_session_id
+    : null;
+
+  // -- Step 2: release, owner-proof gated (#987/#989) ------------------------
+  // `proof` is null whenever ownership cannot be proven; release() treats null
+  // as absent and degrades to the session_id-only path, so it is passed
+  // through unguarded.
+  const proof = loadOwnerProof({ repoRoot });
+  const releaseResult = release({ sessionId, repoRoot, proof });
+
+  if (releaseResult.ok !== true) {
+    process.stderr.write(`release-session-lock: release failed — ${releaseResult.reason ?? 'fs-error'}\n`);
+    await emitResult({
+      ok: false, outcome: `release-${releaseResult.reason ?? 'fs-error'}`, verified: false, session_id: sessionId, event_emitted: false,
+    });
+    return 2;
+  }
+
+  const alreadyGone = releaseResult.deleted !== true && releaseResult.reason === 'no-lock';
+  if (releaseResult.deleted !== true && !alreadyGone) {
+    // 'proof-mismatch' (and any future non-delete reason): ownership matched on
+    // the raw id but the second factor contradicted it. Contradictory on-disk
+    // state, not a bad argument — exit 2.
+    process.stderr.write(`release-session-lock: lock not released — ${releaseResult.reason ?? 'not-deleted'}\n`);
+    await emitResult({
+      ok: false, outcome: `release-${releaseResult.reason ?? 'not-deleted'}`, verified: false, session_id: sessionId, event_emitted: false,
+    });
+    return 2;
+  }
+
+  // -- Step 3: prove it ------------------------------------------------------
+  const verified = ourLockIsGone(repoRoot, sessionId);
+  const outcome = alreadyGone ? 'already-gone' : 'deleted';
+
+  // -- Step 4: the terminal breadcrumb --------------------------------------
+  // The ids are passed EXPLICITLY: the lock is gone by now, so emitEvent's
+  // lock-derived correlation would find nothing to attribute this record to.
+  let eventEmitted = true;
+  let emitError = null;
+  try {
+    await emitEvent(LOCK_RELEASED_EVENT, {
+      session_id: sessionId,
+      ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+      caller: PHASE_CALLER,
+      outcome,
+      verified,
+    }, { repoRoot });
+  } catch (err) {
+    eventEmitted = false;
+    emitError = err?.message ?? String(err);
+  }
+
+  const result = {
+    ok: verified && eventEmitted,
+    outcome,
+    verified,
+    session_id: sessionId,
+    ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
+    event_emitted: eventEmitted,
+    ...(emitError !== null ? { event_error: emitError } : {}),
+  };
+  await emitResult(result);
+
+  if (!verified) {
+    process.stderr.write('release-session-lock: the lock is STILL present after release — not verified.\n');
+    return 2;
+  }
+  if (!eventEmitted) {
+    // The release itself succeeded; what failed is the one thing this command
+    // exists to guarantee, so it is reported as a system error rather than
+    // swallowed. Phase 3.8 treats a non-zero exit as a WARN and continues.
+    process.stderr.write(`release-session-lock: breadcrumb could not be written — ${emitError}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// CLI guard — prevents execution during test-time imports.
+// ---------------------------------------------------------------------------
+
+if (isMainModule(import.meta.url)) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`release-session-lock: unexpected error: ${err?.stack ?? err}\n`);
+      process.exit(2);
+    });
+}

package/scripts/release.mjs

@@ -384,7 +384,10 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // September 10 campaign snapshot: inputs and receipt reproduce the dated 4.3-planned
 // render made while 4.2.0 was current. Exact files only; neighboring marketing
 // remains checked. Do not bump receipt props without a newly reviewed render.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
+// `scripts/lib/locks/index.mjs` is the one-cycle deprecation shim (5.2.0 CHANGELOG, Changed): its
+// runtime warning names the version it was deprecated IN, so it legitimately carries the previous
+// release literal until its 6.0.0 removal — version history by construction, not drift.
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -881,14 +884,36 @@ export function evaluateNpmAuth(whoami) {
  * never found out". Only an actual `status: 'green'` reading passes; a release
  * must never proceed on an unknown CI state.
  *
- * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
+ * The row also carries the CAUSE the probe already knows, because the three
+ * ways this row goes red are indistinguishable without it (#1384 P5): a short
+ * `sha`, a commit the mirror has never seen, and a HEAD with no pipeline all
+ * printed `CI status unknown (query-failed)` / `status: unknown`. The probe's
+ * `detail` (degraded branch, `degradedResult`) and `details.reason` /
+ * `failingJobName` (read branch, `sanitizeApiText`) are clamped and
+ * control-byte-escaped AT THEIR GENERATION in `ci-status-banner.mjs` —
+ * appended here, never re-formatted. That escaping is load-bearing, not
+ * hygiene: the read branch interpolates a RAW API `status` value into
+ * `reason`, and until #1384 f-4 a status carrying `\r` + an ANSI sequence
+ * could repaint THIS row green while its verdict stayed `ok:false`. Do not
+ * append a further probe field here without checking it goes through one of
+ * those two. With neither present the text is byte-identical to
+ * before, so a plain green or a named failing job reads exactly as it did.
+ *
+ * @param {null | {status?: string, failingJobName?: string, degraded?: string,
+ *   detail?: string, details?: {reason?: string}}} ci
  * @returns {{ok: boolean, detail: string}}
  */
 export function evaluateCiRow(ci) {
   if (ci === null || ci === undefined) return { ok: false, detail: 'CI status unavailable' };
-  if (ci.degraded) return { ok: false, detail: `CI status unknown (${ci.degraded})` };
-  const job = ci.failingJobName ? ` (${ci.failingJobName})` : '';
-  return { ok: ci.status === 'green', detail: `status: ${ci.status}${job}` };
+  if (ci.degraded) {
+    const why = ci.detail ? `: ${ci.detail}` : '';
+    return { ok: false, detail: `CI status unknown (${ci.degraded}${why})` };
+  }
+  // A failing job NAMES the failure, so it wins over the generic reason;
+  // `reason` is what fills the gap when there is no job to name (`unknown`).
+  const reason = ci.failingJobName || ci.details?.reason || '';
+  const why = reason ? ` (${reason})` : '';
+  return { ok: ci.status === 'green', detail: `status: ${ci.status}${why}` };
 }
 
 /**