@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/managed-spawn.js

@@ -24,6 +24,7 @@ const https = require('https');
 const { spawn, exec } = require('child_process');
 const shared = require('./shared');
 const queries = require('./queries');
+const processUtils = require('./process-utils');
 
 const { log, ENGINE_DEFAULTS } = shared;
 
@@ -38,6 +39,24 @@ const HEALTHCHECK_TYPES = ['http', 'command'];
 // no leading/trailing hyphen. Mirrors the spawn-name conventions used elsewhere
 // in the codebase (worktree-pool, dispatch IDs).
 const _KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MANAGED_LOG_TAIL_DEFAULT_BYTES = 64 * 1024;
+const MANAGED_LOG_TAIL_MAX_BYTES = 1024 * 1024;
+const MANAGED_RESERVATION_TTL_MS = 60 * 1000;
+
+function validateManagedSpecName(name) {
+  const limits = ENGINE_DEFAULTS.managedSpawn || {};
+  const maxLength = Math.max(8, Number(limits.maxNameLength) || 64);
+  if (typeof name !== 'string' || name.length === 0) {
+    return { ok: false, reason: 'name-missing', maxLength };
+  }
+  if (name.length > maxLength) {
+    return { ok: false, reason: 'name-too-long (>' + maxLength + ')', maxLength };
+  }
+  if (!_KEBAB_RE.test(name)) {
+    return { ok: false, reason: 'name-not-kebab-case (' + name + ')', maxLength };
+  }
+  return { ok: true, value: name, maxLength };
+}
 
 function _agentsDir() {
   return queries.AGENTS_DIR || path.join(shared.MINIONS_DIR, 'agents');
@@ -260,16 +279,8 @@ function _validateSpec(spec, index, limits, opts) {
   }
 
   // name
-  if (typeof spec.name !== 'string' || spec.name.length === 0) {
-    return { ok: false, reason: 'name-missing' };
-  }
-  const maxName = Math.max(8, Number(limits.maxNameLength) || 64);
-  if (spec.name.length > maxName) {
-    return { ok: false, reason: 'name-too-long (>' + maxName + ')' };
-  }
-  if (!_KEBAB_RE.test(spec.name)) {
-    return { ok: false, reason: 'name-not-kebab-case (' + spec.name + ')' };
-  }
+  const nameValidation = validateManagedSpecName(spec.name);
+  if (!nameValidation.ok) return nameValidation;
 
   // cmd
   if (typeof spec.cmd !== 'string' || spec.cmd.length === 0) {
@@ -531,22 +542,59 @@ function readManagedSpawnFile(agentId, opts) {
 
 // Pure engine-side acceptance helper. Mirrors evaluateKeepPidsAcceptance:
 // returns a structured summary the engine close handler uses to decide
-// whether to (a) silently accept (no file present, or valid), (b) reject as
-// workdir-invalid → fail dispatch + inbox alert + unlink sidecar, or
-// (c) reject as schema-invalid → fail dispatch + inbox alert + unlink.
+// whether to (a) accept a valid record, (b) reject a required missing file,
+// (c) reject as workdir-invalid, or (d) reject as schema/identity-invalid.
 // No side effects; caller owns kill + unlink + WI mutation.
 function evaluateManagedSpawnAcceptance(agentId, opts) {
   opts = opts || {};
   const filePath = path.join(_agentsDir(), String(agentId || ''), MANAGED_SPAWN_FILENAME);
   if (!fs.existsSync(filePath)) {
-    return { exists: false, accepted: false, isWorkdirRejection: false, reason: null, record: null, filePath: filePath };
+    return {
+      exists: false,
+      accepted: false,
+      isWorkdirRejection: false,
+      reason: opts.required ? 'sidecar-missing' : null,
+      record: null,
+      filePath: filePath,
+    };
   }
   const rec = readManagedSpawnFile(agentId, opts);
   if (!rec) {
     // Race: file existed in existsSync above but was unlinked before read.
-    return { exists: false, accepted: false, isWorkdirRejection: false, reason: null, record: null, filePath: filePath };
+    return {
+      exists: false,
+      accepted: false,
+      isWorkdirRejection: false,
+      reason: opts.required ? 'sidecar-missing' : null,
+      record: null,
+      filePath: filePath,
+    };
   }
   if (rec.valid) {
+    const expectedAgentId = typeof opts.expectedAgentId === 'string' ? opts.expectedAgentId : '';
+    if (expectedAgentId && rec.value.written_by !== expectedAgentId) {
+      return {
+        exists: true,
+        accepted: false,
+        isWorkdirRejection: false,
+        reason: `written-by-mismatch (expected ${expectedAgentId}, got ${rec.value.written_by || 'missing'})`,
+        record: null,
+        filePath: rec.filePath,
+        parsedRaw: rec.parsed || null,
+      };
+    }
+    const expectedWorkItemId = typeof opts.expectedWorkItemId === 'string' ? opts.expectedWorkItemId : '';
+    if (expectedWorkItemId && rec.value.wi_id !== expectedWorkItemId) {
+      return {
+        exists: true,
+        accepted: false,
+        isWorkdirRejection: false,
+        reason: `wi-id-mismatch (expected ${expectedWorkItemId}, got ${rec.value.wi_id || 'missing'})`,
+        record: null,
+        filePath: rec.filePath,
+        parsedRaw: rec.parsed || null,
+      };
+    }
     return {
       exists: true,
       accepted: true,
@@ -805,7 +853,7 @@ function _getLogsDir() {
 }
 
 function openManagedLog(name) {
-  if (typeof name !== 'string' || name.length === 0 || !_KEBAB_RE.test(name)) {
+  if (!validateManagedSpecName(name).ok) {
     throw new Error('openManagedLog: name must be a non-empty kebab-case string');
   }
   // P-8a4d6f29 — rotate-on-open is centralised in shared.openAppendLogFd so
@@ -983,43 +1031,234 @@ function recordManagedSpec(spec, runtime, ctx) {
     }
     const idx = data.specs.findIndex(s => s && s.name === spec.name);
     const rec = _toStateRecord(spec, runtime, ctx);
+    if (idx >= 0 && (data.specs[idx]._restart_token || data.specs[idx]._spawn_token)) {
+      throw new Error(`recordManagedSpec: reservation active for ${spec.name}`);
+    }
     if (idx >= 0) data.specs[idx] = rec;
     else data.specs.push(rec);
     return data;
   }, { defaultValue: _initialStateShape() });
 }
 
+function reserveManagedBatch(specs, ctx) {
+  if (!Array.isArray(specs) || specs.length === 0) return [];
+  const names = specs.map(spec => spec && spec.name);
+  if (names.some(name => !validateManagedSpecName(name).ok)
+      || new Set(names).size !== names.length) {
+    throw new Error('reserveManagedBatch: specs require unique valid names');
+  }
+  const reservations = specs.map((spec) => {
+    const token = 'spawn-' + shared.uid();
+    const record = _toStateRecord(spec, {
+      pid: null,
+      started_at: Date.now(),
+      log_path: '',
+    }, ctx);
+    record.alive = false;
+    record._spawn_token = token;
+    record._reservation_expires_at = Date.now() + MANAGED_RESERVATION_TTL_MS;
+    return { name: spec.name, token, record };
+  });
+  shared.mutateManagedProcesses((data) => {
+    if (!data || !Array.isArray(data.specs)) data = _initialStateShape();
+    const existingNames = new Set(data.specs.map(item => item && item.name).filter(Boolean));
+    const conflict = reservations.find(reservation => existingNames.has(reservation.name));
+    if (conflict) {
+      const error = new Error(`reserveManagedBatch: name already active: ${conflict.name}`);
+      error.statusCode = 409;
+      error.code = 'managed-process-generation-changed';
+      throw error;
+    }
+    data.specs.push(...reservations.map(reservation => reservation.record));
+    return data;
+  }, { defaultValue: _initialStateShape() });
+  return reservations.map(({ name, token }) => ({ name, token }));
+}
+
+function releaseManagedReservations(reservations) {
+  if (!Array.isArray(reservations) || reservations.length === 0) return 0;
+  const tokens = new Map(reservations.map(item => [item && item.name, item && item.token]));
+  let released = 0;
+  shared.mutateManagedProcesses((data) => {
+    if (!data || !Array.isArray(data.specs)) return data;
+    data.specs = data.specs.filter((record) => {
+      const token = tokens.get(record && record.name);
+      const remove = !!token && record._spawn_token === token;
+      if (remove) released += 1;
+      return !remove;
+    });
+    return data;
+  }, { defaultValue: _initialStateShape() });
+  return released;
+}
+
 function recordManagedBatch(items, ctx) {
   if (!Array.isArray(items) || items.length === 0) return;
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
     }
+    const writes = [];
     for (const entry of items) {
       const spec = entry && entry.spec;
       const runtime = entry && entry.runtime;
       if (!spec || !spec.name) continue;
       const idx = data.specs.findIndex(s => s && s.name === spec.name);
       const rec = _toStateRecord(spec, runtime, ctx);
-      if (idx >= 0) data.specs[idx] = rec;
-      else data.specs.push(rec);
+      if (entry.reservationToken) {
+        if (idx < 0 || data.specs[idx]._spawn_token !== entry.reservationToken) {
+          throw new Error(`recordManagedBatch: reservation changed for ${spec.name}`);
+        }
+      } else if (idx >= 0 && (data.specs[idx]._restart_token || data.specs[idx]._spawn_token)) {
+        throw new Error(`recordManagedBatch: reservation active for ${spec.name}`);
+      }
+      writes.push({ idx, rec });
+    }
+    for (const write of writes) {
+      if (write.idx >= 0) data.specs[write.idx] = write.rec;
+      else data.specs.push(write.rec);
     }
     return data;
   }, { defaultValue: _initialStateShape() });
 }
 
-function removeManagedSpec(name) {
-  if (typeof name !== 'string' || name.length === 0) return;
-  let killPid = null;
+function _managedStartedAtMs(record) {
+  const numeric = Number(record && record.started_at);
+  return Number.isFinite(numeric) ? numeric : Date.parse(record && record.started_at);
+}
+
+function managedGenerationMatches(record, expected) {
+  if (!record || !expected) return false;
+  const recordStartedAt = _managedStartedAtMs(record);
+  const expectedStartedAt = _managedStartedAtMs(expected);
+  return record.pid === expected.pid
+    && Number.isFinite(recordStartedAt)
+    && recordStartedAt === expectedStartedAt;
+}
+
+function _restoreManagedRecord(record, options = {}) {
+  let restored = false;
+  shared.mutateManagedProcesses((data) => {
+    if (!data || !Array.isArray(data.specs)) data = _initialStateShape();
+    if (!data.specs.some(item => item && item.name === record.name)) {
+      data.specs.push(JSON.parse(JSON.stringify(record)));
+      restored = true;
+    } else if (options.trackCollision === true) {
+      const cleanup = JSON.parse(JSON.stringify(record));
+      cleanup.attrs = {
+        ...cleanup.attrs,
+        cleanup_original_name: cleanup.name,
+      };
+      cleanup.name = 'cleanup-' + shared.uid();
+      cleanup.healthy = false;
+      cleanup.ttl_expires_at = Date.now();
+      cleanup._cleanup_reason = options.reason || 'managed kill retry';
+      data.specs.push(cleanup);
+      restored = true;
+    }
+    return data;
+  }, { defaultValue: _initialStateShape() });
+  return restored;
+}
+
+function reapOrTrackManagedRuntime(spec, runtime, ctx, options = {}) {
+  const pid = runtime && runtime.pid;
+  // Base the reaped/tracked decision on killImmediate's authoritative result,
+  // not a racy synchronous liveness probe. killImmediate returns true once the
+  // SIGKILL / taskkill was delivered to the whole process tree; on Unix the
+  // just-killed process can linger for a few microseconds in a dying ('R') or
+  // unreaped zombie ('Z') state before the kernel tears it down, so a single
+  // isPidAlive() immediately after the kill can still read it as alive (Windows
+  // taskkill /F /T blocks until termination, which is why this only bit the
+  // Linux CI). Mirror removeManagedSpec: trust a confirmed kill and only fall
+  // back to a liveness re-check + sweep-retry tracking when the kill itself
+  // FAILED (or there was no pid to kill).
+  let killed = false;
+  if (Number.isInteger(pid) && pid > 0) {
+    try { killed = shared.killImmediate({ pid }) !== false; }
+    catch (_e) { killed = false; }
+  }
+  if (killed || !shared.isPidAlive(pid)) return { reaped: true, tracked: false };
+
+  const record = _toStateRecord(spec, runtime, ctx);
+  record.healthy = false;
+  record.ttl_expires_at = Date.now();
+  record._cleanup_reason = options.reason || 'managed runtime cleanup retry';
+  let tracked = false;
+  shared.mutateManagedProcesses((data) => {
+    if (!data || !Array.isArray(data.specs)) data = _initialStateShape();
+    const reservationIndex = options.reservationField && options.reservationToken
+      ? data.specs.findIndex(item => (
+        item
+        && item.name === spec.name
+        && item[options.reservationField] === options.reservationToken
+      ))
+      : -1;
+    if (reservationIndex >= 0) {
+      data.specs[reservationIndex] = record;
+      tracked = true;
+      return data;
+    }
+    if (!data.specs.some(item => item && item.name === record.name)) {
+      data.specs.push(record);
+      tracked = true;
+      return data;
+    }
+    record.attrs = {
+      ...record.attrs,
+      cleanup_original_name: record.name,
+    };
+    record.name = 'cleanup-' + shared.uid();
+    data.specs.push(record);
+    tracked = true;
+    return data;
+  }, { defaultValue: _initialStateShape() });
+  return { reaped: false, tracked };
+}
+
+function removeManagedSpec(name, opts = {}) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return { removed: false, reason: 'invalid-name' };
+  }
+  const candidate = getManagedSpecByName(name);
+  if (!candidate) return { removed: false, reason: 'not-found' };
+  const expected = opts.expected || candidate;
+  if (!managedGenerationMatches(candidate, expected)) {
+    return { removed: false, reason: 'generation-changed' };
+  }
+  const killPid = Number.isInteger(candidate.pid) && candidate.pid > 0 ? candidate.pid : null;
+  const verifyIdentity = opts.verifyIdentity === true;
+  const getIdentity = typeof opts.getProcessIdentity === 'function'
+    ? opts.getProcessIdentity
+    : processUtils.getProcessIdentity;
+  const wasAlive = killPid !== null && shared.isPidAlive(killPid);
+  let identityBefore = null;
+  if (verifyIdentity && wasAlive) {
+    identityBefore = getIdentity(killPid);
+    if (!identityBefore) return { removed: false, reason: 'identity-unavailable' };
+    if (!processUtils.isProcessIdentityCompatible(identityBefore, _managedStartedAtMs(candidate))) {
+      return { removed: false, reason: 'identity-mismatch' };
+    }
+  }
+
+  let removedRecord = null;
+  let conflict = false;
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const idx = data.specs.findIndex(s => s && s.name === name);
     if (idx < 0) return data;
     const rec = data.specs[idx];
-    if (rec && Number.isInteger(rec.pid) && rec.pid > 0) killPid = rec.pid;
+    if (!managedGenerationMatches(rec, expected)) {
+      conflict = true;
+      return data;
+    }
+    removedRecord = JSON.parse(JSON.stringify(rec));
     data.specs.splice(idx, 1);
     return data;
   }, { defaultValue: _initialStateShape() });
