@deksden-com/dd-flow-cli 0.9.0-beta.150 → 0.9.0-beta.151

package/dist/harness-runtime/lib/model-observations.mjs

@@ -29,7 +29,7 @@ export async function readModelObservations(journal) {
 
 /** Only adapter-verified native facts enter this file. It records changes,
  * not every tool or token; reading it never requires replaying native history. */
-export async function observeModel({ journal, harness, sessionId, parentSessionId = null, requested = {}, observed = {}, source, evidence = "configured", reason = null, nativeTimestamp = null, previousModel = null }) {
+export async function observeModel({ journal, harness, sessionId, parentSessionId = null, requested = {}, observed = {}, source, evidence = "configured", reason = null, nativeTimestamp = null, previousModel = null, nativeAgentRole = null }) {
   if (!journal || !sessionId) return null;
   if (!source || !["configured", "request", "response", "unavailable"].includes(evidence)) throw new Error("model observation requires a native source and evidence level");
   if (typeof source === "string") source = { channel: source, ...(["configured", "response"].includes(evidence) ? { scope: evidence } : {}) };
@@ -38,11 +38,17 @@ export async function observeModel({ journal, harness, sessionId, parentSessionI
   return withRunnerLock(file, async () => {
     const events = await readModelObservations(journal);
     const replay = source?.event_sha256 ? events.find(item => item.harness === harness && item.session_id === sessionId && observationScope(item.source) === observationScope(source) && item.source?.event_sha256 === source.event_sha256) : null;
-    if (replay) return replay;
     const previous = events.findLast(item => item.harness === harness && item.session_id === sessionId && observationScope(item.source) === observationScope(source));
     const normalizedReason = text(reason)?.slice(0, 200) ?? null;
-    if (previous && JSON.stringify(previous.observed) === JSON.stringify(profile) && previous.reason === normalizedReason && previous.evidence === evidence
-      && previous.source?.raw_model === source?.raw_model && previous.source?.raw_provider === source?.raw_provider) return previous;
+    const tuple = item => JSON.stringify([observedFields(item.requested), item.observed, item.parent_session_id ?? null, item.source, item.reason, item.evidence, item.native_agent_role ?? null]);
+    const candidate = { requested: observedFields(requested), observed: profile, parent_session_id: parentSessionId, source, reason: normalizedReason, evidence, native_agent_role: nativeAgentRole };
+    if (replay && tuple(replay) === tuple(candidate)) return replay;
+    const conflict = replay ? { code: 'model_observation_identity_conflict', original_id: replay.id } : null;
+    if (conflict) {
+      const recorded = events.find(item => item.evidence_conflict?.original_id === replay.id && tuple(item) === tuple(candidate));
+      if (recorded) return recorded;
+    }
+    if (!conflict && previous && tuple(previous) === tuple(candidate)) return previous;
     const previousKnown = events.findLast(item => item.harness === harness && item.session_id === sessionId && item.evidence === evidence && item.observed?.model
       && (item.source?.scope ?? "session") === (source?.scope ?? "session") && (item.source?.attempt_id ?? null) === (source?.attempt_id ?? null));
     const fromModel = text(previousModel) ?? previousKnown?.observed.model ?? null;
@@ -53,7 +59,8 @@ export async function observeModel({ journal, harness, sessionId, parentSessionI
       harness, session_id: sessionId, parent_session_id: parentSessionId,
       kind: changed ? "model_changed" : !profile.model ? "model_observation_unavailable" : "model_observed",
       previous_model: fromModel, requested: observedFields(requested), observed: profile,
-      source, evidence, reason: normalizedReason, native_timestamp: text(nativeTimestamp), observed_at: new Date().toISOString() };
+      source, evidence, reason: normalizedReason, native_timestamp: text(nativeTimestamp), observed_at: new Date().toISOString(),
+      ...(nativeAgentRole ? { native_agent_role: nativeAgentRole } : {}), ...(conflict ? { evidence_conflict: conflict } : {}) };
     value.id = createHash("sha256").update(JSON.stringify(value)).digest("hex");
     const handle = await open(file, "a", 0o600);
     try {
@@ -81,7 +88,12 @@ export function modelAttribution(events, expectedSessions = []) {
     : !sessions.has(`${session.harness}:${session.session_id}`));
   const models = [...new Set(events.map(event => event.observed?.model).filter(Boolean))];
   const providers = [...new Set(events.map(event => event.observed?.provider).filter(Boolean))];
-  const incomplete = !events.length || missingSessions.length > 0 || [...sessions.values()].some(session => {
+  const conflicts = events.filter(event => event.evidence_conflict).map(event => ({ session_id: event.session_id, ...event.evidence_conflict }));
+  for (const session of sessions.values()) {
+    const parents = [...new Set(session.observations.filter(event => !event.source?.non_asserting && Object.hasOwn(event, 'parent_session_id')).map(event => event.parent_session_id))];
+    if (parents.length > 1) conflicts.push({ session_id: session.session_id, code: 'model_observation_parent_conflict' });
+  }
+  const incomplete = conflicts.length > 0 || !events.length || missingSessions.length > 0 || [...sessions.values()].some(session => {
     const known = session.observations.filter(event => event.observed?.model);
     if (!known.length) return true;
     const knownScopes = new Set(known.map(event => `${event.evidence}:${event.source?.scope ?? "session"}:${event.source?.attempt_id ?? ""}:${event.source?.turn_id ?? ""}`));
@@ -97,5 +109,5 @@ export function modelAttribution(events, expectedSessions = []) {
   return { models, providers, mixed: models.length > 1 || providers.length > 1 || events.some(event => event.observed?.model && event.requested?.model && event.observed.model !== event.requested.model
     || event.observed?.provider && event.requested?.provider && event.observed.provider !== event.requested.provider),
     observation_completeness: incomplete ? "incomplete" : "available_native_sources", transitions: events.filter(event => event.kind === "model_changed"),
-    sessions: [...sessions.values()], missing_sessions: missingSessions, usage_attribution: "session_totals_unattributed_to_model", note: "Native settings/events do not prove undisclosed server routing or per-model token costs." };
+    sessions: [...sessions.values()], missing_sessions: missingSessions, ...(conflicts.length ? { evidence_conflicts: conflicts } : {}), usage_attribution: "session_totals_unattributed_to_model", note: "Native settings/events do not prove undisclosed server routing or per-model token costs." };
 }

package/dist/harness-runtime/lib/native-children.d.mts

@@ -8,6 +8,12 @@ export type NativeTreeReadiness = "ready" | "owned_children_live" | "inspection_
 export function nativeTreeReadiness(receipt: Record<string, unknown>, binding: { sessionId: string; operationId: string; turnId?: string; requestProof?: unknown; allowDescendants?: boolean }): NativeTreeReadiness;
 export function settledNativeTree(root: string, children: Record<string, unknown>[], settled: boolean, rootSettled?: boolean): Record<string, unknown>;
 export function safeNativeFailure(value: unknown): Record<string, unknown> | undefined;
+export type NativeContinuationReference = { schema_id: "zcode/child-continuation@1"; capability: "dd-flow/managed-provider-recovery@1"; agent_id: string; child_session_id: string; parent_session_id: string; parent_tool_call_id: string; terminal_turn_id: string; started_at: number; ended_at: number; task_id?: string };
+export function nativeContinuationReference(value: unknown, sessionId: string, parentId: string, turnId?: string): NativeContinuationReference | null;
+export type NativeContinuationAdmission = { schema_id: "zcode/child-admission@1"; operation_id?: string; predecessor_turn_id?: string; parent_session_id: string; child_session_id: string; agent_id: string; parent_tool_call_id: string; parent_turn_id: string } & ({ proof_kind?: "message"; message_id: string; delivery: "queued" | "steered" | "resumed_background" } | { proof_kind: "parent_tool_successor"; successor_started_at: number; successor_turn_id: string; native_evidence_sha256: string } | { proof_kind: "parent_tool_admission"; successor_started_at: number; native_evidence_sha256: string });
+export function nativeContinuationAdmission(value: unknown, sessionId: string, parentId: string): NativeContinuationAdmission | null;
+export function nativeContinuationSuccessor(child: NativeChild, predecessorTurnId?: string, predecessorEndedAt?: number): boolean;
+export function nativeContinuationAdmitted(child: NativeChild, predecessorTurnId?: string, predecessorEndedAt?: number): boolean;
 export interface NativeChild {
   session_id: string;
   parent_session_id: string;
@@ -17,7 +23,12 @@ export interface NativeChild {
   terminal_turn_id?: string;
   terminal_observed_at?: string;
   provider_error?: unknown;
-  native_source?: "opencode.v2.session.execution" | "agy.result" | "acp.error_response" | "droid.agent_turn_outcome" | "grok.subagent.event";
+  recovery_unavailable_reason?: string;
+  continuation_ref?: NativeContinuationReference;
+  continuation_admission?: NativeContinuationAdmission;
+  resumed_from_message_id?: string;
+  current_turn_id?: string;
+  native_source?: "opencode.v2.session.execution" | "agy.result" | "acp.error_response" | "droid.agent_turn_outcome" | "grok.subagent.event" | "zcode.retained-terminal";
   native_turn_items?: { observed?: boolean; possible_effects?: boolean; pending?: boolean };
 }
 export function normalizeNativeChildren(receipt: Record<string, unknown>, rootSessionId: string): NativeChild[];

package/dist/harness-runtime/lib/native-children.mjs

@@ -125,6 +125,9 @@ export function safeNativeFailure(value, depth = 0) {
   // invalid value must reach the policy as invalid, not disappear into default backoff.
   const timing = safeProviderError(value);
   if (Object.hasOwn(timing, "retryAfter")) result.retryAfter = timing.retryAfter;
+  if (Object.hasOwn(timing, "retry_after")) result.retry_after = timing.retry_after;
+  if (Object.hasOwn(timing, "retryAfterMs")) result.retryAfterMs = timing.retryAfterMs;
+  if (timing.headers) result.headers = timing.headers;
   if (typeof value.codexErrorInfo === "string" && /^[\w-]{1,128}$/.test(value.codexErrorInfo)) result.codexErrorInfo = value.codexErrorInfo;
   else if (value.codexErrorInfo && typeof value.codexErrorInfo.code === "string" && /^[\w-]{1,128}$/.test(value.codexErrorInfo.code)) result.codexErrorInfo = { code: value.codexErrorInfo.code };
   const attribution = depth === 0 && value.attribution && safeNativeFailure(value.attribution, 1);
@@ -134,6 +137,40 @@ export function safeNativeFailure(value, depth = 0) {
 
 
 /** Normalize provider-observed topology only; never parse assistant prose. */
+export function nativeContinuationReference(value, sessionId, parentId, turnId) {
+  if (value?.schema_id !== "zcode/child-continuation@1" || value.capability !== "dd-flow/managed-provider-recovery@1"
+    || value.child_session_id !== sessionId || value.parent_session_id !== parentId || value.terminal_turn_id !== turnId
+    || !/^agent_[\w-]{1,200}$/.test(value.agent_id ?? "") || ![value.parent_tool_call_id, value.terminal_turn_id].every(item => typeof item === "string" && item.length > 0 && item.length <= 256)
+    || !Number.isSafeInteger(value.started_at) || !Number.isSafeInteger(value.ended_at) || value.started_at <= 0 || value.ended_at < value.started_at) return null;
+  return { schema_id: value.schema_id, capability: value.capability, agent_id: value.agent_id, child_session_id: sessionId, parent_session_id: parentId,
+    parent_tool_call_id: value.parent_tool_call_id, terminal_turn_id: turnId, started_at: value.started_at, ended_at: value.ended_at,
+    ...(typeof value.task_id === "string" && value.task_id.length <= 256 ? { task_id: value.task_id } : {}) };
+}
+export function nativeContinuationAdmission(value, sessionId, parentId) {
+  const keys = ["parent_tool_call_id", "parent_turn_id", "agent_id"];
+  if (value?.schema_id !== "zcode/child-admission@1" || value.child_session_id !== sessionId || value.parent_session_id !== parentId
+    || !keys.every(key => typeof value[key] === "string" && value[key].length > 0 && value[key].length <= 512)) return null;
+  const successorProof = value.proof_kind === "parent_tool_successor";
+  const parentAdmission = successorProof || value.proof_kind === "parent_tool_admission";
+  if (parentAdmission ? !Number.isSafeInteger(value.successor_started_at) || value.successor_started_at <= 0 || successorProof && (typeof value.successor_turn_id !== "string" || !value.successor_turn_id || value.successor_turn_id.length > 512) || !/^[a-f0-9]{64}$/.test(value.native_evidence_sha256 ?? "")
+    : value.proof_kind !== undefined && value.proof_kind !== "message" || typeof value.message_id !== "string" || !value.message_id || value.message_id.length > 512 || !["queued", "steered", "resumed_background"].includes(value.delivery)) return null;
+  return Object.fromEntries(["schema_id", "child_session_id", "parent_session_id", ...keys,
+    ...(parentAdmission ? ["proof_kind", "successor_started_at", "native_evidence_sha256", ...(successorProof ? ["successor_turn_id"] : [])] : ["message_id", "delivery"]),
+    ...["operation_id", "predecessor_turn_id"].filter(key => typeof value[key] === "string" && value[key].length > 0 && value[key].length <= 512)].map(key => [key, value[key]]));
+}
+export function nativeContinuationSuccessor(child, predecessorTurnId, predecessorEndedAt) {
+  const admission = child?.continuation_admission, turn = child?.current_turn_id ?? child?.terminal_turn_id;
+  if (!admission?.operation_id || admission.predecessor_turn_id !== predecessorTurnId || typeof turn !== "string" || turn === predecessorTurnId) return false;
+  if (admission.proof_kind === "parent_tool_admission") return false;
+  return admission.proof_kind === "parent_tool_successor"
+    ? Number.isSafeInteger(predecessorEndedAt) && admission.successor_started_at > predecessorEndedAt && admission.successor_turn_id === turn
+    : child.resumed_from_message_id === admission.message_id;
+}
+export function nativeContinuationAdmitted(child, predecessorTurnId, predecessorEndedAt) {
+  const admission = child?.continuation_admission;
+  return Boolean(admission?.proof_kind === "parent_tool_admission" && (child.status === "running" || child.status === "failed" && child.terminal_turn_id === predecessorTurnId) && admission.operation_id
+    && admission.predecessor_turn_id === predecessorTurnId && Number.isSafeInteger(predecessorEndedAt) && admission.successor_started_at > predecessorEndedAt);
+}
 export function normalizeNativeChildren(receipt, rootSessionId) {
   const candidates = [];
   const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -173,7 +210,12 @@ export function normalizeNativeChildren(receipt, rootSessionId) {
       ...(text(value, ["terminal_turn_id"]) ? { terminal_turn_id: text(value, ["terminal_turn_id"]) } : {}),
       ...(text(value, ["terminal_observed_at"]) ? { terminal_observed_at: text(value, ["terminal_observed_at"]) } : {}),
       ...(value.provider_error !== undefined ? { provider_error: value.provider_error } : {}),
-      ...(["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event"].includes(value.native_source) ? { native_source: value.native_source } : {}),
+      ...(typeof value.recovery_unavailable_reason === "string" && /^[a-z][a-z0-9_]{0,127}$/.test(value.recovery_unavailable_reason) ? { recovery_unavailable_reason: value.recovery_unavailable_reason } : {}),
+      ...(nativeContinuationReference(value.continuation_ref, id, parent, value.terminal_turn_id) ? { continuation_ref: nativeContinuationReference(value.continuation_ref, id, parent, value.terminal_turn_id) } : {}),
+      ...(nativeContinuationAdmission(value.continuation_admission, id, parent) ? { continuation_admission: nativeContinuationAdmission(value.continuation_admission, id, parent) } : {}),
+      ...(text(value, ["resumed_from_message_id"]) ? { resumed_from_message_id: text(value, ["resumed_from_message_id"]) } : {}),
+      ...(text(value, ["current_turn_id"]) ? { current_turn_id: text(value, ["current_turn_id"]) } : {}),
+      ...(["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event", "zcode.retained-terminal"].includes(value.native_source) ? { native_source: value.native_source } : {}),
       ...(value.native_turn_items && typeof value.native_turn_items === "object" ? { native_turn_items: value.native_turn_items } : {}) });
   };
   for (const value of list(receipt.descendants)) add(value, "adapter.descendants");
@@ -190,6 +232,10 @@ export function normalizeNativeChildren(receipt, rootSessionId) {
   const terminal = value => ["completed", "failed", "cancelled", "settled_by_root"].includes(value);
   for (const child of candidates) {
     const previous = unique.get(child.session_id);
+    const successor = (current, old) => current.parent_session_id === old.parent_session_id
+      && (nativeContinuationSuccessor(current, old.terminal_turn_id, old.continuation_ref?.ended_at) || nativeContinuationAdmitted(current, old.terminal_turn_id, old.continuation_ref?.ended_at));
+    if (previous && successor(child, previous)) { unique.set(child.session_id, child); continue; }
+    if (previous && successor(previous, child)) continue;
     if (previous && (terminal(previous.status) && child.native_turn_items?.pending === true
       || terminal(child.status) && previous.native_turn_items?.pending === true))
       throw nativeFailure("native_child_observation_conflict", "Current child outcome contradicts pending native items", 1, { session_id: child.session_id, observations: [previous, child] });

package/dist/harness-runtime/lib/provider-overload-policy.d.mts

@@ -1,11 +1,19 @@
 export const CAPACITY_POLICY: "provider-overload-episode@1";
+export const RECOVERY_POLICY: "provider-recovery-episode@1";
+export function classifyRecoveryError(native: unknown): string;
+export function recoveryRetryAfter(native: unknown, now?: number): number;
+export const normalizeRecoveryFailure: typeof normalizeProviderFailure;
+export const terminalProviderRecovery: typeof terminalProviderOverload;
+export const recoveryBackoff: typeof capacityBackoff;
+export const recoveryRefusal: typeof refusalObservation;
+export const recoveryExhausted: typeof overloadExhausted;
 export const MAX_OVERLOAD_RETRIES: 3;
 export const MAX_RETRY_AFTER_MS: 30000;
 export function classifyProviderError(native: unknown): string;
 export function safeProviderError(native: unknown): Record<string, unknown>;
 export type RequestProof = { kind: "native_turn"; session_id: string; turn_id: string } | { kind: "stream_request"; daemon_instance: string; connection_id: string; operation_id: string; turn_generation: number; session_id: string; outbound_position: number; terminal_position: number };
 export function streamRequestKey(proof: unknown): string | null;
-export type CapacityRefusal = { policy: string; ordinal: number; session_id: string; turn_id: string; request_key?: string; request_proof?: RequestProof; first_observed_at: string; native_terminal_at?: string; native_terminal_basis?: string };
+export type CapacityRefusal = { policy: string; ordinal: number; session_id: string; turn_id: string; category?: string; request_key?: string; request_proof?: RequestProof; first_observed_at: string; native_terminal_at?: string; native_terminal_basis?: string };
 export function parseCapacityOperation(id: string): { root: string; ordinal: number };
 export function normalizeProviderFailure(error: unknown, sessionId?: string, turnId?: string): null | { code: string; session_id: string; turn_id: string; request_key: string; request_proof: RequestProof; native_error: Record<string, unknown>; observed_at: unknown; terminal_at: unknown; native_turn_items: unknown; primary_error: { details?: Record<string, unknown> } };
 export function terminalProviderOverload(error: unknown, sessionId?: string, turnId?: string): boolean;

package/dist/harness-runtime/lib/provider-overload-policy.mjs

@@ -2,6 +2,7 @@
 export const CAPACITY_POLICY = "provider-overload-episode@1";
 export const MAX_OVERLOAD_RETRIES = 3;
 export const MAX_RETRY_AFTER_MS = 30_000;
+export const RECOVERY_POLICY = "provider-recovery-episode@1";
 
 function policyError(code, message, details = {}) { return Object.assign(new Error(message), { code, details }); }
 
@@ -25,10 +26,28 @@ export function safeProviderError(native) {
   if (!native || typeof native !== "object") return result;
   const status = native.status ?? native.statusCode ?? native.status_code ?? native.http_status;
   if (Number.isInteger(Number(status))) result.status = Number(status);
-  const header = Object.entries(native.headers ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
-  const retry = header ?? native.retryAfter ?? native.retry_after;
+  const retryHeaders = Object.entries(native.headers ?? {}).filter(([key]) => key.toLowerCase() === "retry-after");
+  const header = retryHeaders[0]?.[1];
+  const retry = native.retryAfter ?? native.retry_after ?? header;
   if (retry !== undefined && retry !== null) result.retryAfter = typeof retry === "string" && retry.length <= 128 || typeof retry === "number" && Number.isFinite(retry) ? retry : "invalid-retry-after";
+  if (native.retry_after !== undefined && native.retry_after !== null) result.retry_after = typeof native.retry_after === "string" && native.retry_after.length <= 128 || typeof native.retry_after === "number" && Number.isFinite(native.retry_after) ? native.retry_after : "invalid-retry-after";
+  if (header !== undefined && header !== null && (native.retryAfter !== undefined || native.retry_after !== undefined || retryHeaders.length > 1)) result.headers = Object.fromEntries(retryHeaders.map(([key, value]) => [key, typeof value === "string" && value.length <= 128 || typeof value === "number" && Number.isFinite(value) ? value : "invalid-retry-after"]));
   if (typeof native.willRetry === "boolean") result.willRetry = native.willRetry;
+  for (const key of ["type", "source", "reason", "errorPhase", "exceptionKind", "transport", "retryable", "retryAfterMs"]) {
+    const value = native[key];
+    if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) || typeof value === "string" && value.length <= 128) result[key] = value;
+  }
+  if (!result.type && /^(model_request_failed|ECONNRESET|EPIPE|ETIMEDOUT|EAI_AGAIN|UND_ERR_SOCKET|UND_ERR_CONNECT_TIMEOUT|UND_ERR_HEADERS_TIMEOUT|UND_ERR_BODY_TIMEOUT)$/.test(native.code ?? "")) result.type = native.code;
+  if (Object.hasOwn(native, "retryAfterMs") && native.retryAfterMs !== null) result.retryAfterMs = typeof native.retryAfterMs === "number" && Number.isFinite(native.retryAfterMs) || typeof native.retryAfterMs === "string" && native.retryAfterMs.length <= 128 ? native.retryAfterMs : "invalid-retry-after";
+  if (native.attribution && typeof native.attribution === "object") {
+    const attribution = {};
+    for (const key of ["source", "reason", "errorPhase", "exceptionKind", "transport", "retryable", "retryAfterMs"]) {
+      const value = native.attribution[key];
+      if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) || typeof value === "string" && value.length <= 128) attribution[key] = value;
+    }
+    if (Object.hasOwn(native.attribution, "retryAfterMs") && native.attribution.retryAfterMs !== null) attribution.retryAfterMs = typeof native.attribution.retryAfterMs === "number" && Number.isFinite(native.attribution.retryAfterMs) || typeof native.attribution.retryAfterMs === "string" && native.attribution.retryAfterMs.length <= 128 ? native.attribution.retryAfterMs : "invalid-retry-after";
+    if (Object.keys(attribution).length) result.attribution = attribution;
+  }
   for (const key of ["reset_at", "resets_at", "resetAt", "resetsAt", "reset_time"]) {
     const value = native[key];
     if (typeof value === "string" && value.length <= 128 || typeof value === "number" && Number.isFinite(value)) result[key] = value;
@@ -36,6 +55,70 @@ export function safeProviderError(native) {
   return result;
 }
 
+/** New native-recovery ABI; the overload-only exports below retain their scope. */
+export function classifyRecoveryError(native) {
+  const legacy = classifyProviderError(native);
+  if (["provider_quota_exhausted", "provider_auth_failed"].includes(legacy)) return legacy;
+  if (!native || typeof native !== "object") return legacy;
+  const facts = [native, native.attribution].filter(value => value && typeof value === "object");
+  const text = [native.code, native.type, native.message, ...facts.flatMap(value => [value.reason, value.exceptionKind])].filter(value => typeof value === "string").join(" ");
+  if (facts.some(value => value.retryable === false) || /cancel|CERT_|certificate|permission|configuration/i.test(text)) return "provider_failed";
+  if (legacy === "provider_capacity_transient") return legacy;
+  if (["provider_rate_limited", "provider_limit_unknown"].includes(legacy) && facts.some(value => value.retryAfterMs !== undefined)) return "provider_rate_limited";
+  if (legacy === "provider_rate_limited") return legacy;
+  const structuredNetwork = [native.type, native.code].includes("model_request_failed") && facts.some(value => value.source === "network" && value.reason === "network_error" && value.errorPhase === "stream" && value.exceptionKind === "transport");
+  const networkSource = facts.some(value => ["network", "provider", "transport"].includes(value.source));
+  const code = [native.code, native.type, native.transport, ...facts.map(value => value.transport)].filter(value => typeof value === "string");
+  const knownCode = code.some(value => /^(ECONNRESET|EPIPE|ETIMEDOUT|EAI_AGAIN|UND_ERR_SOCKET|UND_ERR_CONNECT_TIMEOUT|UND_ERR_HEADERS_TIMEOUT|UND_ERR_BODY_TIMEOUT)$/.test(value));
+  const status = Number(native.status ?? native.statusCode ?? native.status_code ?? native.http_status);
+  return structuredNetwork || networkSource && (knownCode || [408, 502, 504].includes(status)) ? "provider_network_transient" : legacy;
+}
+
+/** All delay representations must agree; no units guessing and no moving deadline. */
+export function recoveryRetryAfter(native, now = Date.now()) {
+  if (!Number.isFinite(now)) throw policyError("capacity_retry_metadata_invalid", "Invalid recovery observation time");
+  if (!native || typeof native !== "object") return 0;
+  const values = [];
+  for (const source of [native, native.attribution].filter(value => value && typeof value === "object")) {
+    for (const key of ["retryAfterMs", "retryAfter", "retry_after"]) if (source[key] !== undefined && source[key] !== null) values.push([source[key], key === "retryAfterMs"]);
+    for (const [key, value] of Object.entries(source.headers ?? {})) if (key.toLowerCase() === "retry-after") values.push([value, false]);
+  }
+  const parsed = values.map(([value, milliseconds]) => {
+    const numeric = typeof value === "number" || typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value.trim());
+    const duration = numeric ? Number(value) * (milliseconds ? 1 : 1000) : !milliseconds && typeof value === "string" && /^\w{3}, \d{2} \w{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value.trim()) ? Math.max(0, Date.parse(value) - now) : NaN;
+    if (!numeric && Number.isFinite(duration) && new Date(Date.parse(value)).toUTCString() !== value.trim()) throw policyError("capacity_retry_metadata_invalid", "Invalid recovery HTTP date");
+    if (!Number.isFinite(duration) || duration < 0 || !Number.isFinite(now + duration) || now + duration > 8.64e15) throw policyError("capacity_retry_metadata_invalid", "Invalid recovery Retry-After metadata");
+    return duration;
+  });
+  if (parsed.some(value => value !== parsed[0])) throw policyError("capacity_retry_metadata_invalid", "Conflicting recovery Retry-After metadata");
+  return parsed[0] ?? 0;
+}
+
+export function normalizeRecoveryFailure(error, expectedSessionId, expectedTurnId) {
+  const normalized = normalizeNativeFailure(error, expectedSessionId, expectedTurnId, true);
+  if (!normalized) return null;
+  const category = classifyRecoveryError(normalized.native_error);
+  if (!["provider_capacity_transient", "provider_rate_limited", "provider_network_transient"].includes(category)) return null;
+  const nativeCode = typeof normalized.native_error.codexErrorInfo === "string" ? normalized.native_error.codexErrorInfo : normalized.native_error.codexErrorInfo?.code;
+  return { ...normalized, code: nativeCode ?? category, category };
+}
+
+export function terminalProviderRecovery(error, sessionId, turnId) { return normalizeRecoveryFailure(error, sessionId, turnId) !== null; }
+export function recoveryBackoff(error, ordinal, now = Date.now(), random = Math.random) {
+  const native = normalizeRecoveryFailure(error)?.native_error ?? error?.details?.provider_error ?? error;
+  try { return capacityBackoff({ retryAfter: recoveryRetryAfter(native, now) / 1000 }, ordinal, now, random); }
+  catch (failure) { if (failure.details?.policy === CAPACITY_POLICY) failure.details = { ...failure.details, policy: RECOVERY_POLICY }; throw failure; }
+}
+export function recoveryRefusal(error, ordinal, firstObservedAt) {
+  const failure = normalizeRecoveryFailure(error);
+  return { ...observedRefusal(failure, ordinal, firstObservedAt, RECOVERY_POLICY), category: failure.category };
+}
+export function recoveryExhausted(refusals, maxRetries = MAX_OVERLOAD_RETRIES) {
+  if (refusals.some(value => value.policy !== RECOVERY_POLICY)) throw policyError("capacity_policy_mismatch", "Retained episode uses another recovery policy");
+  const exhausted = overloadExhausted(refusals.map(value => ({ ...value, policy: CAPACITY_POLICY })), maxRetries);
+  return exhausted ? { ...exhausted, policy: RECOVERY_POLICY, reason: "provider_retries_exhausted", refusals } : null;
+}
+
 export function parseCapacityOperation(id) {
   if (typeof id !== "string" || !id) throw policyError("capacity_continuation_conflict", "Missing capacity operation identity");
   const match = /^(.*):capacity:(\d+):session\.prompt$/.exec(id);
@@ -55,17 +138,22 @@ export function streamRequestKey(proof) {
 }
 
 export function normalizeProviderFailure(error, expectedSessionId, expectedTurnId) {
+  return normalizeNativeFailure(error, expectedSessionId, expectedTurnId, false);
+}
+function normalizeNativeFailure(error, expectedSessionId, expectedTurnId, recovery) {
   let current = error;
   for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
     // The same continuation authority applies to a proven v2 execution
     // refusal. Never classify transport loss or an active native retry here.
-    if (current.code === "provider_capacity_transient" || current.code === "provider_rate_limited") {
+    if (current.code === "provider_capacity_transient" || current.code === "provider_rate_limited" || recovery && current.code === "provider_network_transient") {
       const details = current.details ?? {};
       const streamKey = details.native_source === "agy.result" && details.turn_id === undefined && details.native_turn_id === undefined ? streamRequestKey(details.request_proof) : null;
       const turnKey = streamKey ?? details.turn_id;
-      if (!["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event"].includes(details.native_source) || details.terminal_status !== "failed"
+      const sources = ["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event", ...(recovery ? ["zcode.retained-terminal"] : [])];
+      const categories = ["provider_capacity_transient", "provider_rate_limited", ...(recovery ? ["provider_network_transient"] : [])];
+      if (!sources.includes(details.native_source) || details.terminal_status !== "failed"
         || details.will_retry === true || details.native_retry_active === true || details.provider_error?.willRetry === true
-        || details.provider_error && !["provider_capacity_transient", "provider_rate_limited"].includes(classifyProviderError(details.provider_error))
+        || details.provider_error && !categories.includes((recovery ? classifyRecoveryError : classifyProviderError)(details.provider_error))
         || typeof details.provider_session_id !== "string" || !details.provider_session_id
         || typeof turnKey !== "string" || !turnKey || (streamKey ? details.request_proof.session_id !== details.provider_session_id || details.native_turn_id !== undefined : details.native_turn_id !== details.turn_id)
         || expectedSessionId !== undefined && details.provider_session_id !== expectedSessionId
@@ -123,13 +211,16 @@ export function capacityBackoff(error, ordinal, now = Date.now(), random = Math.
 
 export function refusalObservation(error, ordinal, firstObservedAt) {
   const failure = normalizeProviderFailure(error);
+  return observedRefusal(failure, ordinal, firstObservedAt, CAPACITY_POLICY);
+}
+function observedRefusal(failure, ordinal, firstObservedAt, policy) {
   const observed = Date.parse(firstObservedAt);
   if (!failure || !Number.isSafeInteger(ordinal) || ordinal < 0 || !Number.isFinite(observed))
     throw policyError("capacity_continuation_conflict", "Refusal lacks an immutable native identity/time");
   if (failure.observed_at !== null && (typeof failure.observed_at !== "string" || !Number.isFinite(Date.parse(failure.observed_at)) || Date.parse(failure.observed_at) !== observed))
     throw policyError("capacity_continuation_conflict", "Native refusal observation time is invalid or changed");
   const native = failure.terminal_at && Date.parse(failure.terminal_at);
-  return { policy: CAPACITY_POLICY, ordinal, session_id: failure.session_id, turn_id: failure.turn_id,
+  return { policy, ordinal, session_id: failure.session_id, turn_id: failure.turn_id,
     request_key: failure.request_key, request_proof: failure.request_proof,
     first_observed_at: firstObservedAt, ...(Number.isFinite(native) && typeof failure.terminal_basis === "string" && failure.terminal_basis ? { native_terminal_at: failure.terminal_at, native_terminal_basis: failure.terminal_basis } : {}) };
 }