@replayci/replay 0.1.16 → 0.1.18

package/dist/index.cjs

@@ -5213,7 +5213,9 @@ var RuntimeClient = class {
       accepted: r.accepted,
       commitState: r.commit_state,
       stateAdvanced: r.state_advanced,
-      stateVersion: r.state_version
+      stateVersion: r.state_version,
+      executionState: r.execution_state ?? "outcome_recorded",
+      pendingStatus: r.pending_status ?? (r.state_advanced ? "resolved" : "pending")
     };
   }
   async setToolFilter(input) {
@@ -5474,6 +5476,7 @@ var DEFAULT_AGENT2 = "default";
 var DEFAULT_MAX_UNGUARDED_CALLS = 3;
 function replay(client, opts = {}) {
   assertSupportedNodeRuntime();
+  const internalOpts = opts;
   const sessionId = opts.sessionId ?? generateSessionId2();
   const agent = typeof opts.agent === "string" && opts.agent.length > 0 ? opts.agent : DEFAULT_AGENT2;
   const mode = opts.mode ?? "enforce";
@@ -5495,17 +5498,20 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Client already has an active observe() or replay() attachment");
   }
   let contracts;
-  let zeroConfigMode = false;
-  try {
-    contracts = resolveContracts(opts);
-  } catch (err) {
-    const apiKeyForGov = resolveApiKey2(opts);
-    if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
-      return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+  if (internalOpts.__preparedContracts && internalOpts.__preparedContracts.length > 0) {
+    contracts = internalOpts.__preparedContracts;
+  } else {
+    try {
+      contracts = resolveContracts(opts);
+    } catch (err) {
+      const apiKeyForGov = resolveApiKey2(opts);
+      if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
+        return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+      }
+      const detail = err instanceof Error ? err.message : "Failed to load contracts";
+      emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
+      return createBlockingInactiveSession(client, sessionId, detail);
     }
-    const detail = err instanceof Error ? err.message : "Failed to load contracts";
-    emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
-    return createBlockingInactiveSession(client, sessionId, detail);
   }
   const configError = validateConfig(contracts, opts);
   if (configError) {
@@ -5532,20 +5538,22 @@ function replay(client, opts = {}) {
   } else if (sessionYaml && opts.providerConstraints && !sessionYaml.provider_constraints) {
     sessionYaml = { ...sessionYaml, provider_constraints: opts.providerConstraints };
   }
-  let compiledSession = null;
-  try {
-    compiledSession = (0, import_contracts_core7.compileSession)(contracts, sessionYaml, {
-      principal: opts.principal,
-      tools: opts.tools ? new Map(Object.entries(opts.tools)) : void 0
-    });
-  } catch (err) {
-    const detail = `Session compilation failed: ${err instanceof Error ? err.message : String(err)}`;
-    emitDiagnostic2(diagnostics, {
-      type: "replay_compile_error",
-      details: detail
-    });
-    if (discoveredSessionYaml) {
-      return createBlockingInactiveSession(client, sessionId, detail);
+  let compiledSession = internalOpts.__compiledSession ?? null;
+  if (!compiledSession) {
+    try {
+      compiledSession = (0, import_contracts_core7.compileSession)(contracts, sessionYaml, {
+        principal: opts.principal,
+        tools: opts.tools ? new Map(Object.entries(opts.tools)) : void 0
+      });
+    } catch (err) {
+      const detail = `Session compilation failed: ${err instanceof Error ? err.message : String(err)}`;
+      emitDiagnostic2(diagnostics, {
+        type: "replay_compile_error",
+        details: detail
+      });
+      if (discoveredSessionYaml) {
+        return createBlockingInactiveSession(client, sessionId, detail);
+      }
     }
   }
   if (compiledSession?.warnings && compiledSession.warnings.length > 0) {
@@ -5612,7 +5620,7 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
   }
   const apiKey = resolveApiKey2(opts);
-  const protectionLevel = determineProtectionLevel(mode, opts.tools, contracts, apiKey);
+  const protectionLevel = internalOpts.__disableRuntimeControlPlane ? determineRuntimeFreeProtectionLevel(mode) : determineProtectionLevel(mode, opts.tools, contracts, apiKey);
   const maxUnguardedCalls = opts.maxUnguardedCalls ?? DEFAULT_MAX_UNGUARDED_CALLS;
   const narrowingFeedback = opts.narrowingFeedback ?? "silent";
   let runtimeClient = null;
@@ -7971,6 +7979,185 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     handoff: () => Promise.resolve(null)
   };
 }
+function createPreparedContractsFromCompiledSession(compiledSession) {
+  return Array.from(compiledSession.perToolContracts.values()).map((contract) => ({
+    ...contract,
+    contract_file: contract.tool
+  }));
+}
+function requireArtifactRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value;
+}
+function requireArtifactStringArray(value, field) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value;
+}
+function requireArtifactEntryArray(value, field) {
+  if (!Array.isArray(value)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value.map((entry) => {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string") {
+      throw new ReplayConfigError(
+        "compilation_failed",
+        `Approved governance artifact has invalid ${field}`
+      );
+    }
+    return [entry[0], entry[1]];
+  });
+}
+function hydrateStringArrayMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => [
+      key,
+      requireArtifactStringArray(entryValue, `${field}.${key}`)
+    ])
+  );
+}
+function hydrateContractMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => [
+      key,
+      requireArtifactRecord(entryValue, `${field}.${key}`)
+    ])
+  );
+}
+function hydrateExecutionConstraintMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => {
+      if (!Array.isArray(entryValue)) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          `Approved governance artifact has invalid ${field}.${key}`
+        );
+      }
+      return [key, entryValue];
+    })
+  );
+}
+function hydrateNestedStringMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([outerKey, innerValue]) => {
+      const nested = new Map(
+        requireArtifactEntryArray(innerValue, `${field}.${outerKey}`).map(([innerKey, nestedValue]) => {
+          if (typeof nestedValue !== "string") {
+            throw new ReplayConfigError(
+              "compilation_failed",
+              `Approved governance artifact has invalid ${field}.${outerKey}.${innerKey}`
+            );
+          }
+          return [innerKey, nestedValue];
+        })
+      );
+      return [outerKey, nested];
+    })
+  );
+}
+function hydratePolicyProgram(value) {
+  if (value == null) return null;
+  const policyProgram = requireArtifactRecord(value, "policyProgram");
+  if (typeof policyProgram.defaultDeny !== "boolean" || !Array.isArray(policyProgram.sessionRules)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid policyProgram"
+    );
+  }
+  return {
+    defaultDeny: policyProgram.defaultDeny,
+    sessionRules: policyProgram.sessionRules,
+    perToolRules: new Map(
+      requireArtifactEntryArray(policyProgram.perToolRules ?? [], "policyProgram.perToolRules").map(
+        ([toolName, ruleValue]) => [toolName, requireArtifactRecord(ruleValue, `policyProgram.perToolRules.${toolName}`)]
+      )
+    )
+  };
+}
+function rehydrateCompiledSessionArtifact(artifact, expectedHash) {
+  const record = requireArtifactRecord(artifact, "compiled_session");
+  if (typeof record.agent !== "string" || typeof record.schemaVersion !== "string") {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact is missing required session metadata"
+    );
+  }
+  if (record.phases != null && !Array.isArray(record.phases)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid phases"
+    );
+  }
+  if (!Array.isArray(record.contractHashes) || record.contractHashes.some((hash) => typeof hash !== "string")) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid contractHashes"
+    );
+  }
+  const compiledSession = {
+    agent: record.agent,
+    schemaVersion: record.schemaVersion,
+    phases: record.phases ?? null,
+    transitions: hydrateStringArrayMap(record.transitions ?? [], "transitions"),
+    sessionLimits: record.sessionLimits ?? {},
+    perToolContracts: hydrateContractMap(record.perToolContracts ?? [], "perToolContracts"),
+    riskDefaults: requireArtifactRecord(record.riskDefaults ?? {}, "riskDefaults"),
+    providerConstraints: record.providerConstraints ?? null,
+    contractHashes: record.contractHashes,
+    compiledHash: "",
+    principal: null,
+    policyProgram: hydratePolicyProgram(record.policyProgram),
+    executionConstraints: hydrateExecutionConstraintMap(record.executionConstraints ?? [], "executionConstraints"),
+    toolExecutors: null,
+    resources: hydrateNestedStringMap(record.resources ?? [], "resources"),
+    warnings: [],
+    graphDiagnostics: [],
+    schemaDerivedDiagnostics: [],
+    aggregates: Array.isArray(record.aggregates) ? record.aggregates : [],
+    envelopes: Array.isArray(record.envelopes) ? record.envelopes : [],
+    labelGates: Array.isArray(record.labelGates) ? record.labelGates : [],
+    checkpoints: Array.isArray(record.checkpoints) ? record.checkpoints : []
+  };
+  const serialized = (0, import_contracts_core7.serializeCompiledSession)(compiledSession);
+  const computedHash = import_node_crypto6.default.createHash("sha256").update(serialized).digest("hex");
+  compiledSession.compiledHash = computedHash;
+  if (expectedHash && expectedHash !== computedHash) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact hash mismatch: expected ${expectedHash}, got ${computedHash}`
+    );
+  }
+  return compiledSession;
+}
+function createDetachedProviderClient(provider, terminal, originalCreate) {
+  const boundCreate = (...args) => originalCreate.apply(terminal, args);
+  if (provider === "openai") {
+    return {
+      chat: {
+        completions: {
+          create: boundCreate
+        }
+      }
+    };
+  }
+  return {
+    messages: {
+      create: boundCreate
+    }
+  };
+}
 function resolveGovernanceEnvironment(opts) {
   if (opts.environment) return opts.environment;
   const envVar = typeof process !== "undefined" ? process.env.REPLAYCI_ENVIRONMENT : void 0;
@@ -7993,7 +8180,7 @@ function governanceProtectionLevel(env) {
 }
 function createGovernanceSession(client, sessionId, agent, provider, apiKey, opts, diagnostics) {
   const environment = resolveGovernanceEnvironment(opts);
-  const protLevel = governanceProtectionLevel(environment);
+  const observeProtectionLevel = governanceProtectionLevel(environment);
   const runtimeClient = new RuntimeClient({
     apiKey,
     apiUrl: opts.runtimeUrl
@@ -8002,13 +8189,22 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
   let planFetchPromise = null;
   let planFetchDone = false;
   let planFetchError = null;
+  let planFetchErrorCode = null;
+  let approvedRuntimeSession = null;
+  let approvedRuntimeInitPromise = null;
+  let approvedRuntimeInitError = null;
   planFetchPromise = runtimeClient.fetchGovernancePlan(agent, environment).then((result) => {
     governancePlan = result;
     planFetchDone = true;
+    if (!hasApprovedGovernanceArtifact(result)) {
+      emitDiagnostic2(diagnostics, { type: "replay_governance_no_plan", session_id: sessionId, environment });
+    }
   }).catch((err) => {
     planFetchDone = true;
     planFetchError = err instanceof Error ? err.message : String(err);
+    planFetchErrorCode = err instanceof RuntimeClientError ? err.code : null;
     governancePlan = null;
+    emitDiagnostic2(diagnostics, { type: "replay_governance_fetch_failed", session_id: sessionId, details: planFetchError });
   });
   const captureBuffer = new CaptureBuffer({
     apiKey,
@@ -8021,12 +8217,139 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
     return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
   }
   const { terminal, originalCreate } = terminalInfo;
+  const fallbackTools = buildWrappedToolsMap(opts.tools, null);
+  function hasApprovedGovernanceArtifact(plan) {
+    return Boolean(
+      plan && (plan.status === "approved" || plan.status === "enforcing")
+    );
+  }
+  async function ensureApprovedRuntimeSession() {
+    if (approvedRuntimeSession) return approvedRuntimeSession;
+    if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+    if (approvedRuntimeInitPromise) {
+      await approvedRuntimeInitPromise;
+      if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+      return approvedRuntimeSession;
+    }
+    approvedRuntimeInitPromise = (async () => {
+      if (!hasApprovedGovernanceArtifact(governancePlan)) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance artifact was not available for runtime enforcement"
+        );
+      }
+      if (!governancePlan?.compiledSession) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance plan is missing compiled_session"
+        );
+      }
+      if (!governancePlan.compiledHash) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance plan is missing compiled_hash"
+        );
+      }
+      const compiledSession = rehydrateCompiledSessionArtifact(
+        governancePlan.compiledSession,
+        governancePlan.compiledHash
+      );
+      const preparedContracts = createPreparedContractsFromCompiledSession(compiledSession);
+      const detachedClient = createDetachedProviderClient(
+        provider,
+        terminal,
+        originalCreate
+      );
+      const approvedMode = environment === "development" ? "shadow" : "enforce";
+      const approvedCompatEnforcement = environment === "staging" ? "advisory" : opts.compatEnforcement ?? "protective";
+      approvedRuntimeSession = replay(detachedClient, {
+        ...opts,
+        agent,
+        sessionId,
+        apiKey,
+        mode: approvedMode,
+        compatEnforcement: approvedCompatEnforcement,
+        contracts: void 0,
+        contractsDir: void 0,
+        sessionYamlPath: void 0,
+        environment: void 0,
+        __preparedContracts: preparedContracts,
+        __compiledSession: compiledSession,
+        __disableRuntimeControlPlane: true
+      });
+      emitDiagnostic2(diagnostics, { type: "replay_governance_attached", session_id: sessionId, environment });
+    })().catch((err) => {
+      approvedRuntimeInitError = err instanceof Error ? err : new ReplayConfigError("compilation_failed", String(err));
+      const isArtifactInvalid = approvedRuntimeInitError.message.includes("Approved governance artifact");
+      emitDiagnostic2(diagnostics, {
+        type: isArtifactInvalid ? "replay_governance_artifact_invalid" : "replay_governance_attachment_failed",
+        session_id: sessionId,
+        details: approvedRuntimeInitError.message
+      });
+      emitDiagnostic2(diagnostics, {
+        type: "replay_compile_error",
+        details: approvedRuntimeInitError.message
+      });
+    });
+    await approvedRuntimeInitPromise;
+    if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+    return approvedRuntimeSession;
+  }
+  async function invokeApprovedRuntimeCreate(args) {
+    const runtimeSession = await ensureApprovedRuntimeSession();
+    if (provider === "openai") {
+      return runtimeSession.client.chat.completions.create(...args);
+    }
+    return runtimeSession.client.messages.create(...args);
+  }
+  const tools = opts.tools ? new Proxy(fallbackTools, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      if (approvedRuntimeSession?.tools[prop]) {
+        return approvedRuntimeSession.tools[prop];
+      }
+      return fallbackTools[prop];
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") return false;
+      return Boolean(approvedRuntimeSession?.tools[prop] ?? fallbackTools[prop]);
+    },
+    ownKeys() {
+      const keys = /* @__PURE__ */ new Set([
+        ...Reflect.ownKeys(fallbackTools),
+        ...Reflect.ownKeys(approvedRuntimeSession?.tools ?? {})
+      ]);
+      return Array.from(keys);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      if (approvedRuntimeSession?.tools[prop] || fallbackTools[prop]) {
+        return {
+          configurable: true,
+          enumerable: true,
+          writable: false,
+          value: approvedRuntimeSession?.tools[prop] ?? fallbackTools[prop]
+        };
+      }
+      return void 0;
+    }
+  }) : {};
   const patchedCreate = async function(...args) {
     if (!planFetchDone && planFetchPromise) {
       await planFetchPromise;
     }
-    const hasApprovedPlan = governancePlan && (governancePlan.status === "approved" || governancePlan.status === "enforcing") && governancePlan.compiledSession;
-    if (hasApprovedPlan) {
+    if (planFetchError) {
+      const artifactBroken = planFetchErrorCode === "APPROVED_ARTIFACT_INVALID";
+      const requiresEnforcement = observeProtectionLevel !== "monitor";
+      if (artifactBroken || requiresEnforcement) {
+        throw new ReplayConfigError(
+          "governance_unavailable",
+          `Governance plan fetch failed (fail-closed): ${planFetchError}`
+        );
+      }
+    }
+    if (hasApprovedGovernanceArtifact(governancePlan)) {
+      return invokeApprovedRuntimeCreate(args);
     }
     const result = await originalCreate.apply(this, args);
     try {
@@ -8055,40 +8378,81 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
   setReplayAttached(client);
   return {
     client,
-    flush: () => captureBuffer.flush(),
+    flush: () => approvedRuntimeSession ? approvedRuntimeSession.flush() : captureBuffer.flush(),
     restore() {
       terminal[terminalInfo.methodName] = originalCreate;
+      approvedRuntimeSession?.restore();
+      clearReplayAttached(client);
     },
     kill() {
+      approvedRuntimeSession?.kill();
     },
-    getHealth: () => ({
-      status: "healthy",
-      authorityState: "active",
-      protectionLevel: protLevel,
-      durability: "inactive",
-      tier: "compat",
-      compatEnforcement: "protective",
-      cluster_detected: false,
-      bypass_detected: false,
-      totalSteps: 0,
-      totalBlocks: 0,
-      totalErrors: 0,
-      killed: false,
-      shadowEvaluations: 0
-    }),
-    getState: () => EMPTY_STATE_SNAPSHOT,
-    getLastNarrowing: () => null,
-    getLastShadowDelta: () => null,
-    getLastTrace: () => null,
-    narrow() {
+    getHealth: () => {
+      if (approvedRuntimeSession) {
+        const inner = approvedRuntimeSession.getHealth();
+        return { ...inner, governanceAttachment: "attached" };
+      }
+      let governanceAttachment;
+      let status;
+      let authorityState;
+      let totalErrors = 0;
+      if (!planFetchDone) {
+        governanceAttachment = "pending";
+        status = "healthy";
+        authorityState = "advisory";
+      } else if (planFetchError) {
+        governanceAttachment = "fetch_failed";
+        status = "degraded";
+        authorityState = "inactive";
+        totalErrors = 1;
+      } else if (approvedRuntimeInitError) {
+        const isArtifactInvalid = approvedRuntimeInitError.message.includes("Approved governance artifact");
+        governanceAttachment = isArtifactInvalid ? "artifact_invalid" : "attachment_failed";
+        status = "degraded";
+        authorityState = "inactive";
+        totalErrors = 1;
+      } else if (!hasApprovedGovernanceArtifact(governancePlan)) {
+        governanceAttachment = "no_plan";
+        status = "healthy";
+        authorityState = "advisory";
+      } else {
+        governanceAttachment = "pending";
+        status = "healthy";
+        authorityState = "advisory";
+      }
+      return {
+        status,
+        authorityState,
+        protectionLevel: observeProtectionLevel,
+        durability: "inactive",
+        tier: "compat",
+        compatEnforcement: "protective",
+        cluster_detected: false,
+        bypass_detected: false,
+        totalSteps: 0,
+        totalBlocks: 0,
+        totalErrors,
+        killed: false,
+        shadowEvaluations: 0,
+        governanceAttachment
+      };
+    },
+    getState: () => approvedRuntimeSession ? approvedRuntimeSession.getState() : EMPTY_STATE_SNAPSHOT,
+    getLastNarrowing: () => approvedRuntimeSession ? approvedRuntimeSession.getLastNarrowing() : null,
+    getLastShadowDelta: () => approvedRuntimeSession ? approvedRuntimeSession.getLastShadowDelta() : null,
+    getLastTrace: () => approvedRuntimeSession ? approvedRuntimeSession.getLastTrace() : null,
+    narrow(...args) {
+      approvedRuntimeSession?.narrow(...args);
     },
     widen() {
+      approvedRuntimeSession?.widen();
     },
-    addLabel() {
+    addLabel(label) {
+      approvedRuntimeSession?.addLabel(label);
     },
-    tools: {},
-    getWorkflowState: () => Promise.resolve(null),
-    handoff: () => Promise.resolve(null)
+    tools,
+    getWorkflowState: () => approvedRuntimeSession ? approvedRuntimeSession.getWorkflowState() : Promise.resolve(null),
+    handoff: (offer) => approvedRuntimeSession ? approvedRuntimeSession.handoff(offer) : Promise.resolve(null)
   };
 }
 function toNarrowingSnapshot(result) {
@@ -8265,6 +8629,9 @@ function determineProtectionLevel(mode, tools, contracts, apiKey) {
   const allWrapped = stateBearingTools.every((c) => wrappedTools.has(c.tool));
   return allWrapped ? "govern" : "protect";
 }
+function determineRuntimeFreeProtectionLevel(mode) {
+  return mode === "enforce" ? "protect" : "monitor";
+}
 function isStateBearing(contract) {
   if (contract.commit_requirement != null && contract.commit_requirement !== "none") return true;
   if (contract.transitions != null) return true;

package/dist/index.d.cts

@@ -699,6 +699,11 @@ type ReplaySession<T> = {
      */
     handoff: (offer: HandoffOfferInput$1) => Promise<HandoffOfferResult$1 | null>;
 };
+/**
+ * Governance attachment state for zero-config governance sessions.
+ * @see replay.ts § createGovernanceSession
+ */
+type GovernanceAttachmentState = "pending" | "no_plan" | "attached" | "artifact_invalid" | "attachment_failed" | "fetch_failed";
 /** @see specs/runtime-replay.md § ReplayHealthSnapshot */
 type ReplayHealthSnapshot = {
     status: "healthy" | "degraded" | "inactive";
@@ -716,6 +721,8 @@ type ReplayHealthSnapshot = {
     killed: boolean;
     /** Number of shadow-mode evaluations performed (always 0 in enforce/log-only). */
     shadowEvaluations: number;
+    /** Governance attachment state. Only present for zero-config governance sessions. */
+    governanceAttachment?: GovernanceAttachmentState;
 };
 /**
  * Public, redacted, JSON-serializable snapshot of session state.
@@ -1031,6 +1038,26 @@ type ReplayDiagnosticEvent = {
     tool?: string;
     phase?: string;
     suggestion?: string;
+} | {
+    type: "replay_governance_attached";
+    session_id: string;
+    environment: string;
+} | {
+    type: "replay_governance_no_plan";
+    session_id: string;
+    environment: string;
+} | {
+    type: "replay_governance_artifact_invalid";
+    session_id: string;
+    details: string;
+} | {
+    type: "replay_governance_attachment_failed";
+    session_id: string;
+    details: string;
+} | {
+    type: "replay_governance_fetch_failed";
+    session_id: string;
+    details: string;
 };
 /**
  * Workflow state snapshot returned by `session.getWorkflowState()`.
@@ -1113,9 +1140,9 @@ declare class ReplayKillError extends Error {
  * @see specs/replay-v1.md § Config errors (fail-closed)
  */
 declare class ReplayConfigError extends ReplayConfigurationError {
-    readonly condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible";
+    readonly condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible" | "governance_unavailable";
     readonly details: string;
-    constructor(condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible", details: string);
+    constructor(condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible" | "governance_unavailable", details: string);
 }
 
 /**
@@ -1242,7 +1269,7 @@ type ReceiptInput = {
     executorId?: string | null;
     toolName: string;
     argumentsHash: string;
-    status: "SUCCEEDED" | "FAILED" | "DISCARDED";
+    status: "SUCCEEDED" | "FAILED" | "DISCARDED" | "AMBIGUOUS";
     outputHash?: string | null;
     outputExtract?: Record<string, unknown> | null;
     resourceValues?: Record<string, unknown> | null;
@@ -1255,6 +1282,8 @@ type ReceiptResult = {
     commitState: "committed" | "uncommitted";
     stateAdvanced: boolean;
     stateVersion: number;
+    executionState: "outcome_recorded" | "ambiguous";
+    pendingStatus: "resolved" | "pending" | "ambiguous";
 };
 type ToolFilterInput = {
     sessionId: string;
@@ -1366,4 +1395,4 @@ declare class RuntimeClient {
     private recordFailure;
 }
 
-export { type AggregateState, type BlockReason, type BlockedToolCall, type BoundValue, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };
+export { type AggregateState, type BlockReason, type BlockedToolCall, type BoundValue, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type GovernanceAttachmentState, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };

package/dist/index.d.ts

@@ -699,6 +699,11 @@ type ReplaySession<T> = {
      */
     handoff: (offer: HandoffOfferInput$1) => Promise<HandoffOfferResult$1 | null>;
 };
+/**
+ * Governance attachment state for zero-config governance sessions.
+ * @see replay.ts § createGovernanceSession
+ */
+type GovernanceAttachmentState = "pending" | "no_plan" | "attached" | "artifact_invalid" | "attachment_failed" | "fetch_failed";
 /** @see specs/runtime-replay.md § ReplayHealthSnapshot */
 type ReplayHealthSnapshot = {
     status: "healthy" | "degraded" | "inactive";
@@ -716,6 +721,8 @@ type ReplayHealthSnapshot = {
     killed: boolean;
     /** Number of shadow-mode evaluations performed (always 0 in enforce/log-only). */
     shadowEvaluations: number;
+    /** Governance attachment state. Only present for zero-config governance sessions. */
+    governanceAttachment?: GovernanceAttachmentState;
 };
 /**
  * Public, redacted, JSON-serializable snapshot of session state.
@@ -1031,6 +1038,26 @@ type ReplayDiagnosticEvent = {
     tool?: string;
     phase?: string;
     suggestion?: string;
+} | {
+    type: "replay_governance_attached";
+    session_id: string;
+    environment: string;
+} | {
+    type: "replay_governance_no_plan";
+    session_id: string;
+    environment: string;
+} | {
+    type: "replay_governance_artifact_invalid";
+    session_id: string;
+    details: string;
+} | {
+    type: "replay_governance_attachment_failed";
+    session_id: string;
+    details: string;
+} | {
+    type: "replay_governance_fetch_failed";
+    session_id: string;
+    details: string;
 };
 /**
  * Workflow state snapshot returned by `session.getWorkflowState()`.
@@ -1113,9 +1140,9 @@ declare class ReplayKillError extends Error {
  * @see specs/replay-v1.md § Config errors (fail-closed)
  */
 declare class ReplayConfigError extends ReplayConfigurationError {
-    readonly condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible";
+    readonly condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible" | "governance_unavailable";
     readonly details: string;
-    constructor(condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible", details: string);
+    constructor(condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible" | "governance_unavailable", details: string);
 }
 
 /**
@@ -1242,7 +1269,7 @@ type ReceiptInput = {
     executorId?: string | null;
     toolName: string;
     argumentsHash: string;
-    status: "SUCCEEDED" | "FAILED" | "DISCARDED";
+    status: "SUCCEEDED" | "FAILED" | "DISCARDED" | "AMBIGUOUS";
     outputHash?: string | null;
     outputExtract?: Record<string, unknown> | null;
     resourceValues?: Record<string, unknown> | null;
@@ -1255,6 +1282,8 @@ type ReceiptResult = {
     commitState: "committed" | "uncommitted";
     stateAdvanced: boolean;
     stateVersion: number;
+    executionState: "outcome_recorded" | "ambiguous";
+    pendingStatus: "resolved" | "pending" | "ambiguous";
 };
 type ToolFilterInput = {
     sessionId: string;
@@ -1366,4 +1395,4 @@ declare class RuntimeClient {
     private recordFailure;
 }
 
-export { type AggregateState, type BlockReason, type BlockedToolCall, type BoundValue, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };
+export { type AggregateState, type BlockReason, type BlockedToolCall, type BoundValue, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type GovernanceAttachmentState, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };

package/dist/index.js

@@ -5205,7 +5205,9 @@ var RuntimeClient = class {
       accepted: r.accepted,
       commitState: r.commit_state,
       stateAdvanced: r.state_advanced,
-      stateVersion: r.state_version
+      stateVersion: r.state_version,
+      executionState: r.execution_state ?? "outcome_recorded",
+      pendingStatus: r.pending_status ?? (r.state_advanced ? "resolved" : "pending")
     };
   }
   async setToolFilter(input) {
@@ -5466,6 +5468,7 @@ var DEFAULT_AGENT2 = "default";
 var DEFAULT_MAX_UNGUARDED_CALLS = 3;
 function replay(client, opts = {}) {
   assertSupportedNodeRuntime();
+  const internalOpts = opts;
   const sessionId = opts.sessionId ?? generateSessionId2();
   const agent = typeof opts.agent === "string" && opts.agent.length > 0 ? opts.agent : DEFAULT_AGENT2;
   const mode = opts.mode ?? "enforce";
@@ -5487,17 +5490,20 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Client already has an active observe() or replay() attachment");
   }
   let contracts;
-  let zeroConfigMode = false;
-  try {
-    contracts = resolveContracts(opts);
-  } catch (err) {
-    const apiKeyForGov = resolveApiKey2(opts);
-    if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
-      return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+  if (internalOpts.__preparedContracts && internalOpts.__preparedContracts.length > 0) {
+    contracts = internalOpts.__preparedContracts;
+  } else {
+    try {
+      contracts = resolveContracts(opts);
+    } catch (err) {
+      const apiKeyForGov = resolveApiKey2(opts);
+      if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
+        return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+      }
+      const detail = err instanceof Error ? err.message : "Failed to load contracts";
+      emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
+      return createBlockingInactiveSession(client, sessionId, detail);
     }
-    const detail = err instanceof Error ? err.message : "Failed to load contracts";
-    emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
-    return createBlockingInactiveSession(client, sessionId, detail);
   }
   const configError = validateConfig(contracts, opts);
   if (configError) {
@@ -5524,20 +5530,22 @@ function replay(client, opts = {}) {
   } else if (sessionYaml && opts.providerConstraints && !sessionYaml.provider_constraints) {
     sessionYaml = { ...sessionYaml, provider_constraints: opts.providerConstraints };
   }
-  let compiledSession = null;
-  try {
-    compiledSession = compileSession(contracts, sessionYaml, {
-      principal: opts.principal,
-      tools: opts.tools ? new Map(Object.entries(opts.tools)) : void 0
-    });
-  } catch (err) {
-    const detail = `Session compilation failed: ${err instanceof Error ? err.message : String(err)}`;
-    emitDiagnostic2(diagnostics, {
-      type: "replay_compile_error",
-      details: detail
-    });
-    if (discoveredSessionYaml) {
-      return createBlockingInactiveSession(client, sessionId, detail);
+  let compiledSession = internalOpts.__compiledSession ?? null;
+  if (!compiledSession) {
+    try {
+      compiledSession = compileSession(contracts, sessionYaml, {
+        principal: opts.principal,
+        tools: opts.tools ? new Map(Object.entries(opts.tools)) : void 0
+      });
+    } catch (err) {
+      const detail = `Session compilation failed: ${err instanceof Error ? err.message : String(err)}`;
+      emitDiagnostic2(diagnostics, {
+        type: "replay_compile_error",
+        details: detail
+      });
+      if (discoveredSessionYaml) {
+        return createBlockingInactiveSession(client, sessionId, detail);
+      }
     }
   }
   if (compiledSession?.warnings && compiledSession.warnings.length > 0) {
@@ -5604,7 +5612,7 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
   }
   const apiKey = resolveApiKey2(opts);
-  const protectionLevel = determineProtectionLevel(mode, opts.tools, contracts, apiKey);
+  const protectionLevel = internalOpts.__disableRuntimeControlPlane ? determineRuntimeFreeProtectionLevel(mode) : determineProtectionLevel(mode, opts.tools, contracts, apiKey);
   const maxUnguardedCalls = opts.maxUnguardedCalls ?? DEFAULT_MAX_UNGUARDED_CALLS;
   const narrowingFeedback = opts.narrowingFeedback ?? "silent";
   let runtimeClient = null;
@@ -7963,6 +7971,185 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     handoff: () => Promise.resolve(null)
   };
 }
+function createPreparedContractsFromCompiledSession(compiledSession) {
+  return Array.from(compiledSession.perToolContracts.values()).map((contract) => ({
+    ...contract,
+    contract_file: contract.tool
+  }));
+}
+function requireArtifactRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value;
+}
+function requireArtifactStringArray(value, field) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value;
+}
+function requireArtifactEntryArray(value, field) {
+  if (!Array.isArray(value)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact has invalid ${field}`
+    );
+  }
+  return value.map((entry) => {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string") {
+      throw new ReplayConfigError(
+        "compilation_failed",
+        `Approved governance artifact has invalid ${field}`
+      );
+    }
+    return [entry[0], entry[1]];
+  });
+}
+function hydrateStringArrayMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => [
+      key,
+      requireArtifactStringArray(entryValue, `${field}.${key}`)
+    ])
+  );
+}
+function hydrateContractMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => [
+      key,
+      requireArtifactRecord(entryValue, `${field}.${key}`)
+    ])
+  );
+}
+function hydrateExecutionConstraintMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([key, entryValue]) => {
+      if (!Array.isArray(entryValue)) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          `Approved governance artifact has invalid ${field}.${key}`
+        );
+      }
+      return [key, entryValue];
+    })
+  );
+}
+function hydrateNestedStringMap(value, field) {
+  return new Map(
+    requireArtifactEntryArray(value, field).map(([outerKey, innerValue]) => {
+      const nested = new Map(
+        requireArtifactEntryArray(innerValue, `${field}.${outerKey}`).map(([innerKey, nestedValue]) => {
+          if (typeof nestedValue !== "string") {
+            throw new ReplayConfigError(
+              "compilation_failed",
+              `Approved governance artifact has invalid ${field}.${outerKey}.${innerKey}`
+            );
+          }
+          return [innerKey, nestedValue];
+        })
+      );
+      return [outerKey, nested];
+    })
+  );
+}
+function hydratePolicyProgram(value) {
+  if (value == null) return null;
+  const policyProgram = requireArtifactRecord(value, "policyProgram");
+  if (typeof policyProgram.defaultDeny !== "boolean" || !Array.isArray(policyProgram.sessionRules)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid policyProgram"
+    );
+  }
+  return {
+    defaultDeny: policyProgram.defaultDeny,
+    sessionRules: policyProgram.sessionRules,
+    perToolRules: new Map(
+      requireArtifactEntryArray(policyProgram.perToolRules ?? [], "policyProgram.perToolRules").map(
+        ([toolName, ruleValue]) => [toolName, requireArtifactRecord(ruleValue, `policyProgram.perToolRules.${toolName}`)]
+      )
+    )
+  };
+}
+function rehydrateCompiledSessionArtifact(artifact, expectedHash) {
+  const record = requireArtifactRecord(artifact, "compiled_session");
+  if (typeof record.agent !== "string" || typeof record.schemaVersion !== "string") {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact is missing required session metadata"
+    );
+  }
+  if (record.phases != null && !Array.isArray(record.phases)) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid phases"
+    );
+  }
+  if (!Array.isArray(record.contractHashes) || record.contractHashes.some((hash) => typeof hash !== "string")) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      "Approved governance artifact has invalid contractHashes"
+    );
+  }
+  const compiledSession = {
+    agent: record.agent,
+    schemaVersion: record.schemaVersion,
+    phases: record.phases ?? null,
+    transitions: hydrateStringArrayMap(record.transitions ?? [], "transitions"),
+    sessionLimits: record.sessionLimits ?? {},
+    perToolContracts: hydrateContractMap(record.perToolContracts ?? [], "perToolContracts"),
+    riskDefaults: requireArtifactRecord(record.riskDefaults ?? {}, "riskDefaults"),
+    providerConstraints: record.providerConstraints ?? null,
+    contractHashes: record.contractHashes,
+    compiledHash: "",
+    principal: null,
+    policyProgram: hydratePolicyProgram(record.policyProgram),
+    executionConstraints: hydrateExecutionConstraintMap(record.executionConstraints ?? [], "executionConstraints"),
+    toolExecutors: null,
+    resources: hydrateNestedStringMap(record.resources ?? [], "resources"),
+    warnings: [],
+    graphDiagnostics: [],
+    schemaDerivedDiagnostics: [],
+    aggregates: Array.isArray(record.aggregates) ? record.aggregates : [],
+    envelopes: Array.isArray(record.envelopes) ? record.envelopes : [],
+    labelGates: Array.isArray(record.labelGates) ? record.labelGates : [],
+    checkpoints: Array.isArray(record.checkpoints) ? record.checkpoints : []
+  };
+  const serialized = serializeCompiledSession(compiledSession);
+  const computedHash = crypto5.createHash("sha256").update(serialized).digest("hex");
+  compiledSession.compiledHash = computedHash;
+  if (expectedHash && expectedHash !== computedHash) {
+    throw new ReplayConfigError(
+      "compilation_failed",
+      `Approved governance artifact hash mismatch: expected ${expectedHash}, got ${computedHash}`
+    );
+  }
+  return compiledSession;
+}
+function createDetachedProviderClient(provider, terminal, originalCreate) {
+  const boundCreate = (...args) => originalCreate.apply(terminal, args);
+  if (provider === "openai") {
+    return {
+      chat: {
+        completions: {
+          create: boundCreate
+        }
+      }
+    };
+  }
+  return {
+    messages: {
+      create: boundCreate
+    }
+  };
+}
 function resolveGovernanceEnvironment(opts) {
   if (opts.environment) return opts.environment;
   const envVar = typeof process !== "undefined" ? process.env.REPLAYCI_ENVIRONMENT : void 0;
@@ -7985,7 +8172,7 @@ function governanceProtectionLevel(env) {
 }
 function createGovernanceSession(client, sessionId, agent, provider, apiKey, opts, diagnostics) {
   const environment = resolveGovernanceEnvironment(opts);
-  const protLevel = governanceProtectionLevel(environment);
+  const observeProtectionLevel = governanceProtectionLevel(environment);
   const runtimeClient = new RuntimeClient({
     apiKey,
     apiUrl: opts.runtimeUrl
@@ -7994,13 +8181,22 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
   let planFetchPromise = null;
   let planFetchDone = false;
   let planFetchError = null;
+  let planFetchErrorCode = null;
+  let approvedRuntimeSession = null;
+  let approvedRuntimeInitPromise = null;
+  let approvedRuntimeInitError = null;
   planFetchPromise = runtimeClient.fetchGovernancePlan(agent, environment).then((result) => {
     governancePlan = result;
     planFetchDone = true;
+    if (!hasApprovedGovernanceArtifact(result)) {
+      emitDiagnostic2(diagnostics, { type: "replay_governance_no_plan", session_id: sessionId, environment });
+    }
   }).catch((err) => {
     planFetchDone = true;
     planFetchError = err instanceof Error ? err.message : String(err);
+    planFetchErrorCode = err instanceof RuntimeClientError ? err.code : null;
     governancePlan = null;
+    emitDiagnostic2(diagnostics, { type: "replay_governance_fetch_failed", session_id: sessionId, details: planFetchError });
   });
   const captureBuffer = new CaptureBuffer({
     apiKey,
@@ -8013,12 +8209,139 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
     return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
   }
   const { terminal, originalCreate } = terminalInfo;
+  const fallbackTools = buildWrappedToolsMap(opts.tools, null);
+  function hasApprovedGovernanceArtifact(plan) {
+    return Boolean(
+      plan && (plan.status === "approved" || plan.status === "enforcing")
+    );
+  }
+  async function ensureApprovedRuntimeSession() {
+    if (approvedRuntimeSession) return approvedRuntimeSession;
+    if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+    if (approvedRuntimeInitPromise) {
+      await approvedRuntimeInitPromise;
+      if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+      return approvedRuntimeSession;
+    }
+    approvedRuntimeInitPromise = (async () => {
+      if (!hasApprovedGovernanceArtifact(governancePlan)) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance artifact was not available for runtime enforcement"
+        );
+      }
+      if (!governancePlan?.compiledSession) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance plan is missing compiled_session"
+        );
+      }
+      if (!governancePlan.compiledHash) {
+        throw new ReplayConfigError(
+          "compilation_failed",
+          "Approved governance plan is missing compiled_hash"
+        );
+      }
+      const compiledSession = rehydrateCompiledSessionArtifact(
+        governancePlan.compiledSession,
+        governancePlan.compiledHash
+      );
+      const preparedContracts = createPreparedContractsFromCompiledSession(compiledSession);
+      const detachedClient = createDetachedProviderClient(
+        provider,
+        terminal,
+        originalCreate
+      );
+      const approvedMode = environment === "development" ? "shadow" : "enforce";
+      const approvedCompatEnforcement = environment === "staging" ? "advisory" : opts.compatEnforcement ?? "protective";
+      approvedRuntimeSession = replay(detachedClient, {
+        ...opts,
+        agent,
+        sessionId,
+        apiKey,
+        mode: approvedMode,
+        compatEnforcement: approvedCompatEnforcement,
+        contracts: void 0,
+        contractsDir: void 0,
+        sessionYamlPath: void 0,
+        environment: void 0,
+        __preparedContracts: preparedContracts,
+        __compiledSession: compiledSession,
+        __disableRuntimeControlPlane: true
+      });
+      emitDiagnostic2(diagnostics, { type: "replay_governance_attached", session_id: sessionId, environment });
+    })().catch((err) => {
+      approvedRuntimeInitError = err instanceof Error ? err : new ReplayConfigError("compilation_failed", String(err));
+      const isArtifactInvalid = approvedRuntimeInitError.message.includes("Approved governance artifact");
+      emitDiagnostic2(diagnostics, {
+        type: isArtifactInvalid ? "replay_governance_artifact_invalid" : "replay_governance_attachment_failed",
+        session_id: sessionId,
+        details: approvedRuntimeInitError.message
+      });
+      emitDiagnostic2(diagnostics, {
+        type: "replay_compile_error",
+        details: approvedRuntimeInitError.message
+      });
+    });
+    await approvedRuntimeInitPromise;
+    if (approvedRuntimeInitError) throw approvedRuntimeInitError;
+    return approvedRuntimeSession;
+  }
+  async function invokeApprovedRuntimeCreate(args) {
+    const runtimeSession = await ensureApprovedRuntimeSession();
+    if (provider === "openai") {
+      return runtimeSession.client.chat.completions.create(...args);
+    }
+    return runtimeSession.client.messages.create(...args);
+  }
+  const tools = opts.tools ? new Proxy(fallbackTools, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      if (approvedRuntimeSession?.tools[prop]) {
+        return approvedRuntimeSession.tools[prop];
+      }
+      return fallbackTools[prop];
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") return false;
+      return Boolean(approvedRuntimeSession?.tools[prop] ?? fallbackTools[prop]);
+    },
+    ownKeys() {
+      const keys = /* @__PURE__ */ new Set([
+        ...Reflect.ownKeys(fallbackTools),
+        ...Reflect.ownKeys(approvedRuntimeSession?.tools ?? {})
+      ]);
+      return Array.from(keys);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== "string") return void 0;
+      if (approvedRuntimeSession?.tools[prop] || fallbackTools[prop]) {
+        return {
+          configurable: true,
+          enumerable: true,
+          writable: false,
+          value: approvedRuntimeSession?.tools[prop] ?? fallbackTools[prop]
+        };
+      }
+      return void 0;
+    }
+  }) : {};
   const patchedCreate = async function(...args) {
     if (!planFetchDone && planFetchPromise) {
       await planFetchPromise;
     }
-    const hasApprovedPlan = governancePlan && (governancePlan.status === "approved" || governancePlan.status === "enforcing") && governancePlan.compiledSession;
-    if (hasApprovedPlan) {
+    if (planFetchError) {
+      const artifactBroken = planFetchErrorCode === "APPROVED_ARTIFACT_INVALID";
+      const requiresEnforcement = observeProtectionLevel !== "monitor";
+      if (artifactBroken || requiresEnforcement) {
+        throw new ReplayConfigError(
+          "governance_unavailable",
+          `Governance plan fetch failed (fail-closed): ${planFetchError}`
+        );
+      }
+    }
+    if (hasApprovedGovernanceArtifact(governancePlan)) {
+      return invokeApprovedRuntimeCreate(args);
     }
     const result = await originalCreate.apply(this, args);
     try {
@@ -8047,40 +8370,81 @@ function createGovernanceSession(client, sessionId, agent, provider, apiKey, opt
   setReplayAttached(client);
   return {
     client,
-    flush: () => captureBuffer.flush(),
+    flush: () => approvedRuntimeSession ? approvedRuntimeSession.flush() : captureBuffer.flush(),
     restore() {
       terminal[terminalInfo.methodName] = originalCreate;
+      approvedRuntimeSession?.restore();
+      clearReplayAttached(client);
     },
     kill() {
+      approvedRuntimeSession?.kill();
     },
-    getHealth: () => ({
-      status: "healthy",
-      authorityState: "active",
-      protectionLevel: protLevel,
-      durability: "inactive",
-      tier: "compat",
-      compatEnforcement: "protective",
-      cluster_detected: false,
-      bypass_detected: false,
-      totalSteps: 0,
-      totalBlocks: 0,
-      totalErrors: 0,
-      killed: false,
-      shadowEvaluations: 0
-    }),
-    getState: () => EMPTY_STATE_SNAPSHOT,
-    getLastNarrowing: () => null,
-    getLastShadowDelta: () => null,
-    getLastTrace: () => null,
-    narrow() {
+    getHealth: () => {
+      if (approvedRuntimeSession) {
+        const inner = approvedRuntimeSession.getHealth();
+        return { ...inner, governanceAttachment: "attached" };
+      }
+      let governanceAttachment;
+      let status;
+      let authorityState;
+      let totalErrors = 0;
+      if (!planFetchDone) {
+        governanceAttachment = "pending";
+        status = "healthy";
+        authorityState = "advisory";
+      } else if (planFetchError) {
+        governanceAttachment = "fetch_failed";
+        status = "degraded";
+        authorityState = "inactive";
+        totalErrors = 1;
+      } else if (approvedRuntimeInitError) {
+        const isArtifactInvalid = approvedRuntimeInitError.message.includes("Approved governance artifact");
+        governanceAttachment = isArtifactInvalid ? "artifact_invalid" : "attachment_failed";
+        status = "degraded";
+        authorityState = "inactive";
+        totalErrors = 1;
+      } else if (!hasApprovedGovernanceArtifact(governancePlan)) {
+        governanceAttachment = "no_plan";
+        status = "healthy";
+        authorityState = "advisory";
+      } else {
+        governanceAttachment = "pending";
+        status = "healthy";
+        authorityState = "advisory";
+      }
+      return {
+        status,
+        authorityState,
+        protectionLevel: observeProtectionLevel,
+        durability: "inactive",
+        tier: "compat",
+        compatEnforcement: "protective",
+        cluster_detected: false,
+        bypass_detected: false,
+        totalSteps: 0,
+        totalBlocks: 0,
+        totalErrors,
+        killed: false,
+        shadowEvaluations: 0,
+        governanceAttachment
+      };
+    },
+    getState: () => approvedRuntimeSession ? approvedRuntimeSession.getState() : EMPTY_STATE_SNAPSHOT,
+    getLastNarrowing: () => approvedRuntimeSession ? approvedRuntimeSession.getLastNarrowing() : null,
+    getLastShadowDelta: () => approvedRuntimeSession ? approvedRuntimeSession.getLastShadowDelta() : null,
+    getLastTrace: () => approvedRuntimeSession ? approvedRuntimeSession.getLastTrace() : null,
+    narrow(...args) {
+      approvedRuntimeSession?.narrow(...args);
     },
     widen() {
+      approvedRuntimeSession?.widen();
     },
-    addLabel() {
+    addLabel(label) {
+      approvedRuntimeSession?.addLabel(label);
     },
-    tools: {},
-    getWorkflowState: () => Promise.resolve(null),
-    handoff: () => Promise.resolve(null)
+    tools,
+    getWorkflowState: () => approvedRuntimeSession ? approvedRuntimeSession.getWorkflowState() : Promise.resolve(null),
+    handoff: (offer) => approvedRuntimeSession ? approvedRuntimeSession.handoff(offer) : Promise.resolve(null)
   };
 }
 function toNarrowingSnapshot(result) {
@@ -8257,6 +8621,9 @@ function determineProtectionLevel(mode, tools, contracts, apiKey) {
   const allWrapped = stateBearingTools.every((c) => wrappedTools.has(c.tool));
   return allWrapped ? "govern" : "protect";
 }
+function determineRuntimeFreeProtectionLevel(mode) {
+  return mode === "enforce" ? "protect" : "monitor";
+}
 function isStateBearing(contract) {
   if (contract.commit_requirement != null && contract.commit_requirement !== "none") return true;
   if (contract.transitions != null) return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayci/replay",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "ReplayCI SDK for deterministic tool-call validation and observation.",
   "license": "ISC",
   "author": "ReplayCI",
@@ -45,12 +45,14 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
+    "postbuild": "node scripts/check-dist-parity.mjs",
     "prepublishOnly": "npm run build",
+    "check-dist": "node scripts/check-dist-parity.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "@replayci/contracts-core": "^0.1.0",
+    "@replayci/contracts-core": "^0.1.11",
     "re2": "^1.20.0",
     "yaml": "^2.0.0"
   },