stacktrace-cli 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

stacktrace_cli/correlate/composition.py

@@ -115,6 +115,17 @@ class Composition:
     #: Where it was scanned instead. Set together with `relocated_from`; the pair
     #: is what makes the inference auditable rather than merely disclosed.
     relocated_to: str | None = None
+    #: `openaca:agent_id` off the BOM root: *which* agent, where `agent_kind`
+    #: says *what*. Absent for a singleton kind — every kind OpenACA registers,
+    #: whose lint refuses an id outright — so `None` is the ordinary case and
+    #: not a gap.
+    #:
+    #: Carried because the hosted side keys an agent on it (issue #12): a BOM
+    #: upload lets the Cloud read this off the root itself, while a detect run
+    #: sends no BOM and must state it, and the two naming different things files
+    #: one agent as two rows. Defaulted rather than positional so it sits with
+    #: the fields a document may omit, though it belongs beside `agent_kind`.
+    agent_instance_id: str | None = None
 
     def find(self, component_type: str, name: str) -> tuple[Component, ...]:
         """Every component of this type and name, in BOM order.
@@ -169,9 +180,57 @@ def composition_from_bom(
         lineage=lineage,
         advisories=advisories or {},
         advisories_checked=advisories is not None,
+        agent_instance_id=_declared_instance_id(document),
     )
 
 
+#: `openaca:agent_id` on `metadata.component`. Read here rather than in
+#: `acquire` so the projection that owns every other root field owns this one.
+_AGENT_ID_PROPERTY = "openaca:agent_id"
+
+
+def _declared_instance_id(document: dict[str, Any]) -> str | None:
+    """`openaca:agent_id`, blank-checked but **never rewritten**.
+
+    Blank folds to absent because the Cloud's `agent_instance_id` is
+    `min_length=1`: a present-but-empty value is a 422 that rejects the *whole*
+    detect run, every detection in it. OpenACA's lint already refuses an empty
+    id, so only a hand-written document arrives with one, and losing that BOM's
+    id costs less than losing the machine's detections. The two stay
+    distinguishable where it counts -- the hosted side still rejects an empty
+    string; this simply never sends one.
+
+    **Whitespace is not trimmed.** The Cloud reads this same property off the
+    same root on the BOM upload path and does not trim it either, so
+    normalising here would leave the two paths naming different strings for one
+    agent -- which is the split (issue #12) reintroduced for a padded value. A
+    padded id already satisfies `min_length=1`, so there is nothing to fix by
+    rewriting it.
+    """
+    declared = root_property(document, _AGENT_ID_PROPERTY)
+    return declared if declared and declared.strip() else None
+
+
+def root_property(document: dict[str, Any], name: str) -> str | None:
+    """One `metadata.component` property's value, or `None`.
+
+    Public because `acquire` reads the agent kind out of a raw document before
+    it has a composition to ask -- the discriminator has to be known to pick
+    which kind a document is even for. Non-`str` reads as absent for the reason
+    `reject_malformed_shape` exists: a value from a document this process did
+    not write is validated, never trusted for its type.
+    """
+    metadata = document.get("metadata")
+    root = metadata.get("component") if isinstance(metadata, dict) else None
+    if not isinstance(root, dict):
+        return None
+    for prop in root.get("properties") or []:
+        if isinstance(prop, dict) and prop.get("name") == name:
+            value = prop.get("value")
+            return value if isinstance(value, str) else None
+    return None
+
+
 #: Where a BOM's shape is checked before anything reads it.
 #:
 #: Every malformed-document finding this module has ever taken was the same

stacktrace_cli/correlate/join.py

@@ -256,6 +256,28 @@ def candidates_for(key: JoinKey, composition: Composition) -> tuple[Component, .
     return candidates
 
 
+def builtin_category_and_name(call: ToolCallLike, agent_kind: str) -> tuple[str, str] | None:
+    """What a built-in resolution was, re-asked rather than read.
+
+    A built-in's `Resolution` is `key=None, candidates=(), target=root` and is
+    byte-identical for a tool, a subagent and a skill, so the category and the
+    name are both unrecoverable from it. The predicates above are the one
+    implementation of that question, and this is the one place that composes
+    them -- it lives here, beside them, because both the wire's activity
+    attribution and a finding's own subject have to give the same answer, and
+    two copies is how they would come to differ.
+    """
+    if is_builtin_subagent(call, agent_kind):
+        requested = (call.arguments or {}).get("subagent_type")
+        return "subagent", str(requested)
+    if is_builtin(call.tool_name, agent_kind):
+        return "tool", call.tool_name
+    key = join_key(call)
+    if key is not None and is_builtin_skill(key, agent_kind):
+        return "skill", key.name
+    return None
+
+
 def join_key(call: ToolCallLike) -> JoinKey | None:
     """What this call names, or None if this component cannot key it.
 
@@ -263,8 +285,32 @@ def join_key(call: ToolCallLike) -> JoinKey | None:
     recognized shape whose expected argument was missing, and a tool this
     component does not recognize at all.
     """
+    addressed = addressed_naming(call)
+    if addressed is None:
+        return None
+    component_type, name = addressed
+    # A server's name is what the client recorded about where the call went;
+    # only a name read out of an argument is the session's own spelling and so
+    # the only one there is anything to normalize away.
+    return JoinKey(component_type, name if call.mcp_server else _unqualified(name))
+
+
+def addressed_naming(call: ToolCallLike) -> tuple[str, str] | None:
+    """The component type this call named, and the word it named it by.
+
+    The same extraction `join_key` keys on, read before normalization and
+    returned as one answer so the two cannot come to disagree about which
+    calls name anything at all.
+
+    The word matters where nothing placed the call: `join_key` drops a plugin
+    qualifier so a session's `superpowers:brainstorming` can match a BOM's
+    `brainstorming`, which is the right question to ask a composition and the
+    wrong name to report back. Two plugins may ship a skill of one name, so
+    the qualifier is the part that says which one ran, and ADR-0027 carries
+    the name the session addressed rather than the key correlation looked up.
+    """
     if call.mcp_server:
-        return JoinKey("mcp_server", call.mcp_server)
+        return "mcp_server", call.mcp_server
     signal = _ARGUMENT_SIGNALS.get(call.tool_name)
     if signal is None:
         return None
@@ -272,7 +318,7 @@ def join_key(call: ToolCallLike) -> JoinKey | None:
     value = (call.arguments or {}).get(argument)
     if not isinstance(value, str) or not value:
         return None
-    return JoinKey(component_type, _unqualified(value))
+    return component_type, value
 
 
 def _unqualified(name: str) -> str:

stacktrace_cli/correlate/orchestrate.py

@@ -34,12 +34,14 @@ now imports from here, which is the direction it should always have been.
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
+from collections.abc import Set as AbstractSet
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, replace
 from pathlib import Path
+from typing import Any
 
 from stacktrace_cli.correlate.acquire import Built, advisories_for, build_bom, load_bom
-from stacktrace_cli.correlate.composition import Composition
+from stacktrace_cli.correlate.composition import Advisory, Composition
 from stacktrace_cli.correlate.join import is_builtin, is_builtin_subagent, join_key
 from stacktrace_cli.correlate.project_map import ProjectMapping, remap
 from stacktrace_cli.correlate.record import CorrelatedView, composition_key
@@ -155,7 +157,39 @@ def _invoked_identities(correlated: object) -> set[str]:
     return identities
 
 
-def _attach_advisories(correlated: CorrelatedView, builts: Sequence[Built]) -> CorrelatedView:
+#: `advisories_for`'s shape: the documents to search and the identities that
+#: were actually invoked, answering `None` for "not checked at all", which must
+#: stay distinguishable from "checked and found nothing".
+AdvisoryLookup = Callable[
+    ["Sequence[dict[str, Any]]", "AbstractSet[str]"],
+    "dict[str, tuple[Advisory, ...]] | None",
+]
+AttachAdvisories = Callable[[CorrelatedView, "Sequence[Built]"], CorrelatedView]
+
+
+def advisory_attacher(lookup: AdvisoryLookup = advisories_for) -> AttachAdvisories:
+    """`_attach_advisories`, with the network call substitutable.
+
+    A long-lived process — `monitor` — asks this question every time a
+    transcript changes, and the answer for a component it already asked about
+    has not changed. Only the *lookup* is swappable: the enrichment below stays
+    in one place because its memo by `id(composition)` is load-bearing for
+    every consumer that dedupes compositions by identity, and a second copy of
+    that reasoning would be a second chance to get it wrong.
+    """
+
+    def attach(correlated: CorrelatedView, builts: Sequence[Built]) -> CorrelatedView:
+        return _attach_advisories(correlated, builts, lookup=lookup)
+
+    return attach
+
+
+def _attach_advisories(
+    correlated: CorrelatedView,
+    builts: Sequence[Built],
+    *,
+    lookup: AdvisoryLookup = advisories_for,
+) -> CorrelatedView:
     """Match advisories once, over what ran, and hang them on every composition.
 
     The scan is deferred to here because this is the first moment the question
@@ -177,7 +211,7 @@ def _attach_advisories(correlated: CorrelatedView, builts: Sequence[Built]) -> C
     two different enriched objects and break that dedup silently.
     """
     identities = _invoked_identities(correlated)
-    matched = advisories_for([b.document for b in builts], identities)
+    matched = lookup([b.document for b in builts], identities)
     checked = matched is not None
     by_identity = matched or {}
     memo: dict[int, Composition] = {}

stacktrace_cli/correlate/record.py

@@ -269,6 +269,14 @@ def _coverage(session: SessionLike, resolutions: dict[str, Resolution]) -> Cover
         resolved += 1
         # An ambiguous match counts once, under its key's type: the call happened
         # once, however many components it might name.
+        #
+        # It counts as **resolved** here and is sent as *unresolved* on the
+        # wire (`remote/detect_payload.classify_call`), so this number and the
+        # Cloud's recomputed coverage legitimately differ by the ambiguous
+        # calls. Deliberate in that direction: coverage summed from per-
+        # component counters has no honest bucket for a call that named two, so
+        # the wire errs toward under-reporting. See the detect-upload spec,
+        # *Ambiguity is named in a finding, never in a counter*.
         if resolution.key is not None:
             by_component_type[resolution.key.component_type] += 1
     return Coverage(

stacktrace_cli/detector/deterministic.py

@@ -37,6 +37,7 @@ from __future__ import annotations
 
 import json
 import re
+from dataclasses import dataclass
 
 from stacktrace_cli.correlate.observed import (
     capabilities,
@@ -454,6 +455,94 @@ def _hung_call(session: SessionLike, ref: SessionRef) -> Detection | None:
     )
 
 
+@dataclass(frozen=True)
+class Scavenging:
+    """One server's refusal, the later success, and what that success added.
+
+    `acquired` is keyed on `(kind, fingerprint)` and is the whole trigger: the
+    credentials the agent did not carry to this server through its refusal.
+    Whatever else a reader is told about the sequence has to be about exactly
+    these, so the set is computed once and handed out rather than re-derived
+    per question -- a second derivation is free to disagree, and a claim about
+    where a credential came from that disagrees with the claim about which
+    credential it was is false however carefully either half was written.
+    """
+
+    refusal: ToolCallLike
+    success: ToolCallLike
+    acquired: frozenset[tuple[str, str]]
+
+
+def _scavenging(calls: list[ToolCallLike]) -> Scavenging | None:
+    """The scavenging one server's calls record, if they record one."""
+    # An **explicit** refusal, never a missing outcome, and never a
+    # `rejected` one either. `pending` was in this set and is the record's
+    # dominant artefact -- 7,242 of 29,176 calls, because upstream withholds
+    # an outcome it could not establish -- so "did not succeed" was
+    # satisfied by any server whose result was merely unreadable.
+    # `rejected` looked like the server's own refusal but is the same fact
+    # `observe()` and every priors rule already act on: a rejected call was
+    # denied by the person before it ever
+    # reached the server, so it is a guardrail working as intended, not a
+    # component turning the agent away. Only a stated `error` is that.
+    #
+    # This narrowing cost nothing on the measured corpus and was not
+    # prompted by a false positive there: all four firings on 621 sessions
+    # are the planted scenarios this rule's own test fixtures supply, and
+    # each of those refuses with `error`. It closes a shape
+    # that had no evidence behind it rather than one that had too much.
+    first_failure = next((i for i, c in enumerate(calls) if failed(c)), None)
+    if first_failure is None:
+        return None
+    # Keyed on (kind, fingerprint), not kind alone: an issuer's refused
+    # credential replaced by a *different* credential of the same kind --
+    # the central recovery this rule exists to catch -- shares a kind with
+    # what was already held, and kind-only dedup silently cleared it.
+    # `fingerprint` is a one-way hash, so this comparison never holds or
+    # emits the matched value itself.
+    held = {
+        (match.kind, match.fingerprint)
+        for c in calls[: first_failure + 1]
+        for match in find_secrets(c.arguments)
+    }
+    carrying = []
+    for i, c in enumerate(calls):
+        if i <= first_failure or not succeeded(c):
+            continue
+        acquired = frozenset(
+            (match.kind, match.fingerprint)
+            for match in find_secrets(c.arguments)
+            if (match.kind, match.fingerprint) not in held
+        )
+        if acquired:
+            carrying.append((c, acquired))
+    if not carrying:
+        return None
+    call, acquired = carrying[-1]
+    return Scavenging(refusal=calls[first_failure], success=call, acquired=acquired)
+
+
+def scavenging_anchored_on(session: SessionLike, refusal_span: str) -> Scavenging | None:
+    """The scavenging a `stacktrace-scavenged-credential` finding is about.
+
+    Read from the record by the same code the rule fired from, so anything
+    added to such a finding after the fact -- where those credentials came
+    from, above all -- is about the credentials that caused it and not about
+    every credential its cited calls happen to carry. The refused call already
+    carrying a credential of its own is the ordinary case, not a corner: that
+    credential has a source, and that source is not a party to the agent then
+    going looking for another one.
+    """
+    calls = [call for turn in session.turns for call in turn.tool_calls]
+    refused = next((call for call in calls if call.span == refusal_span), None)
+    if refused is None or not refused.mcp_server:
+        return None
+    scavenging = _scavenging([c for c in calls if c.mcp_server == refused.mcp_server])
+    if scavenging is None or scavenging.refusal.span != refusal_span:
+        return None
+    return scavenging
+
+
 def _scavenged_credential(session: SessionLike, ref: SessionRef) -> tuple[Detection, ...]:
     """A component that rejected the agent, then accepted it carrying a secret.
 
@@ -474,52 +563,11 @@ def _scavenged_credential(session: SessionLike, ref: SessionRef) -> tuple[Detect
         calls = [
             call for turn in session.turns for call in turn.tool_calls if call.mcp_server == server
         ]
-        # An **explicit** refusal, never a missing outcome, and never a
-        # `rejected` one either. `pending` was in this set and is the record's
-        # dominant artefact -- 7,242 of 29,176 calls, because upstream withholds
-        # an outcome it could not establish -- so "did not succeed" was
-        # satisfied by any server whose result was merely unreadable.
-        # `rejected` looked like the server's own refusal but is the same fact
-        # `observe()` and every priors rule already act on: a rejected call was
-        # denied by the person before it ever
-        # reached the server, so it is a guardrail working as intended, not a
-        # component turning the agent away. Only a stated `error` is that.
-        #
-        # This narrowing cost nothing on the measured corpus and was not
-        # prompted by a false positive there: all four firings on 621 sessions
-        # are the planted scenarios this rule's own test fixtures supply, and
-        # each of those refuses with `error`. It closes a shape
-        # that had no evidence behind it rather than one that had too much.
-        first_failure = next((i for i, c in enumerate(calls) if failed(c)), None)
-        if first_failure is None:
-            continue
-        # Keyed on (kind, fingerprint), not kind alone: an issuer's refused
-        # credential replaced by a *different* credential of the same kind --
-        # the central recovery this rule exists to catch -- shares a kind with
-        # what was already held, and kind-only dedup silently cleared it.
-        # `fingerprint` is a one-way hash, so this comparison never holds or
-        # emits the matched value itself.
-        held = {
-            (match.kind, match.fingerprint)
-            for c in calls[: first_failure + 1]
-            for match in find_secrets(c.arguments)
-        }
-        carrying = []
-        for i, c in enumerate(calls):
-            if i <= first_failure or not succeeded(c):
-                continue
-            acquired = sorted(
-                {
-                    match.kind
-                    for match in find_secrets(c.arguments)
-                    if (match.kind, match.fingerprint) not in held
-                }
-            )
-            if acquired:
-                carrying.append((c, acquired))
-        if not carrying:
+        scavenging = _scavenging(calls)
+        if scavenging is None:
             continue
-        call, kinds = carrying[-1]
+        call = scavenging.success
+        kinds = sorted({kind for kind, _ in scavenging.acquired})
         found.append(
             Detection(
                 rule_id="stacktrace-scavenged-credential",
@@ -530,9 +578,9 @@ def _scavenged_credential(session: SessionLike, ref: SessionRef) -> tuple[Detect
                 observed_capabilities=observed_across(call),
                 evidence=(
                     Evidence(
-                        span=calls[first_failure].span,
+                        span=scavenging.refusal.span,
                         kind="refused",
-                        detail=f"{_tool(calls[first_failure])} did not succeed",
+                        detail=f"{_tool(scavenging.refusal)} did not succeed",
                     ),
                     Evidence(
                         span=call.span,

stacktrace_cli/detector/finding.py

@@ -7,13 +7,19 @@ indistinguishable from *nothing was wrong* and this pipeline may never say that
 by accident (ADR-0004).
 
 **Neither record can carry session content, and that is structural.** There is no
-field here able to hold a prompt, an argument, a result, a matched secret or a
-decoded payload — only spans, kinds and coordinates. Findings travel further than
+field here able to hold a prompt, a result, a matched secret or a decoded
+payload — only spans, kinds and coordinates. Findings travel further than
 sessions do: a session never leaves the machine, but a detection may be uploaded
 agent-keyed (ADR-0006). Putting the boundary in the data model means a future
 rule author cannot breach it by writing a plausible-looking rule; they would have
 to add a field first, and a reviewer sees that.
 
+The one field that is narrower than that is `Participant.name` on a party
+correlation could not place, which ADR-0027 admits *because* it is the only
+name such a thing has and a finding without it names nothing to act on. It is
+one field at one position, carried as a descriptor and never as an identity —
+see `Participant`.
+
 Severity and confidence are this family's own (ADR-0010). `openaca.core` exports
 no ladder to reuse: its `Finding.confidence` is a bare `str` of
 `high`/`low`/`unknown`, and severity is reachable only through
@@ -168,6 +174,88 @@ class Coverage:
     resolved: int = 0
 
 
+#: How well a party to a finding can be known, and the whole of it. Closed
+#: because what a participant may *carry* is defined per kind below -- a fifth
+#: spelling would be a name with no rule behind it and no consumer able to
+#: render it as anything.
+PARTICIPANT_KINDS = ("component", "ambiguous", "builtin", "unplaced")
+
+#: The parts a participant plays in a finding. `subject` is the anchor the
+#: finding is about; `source` is where the credential it cites came from.
+PARTICIPANT_ROLES = ("subject", "source")
+
+
+@dataclass(frozen=True)
+class Participant:
+    """One named party to a finding, labelled by **how well it is known**.
+
+    `components` can only name what correlation *placed* -- a BOM component
+    with a verified identity -- so three of the five things a call resolves to
+    are unnameable by it and reach a reader as a dash: the agent's own built-in
+    tool, a server nothing on the machine declares, and an unplaced skill.
+
+    `kind` is what stops filling that dash being a regression. An unverified
+    name in a column of verified ones reads as inventory, which is worse than a
+    dash -- so a consumer must render `builtin` as what it is, and must never
+    link it or resolve a lookup by it. `identity` is `None` for every kind but
+    `component`, which is the machine-checkable form of the same rule.
+
+    **What a name is worth differs per kind, and that is a boundary rather
+    than a convention.** Three of the four names come from the BOM or from a
+    closed set this package owns. The fourth is the session's own word for
+    something nothing placed, which ADR-0027 admits as a descriptor and
+    nothing more: it may be carried, and it may never be an identity.
+    `__post_init__` is what makes that a property of the record rather than a
+    habit of today's two producers -- an `unplaced` party cannot be
+    constructed with an `identity`, so no later rule or serializer has to
+    remember not to give it one.
+
+    - `component` -- placed, one candidate, `identity` set. `name` is the BOM's.
+    - `ambiguous` -- several candidates could be it; `name` is the alias they
+      share, read off a candidate, and `identity` is `None` because choosing
+      between them is the re-grading correlation refuses to do. The candidates
+      are in `components`.
+    - `builtin` -- the agent's own tool, subagent or skill. Not installed, so
+      not a component, but its name is one of ours -- `join.py` matched it
+      against the closed set of what the kind ships -- and a stall on it is a
+      real finding.
+    - `unplaced` -- called, and absent from every composition. The mirror of
+      "installed but never invoked", and the case a responder most needs. Its
+      only name is the session's own word for it, and a finding that withholds
+      it says a credential left for *a mcp_server* and names nothing to rotate
+      (ADR-0027). So the word is carried, `identity` stays `None` so it can
+      resolve no lookup and join to no inventory, and a consumer must mark it
+      unverified.
+    """
+
+    kind: str
+    name: str
+    component_type: str | None = None
+    identity: str | None = None
+    #: `subject` for the finding's own anchor; `source` for a component whose
+    #: result carried the credential a later call sent on.
+    role: str = "subject"
+
+    def __post_init__(self) -> None:
+        if self.kind not in PARTICIPANT_KINDS:
+            raise ValueError(f"{self.kind!r} is not one of {PARTICIPANT_KINDS}")
+        if self.role not in PARTICIPANT_ROLES:
+            raise ValueError(f"{self.role!r} is not one of {PARTICIPANT_ROLES}")
+        # A name is not required of any kind: a placed component whose BOM
+        # entry omitted its own name reads as `""` out of `composition.py`,
+        # which is a gap in what a reader is told rather than a leak, and
+        # refusing it here would turn a thin BOM into a crash mid-run.
+        #
+        # `identity` is the machine-checkable form of "only a placed component
+        # may be resolved by name", and the rule ADR-0027 leans on: an
+        # unplaced name is a word one session used, so two machines calling
+        # unrelated servers `support` must never join. A component's own
+        # identity may be `None` -- not every BOM entry has a verified one --
+        # but no other kind may hold one.
+        if self.identity is not None and self.kind != "component":
+            raise ValueError(f"a {self.kind} participant has no verified identity to carry")
+
+
 @dataclass(frozen=True)
 class Detection:
     """One claim about one session.
@@ -179,6 +267,19 @@ class Detection:
     of components would name both ends, or every candidate either end implicates
     where the resolution was ambiguous — narrowing an ambiguous match to make a
     finding tidier would be the re-grading correlation refuses to do.
+
+    **What it means differs by rule, deliberately.** For `advisory-reach` the
+    component *is* the finding's subject: the advisory is about it. For a
+    behaviour rule — a stall, an egress, a scavenged credential — it is
+    context: the components the cited calls resolved to. Both are useful and
+    they are not the same claim, so a reader asking "what is this about"
+    should read the rule id first and this second.
+
+    A behaviour rule does not fill this itself; it never sees a composition
+    (`run.py`'s `_resolved_components` attaches it at the same seam as
+    coverage). So what appears here is only ever what the correlator already
+    committed to: a built-in names nothing, an ambiguous match names every
+    candidate and chooses none, and with no BOM at all this stays empty.
     """
 
     rule_id: str
@@ -187,6 +288,14 @@ class Detection:
     title: str
     session: SessionRef
     components: tuple[Component, ...] = ()
+    #: What this finding was about, named however well it is known -- so a
+    #: reader is never left with a dash where the name was in hand. Derived
+    #: from the anchor at the same seam as `components`, never by a rule.
+    subject: Participant | None = None
+    #: The other parties to the same trigger. Today one role: the `source`
+    #: whose result carried the credential a later call sent on, because a sink
+    #: alone says a secret left and not where it was got.
+    involved: tuple[Participant, ...] = ()
     observed_capabilities: tuple[str, ...] = ()
     evidence: tuple[Evidence, ...] = ()
     remediation: str = ""

stacktrace_cli/detector/render.py

@@ -23,7 +23,7 @@ _ORDER = {"high": 0, "medium": 1, "low": 2}
 def render_json(result: DetectorRun) -> str:
     return json.dumps(
         {
-            "detections": [_detection(d) for d in _sorted(result)],
+            "detections": [detection_json(d) for d in _sorted(result)],
             "unknowns": [
                 {
                     "session_id": u.session.session_id,
@@ -56,7 +56,13 @@ def render_json(result: DetectorRun) -> str:
     )
 
 
-def _detection(detection) -> dict[str, object]:
+def detection_json(detection) -> dict[str, object]:
+    """One detection as the published JSON object.
+
+    Named rather than private because it has a second consumer: `monitor`
+    renders the same finding on the local page, and a dict literal there would
+    be a second source for one fact (ADR-0024).
+    """
     verdict = detection.verdict
     return {
         "rule_id": detection.rule_id,
@@ -81,6 +87,12 @@ def _detection(detection) -> dict[str, object]:
             }
             for c in detection.components
         ],
+        # What the finding was about, and who else was party to it. Carried
+        # here as well as on the wire: `--format json` is a machine surface,
+        # and omitting it would make the local command and the upload disagree
+        # about the same run.
+        "subject": _participant_json(detection.subject),
+        "involved": [_participant_json(p) for p in detection.involved],
         "observed_capabilities": list(detection.observed_capabilities),
         # Kind and detail, never a value. See this module's docstring.
         "evidence": [
@@ -105,6 +117,45 @@ def _detection(detection) -> dict[str, object]:
     }
 
 
+def _participant_json(participant) -> dict[str, object] | None:
+    if participant is None:
+        return None
+    return {
+        "kind": participant.kind,
+        "role": participant.role,
+        "name": participant.name,
+        "component_type": participant.component_type,
+        "identity": participant.identity,
+    }
+
+
+#: How a subject that is not a placed component is marked, so a reader never
+#: takes one for inventory. `unplaced` is deliberately not "not installed": the
+#: session called it, so it was there when it ran -- what is missing is an
+#: entry for it in what the scan could see now.
+_QUALIFIERS = {
+    "builtin": " (built-in)",
+    "unplaced": " (not in inventory)",
+    "ambiguous": " (ambiguous)",
+}
+
+
+def _qualifier(kind: str) -> str:
+    return _QUALIFIERS.get(kind, "")
+
+
+def _named(participant) -> str:
+    """How a party to a finding reads on one line.
+
+    A party with no name at all -- a placed component whose BOM entry omitted
+    one -- is named by what it is instead: `a skill (not in inventory)`. The
+    bare qualifier on its own would say only that something was missing, which
+    is the dash this exists to replace.
+    """
+    name = participant.name or f"a {participant.component_type or 'component'}"
+    return f"{name}{_qualifier(participant.kind)}"
+
+
 def render_text(result: DetectorRun, detail: bool = False) -> str:
     """The summary. The per-detection trail only when asked for.
 
@@ -152,6 +203,15 @@ def render_text(result: DetectorRun, detail: bool = False) -> str:
             for component in detection.components:
                 version = f" {component.version}" if component.version else ""
                 lines.append(f"        component {component.name}{version}")
+            # Only where `components` said nothing. A placed subject is the
+            # same thing the line above already named, and printing both would
+            # read as two things being involved.
+            subject = detection.subject
+            if subject is not None and not detection.components:
+                lines.append(f"        on {_named(subject)}")
+            for participant in detection.involved:
+                if participant.role == "source":
+                    lines.append(f"        credential from {_named(participant)}")
             for evidence in detection.evidence:
                 lines.append(f"        {evidence.span}  {evidence.kind}: {evidence.detail}")
             if detection.remediation: