feat(logging): ADR-0013 audit-trace redaction (secret/credential/PII scrubbing)

Deterministic, no-LLM redaction pass applied to the execution trace at a single
seam before it is persisted, so no sink (local/hf/s3) ever receives credentials
or PII. The audit store IS the audit control, so a secret landing in it is a leak
into the trust artifact itself.

- src/core/trace_redaction.py: pure redact_trace() (deep-copies, walks every
string, typed «REDACTED:...» placeholders) + fail-closed redact_trace_safe()
that returns a minimal trace (run_id+timestamp, no payload) on any error and
never raises. Patterns: sk-ant-/hf_/AKIA/generic sk-/Bearer/gh[pousr]_ tokens,
credentialed URLs (host kept), email, whole-value env-dump drop, and an
entropy-gated 40+char base64 run for AWS secret keys. Config: TRACE_REDACTION
(on default; off = local-debug only), TRACE_MAX_FIELD_CHARS, TRACE_REDACTION_EXTRA.
- Wired at both persist seams: agent.run() before persist_trace_safe, and
WorkflowEngine.save_trace_to_file (covers agent.save_trace() too).
- tests/test_trace_redaction.py: 20 network-free tests — each pattern scrubbed,
clean/gene-symbol traces pass through, input not mutated, size cap, off switch,
fail-closed minimal trace, and end-to-end that a planted secret never reaches a
local sink.

Best-effort scrubbing, not a proof of secret-free logs; defense-in-depth with
ADR-0012 token hygiene and ADR-0014 secret scanning.

docs/adr/ADR-0013-audit-trace-redaction.md

