okstra 0.169.0 → 0.170.0

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -33,6 +33,11 @@ from .agent_invocation import (
     agent_model_assignment_from_payload,
     verify_agent_invocation,
 )
+from .final_report_paths import (
+    final_report_data_path,
+    final_report_markdown_path,
+)
+from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
@@ -504,9 +509,20 @@ def link_agent_dispatch_result(
             item for item in links
             if isinstance(item, Mapping) and item.get("resultPath") == result_relative
         ]
-        if same_result and any(dict(item) != link for item in same_result):
+        # A superseded link is the record of a result the lead rejected, kept so
+        # the chain shows the corrective round happened rather than hiding it.
+        # It no longer owns the path, so the re-dispatch may claim it.
+        live_conflicts = [
+            item for item in same_result
+            if not item.get("supersededBy") and dict(item) != link
+        ]
+        if live_conflicts:
             raise DispatchError(
-                f"agent result is already linked to another dispatch: {result_relative}"
+                f"agent result is already linked to another dispatch: "
+                f"{result_relative}. If that result was rejected and re-dispatched, "
+                f"record the rejection with `okstra agent-prompt reject-result "
+                f"--dispatch-id {live_conflicts[0].get('dispatchId')} "
+                f"--superseded-by {dispatch_id}` first"
             )
         if any(
             isinstance(item, Mapping)
@@ -523,6 +539,69 @@ def link_agent_dispatch_result(
     return link
 
 
+def reject_agent_dispatch_result(
+    *,
+    project_root: Path,
+    run_manifest_path: Path,
+    dispatch_id: str,
+    superseded_by: str,
+    reason: str,
+) -> dict[str, str]:
+    """Record that a linked result was rejected and re-dispatched.
+
+    The contract tells the lead to re-dispatch a worker whose answer violated the
+    response format, with a correction paragraph appended. That path did not
+    finish: the prompt is immutable and already dispatched, so
+    `--replace-undispatched` refuses (correctly), and a fresh invocation id
+    produces a worker that writes the same result path — where `link-result`
+    refused because the path already belonged to the first dispatch. The worker
+    ran, wrote a good result, and the ledger could not accept it.
+
+    Rejection is a fact worth recording rather than routing around, so it is
+    written rather than allowed implicitly: the first link stays in the ledger
+    marked `supersededBy` with the lead's reason, and only then may the
+    re-dispatch claim the path. Nothing is deleted, so the chain still shows both
+    attempts and why the second exists.
+    """
+    if not superseded_by.strip():
+        raise DispatchError("superseding dispatch ID is required")
+    if not reason.strip():
+        raise DispatchError(
+            "a rejection reason is required — the ledger has to say why a "
+            "returned result was not accepted"
+        )
+    project_root = project_root.resolve()
+    manifest_path = resolve_project_path(
+        project_root, str(run_manifest_path)
+    ).resolve(strict=True)
+    manifest = load_json_object(manifest_path, "run manifest")
+    team_state_path = resolve_required_path(project_root, manifest, "teamStatePath")
+    with _team_state_lock(team_state_path):
+        team_state = load_json_object(team_state_path, "team-state")
+        links = team_state.get("agentResultLinks")
+        if not isinstance(links, list):
+            raise DispatchError("team-state agentResultLinks must be an array")
+        matches = [
+            item for item in links
+            if isinstance(item, Mapping) and item.get("dispatchId") == dispatch_id
+        ]
+        if len(matches) != 1:
+            raise DispatchError(
+                f"expected exactly one agent result link for {dispatch_id}, "
+                f"found {len(matches)}"
+            )
+        row = matches[0]
+        if row.get("supersededBy"):
+            raise DispatchError(
+                f"agent result link is already superseded by "
+                f"{row['supersededBy']}: {dispatch_id}"
+            )
+        row["supersededBy"] = superseded_by
+        row["rejectionReason"] = reason
+        write_json(team_state_path, team_state)
+    return dict(row)
+
+
 def _relative_project_path(project_root: Path, path: Path) -> str:
     try:
         return path.resolve(strict=False).relative_to(project_root).as_posix()
@@ -644,6 +723,54 @@ def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     return tuple(path for path in job.completion_paths if not path.is_file())
 
 
+def dispatch_result_path(
+    worker_id: str,
+    worker_result_path: Path,
+    manifest: Mapping[str, Any],
+    project_root: Path,
+) -> Path:
+    """What `resultPath` means for this worker.
+
+    For everyone but the report writer it is the worker-result file. The report
+    writer authors three artifacts and its canonical result is the final-report
+    data.json, not its own `.md` pointer — a distinction that is not cosmetic:
+    `dispatch_core` hands `job.result_path` to report finalization as the data
+    path, so a `.md` there is parsed as JSON and a complete report settles
+    `error`.
+
+    This lives beside `worker_jobs_from_file` because both job constructors must
+    apply it. It was `dispatch_core`-private while the roster path applied it and
+    the `--jobs-file` path took whatever the file said, which is how the two
+    produced different jobs for the same worker.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return worker_result_path
+    return final_report_data_path(
+        resolve_required_path(project_root, manifest, "expectedReportPath")
+    )
+
+
+def dispatch_completion_paths(
+    worker_id: str,
+    worker_result_path: Path,
+    manifest: Mapping[str, Any],
+    project_root: Path,
+) -> tuple[Path, ...]:
+    """Every artifact that must exist before this worker counts as done.
+
+    The report writer's three are the data.json, its rendered Markdown sibling,
+    and the worker-result pointer (`prompts/lead/report-writer.md` §"Completion
+    detection"). Same reason as `dispatch_result_path`: both constructors need
+    the same answer.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return (worker_result_path,)
+    data_json = final_report_data_path(
+        resolve_required_path(project_root, manifest, "expectedReportPath")
+    )
+    return (data_json, final_report_markdown_path(data_json), worker_result_path)
+
+
 def validate_initial_prompts(
     manifest: Mapping[str, Any], jobs: Sequence[WorkerJob]
 ) -> None:
@@ -798,6 +925,7 @@ def worker_jobs_from_file(
     project_root: Path,
     jobs_file: Path,
     *,
+    manifest: Mapping[str, Any],
     backend: str,
     idle_timeout_seconds: int,
     default_dispatch_kind: str,
@@ -816,6 +944,7 @@ def worker_jobs_from_file(
         _worker_job_from_file(
             project_root,
             item,
+            manifest=manifest,
             backend=backend,
             idle_timeout_seconds=idle_timeout_seconds,
             dispatch_kind=dispatch_kind,
@@ -831,6 +960,7 @@ def _worker_job_from_file(
     project_root: Path,
     item: Mapping[str, Any],
     *,
+    manifest: Mapping[str, Any],
     backend: str,
     idle_timeout_seconds: int,
     dispatch_kind: str,
@@ -842,16 +972,20 @@ def _worker_job_from_file(
     prompt_path = resolve_project_path(
         project_root, require_string(item, "promptPath")
     )
-    result_path = resolve_project_path(
-        project_root, require_string(item, "resultPath")
-    )
     worker_result_path = resolve_project_path(
         project_root, require_string(item, "workerResultPath")
     )
-    completion_paths = tuple(
-        resolve_project_path(project_root, path)
-        for path in string_list(item.get("completionPaths"))
-    ) or (result_path,)
+    # The file's own `resultPath` / `completionPaths` are advisory: the same
+    # derivation the roster path applies decides them, so a jobs-file dispatch
+    # and a roster dispatch of one worker cannot disagree about which artifact
+    # is the result. A file that names the report writer's `.md` as its result
+    # used to reach report finalization as the data path.
+    result_path = dispatch_result_path(
+        worker_id, worker_result_path, manifest, project_root
+    )
+    completion_paths = dispatch_completion_paths(
+        worker_id, worker_result_path, manifest, project_root
+    )
     digests = item.get("digests")
     digest_values = digests if isinstance(digests, Mapping) else {}
     host_model_value = item.get("hostModelValue")

package/runtime/python/okstra_ctl/doctor.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Iterable
 
 from okstra_project import ResolverError, project_json_path, resolve_project_root
+from okstra_project.resolver import resolve_review_rule_packs
 
 from . import improvement_lenses, worktree_registry
 from .models import provider_wrappers
@@ -99,6 +100,9 @@ def _project_checks(cwd: Path) -> tuple[Path | None, list[DoctorCheck]]:
     architecture = _architecture_declaration_check(project_root)
     if architecture is not None:
         checks.append(architecture)
+    review_packs = _review_rule_pack_check(project_root)
+    if review_packs is not None:
+        checks.append(review_packs)
     return project_root, checks
 
 
@@ -158,6 +162,33 @@ def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
     )
 
 
+def _review_rule_pack_check(project_root: Path) -> DoctorCheck | None:
+    """Report a declared review rule pack that no worker will be able to open.
+
+    `reviewRulePacks` is what makes a project's own review standard apply
+    without every brief citing it, so a stale path costs the whole pack in
+    silence: the phase records `project-review-rules: declared <path>
+    unreadable` at best, and a run that reviewed against nothing still passes.
+    Absent declaration stays quiet — brief-cited packs remain the other, equally
+    valid, channel.
+
+    What this cannot check is whether a pack that does resolve was actually read
+    and applied; that stays the worker's own `project-review-rules:` record.
+    """
+    declared = resolve_review_rule_packs(project_root)
+    if not declared:
+        return None
+    missing = [path for path in declared if not Path(path).is_file()]
+    if not missing:
+        return _ok("review rule packs", f"{len(declared)} declared, all readable")
+    return _fail(
+        "review rule packs",
+        f"declared but not readable: {', '.join(missing)} — phases skip a pack "
+        "they cannot open, so the run reviews against fewer rules than declared. "
+        f"Fix the path in {project_json_path(project_root)} or drop the entry.",
+    )
+
+
 def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
     profile = _profile_path(workspace, phase)
     if profile.is_file():

package/runtime/python/okstra_ctl/error_log_write.py

@@ -0,0 +1,308 @@
+"""Writer core for runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl.
+
+Every error record in a run log is appended through this module. It lives here
+rather than inside `scripts/okstra-error-log.py` because the CLI is no longer the
+only caller: the deterministic dispatcher records a worker wrapper's non-zero
+exit as a `cli-failure` in-process (`dispatch_core`), and the contract sentence
+that says it does is only true while both paths share one writer. The script
+keeps the argparse surface and re-exports these names.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+from pathlib import Path
+
+from .models import provider_ids
+
+STDERR_EXCERPT_MAX_BYTES = 2048
+TRUNCATION_SUFFIX = "...[truncated]"
+PIPE_BUF_BYTES = 4096
+
+ALLOWED_ERROR_TYPES = {"tool-failure", "cli-failure", "contract-violation"}
+# Derived, not listed. The hand-written set had drifted two providers behind the
+# registry: `grok` and `kimi` ship worker definitions and can be dispatched, but
+# their agent names were absent, so every error they reported was rejected at
+# the argument parser — silently, for anyone who did not read the exit code.
+# The registry is where a provider is added, so it is where this follows from.
+ALLOWED_AGENTS = (
+    {f"{provider}-worker" for provider in provider_ids("analyser")}
+    # The report writer is not an analyser and is named without the suffix,
+    # matching `REPORT_WRITER_WORKER_ID`.
+    | {"report-writer"}
+    # Lead identities come from the selected host adapter rather than the
+    # provider registry; `adapters/hosts/*/relay.md` names the value to pass.
+    | {"claude-lead"}
+)
+ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
+SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
+
+ALLOWED_CAUSES = {
+    "sandbox-denied", "service-unavailable", "auth-failed", "unknown",
+}
+# A `sandbox-denied` claim is only admissible with both probes attached.
+CAUSE_EVIDENCE_FIELDS = ("targetProbe", "controlProbe")
+# Both probes share a record's PIPE_BUF_BYTES budget with stderrExcerpt, so
+# they cannot reuse the 2048 cap that assumes stderrExcerpt owns it alone.
+CAUSE_PROBE_MAX_BYTES = 256
+# Backstop vocabulary: scanned in `message` only — never in stderrExcerpt,
+# where a kernel's real "Operation not permitted" is legitimate content.
+# Deliberately excludes bare "blocked"/"blocks": everyday English that would
+# reject honest records like "test blocked on upstream dependency".
+_BLOCKING_CLAIM_TERMS = (
+    "sandbox", "not permitted", "permission denied", "eperm",
+)
+# The backstop targets *unclassified* blocking claims. A worker that declared
+# a specific cause has already done the honest work — `auth-failed` legitimately
+# reads "permission denied" (MySQL 1045).
+_UNCLASSIFIED_CAUSES = (None, "unknown")
+
+
+def _now_utc():
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def _iso(t):
+    return t.isoformat()
+
+
+def _truncate_utf8(s, limit):
+    """Truncate to `limit` bytes without splitting a multibyte character."""
+    if s is None:
+        return None
+    encoded = s.encode("utf-8")
+    if len(encoded) <= limit:
+        return s
+    cut = encoded[:limit]
+    while cut:
+        try:
+            return cut.decode("utf-8") + TRUNCATION_SUFFIX
+        except UnicodeDecodeError:
+            cut = cut[:-1]
+    return TRUNCATION_SUFFIX
+
+
+def truncate_stderr(s):
+    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
+    return _truncate_utf8(s, STDERR_EXCERPT_MAX_BYTES)
+
+
+def normalize_cause_context(context, *, message):
+    """Validate a record's cause claim and return the normalized context.
+
+    Raises ValueError on three conditions:
+    - `cause` is set to a value outside ALLOWED_CAUSES;
+    - `cause` is 'sandbox-denied' but the two probes are missing or blank —
+      those probes are what distinguish a real denial from an unreachable
+      or auth-gated target, the misdiagnosis this gate exists to stop;
+    - `message` asserts a block in prose while the record left its cause
+      unclassified, which would smuggle the same claim past the gate.
+    """
+    cause = context.get("cause") if isinstance(context, dict) else None
+
+    if cause is not None and cause not in ALLOWED_CAUSES:
+        raise ValueError(
+            f"invalid cause: {cause!r} (allowed: {sorted(ALLOWED_CAUSES)})"
+        )
+
+    if cause == "sandbox-denied":
+        evidence = context.get("causeEvidence")
+        if not isinstance(evidence, dict):
+            raise ValueError(
+                "cause 'sandbox-denied' requires context.causeEvidence with "
+                f"{list(CAUSE_EVIDENCE_FIELDS)}"
+            )
+        normalized_evidence = {}
+        for field in CAUSE_EVIDENCE_FIELDS:
+            value = evidence.get(field)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(
+                    f"cause 'sandbox-denied' requires a non-empty "
+                    f"context.causeEvidence.{field}: record the command and "
+                    f"its raw output that proves the claim"
+                )
+            normalized_evidence[field] = _truncate_utf8(
+                value, CAUSE_PROBE_MAX_BYTES
+            )
+        return {**context, "causeEvidence": normalized_evidence}
+
+    if message and cause in _UNCLASSIFIED_CAUSES:
+        lowered = message.lower()
+        hit = next((t for t in _BLOCKING_CLAIM_TERMS if t in lowered), None)
+        if hit:
+            raise ValueError(
+                f"message asserts a blocking claim ({hit!r}) without "
+                "context.cause='sandbox-denied' + context.causeEvidence. "
+                "Either attach the two probes, or state the cause you "
+                "actually verified."
+            )
+
+    return context
+
+
+def append_jsonl_line(path, record):
+    """Append a single JSON record as one line to ``path``.
+
+    Atomicity guarantee (POSIX only):
+        With ``O_APPEND`` and a single ``write()`` syscall, the kernel
+        appends the entire payload as one indivisible operation as long as
+        the payload size is at most ``PIPE_BUF`` (4096 bytes on Linux and
+        macOS). Larger payloads may be split across syscalls and interleave
+        with concurrent writers, so this helper rejects them with
+        ``ValueError`` rather than silently losing atomicity.
+
+    The atomicity contract holds only on POSIX filesystems with O_APPEND
+    semantics. Concurrent writers using ``O_TRUNC``, ``unlink``, or
+    non-append modes against the same path break the contract and are
+    out of scope for this helper.
+
+    Caller responsibilities:
+    - Keep records small (this module's stderr excerpt cap of
+      ``STDERR_EXCERPT_MAX_BYTES`` exists to keep records well under
+      ``PIPE_BUF_BYTES``).
+    - Handle ``TypeError`` from ``json.dumps`` for non-serializable values.
+
+    Creates parent directories as needed.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # ensure_ascii=False keeps UTF-8 compact (no \uXXXX escapes).
+    # json.dumps escapes literal newlines inside string values, so the
+    # only unescaped newline is the record separator we append below.
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    data = line.encode("utf-8")
+    if len(data) > PIPE_BUF_BYTES:
+        raise ValueError(
+            f"record too large for atomic append: {len(data)} bytes > "
+            f"PIPE_BUF ({PIPE_BUF_BYTES})"
+        )
+    # mode 0o644: owner read/write, group/world read-only.
+    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def append_observed(
+    *,
+    out_path,
+    task_key,
+    phase,
+    agent,
+    agent_role,
+    model,
+    error_type,
+    command,
+    command_kind,
+    exit_code,
+    duration_ms,
+    message,
+    stderr_excerpt,
+    context,
+    now=None,
+):
+    """Append a lead-observed error event to errors.jsonl."""
+    if error_type not in ALLOWED_ERROR_TYPES:
+        raise ValueError(f"invalid errorType: {error_type!r}")
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    # Runs before append_jsonl_line so a rejected claim leaves no trace in the
+    # log: a written-then-flagged record is still a record someone can cite.
+    context = normalize_cause_context(context, message=message)
+    ts = _iso(now or _now_utc())
+    rec = {
+        "ts": ts,
+        "recordedAt": ts,
+        "taskKey": task_key,
+        "phase": str(phase),
+        "agent": agent,
+        "agentRole": agent_role,
+        "model": model,
+        "source": "lead-observed",
+        "errorType": error_type,
+        "command": command,
+        "commandKind": command_kind,
+        "exitCode": exit_code,
+        "durationMs": duration_ms,
+        "message": message,
+        "stderrExcerpt": truncate_stderr(stderr_excerpt),
+        "context": context,
+    }
+    append_jsonl_line(out_path, rec)
+    return rec
+
+
+def dump_from_worker_sidecar(
+    *,
+    sidecar_path,
+    out_path,
+    task_key,
+    agent,
+    agent_role,
+    model,
+    now=None,
+):
+    """Read worker sidecar errors[] and append each to errors.jsonl with
+    Lead-side metadata filled in. Returns number of records appended.
+
+    Raises ValueError if:
+      - ``agent`` or ``agent_role`` is not in the allow-lists
+      - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
+      - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
+      - any entry asserts a blocking cause without its required evidence
+
+    Returns 0 (no-op) if the sidecar file does not exist or its
+    ``errors`` list is empty.
+
+    Partial-failure semantics: entries are validated and appended in
+    order. If entry N fails validation, entries 0..N-1 have already
+    been written to ``out_path`` and are NOT rolled back. Callers that
+    require atomicity must validate the sidecar payload before invoking
+    this function.
+    """
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    p = Path(sidecar_path)
+    if not p.exists():
+        return 0
+    payload = json.loads(p.read_text())
+    schema = payload.get("schemaVersion")
+    if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
+        raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
+    entries = payload.get("errors") or []
+    recorded_at = _iso(now or _now_utc())
+    count = 0
+    for e in entries:
+        et = e.get("errorType")
+        if et not in ALLOWED_ERROR_TYPES:
+            raise ValueError(f"invalid errorType in sidecar: {et!r}")
+        entry_context = normalize_cause_context(
+            e.get("context"), message=e.get("message")
+        )
+        rec = {
+            "ts": e.get("ts"),
+            "recordedAt": recorded_at,
+            "taskKey": task_key,
+            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
+            "agent": agent,
+            "agentRole": agent_role,
+            "model": model,
+            "source": "worker-reported",
+            "errorType": et,
+            "command": e.get("command"),
+            "commandKind": e.get("commandKind"),
+            "exitCode": e.get("exitCode"),
+            "durationMs": e.get("durationMs"),
+            "message": e.get("message"),
+            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
+            "context": entry_context,
+        }
+        append_jsonl_line(out_path, rec)
+        count += 1
+    return count

package/runtime/python/okstra_ctl/plan_derivations.py

@@ -0,0 +1,94 @@
+"""Find the statements an answered clarification may have just falsified.
+
+`_common-contract.md` §"Supersession" and `report-writer.md` §"Self-fix rewrite"
+both say the same thing: an answer does not merely add a decision, it invalidates
+whatever the plan wrote under the opposite assumption, so before editing you must
+"grep the constant, the symbol, the path, the requirement ID across the whole
+plan body". Both leave that grep to the author's diligence, and it is the step
+that gets skipped — in one observed run, 17 of 23 blocked plan items were a
+recorded decision whose derivations were never swept.
+
+This does the grep. It is deliberately advisory: it returns candidate locations,
+never a verdict about which ones are now false. Deciding that is the author's
+job, and a tool that guessed would be trading one silent failure for another.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator, Mapping, Sequence
+
+# A backticked span is how both contracts tell an author to write a symbol, a
+# path, or a constant, so it is the highest-signal thing to extract. Bare prose
+# words are deliberately not extracted: they match everywhere and would bury the
+# hits that matter.
+_BACKTICKED_RE = re.compile(r"`([^`\n]+)`")
+# Ids the plan carries in its own rows (`R-001`, `P-Step-3`, `VC-002`) and the
+# ticket ids the brief uses (`DEV-10174`, `PROD-1623`).
+_ID_RE = re.compile(r"\b(?:[A-Z][A-Za-z]*-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b")
+# Below this length a token matches too much to be worth reading: `id`, `db`,
+# and `ko` each hit dozens of unrelated rows.
+_MIN_TOKEN_LENGTH = 3
+_EXCERPT_MAX = 160
+
+
+def extract_tokens(text: str) -> list[str]:
+    """The symbols, paths, and ids an answer names, longest first.
+
+    Longest first so a caller reading the report sees the specific token before
+    the general one it contains (`src/domains/font` before `src/domains`).
+    """
+    found: set[str] = set()
+    for raw in _BACKTICKED_RE.findall(text):
+        token = raw.strip()
+        # A backticked sentence is prose in code font, not a symbol.
+        if len(token) >= _MIN_TOKEN_LENGTH and " " not in token:
+            found.add(token)
+    for token in _ID_RE.findall(text):
+        if len(token) >= _MIN_TOKEN_LENGTH:
+            found.add(token)
+    return sorted(found, key=lambda token: (-len(token), token))
+
+
+def _string_leaves(node: Any, pointer: str = "") -> Iterator[tuple[str, str]]:
+    if isinstance(node, str):
+        yield pointer, node
+    elif isinstance(node, Mapping):
+        for key, value in node.items():
+            yield from _string_leaves(value, f"{pointer}/{key}")
+    elif isinstance(node, Sequence) and not isinstance(node, (str, bytes)):
+        for index, value in enumerate(node):
+            yield from _string_leaves(value, f"{pointer}/{index}")
+
+
+def _excerpt(text: str, token: str) -> str:
+    index = text.find(token)
+    if index < 0:
+        return text[:_EXCERPT_MAX]
+    start = max(0, index - _EXCERPT_MAX // 3)
+    excerpt = text[start:start + _EXCERPT_MAX]
+    return ("…" if start else "") + excerpt + ("…" if len(text) > start + _EXCERPT_MAX else "")
+
+
+def find_derivations(
+    plan: Mapping[str, Any],
+    tokens: Sequence[str],
+    *,
+    exclude_pointer_prefix: str = "",
+) -> list[dict[str, str]]:
+    """Every string in *plan* that mentions one of *tokens*.
+
+    One hit per (pointer, token): a row naming two affected symbols is two things
+    to re-check, not one.
+    """
+    hits: list[dict[str, str]] = []
+    for pointer, text in _string_leaves(plan):
+        if exclude_pointer_prefix and pointer.startswith(exclude_pointer_prefix):
+            continue
+        for token in tokens:
+            if token in text:
+                hits.append({
+                    "token": token,
+                    "pointer": pointer,
+                    "excerpt": _excerpt(text, token),
+                })
+    return hits