@opengeni/contracts 0.18.0 → 0.19.0

package/dist/index.js

@@ -864,6 +864,879 @@ function isPlainRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
+// src/codex-fleet-policy.ts
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+var CODEX_FLEET_POLICY_SCHEMA_VERSION = 1;
+var CODEX_FLEET_POLICY_VERSION = "adaptive-shadow-v1";
+var CODEX_FLEET_POLICY_MAX_CANDIDATES = 32;
+var CODEX_FLEET_POLICY_MAX_OVERLAYS_PER_CANDIDATE = 4;
+var MAX_DURATION_MS = 31 * 24 * 60 * 6e4;
+var MAX_COUNT = 1e6;
+var SCORE_SCALE = 100;
+function compareCodexFleetCanonicalStringsV1(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+var DEFAULT_CODEX_FLEET_POLICY_V1 = Object.freeze({
+  maxCandidates: CODEX_FLEET_POLICY_MAX_CANDIDATES,
+  quotaFreshForMs: 15 * 6e4,
+  quotaStaleAfterMs: 60 * 6e4,
+  placementUsageCeilingPercent: 90,
+  cacheFreshForMs: 30 * 6e4,
+  cacheCollapseThreshold: 0.4,
+  cacheCollapseRecoveryThreshold: 0.65,
+  cacheMinimumSampledTokens: 4096,
+  cacheCollapseDwellMs: 5 * 6e4,
+  cacheRecoveryDwellMs: 10 * 6e4,
+  activeLeaseScore: 8 * SCORE_SCALE,
+  unknownQuotaScore: 16 * SCORE_SCALE,
+  lowQuotaConfidenceScore: 10 * SCORE_SCALE,
+  mediumQuotaConfidenceScore: 4 * SCORE_SCALE,
+  inferredBurnScorePerPercentHour: 0.2 * SCORE_SCALE,
+  observedBurnScorePerPercentHour: 0.1 * SCORE_SCALE,
+  runwayRiskCapHours: 2,
+  runwayScorePerAtRiskHour: 8 * SCORE_SCALE,
+  healthyCacheAffinityBenefit: 32 * SCORE_SCALE,
+  unknownCacheAffinityBenefit: 24 * SCORE_SCALE,
+  collapsedCacheAffinityBenefit: 6 * SCORE_SCALE,
+  switchHysteresisScore: 8 * SCORE_SCALE,
+  admissionPacingEnabled: false,
+  managerPriorityEnabled: false,
+  managerStandardStarvationMs: 2 * 6e4,
+  emergencyFuseEnabled: false,
+  overlaysEnabled: false,
+  overlayPreferenceScore: 12 * SCORE_SCALE
+});
+function createCodexFleetReplayRecordV1(input, policy = DEFAULT_CODEX_FLEET_POLICY_V1) {
+  const normalizedPolicy = normalizePolicy(policy);
+  const normalized = normalizeInput(input, normalizedPolicy.maxCandidates);
+  const decision = evaluateCodexFleetDecisionV1(normalized.input, normalizedPolicy);
+  return {
+    schemaVersion: CODEX_FLEET_POLICY_SCHEMA_VERSION,
+    policyVersion: CODEX_FLEET_POLICY_VERSION,
+    mode: "shadow",
+    policy: normalizedPolicy,
+    input: normalized.input,
+    truncatedCandidateCount: normalized.truncatedCandidateCount,
+    policyFingerprint: fingerprint(normalizedPolicy),
+    inputFingerprint: fingerprintReplayInput(normalized.input, normalized.truncatedCandidateCount),
+    decision,
+    decisionFingerprint: fingerprint(decision)
+  };
+}
+function replayCodexFleetDecisionV1(value) {
+  const record = readCodexFleetReplayRecordV1(value);
+  const policyFingerprintMatches = fingerprint(record.policy) === record.policyFingerprint;
+  const inputFingerprintMatches = fingerprintReplayInput(record.input, record.truncatedCandidateCount) === record.inputFingerprint;
+  const decision = evaluateCodexFleetDecisionV1(record.input, record.policy);
+  const replayedDecisionFingerprint = fingerprint(decision);
+  const recordedDecisionFingerprintMatches = fingerprint(record.decision) === record.decisionFingerprint;
+  const decisionFingerprintMatches = recordedDecisionFingerprintMatches && replayedDecisionFingerprint === record.decisionFingerprint;
+  return {
+    matches: policyFingerprintMatches && inputFingerprintMatches && decisionFingerprintMatches && canonicalJson(decision) === canonicalJson(record.decision),
+    policyFingerprintMatches,
+    inputFingerprintMatches,
+    decisionFingerprintMatches,
+    recordedDecisionFingerprintMatches,
+    decision
+  };
+}
+function canonicalCodexFleetReplayJsonV1(value) {
+  return canonicalJson(value);
+}
+function readCodexFleetReplayRecordV1(value) {
+  const record = strictRecord(value, [
+    "schemaVersion",
+    "policyVersion",
+    "mode",
+    "policy",
+    "input",
+    "truncatedCandidateCount",
+    "policyFingerprint",
+    "inputFingerprint",
+    "decision",
+    "decisionFingerprint"
+  ]);
+  if (record.schemaVersion !== CODEX_FLEET_POLICY_SCHEMA_VERSION || record.policyVersion !== CODEX_FLEET_POLICY_VERSION || record.mode !== "shadow") {
+    throw new Error("Unsupported Codex fleet replay envelope");
+  }
+  const policy = normalizePolicy(record.policy);
+  if (canonicalJson(policy) !== canonicalJson(record.policy)) {
+    throw new Error("Codex fleet replay policy is not in canonical bounded form");
+  }
+  const normalizedInput = normalizeInput(
+    record.input,
+    policy.maxCandidates
+  );
+  if (normalizedInput.truncatedCandidateCount !== 0 || canonicalJson(normalizedInput.input) !== canonicalJson(record.input)) {
+    throw new Error("Codex fleet replay input is not in canonical bounded form");
+  }
+  return {
+    schemaVersion: CODEX_FLEET_POLICY_SCHEMA_VERSION,
+    policyVersion: CODEX_FLEET_POLICY_VERSION,
+    mode: "shadow",
+    policy,
+    input: normalizedInput.input,
+    truncatedCandidateCount: strictInteger(record.truncatedCandidateCount, 0, MAX_COUNT),
+    policyFingerprint: strictSha256(record.policyFingerprint),
+    inputFingerprint: strictSha256(record.inputFingerprint),
+    decision: readCodexFleetDecisionV1(
+      record.decision,
+      new Set(normalizedInput.input.candidates.map((candidate) => candidate.key))
+    ),
+    decisionFingerprint: strictSha256(record.decisionFingerprint)
+  };
+}
+function evaluateCodexFleetDecisionV1(input, policy = DEFAULT_CODEX_FLEET_POLICY_V1) {
+  const admission = evaluateAdmission(input, policy);
+  const current = input.request.currentCandidateKey ? input.candidates.find((candidate) => candidate.key === input.request.currentCandidateKey) : void 0;
+  if (input.request.placement === "fenced_in_flight") {
+    if (!current) {
+      return emptyDecision("fenced_candidate_missing", admission, "unknown");
+    }
+    return {
+      outcome: "selected",
+      selectedCandidateKey: current.key,
+      reason: "fenced_in_flight",
+      admission,
+      borrowedOverlayCapacity: false,
+      strandedEligibleCount: 0,
+      confidence: candidateConfidence(current, policy),
+      scores: [scoreCandidate(current, input, policy, false)]
+    };
+  }
+  if (admission.outcome === "pace") {
+    return emptyDecision("admission_paced", admission, "unknown");
+  }
+  const scored = input.candidates.map(
+    (candidate) => scoreCandidate(candidate, input, policy, false)
+  );
+  const baseEligibleKeys = new Set(
+    scored.filter((candidate) => candidate.eligible).map((candidate) => candidate.candidateKey)
+  );
+  const overlay = selectOverlayScope(input, policy, baseEligibleKeys);
+  const scopedScores = input.candidates.map(
+    (candidate) => scoreCandidate(
+      candidate,
+      input,
+      policy,
+      overlay.rejectedByIsolation.has(candidate.key),
+      overlay.preferredMembers.has(candidate.key)
+    )
+  ).sort((a, b) => compareCodexFleetCanonicalStringsV1(a.candidateKey, b.candidateKey));
+  const eligible = scopedScores.filter((candidate) => candidate.eligible).sort(
+    (a, b) => a.total - b.total || compareCodexFleetCanonicalStringsV1(a.candidateKey, b.candidateKey)
+  );
+  if (eligible.length === 0) {
+    return {
+      ...emptyDecision(
+        overlay.isolatedEmpty ? "overlay_isolated_empty" : "no_eligible_candidate",
+        admission,
+        aggregateConfidence(scopedScores)
+      ),
+      strandedEligibleCount: overlay.strandedEligibleCount,
+      scores: scopedScores
+    };
+  }
+  let selected = eligible[0];
+  let reason = "best_score";
+  const currentScore = input.request.currentCandidateKey ? eligible.find((candidate) => candidate.candidateKey === input.request.currentCandidateKey) : void 0;
+  if (currentScore) {
+    if (selected.candidateKey === currentScore.candidateKey) {
+      reason = "affinity_best";
+    } else if (selected.total + policy.switchHysteresisScore >= currentScore.total) {
+      selected = currentScore;
+      reason = "hysteresis_hold";
+    }
+  }
+  return {
+    outcome: "selected",
+    selectedCandidateKey: selected.candidateKey,
+    reason,
+    admission,
+    borrowedOverlayCapacity: policy.overlaysEnabled && input.request.overlayMode === "prefer" && input.request.overlayKey !== null && !overlay.preferredMembers.has(selected.candidateKey),
+    strandedEligibleCount: overlay.strandedEligibleCount,
+    confidence: aggregateConfidence(eligible),
+    scores: scopedScores
+  };
+}
+function evaluateAdmission(input, policy) {
+  if (input.request.placement === "fenced_in_flight") {
+    return {
+      outcome: "admit",
+      reason: "fenced_in_flight",
+      borrowedIdleCapacity: false
+    };
+  }
+  if (policy.emergencyFuseEnabled && input.admission.emergencyFuseActive) {
+    return {
+      outcome: "pace",
+      reason: "emergency_fuse",
+      borrowedIdleCapacity: false
+    };
+  }
+  if (!policy.admissionPacingEnabled) {
+    return {
+      outcome: "admit",
+      reason: "pacing_disabled",
+      borrowedIdleCapacity: false
+    };
+  }
+  if (input.admission.dynamicCapacityUnits === null) {
+    return {
+      outcome: "admit",
+      reason: "capacity_unknown",
+      borrowedIdleCapacity: false
+    };
+  }
+  const available = Math.max(0, input.admission.dynamicCapacityUnits - input.admission.inUseUnits);
+  if (available === 0) {
+    return {
+      outcome: "pace",
+      reason: "capacity_saturated",
+      borrowedIdleCapacity: false
+    };
+  }
+  if (policy.managerPriorityEnabled && input.request.priority === "standard" && input.admission.queuedManagerCount > 0 && available <= input.admission.queuedManagerCount) {
+    if (input.request.waitAgeMs >= policy.managerStandardStarvationMs) {
+      return {
+        outcome: "admit",
+        reason: "standard_starvation_bound",
+        borrowedIdleCapacity: false
+      };
+    }
+    return {
+      outcome: "pace",
+      reason: "manager_priority",
+      borrowedIdleCapacity: false
+    };
+  }
+  if (input.request.priority === "standard" && input.admission.queuedManagerCount === 0) {
+    return {
+      outcome: "admit",
+      reason: "work_conserving_borrow",
+      borrowedIdleCapacity: true
+    };
+  }
+  return {
+    outcome: "admit",
+    reason: "capacity_available",
+    borrowedIdleCapacity: false
+  };
+}
+function scoreCandidate(candidate, input, policy, rejectedByIsolation, preferredOverlayMember = false) {
+  const confidence = candidateConfidence(candidate, policy);
+  const bindingUsed = bindingUsedPercent(candidate);
+  const hardQuotaKnown = confidence === "high" || confidence === "medium";
+  const rejectionReason = !candidate.allocatorEnabled ? "allocator_disabled" : candidate.status !== "active" ? "unavailable" : (candidate.cooldownRemainingMs ?? 0) > 0 ? "cooling" : hardQuotaKnown && bindingUsed !== null && bindingUsed >= policy.placementUsageCeilingPercent ? "quota_ceiling" : rejectedByIsolation ? "overlay_isolation" : null;
+  const confidenceFactor = confidenceWeight(confidence);
+  const quotaPressure = Math.round(
+    ((bindingUsed ?? 50) * confidenceFactor + 50 * (1 - confidenceFactor)) * SCORE_SCALE
+  );
+  const leasePressure = candidate.activeLeaseCount * policy.activeLeaseScore;
+  const observedBurnConfidence = confidenceWeight(candidate.observedBurn.confidence);
+  const observedBurn = maximumWindowBurn(candidate.observedBurn);
+  const observedBurnPressure = Math.round(
+    observedBurn * policy.observedBurnScorePerPercentHour * observedBurnConfidence
+  );
+  const burnConfidence = confidenceWeight(candidate.inferredUnexplainedBurn.confidence);
+  const inferredBurn = maximumWindowBurn(candidate.inferredUnexplainedBurn);
+  const inferredBurnPressure = Math.round(
+    inferredBurn * policy.inferredBurnScorePerPercentHour * burnConfidence
+  );
+  const runwayPressure = runwayRiskPressure(candidate, confidence, policy);
+  const uncertaintyPressure = quotaUncertaintyScore(confidence, policy);
+  const cacheState = effectiveCodexFleetCacheStateV1(candidate.cache, policy);
+  const cacheAffinityBenefit = candidate.key === input.request.currentCandidateKey ? cacheAffinityBenefitFor(cacheState, policy) : 0;
+  const overlayPreferenceBenefit = preferredOverlayMember ? policy.overlayPreferenceScore : 0;
+  return {
+    candidateKey: candidate.key,
+    eligible: rejectionReason === null,
+    rejectionReason,
+    quotaPressure,
+    leasePressure,
+    observedBurnPressure,
+    inferredBurnPressure,
+    runwayPressure,
+    uncertaintyPressure,
+    cacheAffinityBenefit,
+    cacheState,
+    overlayPreferenceBenefit,
+    total: quotaPressure + leasePressure + observedBurnPressure + inferredBurnPressure + runwayPressure + uncertaintyPressure - cacheAffinityBenefit - overlayPreferenceBenefit,
+    confidence
+  };
+}
+function maximumWindowBurn(burn) {
+  return Math.max(burn.primaryPercentPerHour ?? 0, burn.secondaryPercentPerHour ?? 0);
+}
+function windowBurn(burn, window) {
+  return window === "primary" ? burn.primaryPercentPerHour ?? 0 : burn.secondaryPercentPerHour ?? 0;
+}
+function runwayRiskPressure(candidate, quotaConfidence, policy) {
+  if (quotaConfidence === "unknown") return 0;
+  const windows = [
+    ["primary", candidate.quota.primary],
+    ["secondary", candidate.quota.secondary]
+  ];
+  let maximumPressure = 0;
+  for (const [windowKey, window] of windows) {
+    if (window.usedPercent === null || window.resetRemainingMs === null || window.resetRemainingMs === 0) {
+      continue;
+    }
+    const observedConfidence = confidenceWeight(
+      lowerConfidence(candidate.observedBurn.confidence, quotaConfidence)
+    );
+    const inferredConfidence = confidenceWeight(
+      lowerConfidence(candidate.inferredUnexplainedBurn.confidence, quotaConfidence)
+    );
+    const confidenceBoundedBurn = windowBurn(candidate.observedBurn, windowKey) * observedConfidence + windowBurn(candidate.inferredUnexplainedBurn, windowKey) * inferredConfidence;
+    if (confidenceBoundedBurn <= 0) continue;
+    const exhaustionRunwayHours = Math.max(0, 100 - window.usedPercent) / confidenceBoundedBurn;
+    const resetHorizonHours = window.resetRemainingMs / 60 / 6e4;
+    const atRiskHours = Math.min(
+      policy.runwayRiskCapHours,
+      Math.max(0, resetHorizonHours - exhaustionRunwayHours)
+    );
+    maximumPressure = Math.max(
+      maximumPressure,
+      Math.round(atRiskHours * policy.runwayScorePerAtRiskHour)
+    );
+  }
+  return maximumPressure;
+}
+function selectOverlayScope(input, policy, baseEligibleKeys) {
+  if (!policy.overlaysEnabled || input.request.overlayMode === "none" || input.request.overlayKey === null) {
+    return {
+      rejectedByIsolation: /* @__PURE__ */ new Set(),
+      preferredMembers: /* @__PURE__ */ new Set(),
+      isolatedEmpty: false,
+      strandedEligibleCount: 0
+    };
+  }
+  const members = new Set(
+    input.candidates.filter(
+      (candidate) => baseEligibleKeys.has(candidate.key) && candidate.overlayKeys.includes(input.request.overlayKey)
+    ).map((candidate) => candidate.key)
+  );
+  if (input.request.overlayMode === "prefer") {
+    if (members.size === 0) {
+      return {
+        rejectedByIsolation: /* @__PURE__ */ new Set(),
+        preferredMembers: members,
+        isolatedEmpty: false,
+        strandedEligibleCount: 0
+      };
+    }
+    return {
+      // Preference is a bounded score benefit, never a hard partition. Healthy
+      // authorized outsiders remain eligible and borrowable.
+      rejectedByIsolation: /* @__PURE__ */ new Set(),
+      preferredMembers: members,
+      isolatedEmpty: false,
+      strandedEligibleCount: 0
+    };
+  }
+  const outside = [...baseEligibleKeys].filter((candidateKey) => !members.has(candidateKey));
+  return {
+    rejectedByIsolation: new Set(outside),
+    preferredMembers: members,
+    isolatedEmpty: members.size === 0,
+    strandedEligibleCount: outside.length
+  };
+}
+function candidateConfidence(candidate, policy) {
+  const age = candidate.quota.checkedAgeMs;
+  if (age === null || age > policy.quotaStaleAfterMs) return "unknown";
+  const windows = [candidate.quota.primary, candidate.quota.secondary];
+  const completeWindowCount = windows.filter(
+    (window) => window.usedPercent !== null && window.resetRemainingMs !== null
+  ).length;
+  const hasPartialWindow = windows.some(
+    (window) => window.usedPercent === null !== (window.resetRemainingMs === null)
+  );
+  if (completeWindowCount === 0) return "unknown";
+  const completenessCeiling = hasPartialWindow ? "low" : completeWindowCount === windows.length ? "high" : "medium";
+  const completeConfidence = lowerConfidence(candidate.quota.confidence, completenessCeiling);
+  if (age > policy.quotaFreshForMs) {
+    return lowerConfidence(completeConfidence, "low");
+  }
+  return completeConfidence;
+}
+function effectiveCodexFleetCacheStateV1(cache, policy) {
+  const { hitRatio, sampledTokens, checkedAgeMs, confidence, state, thresholdObservedForMs } = cache;
+  if (hitRatio === null || sampledTokens === null || sampledTokens < policy.cacheMinimumSampledTokens || checkedAgeMs === null || checkedAgeMs > policy.cacheFreshForMs || confidenceWeight(confidence) < confidenceWeight("medium")) {
+    return "unknown";
+  }
+  const observedForMs = thresholdObservedForMs ?? 0;
+  if (state === "healthy") {
+    return hitRatio < policy.cacheCollapseThreshold && observedForMs >= policy.cacheCollapseDwellMs ? "collapsed" : "healthy";
+  }
+  if (state === "collapsed") {
+    return hitRatio >= policy.cacheCollapseRecoveryThreshold && observedForMs >= policy.cacheRecoveryDwellMs ? "healthy" : "collapsed";
+  }
+  if (hitRatio < policy.cacheCollapseThreshold && observedForMs >= policy.cacheCollapseDwellMs) {
+    return "collapsed";
+  }
+  if (hitRatio >= policy.cacheCollapseRecoveryThreshold && observedForMs >= policy.cacheRecoveryDwellMs) {
+    return "healthy";
+  }
+  return "unknown";
+}
+function cacheAffinityBenefitFor(state, policy) {
+  if (state === "healthy") return policy.healthyCacheAffinityBenefit;
+  if (state === "collapsed") return policy.collapsedCacheAffinityBenefit;
+  return policy.unknownCacheAffinityBenefit;
+}
+function bindingUsedPercent(candidate) {
+  const windows = [candidate.quota.primary, candidate.quota.secondary].filter((window) => window.usedPercent !== null && window.resetRemainingMs !== null).map((window) => window.resetRemainingMs === 0 ? 0 : window.usedPercent).filter((used) => used !== null);
+  return windows.length > 0 ? Math.max(...windows) : null;
+}
+function quotaUncertaintyScore(confidence, policy) {
+  if (confidence === "unknown") return policy.unknownQuotaScore;
+  if (confidence === "low") return policy.lowQuotaConfidenceScore;
+  if (confidence === "medium") return policy.mediumQuotaConfidenceScore;
+  return 0;
+}
+function emptyDecision(reason, admission, confidence) {
+  return {
+    outcome: admission.outcome === "pace" ? "paced" : "none",
+    selectedCandidateKey: null,
+    reason,
+    admission,
+    borrowedOverlayCapacity: false,
+    strandedEligibleCount: 0,
+    confidence,
+    scores: []
+  };
+}
+function aggregateConfidence(scores) {
+  if (scores.length === 0) return "unknown";
+  return scores.reduce(
+    (lowest, score) => confidenceWeight(score.confidence) < confidenceWeight(lowest) ? score.confidence : lowest,
+    "high"
+  );
+}
+function normalizeInput(input, maxCandidates) {
+  const currentCandidateKey = normalizeOptionalKey(input.request.currentCandidateKey);
+  const candidates = input.candidates.map(normalizeCandidate).sort((a, b) => compareCodexFleetCanonicalStringsV1(a.key, b.key));
+  for (let index = 1; index < candidates.length; index += 1) {
+    if (candidates[index - 1].key === candidates[index].key) {
+      throw new Error(`Duplicate Codex fleet candidate key: ${candidates[index].key}`);
+    }
+  }
+  let bounded = candidates.slice(0, maxCandidates);
+  if (currentCandidateKey && candidates.some((candidate) => candidate.key === currentCandidateKey) && !bounded.some((candidate) => candidate.key === currentCandidateKey)) {
+    bounded = [
+      ...bounded.slice(0, Math.max(0, maxCandidates - 1)),
+      candidates.find((candidate) => candidate.key === currentCandidateKey)
+    ].sort((a, b) => compareCodexFleetCanonicalStringsV1(a.key, b.key));
+  }
+  return {
+    input: {
+      observedAtMs: normalizeInteger(input.observedAtMs, 0, Number.MAX_SAFE_INTEGER),
+      request: {
+        placement: input.request.placement === "fenced_in_flight" ? "fenced_in_flight" : "new",
+        priority: input.request.priority === "manager" ? "manager" : "standard",
+        currentCandidateKey,
+        waitAgeMs: normalizeInteger(input.request.waitAgeMs, 0, MAX_DURATION_MS),
+        overlayKey: normalizeOptionalKey(input.request.overlayKey),
+        overlayMode: input.request.overlayMode === "isolate" ? "isolate" : input.request.overlayMode === "prefer" ? "prefer" : "none"
+      },
+      admission: {
+        dynamicCapacityUnits: input.admission.dynamicCapacityUnits === null ? null : normalizeInteger(input.admission.dynamicCapacityUnits, 0, MAX_COUNT),
+        inUseUnits: normalizeInteger(input.admission.inUseUnits, 0, MAX_COUNT),
+        queuedManagerCount: normalizeInteger(input.admission.queuedManagerCount, 0, MAX_COUNT),
+        emergencyFuseActive: input.admission.emergencyFuseActive === true
+      },
+      candidates: bounded
+    },
+    truncatedCandidateCount: candidates.length - bounded.length
+  };
+}
+function normalizeCandidate(candidate) {
+  return {
+    key: normalizeKey(candidate.key),
+    status: candidate.status === "active" || candidate.status === "needs_relogin" || candidate.status === "error" ? candidate.status : "unknown",
+    allocatorEnabled: candidate.allocatorEnabled === true,
+    cooldownRemainingMs: normalizeNullableInteger(
+      candidate.cooldownRemainingMs,
+      0,
+      MAX_DURATION_MS
+    ),
+    activeLeaseCount: normalizeInteger(candidate.activeLeaseCount, 0, MAX_COUNT),
+    quota: {
+      primary: normalizeQuotaWindow(candidate.quota.primary),
+      secondary: normalizeQuotaWindow(candidate.quota.secondary),
+      checkedAgeMs: normalizeNullableInteger(candidate.quota.checkedAgeMs, 0, MAX_DURATION_MS),
+      confidence: normalizeConfidence(candidate.quota.confidence)
+    },
+    cache: {
+      hitRatio: normalizeNullableNumber(candidate.cache.hitRatio, 0, 1, 4),
+      sampledTokens: normalizeNullableInteger(candidate.cache.sampledTokens, 0, MAX_COUNT),
+      checkedAgeMs: normalizeNullableInteger(candidate.cache.checkedAgeMs, 0, MAX_DURATION_MS),
+      confidence: normalizeConfidence(candidate.cache.confidence),
+      state: normalizeCacheState(candidate.cache.state),
+      thresholdObservedForMs: normalizeNullableInteger(
+        candidate.cache.thresholdObservedForMs,
+        0,
+        MAX_DURATION_MS
+      )
+    },
+    observedBurn: {
+      primaryPercentPerHour: normalizeNullableNumber(
+        candidate.observedBurn.primaryPercentPerHour,
+        0,
+        100,
+        3
+      ),
+      secondaryPercentPerHour: normalizeNullableNumber(
+        candidate.observedBurn.secondaryPercentPerHour,
+        0,
+        100,
+        3
+      ),
+      confidence: normalizeConfidence(candidate.observedBurn.confidence)
+    },
+    inferredUnexplainedBurn: {
+      primaryPercentPerHour: normalizeNullableNumber(
+        candidate.inferredUnexplainedBurn.primaryPercentPerHour,
+        0,
+        100,
+        3
+      ),
+      secondaryPercentPerHour: normalizeNullableNumber(
+        candidate.inferredUnexplainedBurn.secondaryPercentPerHour,
+        0,
+        100,
+        3
+      ),
+      confidence: normalizeConfidence(candidate.inferredUnexplainedBurn.confidence)
+    },
+    overlayKeys: [...new Set(candidate.overlayKeys.map(normalizeKey))].sort(compareCodexFleetCanonicalStringsV1).slice(0, CODEX_FLEET_POLICY_MAX_OVERLAYS_PER_CANDIDATE)
+  };
+}
+function normalizeQuotaWindow(window) {
+  return {
+    usedPercent: normalizeNullableNumber(window.usedPercent, 0, 100, 3),
+    resetRemainingMs: normalizeNullableInteger(window.resetRemainingMs, 0, MAX_DURATION_MS)
+  };
+}
+function normalizePolicy(policy) {
+  const quotaFreshForMs = normalizeInteger(policy.quotaFreshForMs, 1, MAX_DURATION_MS);
+  const cacheCollapseThreshold = normalizeNumber(policy.cacheCollapseThreshold, 0, 1, 4);
+  return {
+    maxCandidates: normalizeInteger(policy.maxCandidates, 1, CODEX_FLEET_POLICY_MAX_CANDIDATES),
+    quotaFreshForMs,
+    quotaStaleAfterMs: normalizeInteger(policy.quotaStaleAfterMs, quotaFreshForMs, MAX_DURATION_MS),
+    placementUsageCeilingPercent: normalizeNumber(policy.placementUsageCeilingPercent, 1, 100, 3),
+    cacheFreshForMs: normalizeInteger(policy.cacheFreshForMs, 1, MAX_DURATION_MS),
+    cacheCollapseThreshold,
+    cacheCollapseRecoveryThreshold: normalizeNumber(
+      policy.cacheCollapseRecoveryThreshold,
+      cacheCollapseThreshold,
+      1,
+      4
+    ),
+    cacheMinimumSampledTokens: normalizeInteger(policy.cacheMinimumSampledTokens, 1, MAX_COUNT),
+    cacheCollapseDwellMs: normalizeInteger(policy.cacheCollapseDwellMs, 1, MAX_DURATION_MS),
+    cacheRecoveryDwellMs: normalizeInteger(policy.cacheRecoveryDwellMs, 1, MAX_DURATION_MS),
+    activeLeaseScore: normalizeNumber(policy.activeLeaseScore, 0, MAX_COUNT, 3),
+    unknownQuotaScore: normalizeNumber(policy.unknownQuotaScore, 0, MAX_COUNT, 3),
+    lowQuotaConfidenceScore: normalizeNumber(policy.lowQuotaConfidenceScore, 0, MAX_COUNT, 3),
+    mediumQuotaConfidenceScore: normalizeNumber(policy.mediumQuotaConfidenceScore, 0, MAX_COUNT, 3),
+    inferredBurnScorePerPercentHour: normalizeNumber(
+      policy.inferredBurnScorePerPercentHour,
+      0,
+      MAX_COUNT,
+      3
+    ),
+    observedBurnScorePerPercentHour: normalizeNumber(
+      policy.observedBurnScorePerPercentHour,
+      0,
+      MAX_COUNT,
+      3
+    ),
+    runwayRiskCapHours: normalizeNumber(policy.runwayRiskCapHours, 0, 24 * 31, 3),
+    runwayScorePerAtRiskHour: normalizeNumber(policy.runwayScorePerAtRiskHour, 0, MAX_COUNT, 3),
+    healthyCacheAffinityBenefit: normalizeNumber(
+      policy.healthyCacheAffinityBenefit,
+      0,
+      MAX_COUNT,
+      3
+    ),
+    unknownCacheAffinityBenefit: normalizeNumber(
+      policy.unknownCacheAffinityBenefit,
+      0,
+      MAX_COUNT,
+      3
+    ),
+    collapsedCacheAffinityBenefit: normalizeNumber(
+      policy.collapsedCacheAffinityBenefit,
+      0,
+      MAX_COUNT,
+      3
+    ),
+    switchHysteresisScore: normalizeNumber(policy.switchHysteresisScore, 0, MAX_COUNT, 3),
+    admissionPacingEnabled: policy.admissionPacingEnabled === true,
+    managerPriorityEnabled: policy.managerPriorityEnabled === true,
+    managerStandardStarvationMs: normalizeInteger(
+      policy.managerStandardStarvationMs,
+      1,
+      MAX_DURATION_MS
+    ),
+    emergencyFuseEnabled: policy.emergencyFuseEnabled === true,
+    overlaysEnabled: policy.overlaysEnabled === true,
+    overlayPreferenceScore: normalizeNumber(policy.overlayPreferenceScore, 0, MAX_COUNT, 3)
+  };
+}
+function normalizeConfidence(value) {
+  return value === "high" || value === "medium" || value === "low" ? value : "unknown";
+}
+function normalizeCacheState(value) {
+  return value === "healthy" || value === "collapsed" ? value : "unknown";
+}
+function confidenceWeight(confidence) {
+  if (confidence === "high") return 1;
+  if (confidence === "medium") return 0.6;
+  if (confidence === "low") return 0.25;
+  return 0;
+}
+function lowerConfidence(value, ceiling) {
+  return confidenceWeight(value) < confidenceWeight(ceiling) ? value : ceiling;
+}
+function normalizeKey(value) {
+  if (!/^[a-zA-Z0-9._:-]{1,32}$/.test(value)) {
+    throw new Error("Codex fleet candidate/overlay keys must be 1-32 opaque safe characters");
+  }
+  return value;
+}
+function normalizeOptionalKey(value) {
+  return value === null ? null : normalizeKey(value);
+}
+function normalizeNullableNumber(value, min, max, decimals) {
+  return value === null ? null : normalizeNumber(value, min, max, decimals);
+}
+function normalizeNumber(value, min, max, decimals) {
+  const finite = Number.isFinite(value) ? value : min;
+  const clamped = Math.min(max, Math.max(min, finite));
+  const scale = 10 ** decimals;
+  return Math.round(clamped * scale) / scale;
+}
+function normalizeNullableInteger(value, min, max) {
+  return value === null ? null : normalizeInteger(value, min, max);
+}
+function normalizeInteger(value, min, max) {
+  return Math.round(normalizeNumber(value, min, max, 0));
+}
+function readCodexFleetDecisionV1(value, candidateKeys) {
+  const decision = strictRecord(value, [
+    "outcome",
+    "selectedCandidateKey",
+    "reason",
+    "admission",
+    "borrowedOverlayCapacity",
+    "strandedEligibleCount",
+    "confidence",
+    "scores"
+  ]);
+  const outcome = strictEnum(decision.outcome, ["selected", "paced", "none"]);
+  const selectedCandidateKey = strictOptionalKey(decision.selectedCandidateKey);
+  const reason = strictEnum(decision.reason, [
+    "fenced_in_flight",
+    "fenced_candidate_missing",
+    "admission_paced",
+    "no_eligible_candidate",
+    "overlay_isolated_empty",
+    "best_score",
+    "affinity_best",
+    "hysteresis_hold"
+  ]);
+  const admissionRecord = strictRecord(decision.admission, [
+    "outcome",
+    "reason",
+    "borrowedIdleCapacity"
+  ]);
+  const admission = {
+    outcome: strictEnum(admissionRecord.outcome, ["admit", "pace"]),
+    reason: strictEnum(admissionRecord.reason, [
+      "fenced_in_flight",
+      "pacing_disabled",
+      "capacity_unknown",
+      "capacity_available",
+      "work_conserving_borrow",
+      "manager_priority",
+      "standard_starvation_bound",
+      "capacity_saturated",
+      "emergency_fuse"
+    ]),
+    borrowedIdleCapacity: strictBoolean(admissionRecord.borrowedIdleCapacity)
+  };
+  if (!Array.isArray(decision.scores) || decision.scores.length > candidateKeys.size) {
+    throw new Error("Codex fleet replay decision scores are not a bounded array");
+  }
+  const scores = decision.scores.map(readCodexFleetScoreV1);
+  if (new Set(scores.map((score) => score.candidateKey)).size !== scores.length || scores.some((score) => !candidateKeys.has(score.candidateKey))) {
+    throw new Error("Codex fleet replay decision has invalid candidate scores");
+  }
+  const borrowedOverlayCapacity = strictBoolean(decision.borrowedOverlayCapacity);
+  const strandedEligibleCount = strictInteger(decision.strandedEligibleCount, 0, MAX_COUNT);
+  const selectedReasons = [
+    "fenced_in_flight",
+    "best_score",
+    "affinity_best",
+    "hysteresis_hold"
+  ];
+  const noneReasons = [
+    "fenced_candidate_missing",
+    "no_eligible_candidate",
+    "overlay_isolated_empty"
+  ];
+  const paceReasons = ["manager_priority", "capacity_saturated", "emergency_fuse"];
+  const consistent = outcome === "selected" ? selectedCandidateKey !== null && admission.outcome === "admit" && selectedReasons.includes(reason) && scores.some((score) => score.candidateKey === selectedCandidateKey) : outcome === "paced" ? selectedCandidateKey === null && reason === "admission_paced" && admission.outcome === "pace" && paceReasons.includes(admission.reason) : selectedCandidateKey === null && admission.outcome === "admit" && noneReasons.includes(reason);
+  if (!consistent || strandedEligibleCount > candidateKeys.size || admission.borrowedIdleCapacity !== (admission.reason === "work_conserving_borrow") || borrowedOverlayCapacity && (outcome !== "selected" || strandedEligibleCount !== 0)) {
+    throw new Error("Codex fleet replay decision is internally inconsistent");
+  }
+  return {
+    outcome,
+    selectedCandidateKey,
+    reason,
+    admission,
+    borrowedOverlayCapacity,
+    strandedEligibleCount,
+    confidence: strictConfidence(decision.confidence),
+    scores
+  };
+}
+function readCodexFleetScoreV1(value) {
+  const score = strictRecord(value, [
+    "candidateKey",
+    "eligible",
+    "rejectionReason",
+    "quotaPressure",
+    "leasePressure",
+    "observedBurnPressure",
+    "inferredBurnPressure",
+    "runwayPressure",
+    "uncertaintyPressure",
+    "cacheAffinityBenefit",
+    "cacheState",
+    "overlayPreferenceBenefit",
+    "total",
+    "confidence"
+  ]);
+  const parsed = {
+    candidateKey: normalizeKey(strictString(score.candidateKey)),
+    eligible: strictBoolean(score.eligible),
+    rejectionReason: score.rejectionReason === null ? null : strictEnum(score.rejectionReason, [
+      "allocator_disabled",
+      "unavailable",
+      "cooling",
+      "quota_ceiling",
+      "overlay_isolation"
+    ]),
+    quotaPressure: strictFiniteNumber(score.quotaPressure, 0, Number.MAX_SAFE_INTEGER),
+    leasePressure: strictFiniteNumber(score.leasePressure, 0, Number.MAX_SAFE_INTEGER),
+    observedBurnPressure: strictFiniteNumber(
+      score.observedBurnPressure,
+      0,
+      Number.MAX_SAFE_INTEGER
+    ),
+    inferredBurnPressure: strictFiniteNumber(
+      score.inferredBurnPressure,
+      0,
+      Number.MAX_SAFE_INTEGER
+    ),
+    runwayPressure: strictFiniteNumber(score.runwayPressure, 0, Number.MAX_SAFE_INTEGER),
+    uncertaintyPressure: strictFiniteNumber(score.uncertaintyPressure, 0, Number.MAX_SAFE_INTEGER),
+    cacheAffinityBenefit: strictFiniteNumber(
+      score.cacheAffinityBenefit,
+      0,
+      Number.MAX_SAFE_INTEGER
+    ),
+    cacheState: strictEnum(score.cacheState, ["unknown", "healthy", "collapsed"]),
+    overlayPreferenceBenefit: strictFiniteNumber(
+      score.overlayPreferenceBenefit,
+      0,
+      Number.MAX_SAFE_INTEGER
+    ),
+    total: strictFiniteNumber(score.total, -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER),
+    confidence: strictConfidence(score.confidence)
+  };
+  const expectedTotal = parsed.quotaPressure + parsed.leasePressure + parsed.observedBurnPressure + parsed.inferredBurnPressure + parsed.runwayPressure + parsed.uncertaintyPressure - parsed.cacheAffinityBenefit - parsed.overlayPreferenceBenefit;
+  if (parsed.eligible !== (parsed.rejectionReason === null) || parsed.total !== expectedTotal) {
+    throw new Error("Codex fleet replay score is internally inconsistent");
+  }
+  return parsed;
+}
+function strictRecord(value, expectedKeys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new Error("Codex fleet replay value must be a plain object");
+  }
+  const record = value;
+  const actualKeys = Object.keys(record).sort(compareCodexFleetCanonicalStringsV1);
+  const canonicalExpected = [...expectedKeys].sort(compareCodexFleetCanonicalStringsV1);
+  if (canonicalJson(actualKeys) !== canonicalJson(canonicalExpected)) {
+    throw new Error("Codex fleet replay object has missing or unknown fields");
+  }
+  return record;
+}
+function strictEnum(value, values) {
+  if (typeof value !== "string" || !values.includes(value)) {
+    throw new Error("Codex fleet replay enum value is invalid");
+  }
+  return value;
+}
+function strictConfidence(value) {
+  return strictEnum(value, ["unknown", "low", "medium", "high"]);
+}
+function strictString(value) {
+  if (typeof value !== "string") throw new Error("Codex fleet replay value must be a string");
+  return value;
+}
+function strictOptionalKey(value) {
+  return value === null ? null : normalizeKey(strictString(value));
+}
+function strictBoolean(value) {
+  if (typeof value !== "boolean") throw new Error("Codex fleet replay value must be boolean");
+  return value;
+}
+function strictFiniteNumber(value, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+    throw new Error("Codex fleet replay numeric value is invalid");
+  }
+  return value;
+}
+function strictInteger(value, min, max) {
+  const number = strictFiniteNumber(value, min, max);
+  if (!Number.isInteger(number)) throw new Error("Codex fleet replay value must be an integer");
+  return number;
+}
+function strictSha256(value) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new Error("Codex fleet replay fingerprint must be lowercase SHA-256");
+  }
+  return value;
+}
+function fingerprint(value) {
+  const serialized = canonicalJson(value);
+  return bytesToHex(sha256(new TextEncoder().encode(serialized)));
+}
+function fingerprintReplayInput(input, truncatedCandidateCount) {
+  return fingerprint({ input, truncatedCandidateCount });
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => compareCodexFleetCanonicalStringsV1(left, right)).map(([key, child]) => [key, sortJson(child)])
+    );
+  }
+  return value;
+}
+
 // src/index.ts
 var SessionStatus = z2.enum([
   "queued",
@@ -1226,6 +2099,8 @@ var ErrorCode = z2.enum([
   "conflict",
   "idempotency_conflict",
   "limit_exceeded",
+  "nested_agent_depth_exceeded",
+  "nested_agent_depth_override_forbidden",
   "provider_verification_failed",
   "upstream_unavailable",
   "internal_error"
@@ -1238,6 +2113,32 @@ var ErrorEnvelope = z2.object({
     details: z2.record(z2.string(), z2.unknown()).optional()
   })
 });
+var MAX_NESTED_AGENT_DEPTH = 2147483647;
+var NestedAgentDepthValue = z2.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+var NestedAgentDepthAttemptValue = z2.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH + 1);
+var NestedAgentDepthPolicySource = z2.enum([
+  "session",
+  "workspace",
+  "deployment",
+  "default"
+]);
+var SessionSpawnDenial = z2.object({
+  id: z2.string().uuid(),
+  accountId: z2.string().uuid(),
+  workspaceId: z2.string().uuid(),
+  parentSessionId: z2.string().uuid().nullable(),
+  rootSessionId: z2.string().uuid().nullable(),
+  currentDepth: NestedAgentDepthValue,
+  attemptedDepth: NestedAgentDepthAttemptValue,
+  effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+  requestedMaxNestedAgentDepthOverride: NestedAgentDepthValue.nullable(),
+  policySource: NestedAgentDepthPolicySource,
+  policySessionId: z2.string().uuid().nullable(),
+  subjectId: z2.string().nullable(),
+  code: z2.enum(["nested_agent_depth_exceeded", "nested_agent_depth_override_forbidden"]),
+  idempotencyKey: z2.string().nullable(),
+  createdAt: z2.string()
+});
 var Permission = z2.enum([
   "account:read",
   "account:admin",
@@ -1599,7 +2500,10 @@ var WorkspaceTranscriptionPolicy = z2.object({
 });
 var WorkspaceSettingsSchema = z2.object({
   memoryEnabled: z2.boolean().optional(),
-  transcription: WorkspaceTranscriptionPolicy.optional()
+  transcription: WorkspaceTranscriptionPolicy.optional(),
+  // null clears the workspace override and falls back to the persisted
+  // deployment policy. The database boundary validates the same range.
+  maxNestedAgentDepth: NestedAgentDepthValue.nullable().optional()
 }).passthrough();
 function resolveWorkspaceMemoryEnabled(settings) {
   const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
@@ -1607,7 +2511,8 @@ function resolveWorkspaceMemoryEnabled(settings) {
 }
 var UpdateWorkspaceSettingsRequest = z2.object({
   memoryEnabled: z2.boolean().optional(),
-  transcription: WorkspaceTranscriptionPolicy.optional()
+  transcription: WorkspaceTranscriptionPolicy.optional(),
+  maxNestedAgentDepth: NestedAgentDepthValue.nullable().optional()
 }).passthrough();
 var SetWorkspaceDefaultRigRequest = z2.object({
   rigId: z2.string().uuid().nullable()
@@ -2678,7 +3583,7 @@ function reasoningEffortForMetadata(metadata, fallback) {
   return value === "none" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh" ? value : fallback;
 }
 function stableJson(value) {
-  return JSON.stringify(sortJson(value));
+  return JSON.stringify(sortJson2(value));
 }
 function resourceIdentityKey(resource) {
   if (resource.kind === "file") {
@@ -2686,13 +3591,13 @@ function resourceIdentityKey(resource) {
   }
   return `repository:${resource.uri}`;
 }
-function sortJson(value) {
+function sortJson2(value) {
   if (Array.isArray(value)) {
-    return value.map(sortJson);
+    return value.map(sortJson2);
   }
   if (value && typeof value === "object") {
     return Object.fromEntries(
-      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson(nested)])
+      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, sortJson2(nested)])
     );
   }
   return value;
@@ -2729,6 +3634,35 @@ var SessionGoalPausedReason = z2.enum([
   "max_auto_continuations",
   "limits"
 ]);
+var SessionGoalContinuationState = z2.enum([
+  "inactive",
+  "scheduled",
+  "running",
+  "blocked",
+  "invariant_broken"
+]);
+var SessionGoalContinuationReason = z2.enum([
+  "goal_inactive",
+  "wake_pending",
+  "continuation_pending",
+  "human_work_pending",
+  "goal_turn_running",
+  "human_turn_running",
+  "workstream_paused",
+  "approval_required",
+  "provider_backpressure",
+  "session_cancelled",
+  "system_work_pending",
+  "missing_obligation"
+]);
+var SessionGoalContinuation = z2.object({
+  state: SessionGoalContinuationState,
+  reason: SessionGoalContinuationReason,
+  wakeRevision: z2.number().int().nonnegative(),
+  observedRevision: z2.number().int().nonnegative(),
+  nextAttemptAt: z2.string().datetime({ offset: true }).nullable(),
+  lastError: z2.string().nullable()
+});
 var SessionGoal = z2.object({
   id: z2.string().uuid(),
   accountId: z2.string().uuid(),
@@ -2746,6 +3680,9 @@ var SessionGoal = z2.object({
   noProgressStreak: z2.number().int().nonnegative(),
   maxAutoContinuations: z2.number().int().positive().nullable(),
   metadata: z2.record(z2.string(), z2.unknown()),
+  // Optional for source compatibility with older clients; the API always
+  // supplies this authoritative continuation projection.
+  continuation: SessionGoalContinuation.optional(),
   createdAt: z2.string(),
   updatedAt: z2.string()
 });
@@ -3031,6 +3968,33 @@ var SaveComposerDraftRequest = ComposerDraft.pick({
   model: true,
   reasoningEffort: true
 }).extend({ expectedRevision: z2.number().int().nonnegative() });
+var NewSessionDraftOptions = z2.object({
+  sandboxBackend: SandboxBackend.optional(),
+  targetSandboxId: z2.string().uuid().optional(),
+  workingDir: z2.string().min(1).optional(),
+  variableSetId: z2.string().uuid().optional(),
+  rigId: z2.string().uuid().optional(),
+  goal: GoalSpec.optional(),
+  firstPartyMcpPermissions: z2.array(Permission).optional()
+});
+var NewSessionDraft = z2.object({
+  revision: z2.number().int().nonnegative(),
+  text: z2.string(),
+  resources: z2.array(ResourceRef),
+  tools: z2.array(ToolRef),
+  model: z2.string().min(1),
+  reasoningEffort: ReasoningEffort,
+  options: NewSessionDraftOptions,
+  updatedAt: z2.string().nullable()
+});
+var SaveNewSessionDraftRequest = NewSessionDraft.pick({
+  text: true,
+  resources: true,
+  tools: true,
+  model: true,
+  reasoningEffort: true,
+  options: true
+}).extend({ expectedRevision: z2.number().int().nonnegative() });
 var WORKSPACE_CONTROL_REASON_MAX_BYTES = 8 * 1024;
 var WORKSPACE_CONTROL_ACTOR_MAX_BYTES = 1024;
 var WORKSPACE_CONTROL_EVENT_MAX_BYTES = 16 * 1024;
@@ -3435,7 +4399,10 @@ var ScheduledTaskAgentConfig = z2.object({
   model: z2.string().min(1).optional(),
   reasoningEffort: ReasoningEffort.optional(),
   sandboxBackend: SandboxBackend.optional(),
-  goal: GoalSpec.optional()
+  goal: GoalSpec.optional(),
+  // Durable task override. Scheduled dispatch is trusted to preserve this
+  // snapshot even if the workspace/deployment policy narrows later.
+  maxNestedAgentDepth: NestedAgentDepthValue.optional()
 });
 var ScheduledTask = z2.object({
   id: z2.string().uuid(),
@@ -4018,6 +4985,14 @@ var Session = z2.object({
   // direct API creates and scheduled-task runs. When set, this session's
   // terminal-for-now transitions wake the parent.
   parentSessionId: z2.string().uuid().nullable(),
+  // Server-authored nested-agent lineage/policy. Root sessions are depth 0;
+  // snapshots are immutable and govern only future descendant creation.
+  rootSessionId: z2.string().uuid(),
+  nestedAgentDepth: NestedAgentDepthValue,
+  maxNestedAgentDepthOverride: NestedAgentDepthValue.nullable(),
+  effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+  nestedAgentDepthPolicySource: NestedAgentDepthPolicySource,
+  nestedAgentDepthPolicySessionId: z2.string().uuid().nullable(),
   // Workspace-scoped CREATE idempotency key the session was created under (the
   // dedup target collapsing double-submit/retry races to one session); null
   // when the create carried no key.
@@ -4202,6 +5177,10 @@ var SessionEventType = z2.enum([
   // credential allocator per-turn selection audit. Payload is metadata only: credential row
   // id, bounded strategy/reason, and pool counts — never token material.
   "codex.credential.selected",
+  // Adaptive fleet shadow decision record. Contains only bounded opaque candidate aliases,
+  // normalized pressure/cache/confidence features, deterministic fingerprints,
+  // the actual-vs-shadow comparison, and no credential/account identity.
+  "codex.fleet.decision",
   // credential allocator durable zero-capacity wait lifecycle. Runtime/system events only;
   // no synthetic user message is created when capacity returns.
   "codex.capacity.waiting",
@@ -4577,7 +5556,7 @@ var TerminalPtyOutputDeltaPayload = z2.object({
 var TerminalPtyExitedPayload = z2.object({
   ptyId: z2.string().uuid(),
   exitCode: z2.number().int().nullable(),
-  reason: z2.enum(["exit", "killed", "owner_gone", "timeout"])
+  reason: z2.enum(["exit", "killed", "owner_gone", "timeout", "lost"])
 });
 var FsNodeType = z2.enum(["file", "dir", "symlink", "other"]);
 var FsTreeNode = z2.lazy(
@@ -4930,7 +5909,8 @@ var TerminalExecRequest = z2.object({
   command: z2.string().min(1),
   cwd: z2.string().default(""),
   // workspace-relative
-  // Soft per-call wall-clock bound (the box yields output back when reached).
+  // Hard wall-clock bound. A timeout response is returned only after the exact
+  // provider process is physically absent and any retained admission settles.
   timeoutMs: z2.number().int().positive().max(12e4).default(3e4),
   // Stream the deltas onto A1 as the agent firehose (so other viewers see it),
   // in addition to returning the buffered result inline.
@@ -4939,10 +5919,10 @@ var TerminalExecRequest = z2.object({
 var TerminalExecResponse = z2.object({
   stdout: z2.string(),
   stderr: z2.string(),
-  exitCode: z2.number().int().nullable(),
-  // True when the process was still running when the call yielded (a long
-  // command); the remaining output drains onto A1 if emitStream was set.
-  running: z2.boolean(),
+  exitCode: z2.number().int(),
+  // Retained for wire compatibility; synchronous exec never exposes a live
+  // provider process. Interactive work uses the PTY API.
+  running: z2.literal(false),
   wallTimeSeconds: z2.number().nonnegative()
 });
 var PtyOpenRequest = z2.object({
@@ -5665,6 +6645,14 @@ var CreateSessionRequest = withVariableSetIdAlias({
   // creation of a brand-new session. Absent means no create-dedup (each call
   // is an independent create).
   idempotencyKey: z2.string().min(1).max(200).optional(),
+  // The exact actor-private pre-session draft revision represented by this
+  // create. The durable initializer consumes only this revision. A newer draft
+  // written by a sibling tab survives, while every failed pre-initialization
+  // create leaves the submitted draft intact.
+  expectedNewSessionDraftRevision: z2.number().int().nonnegative().optional(),
+  // A child may lower its inherited limit freely; an increase requires
+  // workspace:admin and is checked again at the DB transaction boundary.
+  maxNestedAgentDepth: NestedAgentDepthValue.optional(),
   // Permissions the session's first-party MCP token should carry. A top-level
   // omission uses the deployment's worker default; a child omission inherits
   // the creating session's effective grant. An explicit set is capped at
@@ -5969,6 +6957,9 @@ var SessionCapabilities = z2.object({
   liveness: z2.enum(["cold", "warming", "warm", "draining"]),
   // Echoed on viewer heartbeats (the split-brain fence).
   leaseEpoch: z2.number().int().nonnegative(),
+  workspaceGeneration: z2.number().int().nonnegative().nullable().default(null),
+  archiveGeneration: z2.number().int().nonnegative().nullable().default(null),
+  archiveComplete: z2.boolean().default(false),
   viewerHeartbeatIntervalMs: z2.number().int().positive().default(3e4),
   FileSystem: z2.object({
     available: z2.boolean(),
@@ -6052,6 +7043,9 @@ var ViewerHolder = z2.object({
   liveness: z2.enum(["cold", "warming", "warm", "draining"]),
   // The epoch the viewer is fenced on; echoed back on heartbeats.
   leaseEpoch: z2.number().int().nonnegative(),
+  workspaceGeneration: z2.number().int().nonnegative().nullable(),
+  archiveGeneration: z2.number().int().nonnegative().nullable(),
+  archiveComplete: z2.boolean(),
   viewerHeartbeatIntervalMs: z2.number().int().positive(),
   // The desktop pixel tunnel URL the viewer connects to directly; null until
   // a viewer grant is minted (gated until then).
@@ -6266,6 +7260,9 @@ var MachineView = z2.object({
   state: MachineState,
   active: z2.boolean(),
   isSessionGroup: z2.boolean(),
+  workspaceGeneration: z2.number().int().nonnegative().nullable(),
+  archiveGeneration: z2.number().int().nonnegative().nullable(),
+  archiveComplete: z2.boolean(),
   os: z2.string(),
   arch: z2.string(),
   hasDisplay: z2.boolean(),
@@ -6300,7 +7297,10 @@ var SwapActiveSandboxResponse = z2.object({
     "offline_enrollment",
     "unsupported_backend_context",
     "transient_establishment",
-    "concurrent_swap"
+    "concurrent_swap",
+    "recovery_in_progress",
+    "recovery_degraded",
+    "recovery_unrecoverable"
   ]).optional()
 });
 var MachineMetricsSeriesResponse = z2.object({
@@ -6663,6 +7663,10 @@ export {
   CAPABILITY_DESCRIPTORS,
   CLEARED_RUN_STATE_BLOB,
   CLEARED_RUN_STATE_MARKER,
+  CODEX_FLEET_POLICY_MAX_CANDIDATES,
+  CODEX_FLEET_POLICY_MAX_OVERLAYS_PER_CANDIDATE,
+  CODEX_FLEET_POLICY_SCHEMA_VERSION,
+  CODEX_FLEET_POLICY_VERSION,
   CapabilityCatalogAuthKind,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
@@ -6714,6 +7718,7 @@ export {
   CreateWorkspaceEnvironmentRequest,
   CreateWorkspaceRequest,
   CredentialAuthNeededPayload,
+  DEFAULT_CODEX_FLEET_POLICY_V1,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   DESKTOP_STREAM_PORT,
   DelegatedAccessTokenPayload,
@@ -6837,6 +7842,7 @@ export {
   ListConnectionsResponse,
   ListEnrollmentsResponse,
   ListWorkspaceMembersResponse,
+  MAX_NESTED_AGENT_DEPTH,
   MachineKind,
   MachineMetricsSeriesResponse,
   MachineState,
@@ -6859,6 +7865,11 @@ export {
   ModelPricingScheduleV1,
   ModelPricingV1,
   MoveSessionQueueItemRequest,
+  NestedAgentDepthAttemptValue,
+  NestedAgentDepthPolicySource,
+  NestedAgentDepthValue,
+  NewSessionDraft,
+  NewSessionDraftOptions,
   OAuthStartRequest,
   OAuthStartResponse,
   OPENGENI_API_CONTRACT_HEADER,
@@ -6931,6 +7942,7 @@ export {
   SandboxCommandOutputDeltaPayload,
   SandboxOs,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   ScheduledTask,
   ScheduledTaskAgentConfig,
   ScheduledTaskOverlapPolicy,
@@ -6965,6 +7977,9 @@ export {
   SessionEventSemanticClass,
   SessionEventType,
   SessionGoal,
+  SessionGoalContinuation,
+  SessionGoalContinuationReason,
+  SessionGoalContinuationState,
   SessionGoalCreatedBy,
   SessionGoalPausedReason,
   SessionGoalStatus,
@@ -6978,6 +7993,7 @@ export {
   SessionMcpServerMetadata,
   SessionQueueMutationResponse,
   SessionQueueSnapshot,
+  SessionSpawnDenial,
   SessionStatus,
   SessionStructuredCapabilities,
   SessionSystemUpdate,
@@ -7090,9 +8106,14 @@ export {
   boundSessionEvent,
   boundSessionEventPayload,
   boundWorkspaceControlEvent,
+  canonicalCodexFleetReplayJsonV1,
   capabilityCatalogItemIsTrustedForExposure,
   compactSessionEventResult,
+  compareCodexFleetCanonicalStringsV1,
+  createCodexFleetReplayRecordV1,
   defaultRepositoryMountPath,
+  effectiveCodexFleetCacheStateV1,
+  evaluateCodexFleetDecisionV1,
   evaluateWorkspaceModelPolicy,
   gitCredentialBindingIdForRepository,
   gitCredentialProviderForRepository,
@@ -7104,8 +8125,10 @@ export {
   normalizeRepositorySubpath,
   normalizeResourceMountPath,
   prefixedMcpToolName,
+  readCodexFleetReplayRecordV1,
   readTurnExecutionPolicyV1,
   reasoningEffortForMetadata,
+  replayCodexFleetDecisionV1,
   resolveRetainedOutputRange,
   resolveSessionEventTypeFilters,
   resolveWorkspaceMemoryEnabled,