@@ -0,0 +1,125 @@
+# ADR-0013 — Audit-Trace Redaction (Secret / Credential / PII Scrubbing)
+
+**Status:** Accepted — implemented 2026-07-02 (AWS-independent; live once deployed)
+**Date:** 2026-07-02
+**Deciders:** Annie Voigt (project lead)
+**Driver:** OHSU security review — the always-on audit trace (ADR-0008) captures
+the full prompt and the code the agent generated and executed. Anything a user
+pastes, or that generated code prints, is persisted **verbatim** to the trace
+store. Since that store *is* the audit control, a secret or identifier landing in
+it is a leak into the very artifact meant to be trusted.
+**Related:** ADR-0008 (always-on logging — defines the persist path this hooks),
+ADR-0009 (S3 sink — same redacted payload lands there at cutover), ADR-0011
+(upload de-identification attestation — dataset content; this ADR is about
+secrets/PII in prompts+code, a different surface), ADR-0012 (identity in trace —
+must itself not over-collect).
+
+---
+
+## Context
+
+`CodeAgent.get_trace()` returns
+`{execution_time, config, messages, trace_logs}`, where `messages` is the full
+message history (user prompts + model turns) and `trace_logs` includes the
+generated code and captured stdout. `agent.run()` persists this on every live
+run via `persist_trace_safe(get_log_sink(), run_id, self.get_trace())`. There is
+**no redaction** anywhere in `src/logging_sink.py` or in `get_trace()`.
+
+Realistic leak paths into the trace:
+- A user pastes an API key, token, or a credentialed URL into the chat prompt.
+- Generated code echoes the environment (`print(os.environ)`), a connection
+  string, or a bearer token.
+- The ADR-0012 orchestrator→specialist **service token** appears in an error
+  string or a debug print.
+- Personal identifiers (email, name) in a prompt — the data is de-identified per
+  ADR-0011, but free-text prompts are not.
+
+The fail-open wrapper (`persist_trace_safe`) means a bad trace is written
+silently, so there is no natural backstop.
+
+## Decision
+
+Add a deterministic, **no-LLM** redaction pass applied to the trace immediately
+before it is persisted, in both the always-on sink path and the opt-in
+`save_trace` file dump.
+
+- **A pure function `redact_trace(trace: dict) -> dict`** (new
+  `src/core/trace_redaction.py`, mirroring the shared-helper pattern of
+  `src/core/integrity.py`). It deep-copies and walks all string values in
+  `messages` + `trace_logs` and replaces matches with a typed placeholder
+  (`«REDACTED:anthropic_key»`, `«REDACTED:hf_token»`, etc.).
+- **Pattern set (deterministic regex, high-precision):**
+  - Anthropic keys (`sk-ant-…`), HuggingFace tokens (`hf_…`), AWS access keys
+    (`AKIA…`) + secret-key-shaped high-entropy strings, generic `Bearer <token>`,
+    OpenAI-style `sk-…`, and credentialed URLs (`https://user:pass@…`).
+  - Whole-value drop for obvious environment dumps (a dict/text blob containing
+    multiple `KEY=VALUE` env lines) → `«REDACTED:env_dump»`.
+  - Email addresses → `«REDACTED:email»` (PII; conservative, on by default).
+- **Applied at one seam.** Hook `redact_trace` into `agent.run()` right before
+  `persist_trace_safe(...)` and before the file dump — so every sink (`local` /
+  `hf` / `s3`) and every path receives the redacted payload. The sinks stay
+  dumb; redaction is not per-sink.
+- **Fail-closed on redaction, fail-open on logging.** If `redact_trace` itself
+  raises, persist a **minimal** trace (run_id + timestamp + "redaction_error")
+  rather than the raw payload — never write an unredacted trace, but still never
+  crash the run.
+- **Size cap.** Truncate any single value over a configurable limit
+  (`TRACE_MAX_FIELD_CHARS`) so a pathological paste can't bloat the store.
+- **Config, allow tuning:** `TRACE_REDACTION` (`on` default | `off` for local
+  debug only) + an extensible extra-patterns list; **off is never the prod
+  posture** and that is documented.
+
+Redaction runs on a copy; the in-memory trace the UI/eval harness reads is
+unchanged, so no user-facing behavior changes — only what is *persisted*.
+
+## Plan
+
+- **Now (AWS-independent, ~2–3 days):**
+  1. `src/core/trace_redaction.py` with the pattern set + `redact_trace`.
+  2. Wire it into `agent.run()` before both persist paths.
+  3. Tests (`tests/test_trace_redaction.py`): each pattern is scrubbed; a
+     planted `sk-ant-…` / `hf_…` / env-dump never reaches a stub sink; redaction
+     failure yields the minimal trace, not the raw one; clean traces pass through
+     unchanged.
+  4. Document `TRACE_REDACTION` + the "off ≠ prod" note.
+- **No AWS dependency at all** — this hardens the payload *before* it reaches any
+  sink, so it is complete independent of the S3 cutover, and the S3 sink
+  (ADR-0009) inherits it for free.
+
+## Consequences
+
+- **Positive:** the audit store can no longer silently capture credentials/PII;
+  closes the leak into the trust artifact itself; a single seam covers all
+  sinks; deterministic + testable, no model call, no latency of note.
+- **Cost / caveat:** regex redaction is high-precision but not exhaustive — a
+  novel secret format can slip through, so this is defense-in-depth layered with
+  ADR-0012 (don't put the service token where it can be printed) and secret
+  hygiene (ADR-0014), not a guarantee. Over-eager patterns could redact
+  legitimate content (e.g. a gene identifier that looks token-shaped); keep
+  patterns anchored/high-entropy and cover with tests. State to the review that
+  redaction is best-effort scrubbing, not a proof of secret-free logs.
+- **Honesty note:** this reduces *accidental* capture; it is not a substitute for
+  not exposing secrets to the agent in the first place.
+
+## Start-now checklist
+- [x] `src/core/trace_redaction.py` (`redact_trace`, pattern set, size cap).
+- [x] Hook before `persist_trace_safe` (`agent.run()`) + the `save_trace` file
+      dump (`WorkflowEngine.save_trace_to_file`, which also covers `agent.save_trace()`).
+- [x] Fail-closed minimal-trace path on redaction error (`redact_trace_safe`).
+- [x] `tests/test_trace_redaction.py` (20 tests, network-free) + `TRACE_REDACTION`
+      config doc (module docstring + Decision above).
+
+## Implementation notes (2026-07-02)
+- Patterns landed: anthropic (`sk-ant-…`), hf (`hf_…`), AWS access key (`AKIA…`),
+  generic OpenAI `sk-…`, `Bearer …`, GitHub `gh[pousr]_…`, credentialed URL
+  (host preserved, `user:pass@` dropped), email, whole-value env-dump drop
+  (≥3 `UPPER_SNAKE=value` lines), and an entropy-gated 40+char base64 run for the
+  AWS *secret* key shape (`TRACE_REDACTION_EXTRA` adds operator regexes →
+  `«REDACTED:custom»`).
+- Entropy gate (≥4.0 bits/char) on the 40+char matcher keeps repetitive/low-entropy
+  identifiers (e.g. a long gene-id run) from tripping the secret pattern.
+- Size cap is `TRACE_MAX_FIELD_CHARS` (default 20 000); scrubbing runs *before*
+  truncation so a secret straddling the boundary is removed, not half-exposed.
+- Both seams call `redact_trace_safe`, which fails **closed** to a minimal trace
+  (`run_id` + timestamp + `redaction_error`, no payload) and never raises, so the
+  fail-open sink wrapper still governs crash-safety.

src/agent.py

@@ -537,8 +537,14 @@ class CodeAgent:
         # wrapped so a logging failure never crashes the run.
         try:
             from logging_sink import get_log_sink, persist_trace_safe
+            from core.trace_redaction import redact_trace_safe
             run_id = time.strftime("%Y%m%d_%H%M%S")
-            persist_trace_safe(get_log_sink(), run_id, self.get_trace())
+            # ADR-0013: scrub secrets/credentials/PII on a COPY before it reaches
+            # any sink — fail-closed to a minimal trace if redaction itself fails,
+            # so an unredacted payload is never persisted. The in-memory trace the
+            # UI/eval harness reads is untouched.
+            redacted = redact_trace_safe(self.get_trace(), run_id)
+            persist_trace_safe(get_log_sink(), run_id, redacted)
         except Exception as e:  # noqa: BLE001 — logging must never crash a run
             print(f"[log_sink] trace persistence skipped: {e}")
 

src/core/trace_redaction.py

@@ -0,0 +1,246 @@
+"""Deterministic, no-LLM redaction of the audit trace before it is persisted (ADR-0013).
+
+The always-on audit trace (ADR-0008) captures the full prompt and the code the
+agent generated and ran, verbatim, into the trace store — and that store *is* the
+audit control. A secret, credential, or personal identifier landing in it is a
+leak into the very artifact meant to be trusted. This module scrubs that payload
+*once*, at a single seam right before it reaches any sink (``local`` / ``hf`` /
+``s3``), so the sinks stay dumb and every path inherits redaction for free.
+
+Design (mirrors the shared-helper pattern of :mod:`src.core.integrity`):
+
+- :func:`redact_trace` is a **pure function**: it deep-copies the trace and walks
+  every string value, replacing matches with a typed placeholder
+  (``«REDACTED:anthropic_key»``, ``«REDACTED:hf_token»``, …). The in-memory trace
+  the UI / eval harness reads is never mutated — only the persisted copy.
+- :func:`redact_trace_safe` is the **fail-closed** wrapper the run path calls: if
+  redaction itself raises, it returns a *minimal* trace (run_id + timestamp +
+  ``redaction_error``) rather than the raw payload — never write an unredacted
+  trace, but never crash the run either (the logging sink is fail-open around
+  this in turn).
+
+Redaction is **best-effort scrubbing, not a proof of secret-free logs**: the
+patterns are high-precision regex, so a novel secret format can slip through.
+It is defense-in-depth layered with not exposing secrets to the agent in the
+first place (ADR-0012 service-token hygiene, ADR-0014 secret scanning) — it
+reduces *accidental* capture, it does not license putting secrets in prompts.
+
+Config (all env, all optional):
+
+  TRACE_REDACTION            on (default) | off   — ``off`` is local-debug only and
+                                                    is NEVER the prod posture.
+  TRACE_MAX_FIELD_CHARS      per-value size cap    (default: 20000)
+  TRACE_REDACTION_EXTRA      extra regexes, newline- or comma-separated, each
+                             scrubbed to ``«REDACTED:custom»`` (extensible tuning).
+"""
+from __future__ import annotations
+
+import copy
+import math
+import os
+import re
+import time
+from typing import Any
+
+# --------------------------------------------------------------------------- #
+# Config
+# --------------------------------------------------------------------------- #
+_DEFAULT_MAX_FIELD_CHARS = 20_000
+
+
+def _redaction_enabled() -> bool:
+    """True unless TRACE_REDACTION is explicitly ``off`` (default on).
+
+    ``off`` is for local debugging only and is never the production posture.
+    """
+    return os.environ.get("TRACE_REDACTION", "on").strip().lower() != "off"
+
+
+def _max_field_chars() -> int:
+    """Per-value truncation cap. Non-positive / unparsable disables truncation."""
+    raw = os.environ.get("TRACE_MAX_FIELD_CHARS")
+    if raw is None:
+        return _DEFAULT_MAX_FIELD_CHARS
+    try:
+        val = int(raw)
+    except (TypeError, ValueError):
+        return _DEFAULT_MAX_FIELD_CHARS
+    return val if val > 0 else 0
+
+
+# --------------------------------------------------------------------------- #
+# Pattern set — deterministic, high-precision. Order matters: the most specific
+# key shapes are scrubbed before the generic `sk-…` / Bearer catch-alls.
+# --------------------------------------------------------------------------- #
+def _placeholder(kind: str) -> str:
+    return f"«REDACTED:{kind}»"
+
+
+# (compiled_regex, kind). Applied in order via re.sub.
+_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Credentialed URL (user:pass@host) — scrub the embedded creds, keep the host
+    # so a trace line stays readable. Must run before the generic patterns.
+    (re.compile(r"(https?://)[^\s:/@]+:[^\s:/@]+@"), "credential_url"),
+    # Anthropic keys (sk-ant-…) — before the generic OpenAI-style sk-…
+    (re.compile(r"sk-ant-[A-Za-z0-9_\-]{16,}"), "anthropic_key"),
+    # HuggingFace tokens
+    (re.compile(r"\bhf_[A-Za-z0-9]{20,}\b"), "hf_token"),
+    # AWS access key id
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "aws_access_key"),
+    # OpenAI-style secret keys (generic sk-…), after sk-ant-… above
+    (re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"), "openai_key"),
+    # Bearer <token>
+    (re.compile(r"[Bb]earer\s+[A-Za-z0-9._\-]{8,}"), "bearer_token"),
+    # GitHub / generic ghp_/gho_/ghs_ tokens (cheap, high precision)
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"), "github_token"),
+    # Email addresses (PII; conservative, on by default). Last, so it never
+    # clobbers a token that happens to contain an @.
+    (re.compile(r"\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b"), "email"),
+]
+
+# Credentialed-URL sub keeps the scheme + host, drops the "user:pass@".
+_CREDENTIAL_URL_RE = _PATTERNS[0][0]
+
+# An env line: UPPER_SNAKE=value. Three or more => an env dump; drop the whole value.
+_ENV_LINE_RE = re.compile(r"^\s*[A-Z][A-Z0-9_]{2,}=.+$", re.MULTILINE)
+_ENV_DUMP_MIN_LINES = 3
+
+# AWS secret-access-key shape: a 40-or-more-char base64-ish run, standalone (AWS
+# secrets are exactly 40; ≥40 also catches other long secret blobs). Paired with a
+# Shannon-entropy gate so ordinary long text or gene-id runs don't trip it.
+# Anchored on non-base64 boundaries to avoid slicing a longer token.
+_SECRET40_RE = re.compile(r"(?<![A-Za-z0-9/+])[A-Za-z0-9/+]{40,}(?![A-Za-z0-9/+])")
+_SECRET40_MIN_ENTROPY = 4.0  # bits/char; random base64 ≈ 6, English prose ≈ 2–3.
+
+
+def _shannon_entropy(s: str) -> float:
+    """Bits-per-character Shannon entropy of ``s`` (0.0 for empty)."""
+    if not s:
+        return 0.0
+    counts: dict[str, int] = {}
+    for ch in s:
+        counts[ch] = counts.get(ch, 0) + 1
+    n = len(s)
+    return -sum((c / n) * math.log2(c / n) for c in counts.values())
+
+
+def _looks_like_env_dump(s: str) -> bool:
+    """True if ``s`` contains several UPPER_SNAKE=value lines (a leaked env)."""
+    return len(_ENV_LINE_RE.findall(s)) >= _ENV_DUMP_MIN_LINES
+
+
+def _extra_patterns() -> list[re.Pattern]:
+    """Compile TRACE_REDACTION_EXTRA (newline/comma-separated regexes)."""
+    raw = os.environ.get("TRACE_REDACTION_EXTRA")
+    if not raw:
+        return []
+    out: list[re.Pattern] = []
+    for piece in re.split(r"[\n,]", raw):
+        piece = piece.strip()
+        if not piece:
+            continue
+        try:
+            out.append(re.compile(piece))
+        except re.error:
+            # A bad custom pattern must never break redaction of everything else.
+            continue
+    return out
+
+
+def _scrub_string(s: str, max_chars: int, extra: list[re.Pattern]) -> str:
+    """Scrub one string value: env-dump drop, pattern subs, high-entropy secrets, cap.
+
+    Scrubbing runs *before* truncation so a secret straddling the cap boundary is
+    still removed rather than half-exposed.
+    """
+    if not s:
+        return s
+
+    # Whole-value drop for an obvious environment dump.
+    if _looks_like_env_dump(s):
+        return _placeholder("env_dump")
+
+    # Credentialed URL: keep scheme+host, drop the user:pass@ segment.
+    s = _CREDENTIAL_URL_RE.sub(lambda m: m.group(1) + _placeholder("credential_url") + "@", s)
+
+    # Remaining fixed-shape secrets / PII.
+    for pattern, kind in _PATTERNS[1:]:
+        s = pattern.sub(_placeholder(kind), s)
+
+    # High-entropy 40-char base64 runs (AWS secret-key shape), entropy-gated.
+    def _maybe_secret(m: re.Match) -> str:
+        tok = m.group(0)
+        return _placeholder("high_entropy_secret") if _shannon_entropy(tok) >= _SECRET40_MIN_ENTROPY else tok
+
+    s = _SECRET40_RE.sub(_maybe_secret, s)
+
+    # Operator-supplied extra patterns.
+    for pattern in extra:
+        s = pattern.sub(_placeholder("custom"), s)
+
+    # Size cap last (defends against a pathological paste bloating the store).
+    if max_chars and len(s) > max_chars:
+        s = s[:max_chars] + _placeholder("truncated")
+
+    return s
+
+
+def _walk(node: Any, max_chars: int, extra: list[re.Pattern]) -> Any:
+    """Recursively scrub every string in a nested dict/list structure in place."""
+    if isinstance(node, str):
+        return _scrub_string(node, max_chars, extra)
+    if isinstance(node, dict):
+        for k in list(node.keys()):
+            node[k] = _walk(node[k], max_chars, extra)
+        return node
+    if isinstance(node, list):
+        for i, v in enumerate(node):
+            node[i] = _walk(v, max_chars, extra)
+        return node
+    if isinstance(node, tuple):
+        return tuple(_walk(v, max_chars, extra) for v in node)
+    return node
+
+
+# --------------------------------------------------------------------------- #
+# Public API
+# --------------------------------------------------------------------------- #
+def redact_trace(trace: dict) -> dict:
+    """Return a deep-copied, redacted copy of ``trace`` (pure; input unmutated).
+
+    Walks every string value under ``messages`` and ``trace_logs`` (and any other
+    key present) and replaces secrets / credentials / PII with typed placeholders.
+    When ``TRACE_REDACTION=off`` the trace is returned unchanged (local debug only).
+
+    Raises only on a genuinely malformed input; callers on the persist path use
+    :func:`redact_trace_safe`, which fails closed to a minimal trace instead.
+    """
+    if not _redaction_enabled():
+        return trace
+    redacted = copy.deepcopy(trace)
+    return _walk(redacted, _max_field_chars(), _extra_patterns())
+
+
+def minimal_trace(run_id: "str | None", reason: str = "redaction_error") -> dict:
+    """A stripped trace written when redaction fails — carries no raw payload."""
+    return {
+        "run_id": run_id,
+        "execution_time": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "redaction_error": reason,
+        "messages": [],
+        "trace_logs": [],
+    }
+
+
+def redact_trace_safe(trace: dict, run_id: "str | None" = None) -> dict:
+    """Redact ``trace``, failing **closed** to a minimal trace on any error.
+
+    This is the wrapper the always-on persist path and the file dump call: it
+    never returns the raw payload if scrubbing did not complete, and it never
+    raises (so the surrounding fail-open logging wrapper still governs crashes).
+    """
+    try:
+        return redact_trace(trace)
+    except Exception as e:  # noqa: BLE001 — never persist a raw trace on redaction failure
+        print(f"[trace_redaction] redaction failed, writing minimal trace: {e}")
+        return minimal_trace(run_id, reason=f"redaction_error: {type(e).__name__}")