+  if (conflict) return { removed: false, reason: 'generation-changed' };
+  if (!removedRecord) return { removed: false, reason: 'not-found' };
+
   // Kill OUTSIDE the lock — never run process ops inside a lock callback
   // (copilot-instructions.md "Keep lock callbacks synchronous and fast").
   // Use killImmediate (full process-tree kill: `taskkill /PID <pid> /F /T` on
@@ -1028,10 +1267,28 @@ function removeManagedSpec(name) {
   // launcher-style processes (e.g. Android emulator.exe spawning a detached
   // qemu-system-x86_64 child) whose descendants survive a single-PID kill and
   // leak indefinitely (opg-microsoft/minions#710).
-  if (killPid != null) {
-    try { shared.killImmediate({ pid: killPid }); }
-    catch (e) { log('warn', 'managed-spawn removeManagedSpec: kill ' + killPid + ' failed: ' + e.message); }
+  let killed = false;
+  if (killPid !== null && (!verifyIdentity || wasAlive)) {
+    if (verifyIdentity) {
+      const identityAfter = getIdentity(killPid);
+      if (!processUtils.isSameProcessIdentity(identityBefore, identityAfter)) {
+        _restoreManagedRecord(removedRecord);
+        return { removed: false, reason: 'identity-changed' };
+      }
+    }
+    try { killed = shared.killImmediate({ pid: killPid }) !== false; }
+    catch (e) {
+      log('warn', 'managed-spawn removeManagedSpec: kill ' + killPid + ' failed: ' + e.message);
+    }
+    if (!killed && shared.isPidAlive(killPid)) {
+      _restoreManagedRecord(removedRecord, {
+        trackCollision: true,
+        reason: 'managed kill failed',
+      });
+      return { removed: false, reason: 'kill-failed' };
+    }
   }
+  return { removed: true, record: removedRecord, killed };
 }
 
 function listManagedSpecs(opts) {
@@ -1042,6 +1299,11 @@ function listManagedSpecs(opts) {
   return specs.slice();
 }
 
+function getManagedSpecByName(name) {
+  if (typeof name !== 'string' || !name) return null;
+  return listManagedSpecs().find(spec => spec && spec.name === name) || null;
+}
+
 // ─── Item 3 (P-9c1f47a6) ─────────────────────────────────────────────────────
 //
 // Healthcheck implementations + dispatch SUCCESS/ERROR gate.
@@ -1156,19 +1418,24 @@ async function runHealthcheck(spec) {
 // Flip state.healthy=true + last_health_at on a single locked write. Used by
 // waitForFirstHealth on the first pass. Callers MUST be outside any other
 // lock — this acquires its own.
-function _markHealthy(name, now) {
+function _markHealthy(name, now, expectedGeneration) {
+  let marked = false;
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
-    if (!rec) return data;
+    if (!rec || !managedGenerationMatches(rec, expectedGeneration)) return data;
     rec.healthy = true;
     rec.last_health_at = now;
+    marked = true;
     return data;
   }, { defaultValue: _initialStateShape() });
+  return marked;
 }
 
 function waitForFirstHealth(spec, opts) {
   opts = opts || {};
+  const expectedGeneration = opts.expectedGeneration
+    || (spec && spec.pid && spec.started_at ? spec : getManagedSpecByName(spec && spec.name));
   const intervalMs = Math.max(100, (Number(spec.healthcheck && spec.healthcheck.interval_s) || 1) * 1000);
   const timeoutMs = Math.max(intervalMs, (Number(spec.healthcheck && spec.healthcheck.timeout_s) || 30) * 1000);
   const deadline = Date.now() + timeoutMs;
@@ -1230,8 +1497,25 @@ function waitForFirstHealth(spec, opts) {
       }
       if (stopped) return;
       if (result.healthy) {
-        try { _markHealthy(spec.name, result.lastCheckAt); }
-        catch (e) { log('warn', 'managed-spawn waitForFirstHealth: state write failed for ' + spec.name + ': ' + e.message); }
+        let marked = false;
+        try { marked = _markHealthy(spec.name, result.lastCheckAt, expectedGeneration); }
+        catch (e) {
+          log('warn', 'managed-spawn waitForFirstHealth: state write failed for ' + spec.name + ': ' + e.message);
+          if (expectedGeneration) {
+            return finish({
+              healthy: false,
+              error: 'generation state write failed: ' + e.message,
+              lastCheckAt: result.lastCheckAt,
+            });
+          }
+        }
+        if (expectedGeneration && !marked) {
+          return finish({
+            healthy: false,
+            error: 'generation changed before first-health state update',
+            lastCheckAt: result.lastCheckAt,
+          });
+        }
         return finish({ healthy: true, error: null, lastCheckAt: result.lastCheckAt });
       }
       lastError = result.error;
@@ -1445,8 +1729,8 @@ function validateManagedSpecExecutionContext(record, opts) {
   return { ok: true, project, mode };
 }
 
-function restartManagedSpec(name, opts) {
-  if (typeof name !== 'string' || name.length === 0) {
+function restartManagedSpec(name, opts = {}) {
+  if (!validateManagedSpecName(name).ok) {
     throw new Error('restartManagedSpec: name required');
   }
   const existing = listManagedSpecs().find(s => s && s.name === name);
@@ -1455,8 +1739,17 @@ function restartManagedSpec(name, opts) {
   }
   const executionContext = validateManagedSpecExecutionContext(existing, opts);
   if (!executionContext.ok) {
-    try { removeManagedSpec(name); } catch {}
-    throw new Error('restartManagedSpec: unsafe persisted execution context (' + executionContext.reason + ')');
+    removeManagedSpec(name, {
+      expected: opts.expected || existing,
+      verifyIdentity: opts.verifyIdentity !== false,
+      getProcessIdentity: opts.getProcessIdentity,
+    });
+    const error = new Error(
+      'restartManagedSpec: unsafe persisted execution context (' + executionContext.reason + ')',
+    );
+    error.statusCode = 409;
+    error.code = 'managed-process-unsafe-execution-context';
+    throw error;
   }
   // Reconstruct a sidecar-shaped spec from the persisted state row. The
   // state shape keeps cmd/args/cwd/env/ports/attrs/healthcheck verbatim
@@ -1472,13 +1765,16 @@ function restartManagedSpec(name, opts) {
     attrs: existing.attrs && typeof existing.attrs === 'object' ? existing.attrs : {},
     healthcheck: existing.healthcheck || null,
   };
-  // Kill the old PID before respawn (best-effort; outside of any lock).
-  // Full process-tree kill (see removeManagedSpec above) — a single-PID kill
-  // here would leave launcher descendants (e.g. qemu-system-x86_64 under an
-  // Android emulator.exe) running after "restart" respawns a fresh launcher.
-  if (Number.isInteger(existing.pid) && existing.pid > 0) {
-    try { shared.killImmediate({ pid: existing.pid }); }
-    catch (e) { log('warn', 'restartManagedSpec: kill of old PID ' + existing.pid + ' failed: ' + e.message); }
+  const removal = removeManagedSpec(name, {
+    expected: opts.expected || existing,
+    verifyIdentity: opts.verifyIdentity !== false,
+    getProcessIdentity: opts.getProcessIdentity,
+  });
+  if (!removal.removed) {
+    const error = new Error(`restartManagedSpec: ${removal.reason}: ${name}`);
+    error.statusCode = removal.reason === 'not-found' ? 404 : 409;
+    error.code = `managed-process-${removal.reason}`;
+    throw error;
   }
   const ctx = {
     owner_agent: existing.owner_agent || '',
@@ -1488,10 +1784,86 @@ function restartManagedSpec(name, opts) {
     dispatch_root: existing.dispatch_root || '',
     checkout_mode: existing.checkout_mode || '',
   };
-  const runtime = spawnManagedSpec(spec, ctx);
-  // recordManagedSpec replaces by name (item 2 idempotency contract) and
-  // resets healthy:false / alive:true / new started_at / new ttl_expires_at.
-  recordManagedSpec(spec, runtime, ctx);
+  const restartToken = 'restart-' + shared.uid();
+  const reservation = {
+    ...existing,
+    pid: null,
+    alive: false,
+    healthy: false,
+    last_health_at: null,
+    _restart_token: restartToken,
+    _reservation_expires_at: Date.now() + MANAGED_RESERVATION_TTL_MS,
+  };
+  let reserved = false;
+  shared.mutateManagedProcesses((data) => {
+    if (!data || !Array.isArray(data.specs)) data = _initialStateShape();
+    if (!data.specs.some(item => item && item.name === name)) {
+      data.specs.push(reservation);
+      reserved = true;
+    }
+    return data;
+  }, { defaultValue: _initialStateShape() });
+  if (!reserved) {
+    const error = new Error(`restartManagedSpec: generation-changed: ${name}`);
+    error.statusCode = 409;
+    error.code = 'managed-process-generation-changed';
+    throw error;
+  }
+
+  const clearReservation = () => {
+    shared.mutateManagedProcesses((data) => {
+      if (!data || !Array.isArray(data.specs)) return data;
+      data.specs = data.specs.filter(
+        item => !(item && item.name === name && item._restart_token === restartToken),
+      );
+      return data;
+    }, { defaultValue: _initialStateShape() });
+  };
+
+  let runtime;
+  try {
+    runtime = spawnManagedSpec(spec, ctx);
+  } catch (error) {
+    clearReservation();
+    throw error;
+  }
+  let recorded = false;
+  try {
+    shared.mutateManagedProcesses((data) => {
+      if (!data || !Array.isArray(data.specs)) data = _initialStateShape();
+      const index = data.specs.findIndex(
+        item => item && item.name === name && item._restart_token === restartToken,
+      );
+      if (index >= 0) {
+        data.specs[index] = _toStateRecord(spec, runtime, ctx);
+        recorded = true;
+      }
+      return data;
+    }, { defaultValue: _initialStateShape() });
+  } catch (error) {
+    try {
+      const cleanup = reapOrTrackManagedRuntime(spec, runtime, ctx, {
+        reservationField: '_restart_token',
+        reservationToken: restartToken,
+        reason: 'restart persistence failure',
+      });
+      if (cleanup.reaped) clearReservation();
+    } catch (cleanupError) {
+      error.cleanupError = cleanupError;
+    }
+    throw error;
+  }
+  if (!recorded) {
+    reapOrTrackManagedRuntime(spec, runtime, ctx, {
+      reservationField: '_restart_token',
+      reservationToken: restartToken,
+      reason: 'restart reservation replaced',
+    });
+    const error = new Error(`restartManagedSpec: generation-changed: ${name}`);
+    error.statusCode = 409;
+    error.code = 'managed-process-generation-changed';
+    throw error;
+  }
   log('info', 'managed-spawn restart: name=' + name + ' old_pid=' + existing.pid + ' new_pid=' + runtime.pid);
   return runtime;
 }
@@ -1583,6 +1955,7 @@ function _runManagedReconcile(opts) {
     malformed: 0,
   };
   const ttlPidsToKill = [];
+  const cleanupRetries = [];
   const survivors = []; // [{name, log_path}] post-mutation, used for log rotation + bootReconcile probes
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
@@ -1596,8 +1969,22 @@ function _runManagedReconcile(opts) {
         continue;
       }
       stats.scanned++;
+      if (rec._spawn_token || rec._restart_token) {
+        if (Number.isFinite(rec._reservation_expires_at)
+            && rec._reservation_expires_at > now) {
+          kept.push(rec);
+        } else {
+          stats.deadDropped++;
+        }
+        continue;
+      }
       const ttlExpired = Number.isFinite(rec.ttl_expires_at) && rec.ttl_expires_at <= now;
       const alive = Number.isInteger(rec.pid) && rec.pid > 0 && isAlive(rec.pid);
+      if (rec._cleanup_reason && alive) {
+        kept.push(rec);
+        cleanupRetries.push(rec);
+        continue;
+      }
       if (ttlExpired) {
         stats.ttlExpired++;
         if (alive) ttlPidsToKill.push(rec.pid);
@@ -1613,7 +2000,14 @@ function _runManagedReconcile(opts) {
         continue;
       }
       kept.push(rec);
-      survivors.push({ name: rec.name, log_path: rec.log_path || '', healthy: rec.healthy === true, last_health_at: rec.last_health_at || 0 });
+      survivors.push({
+        name: rec.name,
+        pid: rec.pid,
+        started_at: rec.started_at,
+        log_path: rec.log_path || '',
+        healthy: rec.healthy === true,
+        last_health_at: rec.last_health_at || 0,
+      });
     }
     data.specs = kept;
     return data;
@@ -1625,6 +2019,17 @@ function _runManagedReconcile(opts) {
     try { stats.killedPids = killBatch(ttlPidsToKill); }
     catch (e) { log('warn', 'managed-spawn sweep: kill batch failed: ' + e.message); }
   }
+  for (const rec of cleanupRetries) {
+    try {
+      const result = removeManagedSpec(rec.name, {
+        expected: rec,
+        verifyIdentity: true,
+      });
+      if (result.removed && result.killed) stats.killedPids += 1;
+    } catch (e) {
+      log('warn', 'managed-spawn cleanup retry failed for ' + rec.name + ': ' + e.message);
+    }
+  }
   for (const surv of survivors) {
     if (_rotateManagedLog(surv.log_path, rotateBytes)) stats.rotatedLogs++;
   }
@@ -1640,11 +2045,11 @@ function sweepManagedSpawn(opts) {
 // healthy=true→false would mask a real degradation — keep healthy sticky and
 // rely on the per-spec loop to refresh post-success, or item 7 boot reconcile
 // to (re)establish initial truth on engine restart).
-function _markBootProbe(name, result) {
+function _markBootProbe(name, result, expectedGeneration) {
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
-    if (!rec) return data;
+    if (!rec || !managedGenerationMatches(rec, expectedGeneration)) return data;
     if (result && result.healthy === true) {
       rec.healthy = true;
       rec.last_health_at = Number.isFinite(result.lastCheckAt) ? result.lastCheckAt : Date.now();
@@ -1677,7 +2082,7 @@ async function bootReconcileManagedSpawn(opts) {
     if (!rec || !rec.healthcheck) continue;
     try {
       const r = await runHealthcheck({ name: rec.name, healthcheck: rec.healthcheck });
-      try { _markBootProbe(rec.name, r); }
+      try { _markBootProbe(rec.name, r, rec); }
       catch (e) { log('warn', 'managed-spawn bootReconcile state write failed for ' + rec.name + ': ' + e.message); }
       probed.push({ name: rec.name, healthy: !!r.healthy });
     } catch (e) {
@@ -1729,6 +2134,9 @@ module.exports = {
   MANAGED_LOGS_DIR: MANAGED_LOGS_DIR,
   INVALID_WORKDIR_REASON_PREFIX: INVALID_WORKDIR_REASON_PREFIX,
   HEALTHCHECK_TYPES: HEALTHCHECK_TYPES,
+  MANAGED_LOG_TAIL_DEFAULT_BYTES: MANAGED_LOG_TAIL_DEFAULT_BYTES,
+  MANAGED_LOG_TAIL_MAX_BYTES: MANAGED_LOG_TAIL_MAX_BYTES,
+  validateManagedSpecName: validateManagedSpecName,
   validateManagedSpawnRecord: validateManagedSpawnRecord,
   readManagedSpawnFile: readManagedSpawnFile,
   evaluateManagedSpawnAcceptance: evaluateManagedSpawnAcceptance,
@@ -1737,12 +2145,19 @@ module.exports = {
   openManagedLog: openManagedLog,
   spawnManagedSpec: spawnManagedSpec,
   recordManagedSpec: recordManagedSpec,
+  reserveManagedBatch: reserveManagedBatch,
+  releaseManagedReservations: releaseManagedReservations,
   recordManagedBatch: recordManagedBatch,
+  managedGenerationMatches: managedGenerationMatches,
+  reapOrTrackManagedRuntime: reapOrTrackManagedRuntime,
   removeManagedSpec: removeManagedSpec,
   listManagedSpecs: listManagedSpecs,
+  getManagedSpecByName: getManagedSpecByName,
   // Item 3 (P-9c1f47a6): healthcheck implementations + first-pass waiter.
   runHealthcheck: runHealthcheck,
   waitForFirstHealth: waitForFirstHealth,
+  _markHealthy, // exported for testing
+  _markBootProbe, // exported for testing
   tailManagedLog: tailManagedLog,
   // Item 6 (P-1f9c3a45): playbook auto-inject of live managed processes.
   buildLiveManagedProcessesBlock: buildLiveManagedProcessesBlock,