@replayci/replay 0.1.6 → 0.1.8

package/dist/index.cjs

@@ -1916,7 +1916,12 @@ function safelyCaptureResponse(input) {
       });
       input.persistHealthEvent();
     }
-  } catch {
+  } catch (err) {
+    emitDiagnostic(input.diagnostics, {
+      type: "capture_error",
+      session_id: input.sessionId,
+      details: err instanceof Error ? err.message : "response capture failed"
+    });
   }
 }
 function safelyPushStreamCapture(input) {
@@ -1945,7 +1950,12 @@ function safelyPushStreamCapture(input) {
       });
       input.persistHealthEvent();
     }
-  } catch {
+  } catch (err) {
+    emitDiagnostic(input.diagnostics, {
+      type: "capture_error",
+      session_id: input.sessionId,
+      details: err instanceof Error ? err.message : "stream capture failed"
+    });
   }
 }
 function buildCapturedCall(input) {
@@ -2514,6 +2524,173 @@ function formatErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/preconditions.ts
+function evaluatePreconditions(preconditions, sessionState, currentArguments) {
+  return preconditions.map(
+    (p) => evaluatePrecondition(p, sessionState, currentArguments)
+  );
+}
+function evaluatePrecondition(precondition, sessionState, currentArguments) {
+  if (precondition.requires_step_count) {
+    const required = precondition.requires_step_count.gte;
+    if (sessionState.totalStepCount < required) {
+      return {
+        satisfied: false,
+        detail: `Need ${required} prior steps, have ${sessionState.totalStepCount}`
+      };
+    }
+  }
+  if (precondition.requires_prior_tool) {
+    const toolName = precondition.requires_prior_tool;
+    const resourcePath = precondition.resource ? typeof precondition.resource === "string" ? precondition.resource : precondition.resource.path : void 0;
+    const resourceValue = resourcePath ? extractPath(currentArguments ?? {}, resourcePath) : void 0;
+    const cacheKey = resourceValue !== void 0 ? `${toolName}:${JSON.stringify(resourceValue)}` : toolName;
+    let priorStep;
+    for (let i = sessionState.steps.length - 1; i >= 0; i--) {
+      const s = sessionState.steps[i];
+      if (s.toolCalls.some((tc) => {
+        if (tc.toolName !== toolName) return false;
+        if (tc.proposal_decision !== "allowed") return false;
+        if (resourceValue !== void 0 && tc.resourceValues?.[resourcePath] !== resourceValue) {
+          return false;
+        }
+        return true;
+      })) {
+        priorStep = s;
+        break;
+      }
+    }
+    const cachedExtract = sessionState.satisfiedPreconditions.get(cacheKey);
+    if (!priorStep && cachedExtract === void 0) {
+      const detail = resourceValue !== void 0 ? `Required prior tool ${toolName} not found for resource ${JSON.stringify(resourceValue)}` : `Required prior tool ${toolName} not found in session`;
+      return { satisfied: false, detail };
+    }
+    if (precondition.with_output) {
+      const extract = priorStep?.outputExtract ?? cachedExtract ?? {};
+      for (const assertion of precondition.with_output) {
+        const value = extractPath(extract, assertion.path);
+        if (assertion.equals !== void 0 && value !== assertion.equals) {
+          return {
+            satisfied: false,
+            detail: `Prior tool output assertion failed: ${assertion.path} \u2014 expected ${JSON.stringify(assertion.equals)}, got ${JSON.stringify(value)}`
+          };
+        }
+      }
+    }
+  }
+  return { satisfied: true, detail: "" };
+}
+function extractPath(obj, path) {
+  const cleanPath = path.startsWith("$.") ? path.slice(2) : path;
+  if (cleanPath === "" || cleanPath === "$") return obj;
+  const segments = cleanPath.split(".");
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0) return void 0;
+    if (typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+
+// src/argumentValues.ts
+function evaluateArgumentValueInvariants(parsedArguments, invariants) {
+  const failures = [];
+  for (const inv of invariants) {
+    const value = extractPath(parsedArguments, inv.path);
+    if (inv.exact_match !== void 0) {
+      const strValue = typeof value === "string" ? value : JSON.stringify(value);
+      if (strValue !== inv.exact_match) {
+        failures.push({
+          path: inv.path,
+          operator: "exact_match",
+          expected: inv.exact_match,
+          actual: value,
+          detail: `Expected exact match "${inv.exact_match}", got "${strValue}"`
+        });
+      }
+    }
+    if (inv.regex !== void 0) {
+      const strValue = typeof value === "string" ? value : String(value);
+      try {
+        const re = safeRegex(inv.regex);
+        if (!re.test(strValue)) {
+          failures.push({
+            path: inv.path,
+            operator: "regex",
+            expected: inv.regex,
+            actual: value,
+            detail: `Value "${strValue}" does not match regex "${inv.regex}"`
+          });
+        }
+      } catch {
+        failures.push({
+          path: inv.path,
+          operator: "regex",
+          expected: inv.regex,
+          actual: value,
+          detail: `Invalid regex pattern: "${inv.regex}"`
+        });
+      }
+    }
+    if (inv.one_of !== void 0) {
+      const match = inv.one_of.some((candidate) => {
+        if (typeof candidate === typeof value) {
+          return JSON.stringify(candidate) === JSON.stringify(value);
+        }
+        return false;
+      });
+      if (!match) {
+        failures.push({
+          path: inv.path,
+          operator: "one_of",
+          expected: inv.one_of,
+          actual: value,
+          detail: `Value ${JSON.stringify(value)} not in ${JSON.stringify(inv.one_of)}`
+        });
+      }
+    }
+    if (inv.type !== void 0) {
+      const actualType = Array.isArray(value) ? "array" : typeof value;
+      if (actualType !== inv.type) {
+        failures.push({
+          path: inv.path,
+          operator: "type",
+          expected: inv.type,
+          actual: actualType,
+          detail: `Expected type "${inv.type}", got "${actualType}"`
+        });
+      }
+    }
+    if (typeof inv.gte === "number") {
+      if (typeof value !== "number" || value < inv.gte) {
+        failures.push({
+          path: inv.path,
+          operator: "gte",
+          expected: inv.gte,
+          actual: value,
+          detail: `Expected >= ${inv.gte}, got ${JSON.stringify(value)}`
+        });
+      }
+    }
+    if (typeof inv.lte === "number") {
+      if (typeof value !== "number" || value > inv.lte) {
+        failures.push({
+          path: inv.path,
+          operator: "lte",
+          expected: inv.lte,
+          actual: value,
+          detail: `Expected <= ${inv.lte}, got ${JSON.stringify(value)}`
+        });
+      }
+    }
+  }
+  return {
+    passed: failures.length === 0,
+    failures
+  };
+}
+
 // src/validate.ts
 function prepareContracts(input) {
   assertSupportedNodeRuntime();
@@ -2578,6 +2755,7 @@ function evaluateAllContracts(matchedContracts, extraction) {
     failures.push(...evaluateExpectTools(contract, extraction.toolCalls));
     failures.push(...evaluateOutputInvariants(contract, extraction.normalizedResponse));
     failures.push(...evaluateExpectedToolCallMatchers(contract, extraction.toolCalls));
+    failures.push(...evaluateArgumentInvariants(contract, extraction.toolCalls));
   }
   return {
     pass: failures.length === 0,
@@ -2745,6 +2923,28 @@ function evaluateExpectedToolCallMatchers(contract, toolCalls) {
     contract_file: contract.contract_file
   }));
 }
+function evaluateArgumentInvariants(contract, toolCalls) {
+  if (!contract.argument_value_invariants || contract.argument_value_invariants.length === 0) {
+    return [];
+  }
+  const failures = [];
+  for (const toolCall of toolCalls) {
+    if (toolCall.name !== contract.tool) continue;
+    const parsedArgs = toolCall.parsedArguments != null && typeof toolCall.parsedArguments === "object" ? toolCall.parsedArguments : {};
+    const result = evaluateArgumentValueInvariants(parsedArgs, contract.argument_value_invariants);
+    for (const f of result.failures) {
+      failures.push({
+        path: f.path,
+        operator: f.operator,
+        expected: f.expected,
+        found: f.actual,
+        message: f.detail,
+        contract_file: contract.contract_file
+      });
+    }
+  }
+  return failures;
+}
 function mapInvariantFailure(contract, failure, normalizedResponse) {
   const invariant = findMatchingInvariant(contract.assertions.output_invariants, failure);
   const lookup = (0, import_contracts_core3.getPathValue)(normalizedResponse, failure.path);
@@ -3024,6 +3224,34 @@ function redactCapture(input) {
     pattern_fingerprint: PATTERN_FINGERPRINT
   };
 }
+function redactTrace(trace, captureLevel) {
+  if (captureLevel === "full") return trace;
+  return {
+    ...trace,
+    entries: trace.entries.map((entry) => redactTraceEntry(entry, captureLevel))
+  };
+}
+function redactTraceEntry(entry, captureLevel) {
+  if (captureLevel === "metadata") {
+    return {
+      ...entry,
+      checked: redactRecord(entry.checked),
+      found: redactRecord(entry.found)
+    };
+  }
+  return entry;
+}
+function redactRecord(record) {
+  const result = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === "string") {
+      result[key] = redactString(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
 
 // src/errors/replay.ts
 var ReplayContractError = class extends Error {
@@ -3320,8 +3548,9 @@ function toRecord8(value) {
 var import_node_crypto3 = __toESM(require("crypto"), 1);
 
 // src/phases.ts
-function validatePhaseTransition(toolCalls, sessionState, compiledSession) {
+function validatePhaseTransition(toolCalls, sessionState, compiledSession, ctx) {
   if (!compiledSession.phases) {
+    ctx?.trace.push({ stage: "phase", tool: null, verdict: "skip", reason: "no_phases_configured", checked: {}, found: {} });
     return { legal: true, newPhase: sessionState.currentPhase };
   }
   const attemptedTransitions = [];
@@ -3332,6 +3561,14 @@ function validatePhaseTransition(toolCalls, sessionState, compiledSession) {
       sessionState.currentPhase ?? ""
     );
     if (!allowedTransitions?.includes(contract.transitions.advances_to)) {
+      ctx?.trace.push({
+        stage: "phase",
+        tool: toolCall.name,
+        verdict: "block",
+        reason: "illegal_phase_transition",
+        checked: { advances_to: contract.transitions.advances_to, from: sessionState.currentPhase },
+        found: { allowed_transitions: allowedTransitions ?? [] }
+      });
       return {
         legal: false,
         newPhase: sessionState.currentPhase,
@@ -3348,6 +3585,14 @@ function validatePhaseTransition(toolCalls, sessionState, compiledSession) {
   if (attemptedTransitions.length > 1) {
     const distinctTargets = new Set(attemptedTransitions.map((t) => t.target));
     if (distinctTargets.size > 1) {
+      ctx?.trace.push({
+        stage: "phase",
+        tool: attemptedTransitions.map((t) => t.tool).join(", "),
+        verdict: "block",
+        reason: "ambiguous_phase_transition",
+        checked: { targets: Array.from(distinctTargets) },
+        found: { from: sessionState.currentPhase }
+      });
       return {
         legal: false,
         newPhase: sessionState.currentPhase,
@@ -3358,7 +3603,17 @@ function validatePhaseTransition(toolCalls, sessionState, compiledSession) {
     }
   }
   if (attemptedTransitions.length > 0) {
-    return { legal: true, newPhase: attemptedTransitions[0].target };
+    const target = attemptedTransitions[0].target;
+    const allowedTransitions = compiledSession.transitions.get(sessionState.currentPhase ?? "") ?? [];
+    ctx?.trace.push({
+      stage: "phase",
+      tool: attemptedTransitions[0].tool,
+      verdict: "allow",
+      reason: "phase_advanced",
+      checked: { advances_to: target, from: sessionState.currentPhase },
+      found: { allowed_transitions: allowedTransitions }
+    });
+    return { legal: true, newPhase: target };
   }
   return { legal: true, newPhase: sessionState.currentPhase };
 }
@@ -3607,77 +3862,8 @@ function checkCircuitBreaker(state, config) {
   return { triggered: false, reason: null };
 }
 
-// src/preconditions.ts
-function evaluatePreconditions(preconditions, sessionState, currentArguments) {
-  return preconditions.map(
-    (p) => evaluatePrecondition(p, sessionState, currentArguments)
-  );
-}
-function evaluatePrecondition(precondition, sessionState, currentArguments) {
-  if (precondition.requires_step_count) {
-    const required = precondition.requires_step_count.gte;
-    if (sessionState.totalStepCount < required) {
-      return {
-        satisfied: false,
-        detail: `Need ${required} prior steps, have ${sessionState.totalStepCount}`
-      };
-    }
-  }
-  if (precondition.requires_prior_tool) {
-    const toolName = precondition.requires_prior_tool;
-    const resourcePath = precondition.resource ? typeof precondition.resource === "string" ? precondition.resource : precondition.resource.path : void 0;
-    const resourceValue = resourcePath ? extractPath(currentArguments ?? {}, resourcePath) : void 0;
-    const cacheKey = resourceValue !== void 0 ? `${toolName}:${JSON.stringify(resourceValue)}` : toolName;
-    let priorStep;
-    for (let i = sessionState.steps.length - 1; i >= 0; i--) {
-      const s = sessionState.steps[i];
-      if (s.toolCalls.some((tc) => {
-        if (tc.toolName !== toolName) return false;
-        if (tc.proposal_decision !== "allowed") return false;
-        if (resourceValue !== void 0 && tc.resourceValues?.[resourcePath] !== resourceValue) {
-          return false;
-        }
-        return true;
-      })) {
-        priorStep = s;
-        break;
-      }
-    }
-    const cachedExtract = sessionState.satisfiedPreconditions.get(cacheKey);
-    if (!priorStep && cachedExtract === void 0) {
-      const detail = resourceValue !== void 0 ? `Required prior tool ${toolName} not found for resource ${JSON.stringify(resourceValue)}` : `Required prior tool ${toolName} not found in session`;
-      return { satisfied: false, detail };
-    }
-    if (precondition.with_output) {
-      const extract = priorStep?.outputExtract ?? cachedExtract ?? {};
-      for (const assertion of precondition.with_output) {
-        const value = extractPath(extract, assertion.path);
-        if (assertion.equals !== void 0 && value !== assertion.equals) {
-          return {
-            satisfied: false,
-            detail: `Prior tool output assertion failed: ${assertion.path} \u2014 expected ${JSON.stringify(assertion.equals)}, got ${JSON.stringify(value)}`
-          };
-        }
-      }
-    }
-  }
-  return { satisfied: true, detail: "" };
-}
-function extractPath(obj, path) {
-  const cleanPath = path.startsWith("$.") ? path.slice(2) : path;
-  if (cleanPath === "" || cleanPath === "$") return obj;
-  const segments = cleanPath.split(".");
-  let current = obj;
-  for (const segment of segments) {
-    if (current === null || current === void 0) return void 0;
-    if (typeof current !== "object") return void 0;
-    current = current[segment];
-  }
-  return current;
-}
-
 // src/crossStep.ts
-function validateCrossStep(toolCalls, sessionState, contracts) {
+function validateCrossStep(toolCalls, sessionState, contracts, ctx) {
   const failures = [];
   const contractByTool = new Map(contracts.map((c) => [c.tool, c]));
   const workingForbidden = new Set(sessionState.forbiddenTools);
@@ -3705,8 +3891,17 @@ function validateCrossStep(toolCalls, sessionState, contracts) {
         reason: "forbidden_tool",
         detail: resourceValue !== void 0 ? `Tool "${tc.name}" is forbidden in this session for resource ${JSON.stringify(resourceValue)}` : `Tool "${tc.name}" is forbidden in this session`
       });
+      ctx?.trace.push({
+        stage: "cross_step",
+        tool: tc.name,
+        verdict: "block",
+        reason: "forbidden_tool",
+        checked: { tool: tc.name },
+        found: { is_resource_scoped: resourceValue !== void 0, resource_value: resourceValue ?? null }
+      });
       continue;
     }
+    let crossStepPassed = true;
     if (contract?.preconditions && contract.preconditions.length > 0) {
       const results = evaluatePreconditions(
         contract.preconditions,
@@ -3715,6 +3910,7 @@ function validateCrossStep(toolCalls, sessionState, contracts) {
       );
       for (const result of results) {
         if (!result.satisfied) {
+          crossStepPassed = false;
           failures.push({
             toolName: tc.name,
             reason: "precondition_not_met",
@@ -3723,6 +3919,25 @@ function validateCrossStep(toolCalls, sessionState, contracts) {
         }
       }
     }
+    if (crossStepPassed) {
+      ctx?.trace.push({
+        stage: "cross_step",
+        tool: tc.name,
+        verdict: "allow",
+        reason: "preconditions_satisfied",
+        checked: { requires_prior_tool: contract?.preconditions?.[0]?.requires_prior_tool ?? null },
+        found: { resource_value: resourceValue ?? null }
+      });
+    } else {
+      ctx?.trace.push({
+        stage: "cross_step",
+        tool: tc.name,
+        verdict: "block",
+        reason: "precondition_not_met",
+        checked: { requires_prior_tool: contract?.preconditions?.[0]?.requires_prior_tool ?? null },
+        found: { resource_value: resourceValue ?? null, matching_step_index: null }
+      });
+    }
     if (contract?.forbids_after) {
       for (const entry of contract.forbids_after) {
         if (typeof entry === "string") {
@@ -3749,104 +3964,6 @@ function validateCrossStep(toolCalls, sessionState, contracts) {
   };
 }
 
-// src/argumentValues.ts
-function evaluateArgumentValueInvariants(parsedArguments, invariants) {
-  const failures = [];
-  for (const inv of invariants) {
-    const value = extractPath(parsedArguments, inv.path);
-    if (inv.exact_match !== void 0) {
-      const strValue = typeof value === "string" ? value : JSON.stringify(value);
-      if (strValue !== inv.exact_match) {
-        failures.push({
-          path: inv.path,
-          operator: "exact_match",
-          expected: inv.exact_match,
-          actual: value,
-          detail: `Expected exact match "${inv.exact_match}", got "${strValue}"`
-        });
-      }
-    }
-    if (inv.regex !== void 0) {
-      const strValue = typeof value === "string" ? value : String(value);
-      try {
-        const re = safeRegex(inv.regex);
-        if (!re.test(strValue)) {
-          failures.push({
-            path: inv.path,
-            operator: "regex",
-            expected: inv.regex,
-            actual: value,
-            detail: `Value "${strValue}" does not match regex "${inv.regex}"`
-          });
-        }
-      } catch {
-        failures.push({
-          path: inv.path,
-          operator: "regex",
-          expected: inv.regex,
-          actual: value,
-          detail: `Invalid regex pattern: "${inv.regex}"`
-        });
-      }
-    }
-    if (inv.one_of !== void 0) {
-      const match = inv.one_of.some((candidate) => {
-        if (typeof candidate === typeof value) {
-          return JSON.stringify(candidate) === JSON.stringify(value);
-        }
-        return false;
-      });
-      if (!match) {
-        failures.push({
-          path: inv.path,
-          operator: "one_of",
-          expected: inv.one_of,
-          actual: value,
-          detail: `Value ${JSON.stringify(value)} not in ${JSON.stringify(inv.one_of)}`
-        });
-      }
-    }
-    if (inv.type !== void 0) {
-      const actualType = Array.isArray(value) ? "array" : typeof value;
-      if (actualType !== inv.type) {
-        failures.push({
-          path: inv.path,
-          operator: "type",
-          expected: inv.type,
-          actual: actualType,
-          detail: `Expected type "${inv.type}", got "${actualType}"`
-        });
-      }
-    }
-    if (typeof inv.gte === "number") {
-      if (typeof value !== "number" || value < inv.gte) {
-        failures.push({
-          path: inv.path,
-          operator: "gte",
-          expected: inv.gte,
-          actual: value,
-          detail: `Expected >= ${inv.gte}, got ${JSON.stringify(value)}`
-        });
-      }
-    }
-    if (typeof inv.lte === "number") {
-      if (typeof value !== "number" || value > inv.lte) {
-        failures.push({
-          path: inv.path,
-          operator: "lte",
-          expected: inv.lte,
-          actual: value,
-          detail: `Expected <= ${inv.lte}, got ${JSON.stringify(value)}`
-        });
-      }
-    }
-  }
-  return {
-    passed: failures.length === 0,
-    failures
-  };
-}
-
 // src/messageValidation.ts
 var import_contracts_core4 = require("@replayci/contracts-core");
 function validateToolResultMessages(messages, contracts, provider) {
@@ -4042,20 +4159,23 @@ function extractPath2(obj, path) {
 }
 
 // src/narrow.ts
-function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPolicy, manualFilter) {
+function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPolicy, manualFilter, ctx) {
   const allowed = [];
   const removed = [];
   for (const tool of requestedTools) {
     if (manualFilter && !manualFilter.includes(tool.name)) {
       removed.push({ tool: tool.name, reason: "manual_filter" });
+      ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "remove", reason: "manual_filter", checked: { filter: manualFilter }, found: {} });
       continue;
     }
     const contract = compiledSession.perToolContracts.get(tool.name);
     if (!contract) {
       if (unmatchedPolicy === "allow") {
         allowed.push(tool);
+        ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "allow", reason: "no_contract_passthrough", checked: { unmatched_policy: "allow" }, found: {} });
       } else {
         removed.push({ tool: tool.name, reason: "no_contract" });
+        ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "remove", reason: "no_contract", checked: { unmatched_policy: "block" }, found: {} });
       }
       continue;
     }
@@ -4068,6 +4188,7 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
           reason: "wrong_phase",
           detail: `Tool valid in [${contract.transitions.valid_in_phases.join(", ")}], current phase: ${sessionState.currentPhase}`
         });
+        ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "remove", reason: "wrong_phase", checked: { valid_in_phases: contract.transitions.valid_in_phases }, found: { current_phase: sessionState.currentPhase } });
         continue;
       }
     }
@@ -4078,6 +4199,18 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
       );
       const unsatisfied = results.find((r) => !r.satisfied);
       if (unsatisfied) {
+        const firstPre = contract.preconditions[0];
+        ctx?.trace.push({
+          stage: "narrow",
+          tool: tool.name,
+          verdict: "remove",
+          reason: "precondition_not_met",
+          checked: {
+            requires_prior_tool: firstPre.requires_prior_tool ?? null,
+            with_output: firstPre.with_output ?? []
+          },
+          found: { satisfied_precondition_cache_hit: false }
+        });
         removed.push({
           tool: tool.name,
           reason: "precondition_not_met",
@@ -4091,6 +4224,7 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
         tool: tool.name,
         reason: "forbidden_in_state"
       });
+      ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "remove", reason: "forbidden_in_state", checked: { tool: tool.name }, found: { is_resource_scoped: false } });
       continue;
     }
     if (compiledSession.policyProgram && compiledSession.principal !== null && compiledSession.principal !== void 0) {
@@ -4107,9 +4241,24 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
           reason: "policy_denied",
           detail: verdict.reason ?? "Policy deny rule matched"
         });
+        ctx?.trace.push({ stage: "narrow", tool: tool.name, verdict: "remove", reason: "policy_denied", checked: { rule_type: "session_deny" }, found: { matched: true } });
         continue;
       }
     }
+    ctx?.trace.push({
+      stage: "narrow",
+      tool: tool.name,
+      verdict: "allow",
+      reason: "all_checks_passed",
+      checked: {
+        has_contract: true,
+        phase_ok: true,
+        preconditions_ok: true,
+        not_forbidden: true,
+        policy_ok: true
+      },
+      found: {}
+    });
     allowed.push(tool);
   }
   return { allowed, removed };
