mixdog 0.9.50 → 0.9.52

package/src/runtime/shared/atomic-file.mjs

@@ -100,9 +100,8 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
         contErr.cause = err;
         throw contErr;
       }
-      // Stale-lock reclaim (shared with the async variant). Covers a dead
-      // owner pid, a same-pid-but-foreign-token corpse from a reused pid, and
-      // a pidless/empty corpse lock; a live foreign holder is never stolen.
+      // Reclaim only when owner death is positively established. Age, an
+      // unreadable owner, or a same-pid foreign token remain contended.
       try {
         if (_tryReclaimStaleLock(lockPath, staleMs)) continue;
       } catch {}
@@ -127,11 +126,9 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
       return fn();
     } finally {
       try { closeSync(fd); } catch {}
-      // Only unlink if we still own the lock. If our hold exceeded
-      // staleMs and another process already stole + replaced the
-      // file, unconditionally unlinking here would destroy the new
-      // owner's lock and break mutual exclusion for whoever is
-      // queued behind it.
+      // Only unlink if we still own the lock. If the path was externally
+      // replaced, unconditionally unlinking would destroy the new owner's
+      // lock and break mutual exclusion for whoever is queued behind it.
       try {
         if (_lockOwnedBySelf(lockPath)) unlinkSync(lockPath);
       } catch {}
@@ -147,33 +144,6 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
 // token is the owner pid (see the writeFileSync above). Best-effort
 // only: a parse failure or stat error is treated as "not ours" /
 // "owner unknown" so we err on the side of NOT stealing.
-function _readLockOwnerPid(lockPath) {
-  try {
-    const raw = readFileSync(lockPath, 'utf8');
-    const tok = String(raw).trim().split(/\s+/)[0];
-    const pid = Number.parseInt(tok, 10);
-    return Number.isFinite(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-
-function _pidIsDead(pid) {
-  // Unreadable / unparseable pid: be conservative — treat as alive so
-  // we wait instead of stealing.
-  if (pid === null) return false;
-  if (pid === process.pid) return false;
-  try {
-    process.kill(pid, 0);
-    return false; // signal delivered → process exists
-  } catch (err) {
-    // ESRCH = no such process → owner is gone, safe to steal.
-    // EPERM = process exists but we can't signal it → still alive,
-    // do NOT steal.
-    return err?.code === 'ESRCH';
-  }
-}
-
 // Full owner identity: pid plus per-instance token. token is null for an
 // old-format (`<pid> <ts>`) lock, in which case callers fall back to
 // pid-authoritative handling so a still-running old-format holder is
@@ -196,13 +166,8 @@ function _readLockOwner(lockPath) {
 //  - pid null (empty/unparseable): not live (unknown owner).
 //  - pid === our pid: treated as LIVE. A foreign/absent token on our own
 //    pid is ambiguous — it may be a recycled-pid corpse, but it may also
-//    be a live sibling worker_thread (which shares process.pid yet owns a
-//    separate _OWNER_TOKEN module instance). We cannot distinguish them
-//    from the token alone, so we never call a same-pid owner instantly
-//    dead; the reclaim path gates a same-pid foreign-token steal behind
-//    stale mtime (see _ownerIsSelfForeign / _tryReclaimStaleLock) so a
-//    live sibling is never yanked, while a real corpse still frees once
-//    mtime goes stale.
+//    be a live sibling worker_thread (which shares process.pid). Ambiguity
+//    is never reclaimed.
 //  - foreign pid: probed with kill(pid, 0); ESRCH ⇒ dead, else live.
 function _ownerIsLive(owner) {
   if (owner.pid === null) return false;
@@ -215,15 +180,6 @@ function _ownerIsLive(owner) {
   }
 }
 
-// Our own pid but a foreign (present, non-matching) token: either a
-// recycled-pid corpse or a live sibling worker_thread. Reclaimable only
-// once mtime is past staleMs (handled by the pidless-style stale gate).
-function _ownerIsSelfForeign(owner) {
-  return owner.pid === process.pid
-    && owner.token !== null
-    && owner.token !== _OWNER_TOKEN;
-}
-
 // Release-time guard: unlink only if the lock still carries OUR identity
 // (our pid AND our token). Protects against deleting a lock another
 // instance stole+recreated, and against a same-pid sibling.
@@ -238,23 +194,15 @@ function _lockOwnedBySelf(lockPath) {
 // they wait between attempts. Returns true iff lockPath was reclaimed.
 //
 // Reclaim decision table (owner = identity recorded in the lock file):
-//   owner pid DEAD (ESRCH / self-pid+foreign-token corpse) → reclaim
-//   owner pid NULL (empty/unparseable) AND mtime past staleMs → reclaim
+//   owner pid DEAD (ESRCH) → reclaim
+//   owner pid NULL/uncertain or same-pid foreign token → back off
 //   owner token MISMATCH on guarded re-read (new holder took over) → back off
-//   owner LIVE (foreign pid alive, or our own current token) → back off
+//   owner LIVE → back off regardless of age
 function _tryReclaimStaleLock(lockPath, staleMs) {
-  let st;
-  try { st = statSync(lockPath); } catch { return false; }
+  try { statSync(lockPath); } catch { return false; }
   const owner = _readLockOwner(lockPath);
-  const stale = Date.now() - st.mtimeMs > staleMs;
   const dead = owner.pid !== null && !_ownerIsLive(owner);
-  const pidless = owner.pid === null;
-  const selfForeign = _ownerIsSelfForeign(owner);
-  // A dead foreign owner reclaims immediately. A pidless corpse, or a
-  // same-pid foreign-token owner (which may still be a live sibling
-  // worker_thread), reclaims only once mtime is past staleMs; a live
-  // foreign holder is never stolen even after mtime goes stale.
-  if (!dead && !((pidless || selfForeign) && stale)) return false;
+  if (!dead) return false;
   const reclaim = _tryAcquireReclaimGuard(lockPath, staleMs);
   if (reclaim === null) return false;
   try {
@@ -266,11 +214,8 @@ function _tryReclaimStaleLock(lockPath, staleMs) {
     // the guard window has a different token and is not mistaken for the
     // corpse — so we never yank a freshly-acquired live lock.
     if (curOwner.pid !== owner.pid || curOwner.token !== owner.token) return false;
-    const curStale = Date.now() - cur.mtimeMs > staleMs;
     const curDead = curOwner.pid !== null && !_ownerIsLive(curOwner);
-    const curPidless = curOwner.pid === null;
-    const curSelfForeign = _ownerIsSelfForeign(curOwner);
-    if (curDead || ((curPidless || curSelfForeign) && curStale)) {
+    if (curDead) {
       try { unlinkSync(lockPath); return true; } catch { return false; }
     }
     return false;
@@ -279,89 +224,23 @@ function _tryReclaimStaleLock(lockPath, staleMs) {
   }
 }
 
-function _reclaimGuardIsUnreadableAndStale(guardPath, staleMs) {
-  if (_readLockOwnerPid(guardPath) !== null) return false;
-  try {
-    const st = statSync(guardPath);
-    return Date.now() - st.mtimeMs > staleMs;
-  } catch {
-    return false;
-  }
-}
-
-function _reclaimGuardMatchesToken(guardPath, token) {
-  try {
-    return readFileSync(guardPath, 'utf8') === token;
-  } catch {
-    return false;
-  }
-}
-
-function _readGuardContent(guardPath) {
-  try { return readFileSync(guardPath, 'utf8'); } catch { return null; }
-}
-
-function _parseStampPid(raw) {
-  if (raw === null) return null;
-  const tok = String(raw).trim().split(/\s+/)[0];
-  const pid = Number.parseInt(tok, 10);
-  return Number.isFinite(pid) && pid > 0 ? pid : null;
-}
-
-// Unlink the guard only if its FULL content (pid ts token) is still the
-// exact content the stale/dead decision was made against. A regenerated
-// guard — even one whose pid was recycled to the same value (same-pid
-// ABA) — carries a fresh ts+token and therefore never matches, so a
-// fresh guard is never removed by a stale decision.
-function _unlinkReclaimGuardIfContentMatches(guardPath, content) {
-  if (_readGuardContent(guardPath) !== content) return false;
-  try { unlinkSync(guardPath); return true; } catch { return false; }
-}
-
-function _unlinkUnreadableStaleReclaimGuard(guardPath, staleMs) {
-  if (!_reclaimGuardIsUnreadableAndStale(guardPath, staleMs)) return false;
-  try { unlinkSync(guardPath); return true; } catch { return false; }
-}
-
-function _tryClearStaleReclaimGuard(guardPath, staleMs) {
-  const guardContent = _readGuardContent(guardPath);
-  const guardPid = _parseStampPid(guardContent);
-  if (guardPid !== null) {
-    // Re-read the guard's full content immediately before unlinking so a
-    // regenerated guard (different owner OR same-pid ABA) is not removed
-    // by a stale decision.
-    // This is still not a serialized primitive: correctness comes from
-    // the lockPath owner-token reverify before unlinking lockPath, not
-    // from making guard cleanup itself authoritative.
-    // A guard whose pid was recycled onto a LIVE process would otherwise
-    // never clear, starving reclaim permanently; so also clear a guard
-    // past staleMs regardless of apparent pid-liveness. Safe because the
-    // guard is best-effort — the lockPath owner-token reverify still gates
-    // the actual lock unlink.
-    let guardStale = false;
-    try { guardStale = Date.now() - statSync(guardPath).mtimeMs > staleMs; } catch {}
-    if (_pidIsDead(guardPid) || guardStale) {
-      _unlinkReclaimGuardIfContentMatches(guardPath, guardContent);
-    }
-    return;
-  }
-  // A crash between openSync('wx') and the pid write can leave an empty
-  // guard. There is no pid to prove dead, so clear only once the guard
-  // file itself is stale; any contender that proceeds must still prove
-  // the lockPath token dead before unlinking the lock.
-  _unlinkUnreadableStaleReclaimGuard(guardPath, staleMs);
-}
-
 function _tryAcquireReclaimGuard(lockPath, staleMs) {
   const guardPath = `${lockPath}.reclaim`;
+  const token = `${process.pid} ${Date.now()} ${randomBytes(8).toString('hex')}\n`;
+  const stagedPath = `${guardPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
   try {
-    const fd = openSync(guardPath, 'wx', 0o600);
-    const token = `${process.pid} ${Date.now()} ${randomBytes(8).toString('hex')}\n`;
-    try { writeFileSync(fd, token, 'utf8'); } catch {}
-    return { fd, guardPath, token };
+    // Publish a fully formed guard with no empty-file window. linkSync is
+    // atomic and fails rather than replacing an existing pathname.
+    writeFileSync(stagedPath, token, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    linkSync(stagedPath, guardPath);
+    unlinkSync(stagedPath);
+    return { guardPath };
   } catch (err) {
+    try { unlinkSync(stagedPath); } catch {}
     if (LOCK_WAIT_CODES.has(err?.code)) {
-      _tryClearStaleReclaimGuard(guardPath, staleMs);
+      // There is no portable ownership-conditional unlink. Never revoke a
+      // published guard: age and contents are diagnostic only, and deleting
+      // after a pathname re-read admits an ABA that can steal a live guard.
       return null;
     }
     throw err;
@@ -369,10 +248,9 @@ function _tryAcquireReclaimGuard(lockPath, staleMs) {
 }
 
 function _releaseReclaimGuard(reclaim) {
-  try { closeSync(reclaim.fd); } catch {}
-  if (_reclaimGuardMatchesToken(reclaim.guardPath, reclaim.token)) {
-    try { unlinkSync(reclaim.guardPath); } catch {}
-  }
+  // Protocol participants cannot replace a published guard: contenders only
+  // wait, so the exact owner may remove its non-revocable pathname directly.
+  try { unlinkSync(reclaim.guardPath); } catch {}
 }
 
 // ── Async lock variant (non-blocking wait) ──────────────────────────

package/src/runtime/shared/process-lifecycle.mjs

@@ -0,0 +1,363 @@
+'use strict';
+
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { withFileLockSync } from './atomic-file.mjs';
+import { resolvePluginData } from './plugin-paths.mjs';
+
+export const LIFECYCLE_LEDGER_MAX_BYTES = 64 * 1024;
+export const LIFECYCLE_LEDGER_KEEP_FILES = 2;
+const LEDGER_NAME = 'process-lifecycle.jsonl';
+const MARKER_DIR_NAME = 'process-lifecycle.active';
+const LEGACY_MARKER_NAME = 'process-lifecycle.active.json';
+const REPORT_NAME = 'mixdog-node-report.json';
+const LEDGER_LOCK_NAME = 'process-lifecycle.lock';
+const LEDGER_LOCK_TIMEOUT_MS = 2000;
+const LEDGER_LOCK_STALE_MS = 10000;
+const STATE_KEY = Symbol.for('mixdog.processLifecycle.v1');
+const VALID_REASONS = new Set([
+  'process-start',
+  'prior-process-vanished',
+  'clean-shutdown',
+  'catchable-fatal-error',
+  'forced-cleanup',
+]);
+
+function sharedState() {
+  if (!globalThis[STATE_KEY]) globalThis[STATE_KEY] = { active: null };
+  return globalThis[STATE_KEY];
+}
+
+function paths(directory) {
+  const dir = directory || join(resolvePluginData(), 'diagnostics');
+  return {
+    dir,
+    ledger: join(dir, LEDGER_NAME),
+    previousLedger: join(dir, `${LEDGER_NAME}.1`),
+    markerDir: join(dir, MARKER_DIR_NAME),
+    legacyMarker: join(dir, LEGACY_MARKER_NAME),
+    lock: join(dir, LEDGER_LOCK_NAME),
+    report: join(dir, REPORT_NAME),
+  };
+}
+
+function memoryCounters() {
+  try {
+    const value = process.memoryUsage();
+    return {
+      rss: value.rss,
+      heapTotal: value.heapTotal,
+      heapUsed: value.heapUsed,
+      external: value.external,
+      arrayBuffers: value.arrayBuffers,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function rotateLedger(active) {
+  const size = Number(statSync(active.ledger).size) || 0;
+  try { unlinkSync(active.previousLedger); } catch {}
+  if (size <= LIFECYCLE_LEDGER_MAX_BYTES) {
+    renameSync(active.ledger, active.previousLedger);
+    return;
+  }
+
+  // An oversized file cannot have been produced by this writer. Do not carry
+  // an untrusted/partial record into the retained generation.
+  writeFileSync(active.previousLedger, '', { mode: 0o600 });
+  unlinkSync(active.ledger);
+}
+
+function boundPreviousLedger(active) {
+  if (existsSync(active.previousLedger)
+    && statSync(active.previousLedger).size > LIFECYCLE_LEDGER_MAX_BYTES) {
+    writeFileSync(active.previousLedger, '', { mode: 0o600 });
+  }
+}
+
+function appendEntry(active, entry) {
+  const line = `${JSON.stringify(entry)}\n`;
+  if (Buffer.byteLength(line) > LIFECYCLE_LEDGER_MAX_BYTES) return false;
+  try {
+    return withFileLockSync(active.lock, () => {
+      boundPreviousLedger(active);
+      if (existsSync(active.ledger)
+        && statSync(active.ledger).size + Buffer.byteLength(line) > LIFECYCLE_LEDGER_MAX_BYTES) {
+        rotateLedger(active);
+      }
+      const fd = openSync(active.ledger, 'a', 0o600);
+      try {
+        writeSync(fd, line, null, 'utf8');
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      return statSync(active.ledger).size <= LIFECYCLE_LEDGER_MAX_BYTES;
+    }, {
+      timeoutMs: LEDGER_LOCK_TIMEOUT_MS,
+      staleMs: LEDGER_LOCK_STALE_MS,
+    });
+  } catch {
+    return false;
+  }
+}
+
+function currentProcessIdentity() {
+  return processIdentityForPid(process.pid);
+}
+
+function processIdentityForPid(pid) {
+  if (process.platform === 'linux') {
+    try {
+      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const fields = raw.slice(raw.lastIndexOf(') ') + 2).trim().split(/\s+/);
+      return fields[19] && /^\d+$/.test(fields[19])
+        ? { kind: 'linux-start-ticks', value: fields[19] }
+        : null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('powershell.exe', [
+        '-NoProfile', '-NonInteractive', '-Command',
+        `([DateTimeOffset](Get-Process -Id ${pid} -ErrorAction Stop).StartTime).ToUnixTimeSeconds()`,
+      ], { encoding: 'utf8', timeout: 2000, windowsHide: true });
+      const text = String(out).trim();
+      const value = /^\d+$/.test(text) ? Number(text) : NaN;
+      return Number.isSafeInteger(value) ? { kind: 'start-seconds', value } : null;
+    }
+    const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+      encoding: 'utf8',
+      timeout: 2000,
+      windowsHide: true,
+    });
+    const value = Math.floor(Date.parse(String(out).trim()) / 1000);
+    return Number.isInteger(value) ? { kind: 'start-seconds', value } : null;
+  } catch {
+    return null;
+  }
+}
+
+function sameProcessIdentity(expected, observed) {
+  if (!expected || !observed || expected.kind !== observed.kind) return null;
+  if (expected.kind === 'linux-start-ticks') {
+    if (!/^\d+$/.test(String(expected.value)) || !/^\d+$/.test(String(observed.value))) return null;
+    if (BigInt(expected.value) < 1n || BigInt(observed.value) < 1n) return null;
+    return String(expected.value) === String(observed.value);
+  }
+  if (expected.kind === 'start-seconds') {
+    if (!Number.isSafeInteger(expected.value) || expected.value < 1
+      || !Number.isSafeInteger(observed.value) || observed.value < 1) return null;
+    return expected.value === observed.value;
+  }
+  return null;
+}
+
+function recordCurrent(reason, exitCode = null) {
+  const active = sharedState().active;
+  if (!active || !VALID_REASONS.has(reason)) return false;
+  return appendEntry(active, {
+    version: 1,
+    timestamp: new Date().toISOString(),
+    pid: process.pid,
+    ppid: process.ppid,
+    reason,
+    exitCode: Number.isInteger(exitCode) ? exitCode : null,
+    memory: memoryCounters(),
+    cwd: active.cwd,
+  });
+}
+
+function recordPriorVanished(active, previous) {
+  return appendEntry(active, {
+    version: 1,
+    timestamp: new Date().toISOString(),
+    pid: previous.pid,
+    ppid: Number.isInteger(previous.ppid) ? previous.ppid : null,
+    reason: 'prior-process-vanished',
+    exitCode: null,
+  });
+}
+
+function pidLiveness(pid) {
+  if (!Number.isInteger(pid) || pid < 1 || pid > 2147483647) return 'unknown';
+  try {
+    process.kill(pid, 0);
+    return 'occupied';
+  } catch (error) {
+    if (error?.code === 'ESRCH') return 'dead';
+    if (error?.code === 'EPERM') return 'occupied';
+    return 'unknown';
+  }
+}
+
+function markerOwned(active) {
+  try {
+    const marker = JSON.parse(readFileSync(active.markerPath, 'utf8'));
+    return marker?.pid === process.pid && marker?.token === active.token;
+  } catch {
+    return false;
+  }
+}
+
+function writeMarker(active) {
+  try {
+    mkdirSync(active.markerDir, { recursive: true, mode: 0o700 });
+    writeFileSync(active.markerPath, `${JSON.stringify({
+      version: 1,
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      ppid: process.ppid,
+      token: active.token,
+      processIdentity: active.processIdentity,
+    })}\n`, { encoding: 'utf8', mode: 0o600 });
+    const fd = openSync(active.markerPath, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function reapVanishedMarkers(active) {
+  const candidates = [];
+  try {
+    for (const entry of readdirSync(active.markerDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.json')) {
+        candidates.push(join(active.markerDir, entry.name));
+      }
+    }
+  } catch {}
+  if (existsSync(active.legacyMarker)) candidates.push(active.legacyMarker);
+  for (const markerPath of candidates) {
+    try {
+      const previous = JSON.parse(readFileSync(markerPath, 'utf8'));
+      const liveness = pidLiveness(previous?.pid);
+      let vanished = liveness === 'dead';
+      if (liveness === 'occupied') {
+        const identityMatch = sameProcessIdentity(
+          previous.processIdentity,
+          processIdentityForPid(previous.pid),
+        );
+        vanished = identityMatch === false;
+      }
+      if (!vanished) continue;
+      if (recordPriorVanished(active, previous)) unlinkSync(markerPath);
+    } catch {}
+  }
+}
+
+function configureNodeReports(reportPath, safeCommandLine) {
+  const report = process.report;
+  if (!report || !safeCommandLine || !('excludeEnv' in report)) return false;
+  try {
+    report.directory = '';
+    report.filename = reportPath;
+    report.compact = true;
+    report.excludeEnv = true;
+    if ('excludeNetwork' in report) report.excludeNetwork = true;
+    report.reportOnFatalError = true;
+    report.reportOnUncaughtException = true;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function beginProcessLifecycle({
+  directory,
+  configureReports = true,
+  safeCommandLine = process.argv.length <= 2,
+} = {}) {
+  const state = sharedState();
+  if (state.active) return state.active.api;
+  const resolved = paths(directory);
+  try {
+    mkdirSync(resolved.dir, { recursive: true, mode: 0o700 });
+    mkdirSync(resolved.markerDir, { recursive: true, mode: 0o700 });
+  } catch {}
+  const token = `${Date.now().toString(36)}-${process.hrtime.bigint().toString(36)}`;
+  const active = {
+    ...resolved,
+    token,
+    processIdentity: currentProcessIdentity(),
+    markerPath: join(resolved.markerDir, `${process.pid}-${token}.json`),
+    cwd: (() => { try { return process.cwd(); } catch { return null; } })(),
+  };
+  state.active = active;
+
+  reapVanishedMarkers(active);
+  writeMarker(active);
+  recordCurrent('process-start');
+  if (configureReports && safeCommandLine) {
+    try { unlinkSync(`${active.report}.1`); } catch {}
+    try { renameSync(active.report, `${active.report}.1`); } catch {}
+  }
+  const reportsEnabled = configureReports && configureNodeReports(active.report, safeCommandLine);
+  active.api = {
+    directory: active.dir,
+    ledgerPath: active.ledger,
+    markerDir: active.markerDir,
+    markerPath: active.markerPath,
+    reportPath: reportsEnabled ? active.report : null,
+  };
+  return active.api;
+}
+
+export function recordCatchableFatal(exitCode = 1) {
+  const active = sharedState().active;
+  if (active) {
+    const next = strongerReason(active.finalReason, 'catchable-fatal-error');
+    if (next !== active.finalReason || !Number.isInteger(active.finalExitCode)) {
+      active.finalExitCode = exitCode;
+    }
+    active.finalReason = next;
+  }
+  return recordCurrent('catchable-fatal-error', exitCode);
+}
+
+function strongerReason(current, candidate) {
+  const rank = { 'clean-shutdown': 0, 'catchable-fatal-error': 1, 'forced-cleanup': 2 };
+  return (rank[candidate] ?? 0) > (rank[current] ?? -1) ? candidate : current;
+}
+
+export function finishProcessLifecycle(reason = 'clean-shutdown', exitCode = 0) {
+  const state = sharedState();
+  const active = state.active;
+  if (!active) return false;
+  const finalReason = VALID_REASONS.has(reason) ? reason : 'clean-shutdown';
+  const nextReason = strongerReason(active.finalReason, finalReason);
+  if (nextReason !== active.finalReason || !Number.isInteger(active.finalExitCode)) {
+    active.finalExitCode = exitCode;
+  }
+  active.finalReason = nextReason;
+  const written = recordCurrent(active.finalReason, active.finalExitCode);
+  if (!written) return false;
+  if (markerOwned(active)) {
+    try { unlinkSync(active.markerPath); } catch { return false; }
+  }
+  state.active = null;
+  return true;
+}
+
+export function lifecyclePathsForTest(directory) {
+  return paths(directory);
+}

package/src/runtime/shared/process-shutdown.mjs

@@ -1,5 +1,10 @@
 'use strict';
 
+import {
+  finishProcessLifecycle,
+  recordCatchableFatal,
+} from './process-lifecycle.mjs';
+
 const SIGNAL_EXIT_CODES = {
   SIGINT: 130,
   SIGTERM: 143,
@@ -27,7 +32,6 @@ export function waitWithTimeout(promise, timeoutMs, label = 'cleanup') {
       settled = true;
       reject(new Error(`${label} timed out after ${ms}ms`));
     }, ms);
-    if (typeof timer.unref === 'function') timer.unref();
     Promise.resolve(promise)
       .then((value) => {
         if (settled) return;
@@ -67,6 +71,7 @@ export function installProcessSignalCleanup({
   };
 
   const hardExit = (code) => {
+    finishProcessLifecycle('forced-cleanup', code);
     try { process.exit(code); } catch {}
   };
 
@@ -81,6 +86,9 @@ export function installProcessSignalCleanup({
     }
     running = true;
     removeHandlers();
+    let cleanupFailed = false;
+
+    if (error) recordCatchableFatal(code);
 
     if (shouldExit) {
       hardExitTimer = setTimeout(() => hardExit(code), Math.max(1000, Number(timeoutMs) + 1000));
@@ -91,21 +99,36 @@ export function installProcessSignalCleanup({
       log(`[${name}] ${reason}: ${errorText(error)}`);
     }
 
-    try { beforeCleanup?.(reason, { code, error }); } catch {}
+    try { globalThis.__mixdogShutdownProviderAdmission?.(reason); } catch {}
+    try { globalThis.__mixdogDrainProviderConnections?.(reason); } catch {}
+    try { beforeCleanup?.(reason, { code, error }); } catch (cleanupError) {
+      cleanupFailed = true;
+      if (typeof log === 'function') log(`[${name}] cleanup failed: ${errorText(cleanupError)}`);
+    }
     try {
       if (typeof cleanup === 'function') {
         await waitWithTimeout(cleanup(reason, { code, error }), timeoutMs, `${name} shutdown`);
       }
     } catch (cleanupError) {
+      cleanupFailed = true;
+      if (typeof log === 'function') log(`[${name}] cleanup failed: ${errorText(cleanupError)}`);
+    }
+    try { afterCleanup?.(reason, { code, error }); } catch (cleanupError) {
+      cleanupFailed = true;
       if (typeof log === 'function') log(`[${name}] cleanup failed: ${errorText(cleanupError)}`);
     }
-    try { afterCleanup?.(reason, { code, error }); } catch {}
     if (hardExitTimer) {
       clearTimeout(hardExitTimer);
       hardExitTimer = null;
     }
     running = false;
-    if (shouldExit) hardExit(code);
+    if (shouldExit) {
+      finishProcessLifecycle(
+        cleanupFailed ? 'forced-cleanup' : error ? 'catchable-fatal-error' : 'clean-shutdown',
+        code,
+      );
+      try { process.exit(code); } catch {}
+    }
     return true;
   };