freesolo-flash-dev 1.2.64__tar.gz → 1.2.66__tar.gz

{freesolo_flash_dev-1.2.64 → freesolo_flash_dev-1.2.66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.64
+Version: 1.2.66
 Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

freesolo_flash_dev-1.2.66/flash/_internal/diagnostics.py

@@ -0,0 +1,170 @@
+"""Bounded credential-safe diagnostic rendering."""
+
+from __future__ import annotations
+
+import os
+import re
+import urllib.parse
+from typing import Any
+
+_SECRET_KEY_RE = re.compile(
+    r"(?i)(authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|token|secret|password)"
+    r"(\s*[:=]\s*)(?:bearer\s+)?([^\s,;]+)"
+)
+_BEARER_RE = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+")
+_SECRET_ENV_SUFFIXES = ("_API_KEY", "_TOKEN", "_SECRET", "_PASSWORD")
+
+# comma-separated env-variable names whose values are secrets regardless of naming shape: declared
+# runtime secrets can carry any name (AWS_SECRET_ACCESS_KEY, FLASH_TEACHER_CAPABILITY, ...), so the
+# control plane lists them explicitly in the worker env instead of relying on the suffix heuristic.
+SECRET_ENV_KEYS_ENV = "FLASH_SECRET_ENV_KEYS"
+
+# multiline secrets may appear only partially in truncated logs. register long component lines as
+# needles, but ignore short common fragments such as ``}`` that would erase innocent diagnostics.
+_MIN_SECRET_COMPONENT = 8
+_PERCENT_ESCAPE_RE = re.compile(r"%([0-9A-Fa-f]{2})")
+
+
+def _percent_pattern(needle: str) -> str:
+    """Regex for ``needle`` with only percent-escape hex digits matched case-insensitively."""
+    parts: list[str] = []
+    offset = 0
+    for match in _PERCENT_ESCAPE_RE.finditer(needle):
+        parts.append(re.escape(needle[offset : match.start()]))
+        parts.append("%")
+        parts.extend(
+            f"[{char.lower()}{char.upper()}]" if char.isalpha() else char for char in match.group(1)
+        )
+        offset = match.end()
+    parts.append(re.escape(needle[offset:]))
+    return "".join(parts)
+
+
+def _bounded_pattern(needle: str) -> str:
+    """``needle`` anchored so it cannot match as part of a longer word.
+
+    The guard is applied per EDGE, and only where the needle's own edge is a word character. A
+    value with a punctuation edge already separates itself from neighbouring text, and demanding a
+    non-word character beyond it asks the wrong question: ``/a`` inside ``https://host/a/repo`` is
+    preceded by the ``t`` of ``host``, so an unconditional left guard fails and the secret prints
+    verbatim. ``ati`` keeps both guards and so still cannot rewrite ``authentication``.
+    Mirrors flash.providers._lifecycle.bootstrap_secrets._bounded_pattern.
+    """
+    escaped = re.escape(needle)
+    left = r"(?<!\w)" if needle[:1].isalnum() or needle[:1] == "_" else ""
+    right = r"(?!\w)" if needle[-1:].isalnum() or needle[-1:] == "_" else ""
+    return f"{left}{escaped}{right}"
+
+
+_ValueMatcher = tuple[str, bool, bool]
+
+
+def _configured_secrets() -> tuple[tuple[_ValueMatcher, ...], tuple[str, ...], frozenset[str]]:
+    """Credential matchers plus shape-only and exact raw values.
+
+    Each value matcher carries ``(needle, bounded, encoded)`` metadata. Plain values are replaced as
+    substrings. Bounded values are shorter than ``_MIN_SECRET_COMPONENT`` and may only match where
+    they are not adjacent to a word character: a 3-char global needle would mangle every diagnostic
+    containing those characters (the value ``ati`` rewrites ``authentication``).
+
+    A short raw candidate with no alphanumeric or underscore character is shape-only because it is
+    indistinguishable from ordinary punctuation. Explicit percent-octet forms remain bounded and
+    safely distinguishable. Keyed and bearer matching uses the known shape-only value directly.
+
+    Component lines of a multiline value keep the floor as a hard skip: a short component is
+    punctuation such as ``}``, not a credential.
+    """
+    declared = {
+        name.strip().upper()
+        for name in os.environ.get(SECRET_ENV_KEYS_ENV, "").split(",")
+        if name.strip()
+    }
+    matchers: set[_ValueMatcher] = set()
+    shaped: set[str] = set()
+    raw_values: set[str] = set()
+    for key, value in os.environ.items():
+        upper = key.upper()
+        if not value or not (
+            upper in {"AUTHORIZATION", "HF_TOKEN"}
+            or upper in declared
+            or upper.endswith(_SECRET_ENV_SUFFIXES)
+        ):
+            continue
+        raw_values.add(value)
+        candidates = {(value, False)}
+        encoded = urllib.parse.quote(value, safe="")
+        if encoded != value:
+            candidates.add((encoded, True))
+        if len(value) < _MIN_SECRET_COMPONENT and not any(
+            char.isalnum() or char == "_" for char in value
+        ):
+            candidates.add(("".join(f"%{byte:02X}" for byte in value.encode()), True))
+        if len(value) >= _MIN_SECRET_COMPONENT:
+            matchers.update((candidate, False, is_encoded) for candidate, is_encoded in candidates)
+        else:
+            for candidate, is_encoded in candidates:
+                if any(char.isalnum() or char == "_" for char in candidate):
+                    matchers.add((candidate, True, is_encoded))
+                else:
+                    shaped.add(candidate)
+        if "\n" in value:
+            for raw in value.splitlines():
+                if len(line := raw.strip()) >= _MIN_SECRET_COMPONENT:
+                    matchers.add((line, False, False))
+                    encoded_line = urllib.parse.quote(line, safe="")
+                    if encoded_line != line:
+                        matchers.add((encoded_line, False, True))
+    return tuple(matchers), tuple(shaped), frozenset(raw_values)
+
+
+def sanitize_diagnostic(value: Any, *, limit: int = 2000) -> str:
+    """Keep useful failure context while removing credentials and bounding output."""
+    text = f"{type(value).__name__}: {value}" if isinstance(value, BaseException) else str(value)
+    matchers, shaped, raw_values = _configured_secrets()
+    # protect exact punctuation credentials before a separate value can erase their syntax.
+    for secret in sorted(shaped, key=len, reverse=True):
+        escaped = re.escape(secret)
+        text = re.sub(
+            rf"(?i)(authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|token|secret|password)(\s*[:=]\s*)(?:bearer\s+)?{escaped}(?=[\s,;]|$)",
+            lambda match: (
+                "<redacted>"
+                if match.group(1) in raw_values
+                else f"{match.group(1)}{match.group(2)}<redacted>"
+            ),
+            text,
+        )
+        text = re.sub(
+            rf"(?i)\b(bearer)\s+{escaped}(?=[\s,;]|$)",
+            lambda match: "<redacted>" if match.group(1) in raw_values else "Bearer <redacted>",
+            text,
+        )
+    # apply both matcher types in one longest-first order so a shorter plain value cannot consume
+    # the prefix of a longer bounded encoded value.
+    for secret, is_bounded, is_encoded in sorted(
+        matchers, key=lambda item: len(item[0]), reverse=True
+    ):
+        if is_encoded:
+            pattern = _percent_pattern(secret)
+            if is_bounded:
+                left = r"(?<!\w)" if secret[:1].isalnum() or secret[:1] == "_" else ""
+                right = r"(?!\w)" if secret[-1:].isalnum() or secret[-1:] == "_" else ""
+                pattern = f"{left}{pattern}{right}"
+            text = re.sub(pattern, "<redacted>", text)
+        elif is_bounded:
+            text = re.sub(_bounded_pattern(secret), "<redacted>", text)
+        else:
+            text = text.replace(secret, "<redacted>")
+    text = _BEARER_RE.sub("Bearer <redacted>", text)
+    text = _SECRET_KEY_RE.sub(lambda match: f"{match.group(1)}{match.group(2)}<redacted>", text)
+    return text[: max(0, int(limit))]
+
+
+def neutralize_control_chars(value: Any) -> str:
+    """Escape terminal control characters while preserving newlines as separators."""
+    text = str(value)
+    return "".join(
+        char
+        if char == "\n" or 0x20 <= ord(char) < 0x7F or ord(char) >= 0xA0
+        else f"\\x{ord(char):02x}"
+        for char in text
+    )

{freesolo_flash_dev-1.2.64 → freesolo_flash_dev-1.2.66}/flash/engine/worker/__init__.py

@@ -18,7 +18,7 @@ import traceback
 
 from flash._internal.diagnostics import sanitize_diagnostic
 from flash.adapters.fused_experts import lora_target_parameters
-from flash.core.spec import FIXED_SEED, load_job_spec_from_env
+from flash.core.spec import FIXED_SEED, gpu_count_of, load_job_spec_from_env
 from flash.engine.result.accounting import RunMetrics
 from flash.engine.worker.backend_common import collect_ray_failure_logs
 from flash.engine.worker.entry.opd import run_opd
@@ -80,7 +80,7 @@ from flash.engine.worker.perf import (
     grad_checkpointing_on,
     grpo_use_reentrant,
     is_cuda_oom,
-    preflight_free_vram,
+    preflight_gpu_occupancy,
     wait_for_gpu,
 )
 from flash.engine.worker.runtime.kernel_warmup import _current_cuda_sm, load_mega_cache
@@ -221,22 +221,16 @@ def _worker_failure_flags(exc: BaseException) -> dict[str, bool]:
     return {"retriable": retriable, "oom": (not retriable and is_cuda_oom(exc))}
 
 
-def _preflight_free_vram_for_spec() -> None:
-    """Reject a card that arrived already occupied by another tenant.
+def _preflight_gpu_occupancy_for_spec() -> None:
+    """Screen every GPU in the allocator-resolved worker allocation for substantial occupancy.
 
-    Nothing about the spec is read. An earlier draft re-derived the run's requirement here and
-    compared free bytes against it, which is a second sizing model competing with the allocator's
-    and wrong in both directions -- see ``preflight_free_vram``. Occupancy needs no requirement, so
-    it runs on any shape without reimplementing ``combined_vram_gb``'s non-linear multi-card fit.
+    The allocator stamps the chosen count onto ``JOB_SPEC`` before provider launch, so this passes
+    only the cards rented for this worker. It does not re-derive required VRAM or claim exact fit.
 
-    It samples device 0 only. On a multi-card node that leaves a tenant sitting on device 3 alone
-    undetected, which is a gap and not a false alarm -- device 0 occupancy is still evidence of a
-    shared host.
-
-    Must stay the first CUDA-adjacent call in boot: the reading is only trustworthy while this
+    This must stay the first CUDA-adjacent call in boot. The reading is trustworthy only while this
     process has no context of its own, and ``_force_fla_triton_gdn_on_sm100`` below creates one.
     """
-    preflight_free_vram()
+    preflight_gpu_occupancy(gpu_count_of(JOB_SPEC))
 
 
 THINKING = JOB_SPEC.thinking if JOB_SPEC else False
@@ -347,14 +341,14 @@ def _run_worker_mode() -> None:
     # FIRST, and specifically before `_force_fla_triton_gdn_on_sm100`: that reads
     # `get_device_capability`, which initializes CUDA in this process, and from that moment the
     # driver's "used" includes our own context with no sound way to subtract it -- the occupancy
-    # check declines to run rather than guess (see `preflight_free_vram`), so calling it later means
-    # never calling it at all. This is also before `_ensure_fla_fastpath_on_hopper`, whose repair
+    # check declines to run rather than guess (see `preflight_gpu_occupancy`), so calling it later
+    # means never calling it at all. this is also before `_ensure_fla_fastpath_on_hopper`, whose repair
     # path runs pip installs with 600s timeouts: a card handed over with a co-tenant's ~18GB still
     # resident fails the run either way, and the only question is whether that happens now or after
     # dependency repair, the model download and FSDP init have spent paid GPU on the same
     # conclusion. NVML answers without a context, so nothing here dirties the reading for the code
     # below.
-    _preflight_free_vram_for_spec()
+    _preflight_gpu_occupancy_for_spec()
     # run before model imports: sm100 tilelang GDN computes wrong gradients, so use Triton.
     _force_fla_triton_gdn_on_sm100()
     _ensure_fla_fastpath_on_hopper()

{freesolo_flash_dev-1.2.64 → freesolo_flash_dev-1.2.66}/flash/engine/worker/perf/__init__.py

@@ -28,7 +28,7 @@ from flash.engine.worker.perf.lifecycle import (
     RetriableInfraError,
     free_vram_gb,
     is_cuda_oom,
-    preflight_free_vram,
+    preflight_gpu_occupancy,
     total_vram_gb,
     wait_for_gpu,
 )
@@ -403,7 +403,7 @@ __all__ = [
     "grad_checkpointing_on",
     "grpo_use_reentrant",
     "is_cuda_oom",
-    "preflight_free_vram",
+    "preflight_gpu_occupancy",
     "total_vram_gb",
     "wait_for_gpu",
 ]

{freesolo_flash_dev-1.2.64 → freesolo_flash_dev-1.2.66}/flash/engine/worker/perf/lifecycle.py

@@ -34,36 +34,31 @@ class RetriableInfraError(RuntimeError):
 
 
 class DirtyGpuError(RetriableInfraError):
-    """The allocated card arrived with too little free VRAM to run on.
-
-    A RetriableInfraError, deliberately not an OOM. The two recover differently and only one of them
-    is right here: an OOM means the run does not fit the card and retries on a BIGGER one, spending
-    from a small dedicated OOM budget. A dirty card means the run fits fine and the card was already
-    occupied -- a co-tenant in another container, or a previous tenant's leak. Escalating size for
-    that pays more for a card that can be just as dirty, and burns an OOM retry proving it.
-
-    Infra retry reallocates instead: ``_handle_failure`` records the provider in ``failed_providers``
-    and the shape in ``tried_classes``, so the next attempt prefers a DIFFERENT provider, then an
-    untried shape, before clamping back. That is the right preference order for this failure --
-    co-tenancy is a property of the host pool that handed the instance out, not of the run -- but it
-    is a preference, not a guarantee, so nothing here promises which card comes back.
+    """An allocated GPU arrived with substantial pre-existing occupancy.
+
+    This is retriable infrastructure, deliberately not an OOM. An OOM means the run does not fit
+    and retries on a larger card. Substantial boot-time occupancy instead calls for a fresh
+    allocation, because a larger card can arrive just as occupied. This error does not claim that an
+    accepted card has enough free VRAM for the run: occupancy at or below 5%, unreadable NVML, and
+    invalid readings remain fail-open limits of the best-effort screen.
     """
 
 
-def _nvml_memory_gb() -> tuple[float, float] | None:
-    """``(free, total)`` on device 0 in GB straight from NVML, or None if NVML will not answer.
+def _nvml_memory_gb(device_index: int = 0) -> tuple[float, float] | None:
+    """``(free, total)`` for one device in GB from NVML, or None if NVML will not answer.
 
-    NVML, not ``torch.cuda.mem_get_info``: the torch call needs a CUDA context and CREATES one if the
-    process has none, so the act of measuring adds our own few hundred MB to the number being
-    measured. NVML queries the driver without initializing CUDA in this process, which is what lets
-    the boot reading be taken while the card is still provably untouched by us.
+    NVML, not ``torch.cuda.mem_get_info``: the torch call needs a CUDA context and creates one if the
+    process has none, so the act of measuring adds our own memory to the number being measured. NVML
+    queries the driver without initializing CUDA in this process. Device 0 remains the default for
+    the diagnostic helpers that expose its free and total memory.
     """
     try:
         import pynvml
 
         pynvml.nvmlInit()
         try:
-            info = pynvml.nvmlDeviceGetMemoryInfo(pynvml.nvmlDeviceGetHandleByIndex(0))
+            handle = pynvml.nvmlDeviceGetHandleByIndex(device_index)
+            info = pynvml.nvmlDeviceGetMemoryInfo(handle)
             return float(info.free) / (1024**3), float(info.total) / (1024**3)
         finally:
             with contextlib.suppress(Exception):
@@ -110,76 +105,44 @@ def total_vram_gb() -> float | None:
     return None if reading is None else reading[1]
 
 
-def preflight_free_vram(*, max_occupied_fraction: float = 0.05) -> None:
-    """Fail fast when the allocated card arrives already occupied by somebody else.
-
-    Flash sizes the run, asks the provider for a card that fits, and then trains on whatever comes
-    back without ever checking that the memory is FREE. A real RTX 4090 arrived with
-    ``total=22.5 used=18.6 free=3.4``, only 0.486 GB of it owned by any process in this container:
-    ~18 GB was a co-tenant in another container. The number was already in the first heartbeat,
-    before any work -- recorded and not acted on -- so the run downloaded the model and built FSDP
-    for ~80s of paid GPU before dying on an OOM that was knowable at boot.
-
-    Measured as OCCUPANCY (``used/total`` as the driver reports it), not against a requirement.
-    Re-deriving "what this run needs" here would be a second sizing model competing with the
-    allocator's, and it loses both ways: the allocator sizes SFT from profile-measured knobs
-    (``_overridden_train``) that reduce an authored batch 8 to the executed batch 1, so recomputing
-    from the authored spec demands more than the card was rented for; and a run sized exactly at a
-    catalog tier (24 GB) can exceed a real card's usable total (22.5 GB on a 4090), which no amount
-    of free memory can ever satisfy. Both reject a perfectly clean card and retry until the infra
-    budget is gone -- strictly worse than the OOM this exists to prevent.
-
-    Occupancy has neither failure mode: it needs no requirement, no profile, and no catalog number.
-    An empty card reads ~0 whatever is scheduled on it, so the threshold can sit near zero rather
-    than being padded to cover a requirement it never consults. 5% is the driver's own reserve plus
-    slack; the observed dirty card was at 83% with 0.486 GB attributable to us.
-
-    The floor is low BECAUSE the check is occupancy: a loose threshold has to be justified against
-    the biggest run that could be scheduled, and a 5 GB co-tenant that leaves a 20 GB run 17.5 GB on
-    a 22.5 GB card is 22% occupied and fatal. Sizing the threshold to survive that means re-deriving
-    the requirement, which is the failure above. Refusing every card with a stranger on it needs no
-    requirement and covers the close-fitting case too.
-
-    A threshold that low only works if none of the used memory is OURS, and that is established by
-    WHEN the reading is taken, not by trying to attribute it afterwards. Attribution was tried and
-    cannot work here: ``nvidia-smi --query-compute-apps`` reports HOST pids, while the worker
-    container runs with a private pid namespace (``docker run`` in ``providers/_lifecycle/instance``
-    passes no ``--pid=host``), so testing ``/proc/<pid>`` inside the container is not an ownership
-    test in either direction -- our own rows fail it and get counted as a stranger's, and under
-    ``--pid=host`` a real co-tenant passes it and gets credited to us, silently waving through the
-    exact card this exists to refuse.
-
-    So the check simply declines to run once this process has a CUDA context, which makes WHEN it
-    runs the whole design. There is exactly one call site, ``_preflight_free_vram_for_spec`` at the
-    top of ``_run_worker_mode``, and it is placed before ``_force_fla_triton_gdn_on_sm100`` because
-    that reads ``get_device_capability`` and creates the process's first context. Calling from
-    anywhere below that point is not a weaker check, it is no check at all: the guard above returns
-    immediately and the card is never read. A single early call site is therefore the invariant, not
-    an omission -- a later retry could only run after CUDA came up, when the reading is already
-    unusable. That also means one NVML failure at boot is one lost reading, not a lost run: the
-    guard below returns and training proceeds exactly as it did before this check existed.
+def preflight_gpu_occupancy(gpu_count: int, *, max_occupied_fraction: float = 0.05) -> None:
+    """Screen each allocated GPU for substantial occupancy before CUDA initialization.
+
+    The worker reads exactly the allocator-resolved device indices ``range(gpu_count)`` through NVML.
+    An unreadable device or a non-positive total is skipped without hiding later allocated devices.
+    If any valid reading exceeds 5% occupancy, the allocation is rejected as retriable
+    infrastructure after every allocated device has been inspected.
+
+    This is a best-effort occupancy boundary, not an exact-fit guarantee. It deliberately does not
+    reconstruct the allocator's run requirement. Occupancy at or below 5%, unreadable NVML, and
+    invalid readings remain accepted. Once this process has initialized CUDA, the whole screen is
+    fail-open because the driver reading includes memory owned by this process with no sound way to
+    subtract it.
     """
     if cuda_is_initialized():
-        # some of `used` would be ours and there is no sound way to tell how much. a check that
-        # cannot distinguish our context from a co-tenant would either false-reject clean cards or
-        # need a threshold too loose to catch the tenant it exists for. staying silent is correct:
-        # the boot call already read this card while it was provably untouched.
+        # some of `used` would be ours and there is no sound way to tell how much
         return
-    reading = _nvml_memory_gb()
-    if reading is None:
-        # NVML would not answer. somebody else's failure to report, not evidence of a dirty card --
-        # training fails soon enough with a better message.
-        return
-    free, total = reading
-    if total <= 0:
-        return
-    used = max(0.0, total - free)
-    if used <= total * max_occupied_fraction:
+
+    first_dirty: tuple[int, float, float] | None = None
+    for device_index in range(gpu_count):
+        reading = _nvml_memory_gb(device_index)
+        if reading is None:
+            # one unreadable device is not evidence about any later allocated device
+            continue
+        free, total = reading
+        if total <= 0:
+            continue
+        used = max(0.0, total - free)
+        if used > total * max_occupied_fraction and first_dirty is None:
+            first_dirty = (device_index, used, total)
+
+    if first_dirty is None:
         return
+    device_index, used, total = first_dirty
     raise DirtyGpuError(
-        f"allocated GPU has {used:.1f} GB of {total:.1f} GB ({used / total:.0%}) already in use "
-        "before this run has touched it; the card is occupied by another tenant or a previous "
-        "tenant's leak, so retrying on a freshly allocated instance"
+        f"allocated GPU device {device_index} has {used:.1f} GB of {total:.1f} GB "
+        f"({used / total:.0%}) already in use before this run has touched it; the card is occupied "
+        "by another tenant or a previous tenant's leak, so retrying on a freshly allocated instance"
     )
 
 

{freesolo_flash_dev-1.2.64 → freesolo_flash_dev-1.2.66}/flash/providers/_lifecycle/bootstrap_secrets.py

@@ -22,6 +22,22 @@ _SECRET_RE = re.compile(
 # component lines are registered as needles too; the floor keeps a common fragment such as ``}``
 # from erasing innocent output. Mirrors flash._internal.diagnostics.
 _MIN_SECRET_COMPONENT = 8
+_PERCENT_ESCAPE_RE = re.compile(r"%([0-9A-Fa-f]{2})")
+
+
+def _percent_pattern(needle: str) -> str:
+    """Regex for ``needle`` with only percent-escape hex digits matched case-insensitively."""
+    parts: list[str] = []
+    offset = 0
+    for match in _PERCENT_ESCAPE_RE.finditer(needle):
+        parts.append(re.escape(needle[offset : match.start()]))
+        parts.append("%")
+        parts.extend(
+            f"[{char.lower()}{char.upper()}]" if char.isalpha() else char for char in match.group(1)
+        )
+        offset = match.end()
+    parts.append(re.escape(needle[offset:]))
+    return "".join(parts)
 
 
 def _bounded_pattern(needle: str) -> str:
@@ -39,37 +55,86 @@ def _bounded_pattern(needle: str) -> str:
     return f"{left}{escaped}{right}"
 
 
-def _needles(values: set[str]) -> tuple[set[str], set[str]]:
-    """The ``(plain, bounded)`` needle sets for ``values``.
+_ValueMatcher = tuple[str, bool, bool]
+
+
+def _needles(values: set[str]) -> tuple[set[_ValueMatcher], set[str]]:
+    """The typed value matchers and shape-only needles for ``values``.
 
-    plain = replaced as a substring. bounded = values under the floor, replaced only where not
-    adjacent to a word character: dropping them leaked them verbatim, and replacing them plainly
-    would rewrite innocent text (``ati`` inside ``authentication``). encoded forms are registered
-    too. component lines of a MULTILINE value keep the floor as a hard skip -- a short one is
+    each value matcher carries ``(needle, bounded, encoded)`` metadata. plain needles are replaced as
+    substrings. bounded needles are values under the floor, replaced only where not adjacent to a word
+    character. a short raw candidate with no alphanumeric or underscore character is shape-only
+    because it is indistinguishable from ordinary punctuation; explicit percent-octet forms remain
+    bounded. component lines of a multiline value keep the floor as a hard skip: a short one is
     punctuation such as ``}``, not a credential.
     """
-    plain: set[str] = set()
-    bounded: set[str] = set()
+    matchers: set[_ValueMatcher] = set()
+    shaped: set[str] = set()
     for secret in values:
-        target = plain if len(secret) >= _MIN_SECRET_COMPONENT else bounded
-        target.update({secret, urllib.parse.quote(secret, safe="")})
+        candidates = {(secret, False)}
+        encoded = urllib.parse.quote(secret, safe="")
+        if encoded != secret:
+            candidates.add((encoded, True))
+        if len(secret) < _MIN_SECRET_COMPONENT and not any(
+            char.isalnum() or char == "_" for char in secret
+        ):
+            candidates.add(("".join(f"%{byte:02X}" for byte in secret.encode()), True))
+        if len(secret) >= _MIN_SECRET_COMPONENT:
+            matchers.update((candidate, False, is_encoded) for candidate, is_encoded in candidates)
+        else:
+            for candidate, is_encoded in candidates:
+                if any(char.isalnum() or char == "_" for char in candidate):
+                    matchers.add((candidate, True, is_encoded))
+                else:
+                    shaped.add(candidate)
         if "\n" in secret:
             for raw in secret.splitlines():
                 if len(line := raw.strip()) >= _MIN_SECRET_COMPONENT:
-                    plain.update({line, urllib.parse.quote(line, safe="")})
-    return plain, bounded
+                    matchers.add((line, False, False))
+                    encoded_line = urllib.parse.quote(line, safe="")
+                    if encoded_line != line:
+                        matchers.add((encoded_line, False, True))
+    return matchers, shaped
 
 
 def _redact_values(text: str, values: set[str]) -> str:
     """Replace every credential value in ``text``; see ``_needles`` for how each form is matched.
 
-    Longest-first, so one secret containing another cannot leave a suffix of the longer one behind.
+    Longest-first across both matcher types, so one secret containing another cannot leave a suffix
+    of the longer one behind.
     """
-    plain, bounded = _needles(values)
-    for needle in sorted(plain, key=len, reverse=True):
-        text = text.replace(needle, "<redacted>")
-    for needle in sorted(bounded, key=len, reverse=True):
-        text = re.sub(_bounded_pattern(needle), "<redacted>", text)
+    matchers, shaped = _needles(values)
+    # protect exact punctuation credentials before a separate value can erase their syntax.
+    for needle in sorted(shaped, key=len, reverse=True):
+        escaped = re.escape(needle)
+        text = re.sub(
+            rf"(?i)(authorization|api[-_ ]?key|access[-_ ]?token|token|secret|password)(\s*[:=]\s*)(?:bearer\s+)?{escaped}(?=[\s,;]|$)",
+            lambda match: (
+                "<redacted>"
+                if match.group(1) in values
+                else f"{match.group(1)}{match.group(2)}<redacted>"
+            ),
+            text,
+        )
+        text = re.sub(
+            rf"(?i)\b(bearer)\s+{escaped}(?=[\s,;]|$)",
+            lambda match: "<redacted>" if match.group(1) in values else "Bearer <redacted>",
+            text,
+        )
+    for needle, is_bounded, is_encoded in sorted(
+        matchers, key=lambda item: len(item[0]), reverse=True
+    ):
+        if is_encoded:
+            pattern = _percent_pattern(needle)
+            if is_bounded:
+                left = r"(?<!\w)" if needle[:1].isalnum() or needle[:1] == "_" else ""
+                right = r"(?!\w)" if needle[-1:].isalnum() or needle[-1:] == "_" else ""
+                pattern = f"{left}{pattern}{right}"
+            text = re.sub(pattern, "<redacted>", text)
+        elif is_bounded:
+            text = re.sub(_bounded_pattern(needle), "<redacted>", text)
+        else:
+            text = text.replace(needle, "<redacted>")
     return text