@@ -4603,7 +4752,7 @@ function replay(client, opts = {}) {
   const unmatchedPolicy = opts.unmatchedPolicy ?? "block";
   const maxRetries = Math.min(Math.max(0, opts.maxRetries ?? 0), MAX_RETRIES);
   const compatEnforcement = opts.compatEnforcement ?? "protective";
-  const diagnostics = opts.diagnostics;
+  const diagnostics = opts.diagnostics ?? defaultReplayDiagnosticsHandler;
   let provider;
   try {
     provider = detectProvider(client);
@@ -4620,12 +4769,12 @@ function replay(client, opts = {}) {
     contracts = resolveContracts(opts);
   } catch (err) {
     const detail = err instanceof Error ? err.message : "Failed to load contracts";
-    emitDiagnostic2(diagnostics, { type: "replay_contract_error", details: detail });
+    emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
     return createBlockingInactiveSession(client, sessionId, detail);
   }
   const configError = validateConfig(contracts, opts);
   if (configError) {
-    emitDiagnostic2(diagnostics, { type: "replay_contract_error", details: configError.message });
+    emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: configError.message });
     return createBlockingInactiveSession(client, sessionId, configError.message, configError);
   }
   let discoveredSessionYaml = null;
@@ -4633,9 +4782,15 @@ function replay(client, opts = {}) {
     discoveredSessionYaml = discoverSessionYaml(opts);
   } catch (err) {
     const detail = `session.yaml: ${err instanceof Error ? err.message : String(err)}`;
-    emitDiagnostic2(diagnostics, { type: "replay_contract_error", details: detail });
+    emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
     return createBlockingInactiveSession(client, sessionId, detail);
   }
