@algosuite/vo-mcp 0.2.0-beta.56 → 0.2.0-beta.57

package/dist/runner-supervisor.js

@@ -31,7 +31,7 @@ var init_control_plane_auth_stub = __esm({
 
 // src/runner-supervisor.mjs
 import { spawn } from "node:child_process";
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { dirname as dirname4, join as join5 } from "node:path";
@@ -2090,6 +2090,7 @@ async function finishPendingActivation({
   packageVersion: packageVersion2,
   supervisorIdentity,
   waitForLocalRunner: waitForLocalRunner2,
+  isReadinessDeferred = () => false,
   localStatus: localStatus2,
   waitForCloudRunner = waitForAuthoritativeRunnerHeartbeat,
   cloudTimeoutMs,
@@ -2124,7 +2125,10 @@ async function finishPendingActivation({
   try {
     attestation = attestCurrentSupervisor({ runtimeRoot, selfPath: selfPath2, version: packageVersion2 });
     if (!attestation.ok) throw new Error(attestation.detail);
-    if (!await waitForLocalRunner2(child)) throw new Error("activated runner did not become locally ready");
+    if (!await waitForLocalRunner2(child)) {
+      if (isReadinessDeferred(child)) return false;
+      throw new Error("activated runner did not become locally ready");
+    }
   } catch (error) {
     let detail = `activation attestation failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 400);
     let rolledBack = null;
@@ -2318,8 +2322,97 @@ function resolveSupervisorChildEntry({
 import { hostname as systemHostname } from "node:os";
 
 // src/runner-readiness.mjs
-function failed({ paired = false, operatorId = null, tenantId = null, githubReady = null, error, message }) {
-  return { ok: false, paired, operatorId, tenantId, githubReady, error, message };
+import { createHash as createHash5, randomUUID as randomUUID3 } from "node:crypto";
+var RUNNER_GITHUB_READINESS_TIMEOUT_MS = 5e4;
+var RUNNER_IDENTITY_READINESS_TIMEOUT_MS = 1e4;
+var RUNNER_READINESS_MAX_REPOSITORIES = 4;
+var RUNNER_READINESS_TRANSIENT_MAX_RETRY_AFTER_MS = 3e5;
+var RUNNER_READINESS_DEFERRAL_MESSAGE_TYPE = "vo-runner-readiness-deferred-v1";
+var RUNNER_READINESS_DEFERRAL_ACK_TYPE = "vo-runner-readiness-deferred-ack-v1";
+var RUNNER_REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u;
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+function runnerRepositoryScopeFromEnv(env = {}) {
+  return String(env.VO_CODE_RUNNER_REPOS || "").split(/[\s,]+/u).map((repo) => repo.trim()).filter(Boolean);
+}
+function normalizeRunnerRepositoryScope(repositories) {
+  if (!Array.isArray(repositories) || repositories.length < 1) {
+    throw new Error("VO_CODE_RUNNER_REPOS must name at least one owner/name repository");
+  }
+  if (repositories.length > RUNNER_READINESS_MAX_REPOSITORIES) {
+    throw new Error(`VO_CODE_RUNNER_REPOS supports at most ${RUNNER_READINESS_MAX_REPOSITORIES} repositories`);
+  }
+  const normalized = repositories.map((repo) => {
+    const [owner, name] = typeof repo === "string" ? repo.split("/") : [];
+    if (typeof repo !== "string" || repo.length > 140 || !RUNNER_REPOSITORY.test(repo) || owner === "." || owner === ".." || name === "." || name === "..") {
+      throw new Error("VO_CODE_RUNNER_REPOS entries must be canonical owner/name repositories");
+    }
+    return repo.toLowerCase();
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error("VO_CODE_RUNNER_REPOS entries must be unique");
+  }
+  const owners = new Set(normalized.map((repo) => repo.split("/")[0]));
+  if (owners.size !== 1) {
+    throw new Error("VO_CODE_RUNNER_REPOS entries must share one owner");
+  }
+  return Object.freeze(normalized.sort());
+}
+function runnerRepositoryScopeDigest(repositories) {
+  const scope = normalizeRunnerRepositoryScope(repositories);
+  return createHash5("sha256").update(JSON.stringify({
+    version: 1,
+    repositories: scope
+  }), "utf8").digest("hex");
+}
+function runnerReadinessRetryDelayMs(readiness) {
+  if (readiness?.paired !== true || readiness?.githubReady !== false) return null;
+  if (Number.isFinite(readiness.retryAfterMs) && readiness.retryAfterMs > 0) {
+    return Math.ceil(readiness.retryAfterMs);
+  }
+  return null;
+}
+function parseRunnerReadinessDeferralRequest(message) {
+  if (message?.type !== RUNNER_READINESS_DEFERRAL_MESSAGE_TYPE || !UUID_RE2.test(String(message.nonce || "")) || !Number.isFinite(message.retryAfterMs) || message.retryAfterMs <= 0) return null;
+  return Object.freeze({
+    nonce: message.nonce,
+    retryAfterMs: Math.ceil(message.retryAfterMs),
+    error: typeof message.error === "string" ? message.error : null
+  });
+}
+function failed({
+  paired = false,
+  operatorId = null,
+  tenantId = null,
+  githubReady = null,
+  retryAfterMs = null,
+  error,
+  message
+}) {
+  return {
+    ok: false,
+    paired,
+    operatorId,
+    tenantId,
+    githubReady,
+    ...Number.isFinite(retryAfterMs) && retryAfterMs > 0 ? { retryAfterMs } : {},
+    error,
+    message
+  };
+}
+function responseRetryAfterMs(response, body) {
+  const transientReadinessFailure = response.status === 503 && body?.error === "github_installation_readiness_retryable";
+  if (response.status !== 429 && !transientReadinessFailure) return null;
+  const bound = (retryAfterMs) => transientReadinessFailure ? Math.min(RUNNER_READINESS_TRANSIENT_MAX_RETRY_AFTER_MS, retryAfterMs) : retryAfterMs;
+  const value = response.headers?.get?.("retry-after")?.trim() ?? "";
+  const seconds = Number(value);
+  if (value && Number.isFinite(seconds) && seconds >= 0) {
+    return bound(Math.max(1e3, Math.ceil(seconds * 1e3)));
+  }
+  const at = value ? Date.parse(value) : Number.NaN;
+  if (Number.isFinite(at)) {
+    return bound(Math.max(1e3, Math.ceil(at - Date.now())));
+  }
+  return bound(6e4);
 }
 async function responseBody(response) {
   try {
@@ -2332,11 +2425,21 @@ async function responseBody(response) {
 function serverMessage(body, fallback) {
   return typeof body.message === "string" && body.message.trim() ? body.message.trim() : fallback;
 }
-async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+async function fetchJsonWithTimeout(fetchImpl, url, init, timeoutMs) {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`request aborted after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
   try {
-    return await fetchImpl(url, { ...init, signal: controller.signal });
+    const requestAndBody = (async () => {
+      const response = await fetchImpl(url, { ...init, signal: controller.signal });
+      return { response, body: await responseBody(response) };
+    })();
+    return await Promise.race([requestAndBody, timeout]);
   } finally {
     clearTimeout(timer);
   }
@@ -2346,18 +2449,24 @@ async function probeRunnerReadiness({
   token,
   fetchImpl = fetch,
   requireGithub = false,
-  timeoutMs = 1e4
+  repositories = [],
+  timeoutMs = RUNNER_IDENTITY_READINESS_TIMEOUT_MS,
+  // The server performs at most five sequential App-JWT GETs (installation plus
+  // every one of at most four configured repositories), each bounded at 8s.
+  // Keep a transport margin while preventing a stuck proof from hanging startup.
+  githubTimeoutMs = RUNNER_GITHUB_READINESS_TIMEOUT_MS
 }) {
   const base = controlPlaneUrl.replace(/\/+$/u, "");
   const headers = { authorization: `Bearer ${token}` };
   let identityResponse;
+  let identity;
   try {
-    identityResponse = await fetchWithTimeout(
+    ({ response: identityResponse, body: identity } = await fetchJsonWithTimeout(
       fetchImpl,
       `${base}/api/v1/auth/me`,
       { headers },
       timeoutMs
-    );
+    ));
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     return failed({
@@ -2365,7 +2474,6 @@ async function probeRunnerReadiness({
       message: `AlgoHQ could not be reached: ${detail}`
     });
   }
-  const identity = await responseBody(identityResponse);
   if (!identityResponse.ok) {
     return failed({
       error: "credential_rejected",
@@ -2391,18 +2499,33 @@ async function probeRunnerReadiness({
       message: "Paired to AlgoHQ."
     };
   }
+  let repositoryScope = null;
+  try {
+    if (!Array.isArray(repositories)) {
+      throw new Error("VO_CODE_RUNNER_REPOS must be a repository array");
+    }
+    if (repositories.length > 0) repositoryScope = normalizeRunnerRepositoryScope(repositories);
+  } catch (error) {
+    return failed({
+      paired: true,
+      operatorId,
+      tenantId,
+      githubReady: false,
+      error: "github_repository_scope_invalid",
+      message: error instanceof Error ? error.message : String(error)
+    });
+  }
   let githubResponse;
+  let github;
   try {
-    githubResponse = await fetchWithTimeout(
+    const readinessUrl = new URL(`${base}/api/v1/github/installation-readiness`);
+    for (const repo of repositoryScope ?? []) readinessUrl.searchParams.append("repo", repo);
+    ({ response: githubResponse, body: github } = await fetchJsonWithTimeout(
       fetchImpl,
-      `${base}/api/v1/github/installation-token`,
-      {
-        method: "POST",
-        headers: { ...headers, "content-type": "application/json" },
-        body: "{}"
-      },
-      timeoutMs
-    );
+      readinessUrl.toString(),
+      { headers },
+      githubTimeoutMs
+    ));
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     return failed({
@@ -2414,14 +2537,25 @@ async function probeRunnerReadiness({
       message: `GitHub publication readiness could not be checked: ${detail}`
     });
   }
-  const github = await responseBody(githubResponse);
-  if (!githubResponse.ok || typeof github.token !== "string" || !github.token) {
+  const repositorySelection = github.repository_selection;
+  const repositoriesVerified = github.repositories_verified;
+  const returnedScope = github.repository_scope;
+  let normalizedReturnedScope = null;
+  try {
+    normalizedReturnedScope = normalizeRunnerRepositoryScope(returnedScope);
+  } catch {
+  }
+  const effectiveScope = repositoryScope ?? normalizedReturnedScope;
+  const sourceVerified = repositoryScope === null ? github.repository_scope_source === "persisted_installation_singleton" && normalizedReturnedScope?.length === 1 : github.repository_scope_source === "runner_config";
+  const repositoryScopeVerified = effectiveScope !== null && normalizedReturnedScope !== null && Array.isArray(returnedScope) && returnedScope.length === normalizedReturnedScope.length && returnedScope.every((repo, index) => repo === normalizedReturnedScope[index]) && normalizedReturnedScope.length === effectiveScope.length && normalizedReturnedScope.every((repo, index) => repo === effectiveScope[index]) && github.repository_scope_sha256 === runnerRepositoryScopeDigest(effectiveScope) && repositoriesVerified === effectiveScope.length && sourceVerified && (repositorySelection === "all" || repositorySelection === "selected");
+  if (!githubResponse.ok || github.configured !== true || github.verified !== true || github.publication_ready !== true || !repositoryScopeVerified) {
     const error = typeof github.error === "string" && github.error ? github.error : "github_not_ready";
     return failed({
       paired: true,
       operatorId,
       tenantId,
       githubReady: false,
+      retryAfterMs: responseRetryAfterMs(githubResponse, github),
       error,
       message: serverMessage(github, `GitHub publication preflight failed (HTTP ${githubResponse.status}).`)
     });
@@ -2432,8 +2566,10 @@ async function probeRunnerReadiness({
     operatorId,
     tenantId,
     githubReady: true,
+    repositoryScope: effectiveScope,
+    repositoryScopeSource: github.repository_scope_source,
     error: null,
-    message: "Paired and ready to publish through the Algosuite GitHub App."
+    message: `Paired with a verified Algosuite GitHub App installation (${repositoriesVerified} repos).`
   };
 }
 function pairedOperatorScope(readiness) {
@@ -2472,25 +2608,51 @@ async function prepareSupervisorAuth({
   const token = explicitAdminToken || storedCredential?.vo_credential;
   if (!token) throw new Error("runner is not paired; run `vo-mcp pair` once on this host");
   let operatorId = String(baseEnv.VO_CODE_RUNNER_OPERATOR_IDS || "").split(/[\s,]+/u).filter(Boolean)[0] || void 0;
+  let repositoryScope = runnerRepositoryScopeFromEnv(baseEnv);
+  let startupRetryAfterMs = null;
+  let githubReady = null;
+  let readinessError = null;
   if (!explicitAdminToken) {
-    const readiness = await probeReadiness({ controlPlaneUrl, token, requireGithub: true });
-    if (!readiness.ok) throw new Error(`runner readiness failed: ${readiness.message}`);
-    operatorId = pairedOperatorScope(readiness) || void 0;
+    const readiness = await probeReadiness({
+      controlPlaneUrl,
+      token,
+      requireGithub: true,
+      repositories: repositoryScope
+    });
+    const pairedScope = pairedOperatorScope(readiness) || (readiness?.paired === true && typeof readiness.operatorId === "string" ? readiness.operatorId.trim() : "");
+    operatorId = pairedScope || void 0;
     if (!operatorId) throw new Error("runner readiness failed: paired operator scope is missing");
+    if (readiness.ok && Array.isArray(readiness.repositoryScope)) {
+      repositoryScope = [...readiness.repositoryScope];
+      githubReady = true;
+    } else {
+      githubReady = false;
+      readinessError = typeof readiness?.error === "string" ? readiness.error : "github_not_ready";
+      startupRetryAfterMs = runnerReadinessRetryDelayMs(readiness);
+    }
   }
+  const effectiveBaseEnv = repositoryScope.length > 0 ? { ...baseEnv, VO_CODE_RUNNER_REPOS: repositoryScope.join(",") } : baseEnv;
   const childEnv = buildSupervisorChildEnv({
-    baseEnv,
+    baseEnv: effectiveBaseEnv,
     controlPlaneUrl,
     explicitAdminToken,
     pairedOperatorId: explicitAdminToken ? null : operatorId
   });
   const clientEnv = {
-    ...baseEnv,
+    ...effectiveBaseEnv,
     VO_CONTROL_PLANE_ADMIN_TOKEN: token,
     VO_CONTROL_PLANE_URL: controlPlaneUrl,
     ...operatorId ? { VO_CODE_RUNNER_OPERATOR_IDS: operatorId } : {}
   };
-  return { childEnv, clientEnv, operatorId };
+  return {
+    childEnv,
+    clientEnv,
+    operatorId,
+    repositoryScope,
+    githubReady,
+    readinessError,
+    startupRetryAfterMs
+  };
 }
 
 // src/runner/supervisor-credential-reader.mjs
@@ -2530,12 +2692,309 @@ function readStoredCredentialIsolated({
   }
 }
 
+// src/runner/respawn-circuit.mjs
+var DEFAULT_RESPAWN_CIRCUIT = Object.freeze({
+  baseDelayMs: 2e3,
+  maxDelayMs: 3e4,
+  healthyResetMs: 6e4,
+  maxRapidExits: 5
+});
+function createRespawnCircuit(options = {}) {
+  const config = { ...DEFAULT_RESPAWN_CIRCUIT, ...options };
+  for (const [key, value] of Object.entries(config)) {
+    if (!Number.isInteger(value) || value < 1) throw new Error(`${key} must be a positive integer`);
+  }
+  let rapidExits = 0;
+  return Object.freeze({
+    recordExit(startedAt, exitedAt) {
+      if (!Number.isFinite(startedAt) || !Number.isFinite(exitedAt) || exitedAt < startedAt) {
+        throw new Error("respawn circuit timestamps are invalid");
+      }
+      const uptimeMs = exitedAt - startedAt;
+      rapidExits = uptimeMs >= config.healthyResetMs ? 0 : rapidExits + 1;
+      const tripped = rapidExits >= config.maxRapidExits;
+      const delayMs = Math.min(
+        config.maxDelayMs,
+        config.baseDelayMs * 2 ** Math.max(0, rapidExits - 1)
+      );
+      return Object.freeze({ rapidExits, uptimeMs, delayMs, tripped });
+    },
+    snapshot() {
+      return Object.freeze({ rapidExits, tripped: rapidExits >= config.maxRapidExits });
+    }
+  });
+}
+
+// src/runner/supervisor-child-health.mjs
+var terminatedChildren = /* @__PURE__ */ new WeakSet();
+function attachSupervisorChildTerminationCustody(target, onTerminated, onObservedError = () => {
+}) {
+  let accounted = false;
+  const account = (kind, error = null) => {
+    terminatedChildren.add(target);
+    if (accounted) return false;
+    accounted = true;
+    onTerminated(Object.freeze({ target, kind, error }));
+    return true;
+  };
+  target.on("error", (error) => {
+    onObservedError(error);
+    if (target.pid === void 0 || target.pid === null) account("error", error);
+  });
+  target.on("exit", () => {
+    account("exit");
+  });
+  return Object.freeze({ accounted: () => accounted });
+}
+function supervisorChildHasExited(target) {
+  return terminatedChildren.has(target) || target.exitCode !== null || (target.signalCode ?? null) !== null;
+}
+function supervisorChildIsRunning(target) {
+  return !supervisorChildHasExited(target);
+}
+function shouldRespawnSupervisorChild({ stopping, degraded, handling, child }) {
+  return !stopping && !degraded && !handling && (!child || supervisorChildHasExited(child));
+}
+function shouldDeferSupervisorReadinessExit({
+  target,
+  currentChild,
+  retryAfterMs
+}) {
+  return target === currentChild && target?.exitCode === 75 && Number.isFinite(retryAfterMs) && retryAfterMs > 0;
+}
+function createSupervisorReadinessDeferralTracker({
+  currentChild,
+  releaseCurrentChild,
+  onCaptured
+}) {
+  const pending = /* @__PURE__ */ new WeakMap();
+  const terminal = /* @__PURE__ */ new WeakSet();
+  const recoveryGenerations = /* @__PURE__ */ new WeakMap();
+  return Object.freeze({
+    recordPending(target, request) {
+      if (!target || target !== currentChild() || terminal.has(target) || pending.has(target) || typeof request?.nonce !== "string" || !request.nonce || !Number.isFinite(request.retryAfterMs) || request.retryAfterMs <= 0) return false;
+      pending.set(target, Object.freeze({
+        nonce: request.nonce,
+        retryAfterMs: Math.ceil(request.retryAfterMs)
+      }));
+      return true;
+    },
+    recordRecoveryGeneration(target, generation) {
+      if (!target || !Number.isInteger(generation)) return false;
+      recoveryGenerations.set(target, generation);
+      return true;
+    },
+    isDeferred(target) {
+      const request = target ? pending.get(target) : null;
+      return Boolean(target) && (terminal.has(target) || shouldDeferSupervisorReadinessExit({
+        target,
+        currentChild: currentChild(),
+        retryAfterMs: request?.retryAfterMs
+      }));
+    },
+    capture(target) {
+      if (!target) return false;
+      if (terminal.has(target)) return true;
+      const request = pending.get(target);
+      if (!shouldDeferSupervisorReadinessExit({
+        target,
+        currentChild: currentChild(),
+        retryAfterMs: request?.retryAfterMs
+      })) return false;
+      const recoveryGeneration = recoveryGenerations.get(target);
+      terminal.add(target);
+      pending.delete(target);
+      recoveryGenerations.delete(target);
+      releaseCurrentChild(target);
+      onCaptured(Object.freeze({
+        target,
+        retryAfterMs: request.retryAfterMs,
+        recoveryGeneration: Number.isInteger(recoveryGeneration) ? recoveryGeneration : null
+      }));
+      return true;
+    },
+    forget(target) {
+      if (!target) return;
+      pending.delete(target);
+      recoveryGenerations.delete(target);
+    }
+  });
+}
+function resolveSupervisorChildStartAuthority({
+  degradationState,
+  deferredRecoveryGeneration
+}) {
+  const snapshot = degradationState.snapshot();
+  const exactRecovery = Number.isInteger(deferredRecoveryGeneration) && deferredRecoveryGeneration === snapshot.generation;
+  return Object.freeze({
+    allowed: !snapshot.degraded || exactRecovery,
+    recoveryGeneration: exactRecovery ? deferredRecoveryGeneration : null
+  });
+}
+function createSupervisorStartupDeferral({
+  retryAfterMs = null,
+  nowMs = () => Date.now()
+} = {}) {
+  let started = false;
+  let notBefore = null;
+  const defer = (delayMs) => {
+    if (started || !Number.isFinite(delayMs) || delayMs <= 0) return false;
+    const candidate = nowMs() + Math.ceil(delayMs);
+    notBefore = notBefore === null ? candidate : Math.max(notBefore, candidate);
+    return true;
+  };
+  defer(retryAfterMs);
+  return Object.freeze({
+    defer,
+    reopen(delayMs) {
+      if (!Number.isFinite(delayMs) || delayMs <= 0) return false;
+      started = false;
+      notBefore = null;
+      return defer(delayMs);
+    },
+    isPending() {
+      return !started && notBefore !== null && nowMs() < notBefore;
+    },
+    remainingMs() {
+      return started || notBefore === null ? 0 : Math.max(0, notBefore - nowMs());
+    },
+    consumeIfReady() {
+      if (started || notBefore !== null && nowMs() < notBefore) return false;
+      started = true;
+      notBefore = null;
+      return true;
+    },
+    hasStarted() {
+      return started;
+    }
+  });
+}
+function createSupervisorDegradationState() {
+  let degraded = false;
+  let generation = 0;
+  return {
+    isDegraded() {
+      return degraded;
+    },
+    markDegraded() {
+      degraded = true;
+      generation += 1;
+    },
+    beginHealthProof({ target, currentChild, allowRecovery, onRecovery }) {
+      const observedGeneration = generation;
+      return () => {
+        if (currentChild() !== target || generation !== observedGeneration) return false;
+        if (degraded && !allowRecovery) return false;
+        const recovered = degraded;
+        degraded = false;
+        if (recovered) onRecovery?.();
+        return true;
+      };
+    },
+    beginDegradationProof({ target, currentChild, onDegraded }) {
+      const observedGeneration = generation;
+      return (message) => {
+        if (currentChild() !== target || generation !== observedGeneration) return false;
+        onDegraded(message);
+        return true;
+      };
+    },
+    snapshot() {
+      return { degraded, generation };
+    }
+  };
+}
+function beginSupervisorHealthyStateCommit({
+  degradationState,
+  target,
+  currentChild,
+  allowRecovery,
+  clearStaleExitCode
+}) {
+  return degradationState.beginHealthProof({
+    target,
+    currentChild,
+    allowRecovery,
+    onRecovery: clearStaleExitCode
+  });
+}
+var RUNNER_RECOVERY_ACTIONS = /* @__PURE__ */ new Set(["update", "reinstall", "reconnect"]);
+function shouldRecoverSupervisorChildAfterAction({
+  stoppedChild,
+  actionKind,
+  actionSucceeded
+}) {
+  return Boolean(stoppedChild) || actionSucceeded === true && RUNNER_RECOVERY_ACTIONS.has(actionKind);
+}
+function createSupervisorControlRecoveryFence() {
+  let targetStoppedForControl = null;
+  const consume = () => {
+    const target = targetStoppedForControl;
+    targetStoppedForControl = null;
+    return target;
+  };
+  return {
+    markBeforeStop(target) {
+      targetStoppedForControl = target && supervisorChildIsRunning(target) ? target : null;
+      return targetStoppedForControl !== null;
+    },
+    consume,
+    async recoverOnce(recover) {
+      const target = consume();
+      if (!target) return false;
+      await recover(target);
+      return true;
+    }
+  };
+}
+async function verifySupervisorChildHealth({
+  target,
+  degradeOnExit,
+  context,
+  waitBeforeProbe,
+  waitForLocalRunner: waitForLocalRunner2,
+  stopExpectedly,
+  markHealthy,
+  markDegraded,
+  isReadinessDeferredExit = () => false,
+  isExpectedStop = () => false
+}) {
+  try {
+    await waitBeforeProbe();
+    const healthy = supervisorChildIsRunning(target) && await waitForLocalRunner2(target);
+    const exited = supervisorChildHasExited(target);
+    if (isExpectedStop(target)) return false;
+    if (exited && isReadinessDeferredExit(target)) return false;
+    if (healthy && !exited) {
+      if (markHealthy() !== false) return true;
+      if (supervisorChildIsRunning(target)) await stopExpectedly(target);
+      return false;
+    }
+    if (!exited || degradeOnExit) {
+      const committed = markDegraded(`${context} did not become healthy; entering degraded mode`) !== false;
+      if (!committed) return false;
+      if (supervisorChildIsRunning(target)) await stopExpectedly(target);
+    }
+    return false;
+  } catch (error) {
+    if (isExpectedStop(target)) return false;
+    const committed = markDegraded(
+      `${context} health proof failed; entering degraded mode: ${error instanceof Error ? error.message : String(error)}`
+    ) !== false;
+    if (!committed) return false;
+    if (supervisorChildIsRunning(target)) await stopExpectedly(target).catch(() => {
+    });
+    return false;
+  }
+}
+
 // src/runner-supervisor.mjs
 var DEFAULT_CONTROL_PLANE_URL = "https://vo-control-plane-bzjphrajaq-uc.a.run.app";
 var POLL_MS = 5e3;
 var CHILD_START_MS = 1500;
+var CHILD_READINESS_TIMEOUT_MS = RUNNER_IDENTITY_READINESS_TIMEOUT_MS + RUNNER_GITHUB_READINESS_TIMEOUT_MS + 1e4;
 var SUPERVISOR_CAPABILITIES = ["bundled-runtime-slots-v1", "legacy-orphan-purge-v1"];
-var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 var selfPath = fileURLToPath3(import.meta.url);
 var bundledChildEntry = join5(dirname4(selfPath), "runner-cli.js");
 var supervisorRuntimeRoot = runtimeRootFromEnv(process.env);
@@ -2548,7 +3007,7 @@ function packageVersion() {
     return "unknown";
   }
 }
-var requestedSupervisorInstanceId = UUID_RE2.test(String(process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID || "")) ? process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID : randomUUID3();
+var requestedSupervisorInstanceId = UUID_RE3.test(String(process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID || "")) ? process.env.VO_RUNNER_SUPERVISOR_INSTANCE_ID : randomUUID4();
 var supervisorInstanceId = activationSupervisorInstanceId(
   runtimeRootFromEnv(process.env),
   requestedSupervisorInstanceId
@@ -2572,16 +3031,27 @@ function spawnChild(childEnv) {
   }
   return spawn(process.execPath, resolved.args, {
     env: childEnv,
-    stdio: "inherit",
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
     windowsHide: true
   });
 }
 function spawnPreviousChild(entry, childEnv) {
-  return spawn(process.execPath, [entry, "runner"], {
+  const previous = spawn(process.execPath, [entry, "runner"], {
     env: childEnv,
-    stdio: "inherit",
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
     windowsHide: true
   });
+  attachSupervisorChildTerminationCustody(
+    previous,
+    () => {
+    },
+    (error) => {
+      console.error(
+        `[vo-runner supervisor] rollback child process error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  );
+  return previous;
 }
 async function localStatus() {
   try {
@@ -2595,32 +3065,54 @@ async function localStatus() {
   }
 }
 async function waitForLocalRunner(child) {
-  const deadline = Date.now() + 15e3;
+  const deadline = Date.now() + CHILD_READINESS_TIMEOUT_MS;
   while (Date.now() < deadline) {
-    if (child.exitCode !== null) return false;
+    if (supervisorChildHasExited(child)) return false;
     const status = await localStatus();
     if (status?.running === true && Number(status.pid) === Number(child.pid)) return true;
     await sleep(500);
   }
   return false;
 }
+async function waitForChildExit(child, timeoutMs) {
+  if (!child || supervisorChildHasExited(child)) return true;
+  return new Promise((resolve5) => {
+    let settled = false;
+    const finish = (exited) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.off("exit", onExit);
+      resolve5(exited);
+    };
+    const onExit = () => finish(true);
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    child.once("exit", onExit);
+    if (supervisorChildHasExited(child)) finish(true);
+  });
+}
 async function stopChild(child) {
-  if (!child || child.exitCode !== null) return;
+  if (!child || supervisorChildHasExited(child)) return;
   child.kill(process.platform === "win32" ? void 0 : "SIGTERM");
-  await Promise.race([
-    new Promise((resolve5) => child.once("exit", resolve5)),
-    sleep(15e3)
-  ]);
-  if (child.exitCode === null) child.kill("SIGKILL");
+  if (await waitForChildExit(child, 15e3)) return;
+  if (supervisorChildIsRunning(child)) child.kill("SIGKILL");
+  await waitForChildExit(child, 5e3);
 }
 async function main() {
   const stored = readStoredCredentialIsolated();
   const controlPlaneUrl = process.env.VO_CONTROL_PLANE_URL || DEFAULT_CONTROL_PLANE_URL;
-  const { childEnv, clientEnv, operatorId } = await prepareSupervisorAuth({
+  const pairedSupervisor = !String(process.env.VO_CONTROL_PLANE_ADMIN_TOKEN || "").trim();
+  const supervisorAuthInput = {
     baseEnv: process.env,
     storedCredential: stored,
     controlPlaneUrl
-  });
+  };
+  const {
+    childEnv,
+    clientEnv,
+    operatorId,
+    startupRetryAfterMs
+  } = await prepareSupervisorAuth(supervisorAuthInput);
   Object.assign(childEnv, {
     VO_RUNNER_SUPERVISOR_INSTANCE_ID: supervisorInstanceId,
     VO_RUNNER_SUPERVISOR_VERSION: supervisorVersion,
@@ -2631,37 +3123,266 @@ async function main() {
   let child = null;
   let stopping = false;
   let handling = false;
-  let degraded = false;
+  const expectedChildStops = /* @__PURE__ */ new WeakSet();
+  const healthNeutralizedChildren = /* @__PURE__ */ new WeakSet();
+  const degradationState = createSupervisorDegradationState();
+  const markSupervisorDegraded = () => {
+    degradationState.markDegraded();
+    process.exitCode = 1;
+  };
+  const respawnCircuit = createRespawnCircuit();
+  const controlRecoveryFence = createSupervisorControlRecoveryFence();
+  const startupDeferral = createSupervisorStartupDeferral({
+    retryAfterMs: startupRetryAfterMs
+  });
+  let startupNeedsReadinessRefresh = startupRetryAfterMs !== null;
+  let deferredControlRecoveryGeneration = null;
+  const stopChildExpectedly = async (target) => {
+    if (!target) return;
+    expectedChildStops.add(target);
+    healthNeutralizedChildren.add(target);
+    try {
+      await stopChild(target);
+    } finally {
+      if (supervisorChildHasExited(target)) expectedChildStops.delete(target);
+    }
+  };
+  const readinessDeferrals = createSupervisorReadinessDeferralTracker({
+    currentChild: () => child,
+    releaseCurrentChild: (target) => {
+      if (child === target) child = null;
+    },
+    onCaptured: ({ retryAfterMs, recoveryGeneration }) => {
+      startupNeedsReadinessRefresh = true;
+      if (Number.isInteger(recoveryGeneration) && degradationState.snapshot().generation === recoveryGeneration) {
+        deferredControlRecoveryGeneration = recoveryGeneration;
+      }
+      startupDeferral.reopen(retryAfterMs);
+      console.warn(
+        `[vo-runner supervisor] child deferred by GitHub readiness for ${retryAfterMs}ms; preserving control polling without consuming rapid-exit breaker budget`
+      );
+    }
+  });
+  const isChildReadinessDeferred = (target) => readinessDeferrals.isDeferred(target);
+  const captureChildReadinessDeferral = (target) => readinessDeferrals.capture(target);
   const respawn = () => {
-    if (!stopping && !degraded && !handling && (!child || child.exitCode !== null)) child = launchChild();
+    if (!startupDeferral.hasStarted()) return;
+    if (!shouldRespawnSupervisorChild({
+      stopping,
+      degraded: degradationState.isDegraded(),
+      handling,
+      child
+    })) return;
+    try {
+      child = launchChild();
+      void verifyChildHealth(child, false, "automatic relaunch");
+    } catch (error) {
+      markSupervisorDegraded();
+      console.error(
+        `[vo-runner supervisor] child relaunch failed; entering degraded mode: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   };
   const launchChild = () => {
     const next = spawnChild(childEnv);
-    next.on("exit", () => setTimeout(respawn, 2e3));
+    const startedAt = Date.now();
+    next.on("message", (message) => {
+      const request = parseRunnerReadinessDeferralRequest(message);
+      if (!request || !readinessDeferrals.recordPending(next, request)) return;
+      try {
+        next.send({
+          type: RUNNER_READINESS_DEFERRAL_ACK_TYPE,
+          nonce: request.nonce
+        }, (error) => {
+          if (error) console.warn(`[vo-runner supervisor] readiness deferral ACK failed: ${error.message}`);
+        });
+      } catch (error) {
+        console.warn(
+          `[vo-runner supervisor] readiness deferral ACK failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    });
+    attachSupervisorChildTerminationCustody(
+      next,
+      () => {
+        if (stopping || expectedChildStops.delete(next)) {
+          readinessDeferrals.forget(next);
+          return;
+        }
+        if (captureChildReadinessDeferral(next)) return;
+        readinessDeferrals.forget(next);
+        const decision = respawnCircuit.recordExit(startedAt, Date.now());
+        if (decision.tripped) {
+          markSupervisorDegraded();
+          console.error(
+            `[vo-runner supervisor] child exited rapidly ${decision.rapidExits} times; entering degraded mode to stop startup/token churn while remote repair remains available`
+          );
+          return;
+        }
+        setTimeout(respawn, decision.delayMs);
+      },
+      (error) => {
+        console.error(
+          `[vo-runner supervisor] child process error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    );
     return next;
   };
-  child = launchChild();
-  if (!await finishPendingActivation({
-    client,
-    child,
-    runtimeRoot,
-    operatorId,
-    runnerId,
-    selfPath,
-    packageVersion: supervisorVersion,
-    supervisorIdentity: supervisorControlIdentity,
-    waitForLocalRunner,
-    localStatus,
-    stopChild,
-    launchPreviousChild: (entry) => spawnPreviousChild(entry, childEnv),
-    log: (message) => console.error(`[vo-runner supervisor] ${message}`)
-  })) {
-    degraded = true;
-    process.exitCode = 1;
-    await stopChild(child);
-    child = null;
-    console.error("[vo-runner supervisor] activation FAILED \u2014 entering degraded mode: not serving tasks, still polling for remote control actions");
-  }
+  const verifyChildHealth = async (target, degradeOnExit, context) => {
+    const commitSupervisorHealthyState = beginSupervisorHealthyStateCommit({
+      degradationState,
+      target,
+      currentChild: () => child,
+      allowRecovery: degradeOnExit,
+      clearStaleExitCode: () => {
+        process.exitCode = void 0;
+      }
+    });
+    const commitSupervisorDegradedState = degradationState.beginDegradationProof({
+      target,
+      currentChild: () => child,
+      onDegraded: (message) => {
+        markSupervisorDegraded();
+        console.error(`[vo-runner supervisor] ${message}`);
+      }
+    });
+    return verifySupervisorChildHealth({
+      target,
+      degradeOnExit,
+      context,
+      waitBeforeProbe: () => sleep(CHILD_START_MS),
+      waitForLocalRunner,
+      stopExpectedly: stopChildExpectedly,
+      isReadinessDeferredExit: isChildReadinessDeferred,
+      isExpectedStop: (candidate) => healthNeutralizedChildren.has(candidate),
+      markHealthy: commitSupervisorHealthyState,
+      markDegraded: commitSupervisorDegradedState
+    });
+  };
+  const deferChildAdmission = (retryAfterMs) => {
+    startupNeedsReadinessRefresh = true;
+    if (startupDeferral.hasStarted()) startupDeferral.reopen(retryAfterMs);
+    else startupDeferral.defer(retryAfterMs);
+    console.warn(
+      `[vo-runner supervisor] GitHub readiness embargoed child startup for ${retryAfterMs}ms; control polling remains active`
+    );
+  };
+  const refreshSupervisorChildAdmission = async () => {
+    if (!pairedSupervisor) return true;
+    const refreshed = await prepareSupervisorAuth({
+      ...supervisorAuthInput,
+      baseEnv: childEnv
+    });
+    if (refreshed.operatorId !== operatorId) {
+      throw new Error("runner readiness operator identity changed during supervisor admission");
+    }
+    if (refreshed.startupRetryAfterMs !== null) {
+      deferChildAdmission(refreshed.startupRetryAfterMs);
+      return false;
+    }
+    if (refreshed.repositoryScope.length > 0) {
+      const repositoryScope = refreshed.repositoryScope.join(",");
+      childEnv.VO_CODE_RUNNER_REPOS = repositoryScope;
+      clientEnv.VO_CODE_RUNNER_REPOS = repositoryScope;
+    }
+    startupNeedsReadinessRefresh = false;
+    return true;
+  };
+  const ensureHealthyChildAfterControl = async () => {
+    if (!child || supervisorChildHasExited(child)) {
+      const recoveryGeneration = degradationState.snapshot().generation;
+      if (!startupDeferral.hasStarted() && startupDeferral.isPending()) {
+        deferredControlRecoveryGeneration = recoveryGeneration;
+        return false;
+      }
+      try {
+        if (!await refreshSupervisorChildAdmission()) {
+          deferredControlRecoveryGeneration = recoveryGeneration;
+          return false;
+        }
+        if (!startupDeferral.hasStarted() && !startupDeferral.consumeIfReady()) return false;
+        child = launchChild();
+        readinessDeferrals.recordRecoveryGeneration(child, recoveryGeneration);
+      } catch (error) {
+        markSupervisorDegraded();
+        console.error(
+          `[vo-runner supervisor] control recovery relaunch failed; entering degraded mode: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return false;
+      }
+    }
+    return verifyChildHealth(child, true, "control recovery relaunch");
+  };
+  const startInitialChild = async (recoveryGeneration = null) => {
+    const activationChild = launchChild();
+    child = activationChild;
+    if (Number.isInteger(recoveryGeneration)) {
+      readinessDeferrals.recordRecoveryGeneration(activationChild, recoveryGeneration);
+    }
+    void verifyChildHealth(
+      activationChild,
+      Number.isInteger(recoveryGeneration),
+      Number.isInteger(recoveryGeneration) ? "deferred control recovery" : "initial child"
+    );
+    if (!await finishPendingActivation({
+      client,
+      child: activationChild,
+      runtimeRoot,
+      operatorId,
+      runnerId,
+      selfPath,
+      packageVersion: supervisorVersion,
+      supervisorIdentity: supervisorControlIdentity,
+      waitForLocalRunner,
+      isReadinessDeferred: isChildReadinessDeferred,
+      localStatus,
+      stopChild: stopChildExpectedly,
+      launchPreviousChild: (entry) => spawnPreviousChild(entry, childEnv),
+      log: (message) => console.error(`[vo-runner supervisor] ${message}`)
+    })) {
+      if (captureChildReadinessDeferral(activationChild)) {
+        console.warn("[vo-runner supervisor] activation attestation deferred with GitHub readiness; pending slot remains durable");
+        return false;
+      }
+      markSupervisorDegraded();
+      await stopChildExpectedly(activationChild);
+      if (child === activationChild) child = null;
+      console.error("[vo-runner supervisor] activation FAILED \u2014 entering degraded mode: not serving tasks, still polling for remote control actions");
+      return false;
+    }
+    return true;
+  };
+  const attemptInitialChildStart = async () => {
+    if (startupDeferral.hasStarted() || startupDeferral.isPending()) return false;
+    const beforeRefresh = resolveSupervisorChildStartAuthority({
+      degradationState,
+      deferredRecoveryGeneration: deferredControlRecoveryGeneration
+    });
+    if (!beforeRefresh.allowed) return false;
+    if (startupNeedsReadinessRefresh) {
+      try {
+        if (!await refreshSupervisorChildAdmission()) return false;
+      } catch (error) {
+        markSupervisorDegraded();
+        deferredControlRecoveryGeneration = null;
+        startupDeferral.consumeIfReady();
+        console.error(
+          `[vo-runner supervisor] deferred readiness refresh failed; entering degraded mode: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return false;
+      }
+    }
+    const afterRefresh = resolveSupervisorChildStartAuthority({
+      degradationState,
+      deferredRecoveryGeneration: deferredControlRecoveryGeneration
+    });
+    if (!afterRefresh.allowed) return false;
+    if (!startupDeferral.consumeIfReady()) return false;
+    deferredControlRecoveryGeneration = null;
+    return startInitialChild(afterRefresh.recoveryGeneration);
+  };
+  await attemptInitialChildStart();
   const shutdown = async () => {
     if (stopping) return;
     stopping = true;
@@ -2675,6 +3396,7 @@ async function main() {
   });
   while (!stopping) {
     try {
+      await attemptInitialChildStart();
       const action = await client.pollRunnerControl({
         runnerId,
         ...operatorId ? { operatorId } : {},
@@ -2684,6 +3406,7 @@ async function main() {
         await sleep(POLL_MS);
         continue;
       }
+      deferredControlRecoveryGeneration = null;
       handling = true;
       const beforeStop = await localStatus();
       if (beforeStop && Number(beforeStop.activeTasks || 0) > 0) {
@@ -2695,9 +3418,11 @@ async function main() {
           detail: `deferred safely: ${beforeStop.activeTasks} active task(s); retry when the runner is idle`
         });
         handling = false;
+        respawn();
         continue;
       }
-      await stopChild(child);
+      controlRecoveryFence.markBeforeStop(child);
+      await stopChildExpectedly(child);
       const bundledAction = action.kind === "update" || action.kind === "reinstall";
       const result = bundledAction ? stageAndActivateBundledUpdate({
         runtimeRoot,
@@ -2723,20 +3448,25 @@ async function main() {
         console.warn(`[vo-runner supervisor] activated ${result.active.version}; exiting for new-process attestation`);
         return;
       }
-      child = launchChild();
-      await sleep(CHILD_START_MS);
-      if (child.exitCode !== null || !await waitForLocalRunner(child)) result.ok = false;
-      else degraded = false;
+      const recoveryAuthorized = shouldRecoverSupervisorChildAfterAction({
+        stoppedChild: controlRecoveryFence.consume(),
+        actionKind: action.kind,
+        actionSucceeded: result.ok
+      });
+      const relaunchedHealthy = recoveryAuthorized ? await ensureHealthyChildAfterControl() : false;
+      if (!relaunchedHealthy) result.ok = false;
       await client.completeRunnerControl(action.actionId, {
         runnerId,
         ...operatorId ? { operatorId } : {},
         ...supervisorControlIdentity,
         status: result.ok ? "succeeded" : "failed",
-        detail: result.ok ? result.detail ? `${result.detail}; runner ${packageVersion()} reconnected`.slice(0, 1e3) : `runner ${packageVersion()} reconnected` : `maintenance exited ${result.status}${result.detail ? `: ${result.detail}` : ""}`
+        detail: result.ok ? result.detail ? `${result.detail}; runner ${packageVersion()} reconnected`.slice(0, 1e3) : `runner ${packageVersion()} reconnected` : `maintenance exited ${result.status}${result.detail ? `: ${result.detail}` : ""}${relaunchedHealthy ? "" : "; runner relaunch did not become healthy"}`
       });
       handling = false;
+      respawn();
     } catch (error) {
       console.error(`[vo-runner supervisor] ${error instanceof Error ? error.message : String(error)}`);
+      await controlRecoveryFence.recoverOnce(() => ensureHealthyChildAfterControl());
       handling = false;
       await sleep(POLL_MS);
     }