src/managers/workflow/workflow_engine.py

@@ -3,6 +3,7 @@ Workflow Engine Manager for CodeAct Agent.
 Manages the LangGraph workflow execution.
 """
 
+import os
 import re
 import json
 import uuid
@@ -251,6 +252,13 @@ class WorkflowEngine:
             "trace_logs": self.trace_logs
         }
 
+        # ADR-0013: redact secrets/credentials/PII before writing to disk, on a
+        # copy (in-memory history untouched). Fail-closed to a minimal trace if
+        # scrubbing fails — the opt-in file dump is a persist path too.
+        from core.trace_redaction import redact_trace_safe
+        run_id = os.path.splitext(os.path.basename(filepath))[0]
+        trace_data = redact_trace_safe(trace_data, run_id)
+
         with open(filepath, 'w', encoding='utf-8') as f:
             json.dump(trace_data, f, indent=2, ensure_ascii=False)
 

tests/test_trace_redaction.py

@@ -0,0 +1,212 @@
+"""Tests for audit-trace redaction (ADR-0013).
+
+Covers the pure :func:`redact_trace` pattern set (each secret / credential / PII
+shape is scrubbed to a typed placeholder; clean traces pass through unchanged;
+the input dict is never mutated), the fail-closed :func:`redact_trace_safe`
+wrapper (a redaction error yields a minimal trace, not the raw payload), the
+size cap, the ``TRACE_REDACTION=off`` escape hatch, and end-to-end that a planted
+secret never reaches a stub sink through ``persist_trace_safe``. Nothing here
+touches the network.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+# src/ on path so `import core.trace_redaction` / `import logging_sink` match how
+# agent.py and the sinks import them.
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+import core.trace_redaction as tr  # noqa: E402
+from core.trace_redaction import (  # noqa: E402
+    redact_trace,
+    redact_trace_safe,
+    minimal_trace,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+def _trace_with(text: str) -> dict:
+    """A minimal trace shaped like get_trace() with `text` in a prompt + a log."""
+    return {
+        "execution_time": "2026-07-02 10:00:00",
+        "config": {"max_steps": 10, "timeout_seconds": 60, "verbose": False},
+        "messages": [{"type": "human", "content": text}],
+        "trace_logs": [{"step_count": 1, "step_type": "observation", "content": text}],
+    }
+
+
+def _all_strings(node) -> str:
+    """Concatenate every string in a nested structure (for leak assertions)."""
+    if isinstance(node, str):
+        return node
+    if isinstance(node, dict):
+        return " ".join(_all_strings(v) for v in node.values())
+    if isinstance(node, (list, tuple)):
+        return " ".join(_all_strings(v) for v in node)
+    return ""
+
+
+@pytest.fixture(autouse=True)
+def _redaction_on(monkeypatch):
+    """Default every test to the prod posture (on) unless it overrides."""
+    monkeypatch.setenv("TRACE_REDACTION", "on")
+    monkeypatch.delenv("TRACE_MAX_FIELD_CHARS", raising=False)
+    monkeypatch.delenv("TRACE_REDACTION_EXTRA", raising=False)
+
+
+# --------------------------------------------------------------------------- #
+# Each pattern is scrubbed
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize(
+    "secret, kind",
+    [
+        ("sk-ant-api03-AbCdEf012345678901234567890", "anthropic_key"),
+        ("hf_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456", "hf_token"),
+        ("AKIAIOSFODNN7EXAMPLE", "aws_access_key"),
+        ("sk-proj0123456789ABCDEFXYZ0123456789", "openai_key"),
+        ("Bearer eyJhbGciOi.JIUzI1NiIs.InR5cCI6IkpXVCJ9", "bearer_token"),
+        ("ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456", "github_token"),
+        ("jane.doe@example.com", "email"),
+    ],
+)
+def test_each_pattern_scrubbed(secret, kind):
+    out = redact_trace(_trace_with(f"here is a value {secret} in text"))
+    blob = _all_strings(out)
+    assert secret not in blob, f"{kind} leaked: {secret}"
+    assert f"«REDACTED:{kind}»" in blob
+
+
+def test_credentialed_url_keeps_host_drops_creds():
+    out = redact_trace(_trace_with("connect to https://admin:hunter2@db.internal/x"))
+    blob = _all_strings(out)
+    assert "hunter2" not in blob
+    assert "admin" not in blob
+    assert "«REDACTED:credential_url»" in blob
+    assert "db.internal" in blob  # host preserved for readability
+
+
+def test_env_dump_whole_value_dropped():
+    env_blob = "AWS_SECRET_ACCESS_KEY=abc123\nANTHROPIC_API_KEY=sk-ant-xxx\nHOME=/root\nPATH=/usr/bin"
+    out = redact_trace(_trace_with(env_blob))
+    logged = out["trace_logs"][0]["content"]
+    assert logged == "«REDACTED:env_dump»"
+    assert "AWS_SECRET_ACCESS_KEY" not in _all_strings(out)
+
+
+def test_high_entropy_aws_secret_scrubbed():
+    # 40-char high-entropy base64 (AWS secret-access-key shape).
+    secret = "wJalrXUtnFEMI/K7MDENG+bPxRfiCYzEXAMPLEKEY"
+    out = redact_trace(_trace_with(f"secret={secret}"))
+    assert secret not in _all_strings(out)
+    assert "«REDACTED:high_entropy_secret»" in _all_strings(out)
+
+
+def test_low_entropy_40char_not_scrubbed():
+    # A repetitive 40-char run (low entropy) must NOT be treated as a secret —
+    # guards against false positives on non-secret identifiers.
+    benign = "A" * 40
+    out = redact_trace(_trace_with(f"marker {benign} end"))
+    assert benign in _all_strings(out)
+
+
+# --------------------------------------------------------------------------- #
+# Purity + pass-through
+# --------------------------------------------------------------------------- #
+def test_clean_trace_unchanged():
+    clean = _trace_with("run a DE contrast on gene TP53 in tcga_paad")
+    out = redact_trace(clean)
+    assert out == clean
+
+
+def test_input_not_mutated():
+    original = _trace_with("token hf_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456 here")
+    before = original["messages"][0]["content"]
+    redact_trace(original)
+    assert original["messages"][0]["content"] == before  # deep-copied, not mutated
+
+
+def test_gene_symbols_survive():
+    out = redact_trace(_trace_with("TP53 KRAS SMAD4 CDKN2A collectri progeny hallmark"))
+    for g in ("TP53", "KRAS", "SMAD4", "CDKN2A"):
+        assert g in _all_strings(out)
+
+
+# --------------------------------------------------------------------------- #
+# Config: off + size cap
+# --------------------------------------------------------------------------- #
+def test_redaction_off_passthrough(monkeypatch):
+    monkeypatch.setenv("TRACE_REDACTION", "off")
+    secret = "hf_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456"
+    trace = _trace_with(secret)
+    out = redact_trace(trace)
+    assert secret in _all_strings(out)  # off = raw (local debug only)
+
+
+def test_size_cap_truncates(monkeypatch):
+    monkeypatch.setenv("TRACE_MAX_FIELD_CHARS", "50")
+    out = redact_trace(_trace_with("x" * 500))
+    logged = out["trace_logs"][0]["content"]
+    assert len(logged) < 500
+    assert logged.endswith("«REDACTED:truncated»")
+
+
+def test_extra_pattern_scrubbed(monkeypatch):
+    monkeypatch.setenv("TRACE_REDACTION_EXTRA", r"PROJ-\d{4}")
+    out = redact_trace(_trace_with("ticket PROJ-1234 filed"))
+    blob = _all_strings(out)
+    assert "PROJ-1234" not in blob
+    assert "«REDACTED:custom»" in blob
+
+
+# --------------------------------------------------------------------------- #
+# Fail-closed wrapper
+# --------------------------------------------------------------------------- #
+def test_redaction_failure_yields_minimal_trace(monkeypatch):
+    def _boom(_trace):
+        raise RuntimeError("kaboom")
+
+    monkeypatch.setattr(tr, "redact_trace", _boom)
+    out = redact_trace_safe(_trace_with("sk-ant-secretsecretsecret0123456789"), run_id="run42")
+    assert out["run_id"] == "run42"
+    assert "redaction_error" in out
+    assert out["messages"] == []
+    assert out["trace_logs"] == []
+    # the raw secret must not have leaked into the minimal trace
+    assert "sk-ant" not in _all_strings(out)
+
+
+def test_minimal_trace_shape():
+    m = minimal_trace("abc")
+    assert m["run_id"] == "abc"
+    assert "execution_time" in m
+    assert m["redaction_error"] == "redaction_error"
+
+
+# --------------------------------------------------------------------------- #
+# End-to-end: a planted secret never reaches a sink
+# --------------------------------------------------------------------------- #
+def test_planted_secret_never_reaches_sink(tmp_path, monkeypatch):
+    """Mirror agent.run()'s persist path: redact then persist to a local sink,
+    and assert the on-disk trace has no secret."""
+    import logging_sink
+
+    monkeypatch.setenv("LOG_SINK", "local")
+    monkeypatch.setenv("LOG_SINK_LOCAL_DIR", str(tmp_path))
+
+    trace = _trace_with(
+        "key sk-ant-api03-PLANTEDSECRET0123456789 and hf_PLANTEDTOKEN0123456789ABCDEFG"
+    )
+    redacted = redact_trace_safe(trace, "run_e2e")
+    sink = logging_sink.get_log_sink()
+    location = logging_sink.persist_trace_safe(sink, "run_e2e", redacted)
+
+    assert location is not None
+    written = Path(location).read_text(encoding="utf-8")
+    assert "sk-ant-api03-PLANTEDSECRET" not in written
+    assert "PLANTEDTOKEN" not in written
+    assert "«REDACTED:anthropic_key»" in written