+  if (opts.contractsDir && !discoveredSessionYaml && !opts.sessionYamlPath) {
+    emitDiagnostic2(diagnostics, {
+      type: "replay_compile_warning",
+      details: "No session.yaml found in contractsDir \u2014 session-level features (phases, policy, session_limits) are inactive. Per-tool contracts still apply."
+    });
+  }
   let sessionYaml = discoveredSessionYaml;
   if (!sessionYaml && opts.providerConstraints) {
     sessionYaml = { schema_version: "1.0", agent, provider_constraints: opts.providerConstraints };
@@ -4649,15 +4804,19 @@ function replay(client, opts = {}) {
       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_contract_error",
-      details: `Session compilation: ${err instanceof Error ? err.message : String(err)}`
+      type: "replay_compile_error",
+      details: detail
     });
+    if (discoveredSessionYaml) {
+      return createBlockingInactiveSession(client, sessionId, detail);
+    }
   }
   if (compiledSession?.warnings && compiledSession.warnings.length > 0) {
     for (const warning of compiledSession.warnings) {
       emitDiagnostic2(diagnostics, {
-        type: "replay_contract_error",
+        type: "replay_compile_warning",
         details: `Compile warning: ${warning}`
       });
     }
@@ -4669,7 +4828,7 @@ function replay(client, opts = {}) {
       if (spec.block_incompatible && spec.block_incompatible.length > 0) {
         const detail = `Provider '${provider}' is blocked by provider_constraints: ${spec.block_incompatible.join("; ")}`;
         const err = new ReplayConfigError("provider_incompatible", detail);
-        emitDiagnostic2(diagnostics, { type: "replay_contract_error", details: detail });
+        emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
         return createBlockingInactiveSession(client, sessionId, detail, err);
       }
       if (spec.warn_incompatible && spec.warn_incompatible.length > 0) {
@@ -4703,10 +4862,10 @@ function replay(client, opts = {}) {
     emitDiagnostic2(diagnostics, { type: "replay_inactive", reason: "unsupported_client" });
     return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
   }
-  const protectionLevel = determineProtectionLevel(mode, opts.tools, contracts);
+  const apiKey = resolveApiKey2(opts);
+  const protectionLevel = determineProtectionLevel(mode, opts.tools, contracts, apiKey);
   const maxUnguardedCalls = opts.maxUnguardedCalls ?? DEFAULT_MAX_UNGUARDED_CALLS;
   const narrowingFeedback = opts.narrowingFeedback ?? "silent";
-  const apiKey = resolveApiKey2(opts);
   let runtimeClient = null;
   let runtimeSession = null;
   let runtimeInitPromise = null;
@@ -4791,6 +4950,7 @@ function replay(client, opts = {}) {
   let bypassDetected = false;
   let lastShadowDeltaValue = null;
   let lastNarrowResult = null;
+  let lastTrace = null;
   let shadowEvaluationCount = 0;
   let manualFilter = null;
   const deferredReceipts = /* @__PURE__ */ new Map();
@@ -4846,7 +5006,12 @@ function replay(client, opts = {}) {
         void result.catch(() => {
         });
       }
-    } catch {
+    } catch (err) {
+      emitDiagnostic2(diagnostics, {
+        type: "replay_state_sync_error",
+        session_id: sessionId,
+        details: err instanceof Error ? err.message : "state sync failed"
+      });
     }
   }
   function appendCaptureToStore(capture) {
@@ -4860,6 +5025,18 @@ function replay(client, opts = {}) {
     } catch {
     }
   }
+  function createTrace(stepIndex) {
+    const entries = [];
+    return {
+      sessionId,
+      stepIndex,
+      complete: false,
+      entries,
+      push(entry) {
+        entries.push(entry);
+      }
+    };
+  }
   const enforcementCreate = async function replayEnforcementCreate(...args) {
     if (killed) {
       throw new ReplayKillError(sessionId, killedAt);
@@ -4902,8 +5079,19 @@ function replay(client, opts = {}) {
       total_ms: 0,
       enforcement_ms: 0
     };
+    const trace = createTrace(sessionState.totalStepCount);
+    const traceCtx = { trace };
+    let currentTraceStage = "narrow";
     const request = toRecord10(args[0]);
     const requestToolNames = extractRequestToolNames(request);
+    const messages = Array.isArray(request.messages) ? request.messages : [];
+    if (messages.length > 0) {
+      const toolResults = extractToolResults(messages, provider);
+      if (toolResults.length > 0) {
+        const outputUpdates = extractOutputFromToolResults(toolResults, sessionState, contracts);
+        sessionState = applyOutputExtracts(sessionState, outputUpdates);
+      }
+    }
     let narrowResult = null;
     let activeArgs = args;
     if (compiledSession && Array.isArray(request.tools) && request.tools.length > 0) {
@@ -4914,7 +5102,8 @@ function replay(client, opts = {}) {
           sessionState,
           compiledSession,
           unmatchedPolicy,
-          manualFilter
+          manualFilter,
+          traceCtx
         );
         lastNarrowResult = narrowResult;
         if (narrowResult.removed.length > 0) {
@@ -4952,55 +5141,96 @@ function replay(client, opts = {}) {
     timing.narrow_ms = Date.now() - guardStart;
     const preCheckStart = Date.now();
     try {
+      currentTraceStage = "pre_check";
       if (mode === "enforce" && resolvedSessionLimits) {
         const limitResult = checkSessionLimits(sessionState, resolvedSessionLimits);
         if (limitResult.exceeded) {
-          const decision = {
-            action: "block",
-            tool_calls: [],
-            blocked: [{
-              tool_name: "_session",
-              arguments: "",
-              reason: "session_limit_exceeded",
-              contract_file: "",
-              failures: [{ path: "$", operator: "session_limit", expected: "", found: "", message: limitResult.reason ?? "session limit exceeded" }]
-            }],
-            response_modification: gateMode
-          };
-          sessionState = recordDecisionOutcome(sessionState, "blocked");
-          if (resolvedSessionLimits.circuit_breaker) {
-            const cbResult = checkCircuitBreaker(sessionState, resolvedSessionLimits.circuit_breaker);
-            if (cbResult.triggered) {
-              killed = true;
-              killedAt = (/* @__PURE__ */ new Date()).toISOString();
-              sessionState = killSession(sessionState);
-              emitDiagnostic2(diagnostics, { type: "replay_kill", session_id: sessionId });
+          let narrowedPastLimit = false;
+          if (limitResult.reason?.startsWith("max_tool_calls") && resolvedSessionLimits.max_tool_calls_mode === "narrow" && resolvedSessionLimits.max_calls_per_tool) {
+            const costOk = !(typeof resolvedSessionLimits.max_cost_per_session === "number" && sessionState.actualCost >= resolvedSessionLimits.max_cost_per_session);
+            if (costOk) {
+              const currentRequest = toRecord10(activeArgs[0]);
+              const currentTools = Array.isArray(currentRequest.tools) ? extractToolDefinitions(currentRequest.tools) : [];
+              const budgetedTools = currentTools.filter((tool) => {
+                const max = resolvedSessionLimits.max_calls_per_tool[tool.name];
+                if (typeof max !== "number") return false;
+                return (sessionState.toolCallCounts.get(tool.name) ?? 0) < max;
+              });
+              if (budgetedTools.length > 0) {
+                const modifiedRequest = { ...currentRequest, tools: budgetedTools };
+                activeArgs = [modifiedRequest, ...Array.prototype.slice.call(activeArgs, 1)];
+                narrowedPastLimit = true;
+                trace.push({
+                  stage: "pre_check",
+                  tool: null,
+                  verdict: "narrow",
+                  reason: "max_tool_calls_narrow_mode",
+                  checked: { max_tool_calls: resolvedSessionLimits.max_tool_calls ?? null, budgeted_tools: budgetedTools.map((t) => t.name) },
+                  found: { total_tool_calls: sessionState.totalToolCalls }
+                });
+              }
             }
           }
-          timing.pre_check_ms = Date.now() - preCheckStart;
-          captureDecision(
-            decision,
-            null,
-            request,
-            guardStart,
-            requestToolNames,
-            null,
-            narrowResult,
-            null,
-            null,
-            null,
-            void 0,
-            timing
-          );
-          if (isCompatAdvisory) {
-            emitDiagnostic2(diagnostics, {
-              type: "replay_compat_advisory",
-              session_id: sessionId,
-              would_block: decision.blocked,
-              details: limitResult.reason ?? "session limit exceeded"
+          if (!narrowedPastLimit) {
+            trace.push({
+              stage: "pre_check",
+              tool: null,
+              verdict: "block",
+              reason: "session_limit_exceeded",
+              checked: {
+                max_steps: resolvedSessionLimits.max_steps ?? null,
+                max_tool_calls: resolvedSessionLimits.max_tool_calls ?? null,
+                max_cost: resolvedSessionLimits.max_cost_per_session ?? null
+              },
+              found: { total_steps: sessionState.totalStepCount, total_tool_calls: sessionState.totalToolCalls, actual_cost: sessionState.actualCost }
             });
-          } else {
-            throw buildContractError2(decision);
+            const decision = {
+              action: "block",
+              tool_calls: [],
+              blocked: [{
+                tool_name: "_session",
+                arguments: "",
+                reason: "session_limit_exceeded",
+                contract_file: "",
+                failures: [{ path: "$", operator: "session_limit", expected: "", found: "", message: limitResult.reason ?? "session limit exceeded" }]
+              }],
+              response_modification: gateMode
+            };
+            sessionState = recordDecisionOutcome(sessionState, "blocked");
+            if (resolvedSessionLimits.circuit_breaker) {
+              const cbResult = checkCircuitBreaker(sessionState, resolvedSessionLimits.circuit_breaker);
+              if (cbResult.triggered) {
+                killed = true;
+                killedAt = (/* @__PURE__ */ new Date()).toISOString();
+                sessionState = killSession(sessionState);
+                emitDiagnostic2(diagnostics, { type: "replay_kill", session_id: sessionId });
+              }
+            }
+            timing.pre_check_ms = Date.now() - preCheckStart;
+            captureDecision(
+              decision,
+              null,
+              request,
+              guardStart,
+              requestToolNames,
+              null,
+              narrowResult,
+              null,
+              null,
+              null,
+              void 0,
+              timing
+            );
+            if (isCompatAdvisory) {
+              emitDiagnostic2(diagnostics, {
+                type: "replay_compat_advisory",
+                session_id: sessionId,
+                would_block: decision.blocked,
+                details: limitResult.reason ?? "session limit exceeded"
+              });
+            } else {
+              throw buildContractError2(decision);
+            }
           }
         }
         if (isAtHardStepCap(sessionState)) {
@@ -5033,24 +5263,32 @@ function replay(client, opts = {}) {
           );
           throw buildContractError2(decision);
         }
+        if (!checkSessionLimits(sessionState, resolvedSessionLimits).exceeded) {
+          trace.push({
+            stage: "pre_check",
+            tool: null,
+            verdict: "allow",
+            reason: "session_limits_ok",
+            checked: {
+              max_steps: resolvedSessionLimits.max_steps ?? null,
+              max_tool_calls: resolvedSessionLimits.max_tool_calls ?? null,
+              max_cost: resolvedSessionLimits.max_cost_per_session ?? null
+            },
+            found: { total_steps: sessionState.totalStepCount, total_tool_calls: sessionState.totalToolCalls, actual_cost: sessionState.actualCost }
+          });
+        }
+      } else if (mode === "enforce") {
+        trace.push({ stage: "pre_check", tool: null, verdict: "skip", reason: "no_session_limits", checked: {}, found: {} });
       }
-      const messages = Array.isArray(request.messages) ? request.messages : [];
       if (messages.length > 0) {
         const msgResult = validateToolResultMessages(messages, contracts, provider);
         if (!msgResult.passed) {
           emitDiagnostic2(diagnostics, {
-            type: "replay_contract_error",
+            type: "replay_validation_warning",
             details: `Message validation: ${msgResult.failures.map((f) => f.detail).join("; ")}`
           });
         }
       }
-      if (messages.length > 0) {
-        const toolResults = extractToolResults(messages, provider);
-        if (toolResults.length > 0) {
-          const outputUpdates = extractOutputFromToolResults(toolResults, sessionState, contracts);
-          sessionState = applyOutputExtracts(sessionState, outputUpdates);
-        }
-      }
       const inputFailures = evaluateInputInvariants(request, contracts);
       if (mode === "enforce" && inputFailures.length > 0) {
         if (onError === "block") {
@@ -5125,6 +5363,10 @@ function replay(client, opts = {}) {
           sessionState = updateActualCost(sessionState, costDelta);
         }
         if (mode === "log-only") {
+          trace.push({ stage: "gate", tool: null, verdict: "allow", reason: "log_only_mode", checked: {}, found: {} });
+          trace.complete = true;
+          lastTrace = trace;
+          emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
           captureDecision(
             { action: "allow", tool_calls: extractToolCalls(response, provider) },
             response,
@@ -5137,13 +5379,26 @@ function replay(client, opts = {}) {
             null,
             null,
             void 0,
-            timing
+            timing,
+            trace
           );
           return response;
         }
+        currentTraceStage = "validate";
         const toolCalls = extractToolCalls(response, provider);
         const validateStart = Date.now();
         const validation = validateResponse2(response, toolCalls, contracts, requestToolNames, unmatchedPolicy, provider);
+        for (const f of validation.failures) {
+          const toolName = extractToolNameFromFailure(f, toolCalls);
+          trace.push({
+            stage: "validate",
+            tool: toolName === "_response" ? null : toolName,
+            verdict: "block",
+            reason: f.operator === "response_format" ? "response_format_failed" : "output_invariant_failed",
+            checked: { path: f.path, operator: f.operator, invariant_type: f.operator === "response_format" ? "response_format" : "output" },
+            found: { value: f.found }
+          });
+        }
         timing.validate_ms += Date.now() - validateStart;
         if (isActiveGovern && !attemptDegraded && attemptPreparedRequestId) {
           const rtProposalStart = Date.now();
@@ -5178,9 +5433,10 @@ function replay(client, opts = {}) {
           }
           timing.runtime_ms += Date.now() - rtProposalStart;
         }
+        currentTraceStage = "cross_step";
         const crossStepStart = Date.now();
         const crossStepContracts = compiledSession ? Array.from(compiledSession.perToolContracts.values()) : contracts;
-        const crossStepResult = validateCrossStep(toolCalls, sessionState, crossStepContracts);
+        const crossStepResult = validateCrossStep(toolCalls, sessionState, crossStepContracts, traceCtx);
         if (!crossStepResult.passed) {
           for (const f of crossStepResult.failures) {
             validation.failures.push({
@@ -5194,10 +5450,11 @@ function replay(client, opts = {}) {
           }
         }
         timing.cross_step_ms += Date.now() - crossStepStart;
+        currentTraceStage = "phase";
         let phaseResult = null;
         const phaseStart = Date.now();
         if (compiledSession) {
-          phaseResult = validatePhaseTransition(toolCalls, sessionState, compiledSession);
+          phaseResult = validatePhaseTransition(toolCalls, sessionState, compiledSession, traceCtx);
           if (!phaseResult.legal) {
             validation.failures.push({
               path: `$.tool_calls.${phaseResult.blockedTool}`,
@@ -5211,6 +5468,8 @@ function replay(client, opts = {}) {
         }
         timing.phase_ms += Date.now() - phaseStart;
         const argValuesStart = Date.now();
+        const workingToolCallCounts = new Map(sessionState.toolCallCounts);
+        const intraResponseTuples = [];
         for (const tc of toolCalls) {
           const contract = contracts.find((c) => c.tool === tc.name);
           if (contract?.argument_value_invariants && contract.argument_value_invariants.length > 0) {
@@ -5225,7 +5484,7 @@ function replay(client, opts = {}) {
               for (const f of avResult.failures) {
                 validation.failures.push({
                   path: f.path,
-                  operator: f.operator,
+                  operator: "argument_value_mismatch",
                   expected: String(f.expected),
                   found: String(f.actual),
                   message: f.detail,
@@ -5236,9 +5495,12 @@ function replay(client, opts = {}) {
               }
             }
           }
+          currentTraceStage = "limit";
           if (resolvedSessionLimits) {
-            const perToolResult = checkPerToolLimits(sessionState, tc.name, resolvedSessionLimits);
+            const workingState = { ...sessionState, toolCallCounts: workingToolCallCounts };
+            const perToolResult = checkPerToolLimits(workingState, tc.name, resolvedSessionLimits);
             if (perToolResult.exceeded) {
+              trace.push({ stage: "limit", tool: tc.name, verdict: "block", reason: "per_tool_limit_exceeded", checked: { max_calls: resolvedSessionLimits.max_calls_per_tool?.[tc.name] ?? null }, found: { current_calls: workingToolCallCounts.get(tc.name) ?? 0 } });
               validation.failures.push({
                 path: `$.tool_calls.${tc.name}`,
                 operator: "session_limit",
@@ -5247,28 +5509,39 @@ function replay(client, opts = {}) {
                 message: perToolResult.reason ?? "per-tool limit exceeded",
                 contract_file: ""
               });
+            } else {
+              trace.push({ stage: "limit", tool: tc.name, verdict: "allow", reason: "per_tool_limit_ok", checked: { max_calls: resolvedSessionLimits.max_calls_per_tool?.[tc.name] ?? null }, found: { current_calls: workingToolCallCounts.get(tc.name) ?? 0 } });
             }
           }
+          workingToolCallCounts.set(tc.name, (workingToolCallCounts.get(tc.name) ?? 0) + 1);
           if (resolvedSessionLimits?.loop_detection) {
+            const argsHash = computeArgumentsHash(tc.arguments);
             const loopResult = checkLoopDetection(
               tc.name,
               tc.arguments,
               sessionState,
               resolvedSessionLimits.loop_detection
             );
-            if (loopResult.triggered) {
+            const intraMatches = intraResponseTuples.filter(
+              (t) => t.toolName === tc.name && t.argsHash === argsHash
+            ).length;
+            const totalMatches = loopResult.matchCount + intraMatches;
+            if (totalMatches >= resolvedSessionLimits.loop_detection.threshold) {
+              trace.push({ stage: "limit", tool: tc.name, verdict: "block", reason: "loop_detected", checked: { window: resolvedSessionLimits.loop_detection.window, threshold: resolvedSessionLimits.loop_detection.threshold }, found: { match_count: totalMatches, arguments_hash: argsHash } });
               validation.failures.push({
                 path: `$.tool_calls.${tc.name}`,
                 operator: "loop_detected",
-                expected: `< ${loopResult.threshold} occurrences in window ${loopResult.window}`,
-                found: String(loopResult.matchCount),
-                message: `Loop detected: ${tc.name} repeated ${loopResult.matchCount} times in last ${loopResult.window} steps`,
+                expected: `< ${resolvedSessionLimits.loop_detection.threshold} occurrences in window ${resolvedSessionLimits.loop_detection.window}`,
+                found: String(totalMatches),
+                message: `Loop detected: ${tc.name} repeated ${totalMatches} times in last ${resolvedSessionLimits.loop_detection.window} steps`,
                 contract_file: ""
               });
             }
+            intraResponseTuples.push({ toolName: tc.name, argsHash });
           }
         }
         timing.argument_values_ms += Date.now() - argValuesStart;
+        currentTraceStage = "policy";
         let policyVerdicts = null;
         const policyStart = Date.now();
         if (compiledSession?.policyProgram && compiledSession.principal !== null && compiledSession.principal !== void 0) {
@@ -5289,6 +5562,14 @@ function replay(client, opts = {}) {
             );
             policyVerdicts.set(tc.name, verdict);
             if (!verdict.allowed) {
+              trace.push({
+                stage: "policy",
+                tool: tc.name,
+                verdict: "block",
+                reason: verdict.reason?.startsWith("Session deny") ? "session_deny_matched" : verdict.reason?.startsWith("default_deny") ? "default_deny_no_allow" : "policy_denied",
+                checked: { has_policy: true, default_deny: compiledSession.policyProgram.defaultDeny },
+                found: { matched: true }
+              });
               validation.failures.push({
                 path: `$.tool_calls.${tc.name}`,
                 operator: "policy_denied",
@@ -5297,10 +5578,22 @@ function replay(client, opts = {}) {
                 message: `Policy denied: ${tc.name} \u2014 ${verdict.reason}`,
                 contract_file: ""
               });
+            } else {
+              trace.push({
+                stage: "policy",
+                tool: tc.name,
+                verdict: "allow",
+                reason: "policy_allowed",
+                checked: { has_policy: true, default_deny: compiledSession.policyProgram.defaultDeny },
+                found: { session_deny_matched: false, tool_deny_matched: false }
+              });
             }
           }
+        } else {
+          trace.push({ stage: "policy", tool: null, verdict: "skip", reason: "no_policy_configured", checked: {}, found: {} });
         }
         timing.policy_ms += Date.now() - policyStart;
+        currentTraceStage = "gate";
         if (mode === "shadow") {
           const shadowGateStart = Date.now();
           const shadowDecision = validation.failures.length > 0 ? {
@@ -5309,6 +5602,15 @@ function replay(client, opts = {}) {
             blocked: buildBlockedCalls(toolCalls, validation.failures, validation.unmatchedBlocked),
             response_modification: gateMode
           } : { action: "allow", tool_calls: toolCalls };
+          const blockedTools = shadowDecision.action === "block" ? shadowDecision.blocked.map((b) => b.tool_name) : [];
+          trace.push({
+            stage: "gate",
+            tool: null,
+            verdict: blockedTools.length > 0 ? "info" : "allow",
+            reason: blockedTools.length > 0 ? "violations_found" : "no_violations",
+            checked: { gate_mode: gateMode },
+            found: { blocked_count: blockedTools.length, action: shadowDecision.action, ...blockedTools.length > 0 ? { blocked_tools: blockedTools } : {} }
+          });
           const shadowDelta = {
             would_have_blocked: shadowDecision.action === "block" ? shadowDecision.blocked : [],
             would_have_narrowed: narrowResult?.removed ?? [],
@@ -5318,7 +5620,11 @@ function replay(client, opts = {}) {
           lastShadowDeltaValue = shadowDelta;
           shadowEvaluationCount++;
           timing.gate_ms += Date.now() - shadowGateStart;
-          captureDecision(shadowDecision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, shadowDelta, timing);
+          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: sessionState.currentPhase, phase_after: sessionState.currentPhase, tools_committed: [], tools_blocked: blockedTools, killed: false, step_index: sessionState.totalStepCount } });
+          trace.complete = true;
+          lastTrace = trace;
+          emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
+          captureDecision(shadowDecision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, shadowDelta, timing, trace);
           return response;
         }
         if (isCompatAdvisory) {
@@ -5359,7 +5665,21 @@ function replay(client, opts = {}) {
             sessionState = recordDecisionOutcome(sessionState, "allowed");
           }
           timing.finalize_ms += Date.now() - advisoryFinalizeStart;
-          captureDecision(advisoryDecision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing);
+          const advisoryBlockedTools = advisoryDecision.action === "block" ? advisoryDecision.blocked.map((b) => b.tool_name) : [];
+          trace.push({
+            stage: "gate",
+            tool: null,
+            verdict: advisoryBlockedTools.length > 0 ? "info" : "allow",
+            reason: advisoryBlockedTools.length > 0 ? "violations_found" : "no_violations",
+            checked: { gate_mode: gateMode },
+            found: { blocked_count: advisoryBlockedTools.length, action: advisoryDecision.action, ...advisoryBlockedTools.length > 0 ? { blocked_tools: advisoryBlockedTools } : {} }
+          });
+          const advisoryNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== sessionState.currentPhase ? phaseResult.newPhase : sessionState.currentPhase;
+          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: sessionState.currentPhase, phase_after: advisoryNewPhase, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: advisoryBlockedTools, killed: false, step_index: sessionState.totalStepCount } });
+          trace.complete = true;
+          lastTrace = trace;
+          emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
+          captureDecision(advisoryDecision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing, trace);
           return response;
         }
         const enforceGateStart = Date.now();
@@ -5397,7 +5717,20 @@ function replay(client, opts = {}) {
               });
             }
           }
-          captureDecision(decision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing);
+          trace.push({
+            stage: "gate",
+            tool: null,
+            verdict: "allow",
+            reason: "no_violations",
+            checked: { gate_mode: gateMode },
+            found: { blocked_count: 0, action: "allow" }
+          });
+          const allowNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== sessionState.currentPhase ? phaseResult.newPhase : sessionState.currentPhase;
+          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: completedStep.phase, phase_after: allowNewPhase, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: [], killed: false, step_index: sessionState.totalStepCount } });
+          trace.complete = true;
+          lastTrace = trace;
+          emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
+          captureDecision(decision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing, trace);
           return response;
         }
         sessionState = recordDecisionOutcome(sessionState, "blocked");
@@ -5462,15 +5795,42 @@ function replay(client, opts = {}) {
           );
           continue;
         }
-        captureDecision(decision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing);
+        const blockBlockedTools = decision.action === "block" ? decision.blocked.map((b) => b.tool_name) : [];
+        trace.push({
+          stage: "gate",
+          tool: null,
+          verdict: "block",
+          reason: "violations_found",
+          checked: { gate_mode: gateMode },
+          found: { blocked_count: blockBlockedTools.length, action: "block", blocked_tools: blockBlockedTools }
+        });
+        trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: sessionState.currentPhase, phase_after: sessionState.currentPhase, tools_committed: [], tools_blocked: blockBlockedTools, killed, step_index: sessionState.totalStepCount } });
+        trace.complete = true;
+        lastTrace = trace;
+        emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
+        captureDecision(decision, response, request, guardStart, requestToolNames, crossStepResult, narrowResult, phaseResult, policyVerdicts, null, void 0, timing, trace);
         return applyGateDecision(decision, response, provider, gateMode, opts.onBlock);
       }
       if (lastError) throw lastError;
       throw new ReplayInternalError("Retry loop exhausted without result", { sessionId });
     } catch (err) {
       if (err instanceof ReplayContractError || err instanceof ReplayKillError) {
+        if (!trace.complete) {
+          lastTrace = trace;
+          emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
+        }
         throw err;
       }
+      trace.push({
+        stage: currentTraceStage,
+        tool: null,
+        verdict: "error",
+        reason: "stage_threw",
+        checked: {},
+        found: { error: err instanceof Error ? err.message : String(err) }
+      });
+      lastTrace = trace;
+      emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
       sessionState = recordDecisionOutcome(sessionState, "error");
       if (resolvedSessionLimits?.circuit_breaker) {
         const cbResult = checkCircuitBreaker(sessionState, resolvedSessionLimits.circuit_breaker);
@@ -5555,7 +5915,7 @@ function replay(client, opts = {}) {
     },
     getHealth() {
       const isAuthoritative = runtimeSession != null && !runtimeDegraded;
-      const effectiveProtection = runtimeDegraded ? "protect" : protectionLevel;
+      const effectiveProtection = protectionLevel === "govern" && !isAuthoritative ? "protect" : protectionLevel;
       let durability;
       if (isAuthoritative) {
         durability = runtimeClient?.isCircuitOpen() ? "degraded-local" : "server";
@@ -5596,6 +5956,9 @@ function replay(client, opts = {}) {
     getLastShadowDelta() {
       return lastShadowDeltaValue;
     },
+    getLastTrace() {
+      return lastTrace;
+    },
     /**
      * v3: Manually restrict available tools within compiled legal space.
      * @see specs/replay-v3.md § narrow() / widen()
@@ -5690,6 +6053,9 @@ function replay(client, opts = {}) {
     const wrapped = {};
     for (const [toolName, executor] of Object.entries(baseTools)) {
       wrapped[toolName] = async (args) => {
+        if (killed) {
+          throw new ReplayKillError(sessionId, killedAt);
+        }
         const result = await executor(args);
         if (runtimeClient && leaseFence && !runtimeDegraded) {
           for (const [callId, deferred] of deferredReceipts) {
@@ -5711,7 +6077,13 @@ function replay(client, opts = {}) {
                 if (receiptResult.stateAdvanced) {
                   sessionState = { ...sessionState, stateVersion: receiptResult.stateVersion };
                 }
-              } catch {
+              } catch (err) {
+                emitDiagnostic2(diagnostics, {
+                  type: "replay_receipt_error",
+                  session_id: sessionId,
+                  tool_name: deferred.toolName,
+                  details: err instanceof Error ? err.message : "receipt submission failed"
+                });
               }
               break;
             }
@@ -5722,7 +6094,7 @@ function replay(client, opts = {}) {
     }
     return wrapped;
   }
-  function captureDecision(decision, response, request, guardStart, requestToolNames, crossStep, narrowing = null, phaseResult = null, policyVerdictMap = null, constraintVerdictVal = null, shadowDelta = void 0, timingParam) {
+  function captureDecision(decision, response, request, guardStart, requestToolNames, crossStep, narrowing = null, phaseResult = null, policyVerdictMap = null, constraintVerdictVal = null, shadowDelta = void 0, timingParam, traceParam) {
     if (!buffer && !store) return;
     if (timingParam) {
       timingParam.total_ms = Date.now() - guardStart;
@@ -5757,6 +6129,7 @@ function replay(client, opts = {}) {
       phase: sessionState.currentPhase,
       phase_transition: phaseTransitionStr,
       shadow_delta: shadowDelta,
+      trace: traceParam ? redactTrace(traceParam, opts.captureLevel ?? "full") : void 0,
       receipt: null
     };
     const capturedCall = {
@@ -5786,7 +6159,12 @@ function replay(client, opts = {}) {
       const redactedCall = JSON.parse(redacted);
       if (buffer) buffer.push(redactedCall);
       appendCaptureToStore(redactedCall);
-    } catch {
+    } catch (err) {
+      emitDiagnostic2(diagnostics, {
+        type: "replay_capture_error",
+        session_id: sessionId,
+        details: `capture dropped (redaction failed): ${err instanceof Error ? err.message : "unknown"}`
+      });
     }
   }
 }
@@ -6301,10 +6679,28 @@ function applyOutputExtracts(state, updates) {
   };
 }
 function resolveSessionLimits(contracts) {
+  const merged = {};
+  let found = false;
   for (const c of contracts) {
-    if (c.session_limits) return c.session_limits;
+    if (!c.session_limits) continue;
+    found = true;
+    const sl = c.session_limits;
+    if (sl.max_steps !== void 0 && merged.max_steps === void 0) merged.max_steps = sl.max_steps;
+    if (sl.max_tool_calls !== void 0 && merged.max_tool_calls === void 0) merged.max_tool_calls = sl.max_tool_calls;
+    if (sl.max_tool_calls_mode !== void 0 && merged.max_tool_calls_mode === void 0) merged.max_tool_calls_mode = sl.max_tool_calls_mode;
+    if (sl.max_cost_per_session !== void 0 && merged.max_cost_per_session === void 0) merged.max_cost_per_session = sl.max_cost_per_session;
+    if (sl.loop_detection && !merged.loop_detection) merged.loop_detection = sl.loop_detection;
+    if (sl.circuit_breaker && !merged.circuit_breaker) merged.circuit_breaker = sl.circuit_breaker;
+    if (sl.max_calls_per_tool) {
+      if (!merged.max_calls_per_tool) merged.max_calls_per_tool = {};
+      for (const [tool, limit] of Object.entries(sl.max_calls_per_tool)) {
+        if (merged.max_calls_per_tool[tool] === void 0) {
+          merged.max_calls_per_tool[tool] = limit;
+        }
+      }
+    }
   }
-  return null;
+  return found ? merged : null;
 }
 function buildStateSnapshot(state, lastNarrowing = null) {
   const lastStep = state.lastStep ? {
@@ -6399,6 +6795,7 @@ function createInactiveSession(client, sessionId, reason) {
     getState: () => EMPTY_STATE_SNAPSHOT,
     getLastNarrowing: () => null,
     getLastShadowDelta: () => null,
+    getLastTrace: () => null,
     narrow() {
     },
     widen() {
@@ -6440,6 +6837,7 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     getState: () => EMPTY_STATE_SNAPSHOT,
     getLastNarrowing: () => null,
     getLastShadowDelta: () => null,
+    getLastTrace: () => null,
     narrow() {
     },
     widen() {
@@ -6524,6 +6922,83 @@ function generateSessionId2() {
 function stripHashPrefix(hash) {
   return hash.startsWith("sha256:") ? hash.slice(7) : hash;
 }
+function resolveLogLevel() {
+  const raw = typeof process !== "undefined" ? process.env.REPLAYCI_LOG : void 0;
+  if (!raw) return "warn";
+  const lower = raw.toLowerCase();
+  if (lower === "trace" || lower === "debug") return "trace";
+  if (lower === "silent" || lower === "off" || lower === "none") return "silent";
+  return "warn";
+}
+function defaultReplayDiagnosticsHandler(event) {
+  const level = resolveLogLevel();
+  if (level === "silent") return;
+  switch (event.type) {
+    case "replay_inactive":
+      console.warn(`[replayci] replay() inactive: ${event.reason}${event.error_message ? ` \u2014 ${event.error_message}` : ""}`);
+      break;
+    case "replay_compile_error":
+      console.warn(`[replayci] compile error: ${event.details}`);
+      break;
+    case "replay_compile_warning":
+      console.warn(`[replayci] compile warning: ${event.details}`);
+      break;
+    case "replay_bypass_detected":
+      console.warn(`[replayci] bypass detected on session ${event.session_id}`);
+      break;
+    case "replay_kill":
+      console.warn(`[replayci] session ${event.session_id} killed`);
+      break;
+    case "replay_block":
+      console.warn(`[replayci] blocked ${event.tool_name}: ${event.reason}`);
+      break;
+    case "replay_narrow": {
+      for (const r of event.removed) {
+        console.warn(`[replayci] removed ${r.tool} \u2192 ${r.reason}${r.detail ? ` (${r.detail})` : ""}`);
+      }
+      break;
+    }
+    case "replay_trace": {
+      const t = event.trace;
+      if (level === "trace") {
+        for (const entry of t.entries) {
+          const toolStr = entry.tool ? ` ${entry.tool}` : "";
+          const detail = entry.reason !== entry.verdict ? ` \u2014 ${entry.reason}` : "";
+          const checkedStr = Object.keys(entry.checked).length > 0 ? ` checked=${JSON.stringify(entry.checked)}` : "";
+          const foundStr = Object.keys(entry.found).length > 0 ? ` found=${JSON.stringify(entry.found)}` : "";
+          console.warn(`[replayci] ${entry.stage}${toolStr}: ${entry.verdict}${detail}${checkedStr}${foundStr}`);
+        }
+        if (!t.complete) {
+          console.warn(`[replayci] trace INCOMPLETE (fault in pipeline)`);
+        }
+      } else {
+        const blocks = t.entries.filter((e) => e.verdict === "block");
+        for (const b of blocks) {
+          const toolStr = b.tool ?? "session";
+          console.warn(`[replayci] blocked ${toolStr} at ${b.stage} \u2192 ${b.reason}`);
+        }
+        if (!t.complete) {
+          console.warn(`[replayci] enforcement cycle incomplete (fault) \u2014 session.getLastTrace() for partial trace`);
+        }
+      }
+      break;
+    }
+    case "replay_workflow_error":
+      console.warn(`[replayci] workflow error: ${event.details}`);
+      break;
+    case "replay_state_sync_error":
+      console.warn(`[replayci] state sync error: ${event.details}`);
+      break;
+    case "replay_receipt_error":
+      console.warn(`[replayci] receipt error (${event.tool_name}): ${event.details}`);
+      break;
+    case "replay_capture_error":
+      console.warn(`[replayci] capture error: ${event.details}`);
+      break;
+    default:
+      break;
+  }
+}
 function emitDiagnostic2(diagnostics, event) {
   try {
     diagnostics?.(event);
@@ -6533,9 +7008,10 @@ function emitDiagnostic2(diagnostics, event) {
 function toRecord10(value) {
   return value !== null && typeof value === "object" ? value : {};
 }
-function determineProtectionLevel(mode, tools, contracts) {
+function determineProtectionLevel(mode, tools, contracts, apiKey) {
   if (mode === "shadow" || mode === "log-only") return "monitor";
   if (!tools || Object.keys(tools).length === 0) return "protect";
+  if (!apiKey) return "protect";
   const stateBearingTools = contracts.filter(isStateBearing);
   if (stateBearingTools.length === 0) return "protect";
   const wrappedTools = new Set(Object.keys(tools));