agent-tracegraph 0.6.1__tar.gz → 0.8.0__tar.gz

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/CHANGELOG.md

@@ -6,6 +6,117 @@ The **artifact** schema version and the **report**/**review-candidate** JSON sch
 separate contracts from this version number; changes to any of them are called out
 explicitly.
 
+## 0.8.0 - 2026-10-20
+
+### Changed
+
+- **`analyze` and the incident memo say when a causal parent was chosen heuristically** (#138).
+  Ingest records `otlp.graph_parent_by_timing` (a loop parent taken by start time or, since #136,
+  by start number) or `otlp.graph_parent_fallback` (a declared graph parent not honored, so the
+  span parent is used) in the artifact, and `check` and `summarize` read those codes, but
+  `analyze` and `export-incident-memo` did not, so a report or memo built from the artifact did
+  not say that a parent may have been chosen heuristically, and the memo wrote a graph parent
+  taken by start order as "caused by". `analyze` now adds a warning for each side that
+  carries either code, and the memo adds a fidelity disclosure. The record does not say which
+  edge was chosen that way, so in a trace with `otlp.graph_parent_by_timing` the memo writes every
+  `graph_parent` edge in its causal ancestry graph as "preceded by (graph parent, possibly chosen heuristically)" instead of
+  "caused by"; checkpoint parents and span links keep "caused by". Reports and memos of traces
+  without these codes are unchanged.
+
+- **`explain`, `query --explain` and `inspect` say when a causal parent was chosen heuristically**
+  (#140). They read the same two codes: `inspect` prints the caveat `analyze` uses under its
+  tree, and `explain` and `query --explain` under every chain with at least one cause (a root
+  step has no parent to qualify). In such a trace their fan-in note no longer says "multiple real
+  causes" or "trust this raw chain, not the tree"; it says the single-parent tree drops some
+  recorded causes and the raw chain lists every recorded ancestor, and the `query --explain` note
+  says "in this chain" rather than "in this match", since the step with several causes can be an
+  ancestor outside the match. Output for traces without these codes is unchanged. `analyze` still
+  classifies failures through a `graph_parent` edge as it did.
+
+- **A Phoenix loop parent is chosen by start numbers whose unit is unknown again** (#136). Since
+  0.7.0 a Phoenix time given as a number below 10^17 is reported as unavailable, and with it the
+  only evidence for choosing among several spans that carry the `graph.node.id` a span names as
+  its `graph.node.parent_id`. The span then fell back to its `parent_id`, or the export was
+  refused without one. Now, when that span and every candidate start at such a number, the
+  nearest preceding candidate by those numbers is taken. 0.6.1 also chose by them, read as
+  nanoseconds, but it dropped a float's fraction first, so with fractional seconds (`a` at
+  1783987200.25, `b` at 1783987200.75, the span at 1783987200.5) it took `b` where this release
+  takes `a`. The times themselves stay unavailable. The choice is counted under the existing
+  `otlp.graph_parent_by_timing` gap with its own warning line, which says it assumes the export
+  gives every time in one unit; `check` treats it as a heuristic edge, as it does a choice by
+  readable time. Exports with ISO or nanosecond times are read as before, and so is a set of
+  candidates where any one has a readable time, no start, or no number below the floor. The
+  0.7.0 example (spans `a` and `b` at 1783987200 and 1783987201, `c` at 1783987202 with no
+  `parent_id`) is accepted again with `b` as `c`'s parent. Where 0.7.0 fell back to the span's
+  `parent_id`, the parent taken now can differ, and so can what follows from it. Each case below
+  is a separate export built from that example, adding only what it names:
+  - The export can be refused if the new choice closes a causal cycle. Add a root span `r` at
+    1783987199 and give `c` the `parent_id` `r` and `b` the `parent_id` `c`: 0.7.0 kept `r` as
+    `c`'s parent and exited 0; this release takes `b`, so `ingest-phoenix` and `analyze` exit 2
+    and `phoenix diagnose` exits 1 (0.6.1 refused that export too).
+  - `analyze` can classify failures differently, because the edge is now a `graph_parent`, which
+    it reads as explicit ancestry (#142). Give `c` the `parent_id` `b` and let `b` and `c` fail:
+    0.7.0 reported both as primary failures; this release reports `b` as primary and `c` as
+    propagated.
+  - Step numbers can change. Add spans `x`, `y` (`parent_id` `x`) and `z` with no start time,
+    and give `b` the `parent_id` `y` and `c` the `parent_id` `z`: 0.7.0 numbered `c` 3 and `b` 5;
+    this release numbers `b` 4 and `c` 5.
+
+  Ties are still broken with these spans at time 0, so step order can also differ from 0.6.1.
+
+## 0.7.0 - 2026-10-20
+
+### Added
+
+- **`--redact-errors` on `ingest-otlp` and `ingest`** (#125) leaves error messages out of the
+  artifact. The OTLP and LangGraph adapters record the producer's error text by default
+  (`status.message` and exception events; the error channel's value and a raised exception's
+  `repr`), and `inspect` and `explain` print it; until now only Phoenix ingestion could drop it.
+  With the flag a failed step keeps its `error` status and lists `error_msg` in
+  `unknown_fields`, and nothing else in the artifact changes. A rule that reads the message
+  therefore treats it as unknown, not absent: `check --rule pattern-not-increased:timeout` reports
+  `INSUFFICIENT_EVIDENCE` for a redacted current run, and against a redacted baseline it can still
+  pass but not fail. Names are still recorded as given. The default is unchanged. In Python,
+  `LangGraphCheckpointAdapter` and `ingest_snapshot` take `include_error_messages=False`, as
+  `OTLPSpanAdapter` already did.
+
+### Changed
+
+- **`phoenix diagnose` exits 1, not 2, when `px` is unavailable or its answer cannot be used**
+  (#122). That covers a `px` that is missing or cannot run, fails, times out, prints too much,
+  prints output that is not UTF-8 or not valid JSON, reports no recognizable version or one
+  older than the supported floor, or returns an export tracegraph cannot read, and a project
+  with no traces. The command now
+  prints `FAIL <reason>` on stderr, as `phoenix doctor` does, instead of the usage banner.
+  `diagnose` used 2 for these, the same code as an invalid invocation, so a wrapper could not
+  tell "called wrong" from "Phoenix is not reachable". Some exports 0.6.1 accepted are now refused
+  as unreadable, so `diagnose` goes from 0 to 1 on them; see the Phoenix time fix below. 2 still
+  means invalid arguments or output paths, such as `--limit 0`, two outputs naming the same file,
+  or a destination that cannot be written. `doctor` is unchanged.
+
+### Fixed
+
+- **A Phoenix time given as a number too small to be epoch nanoseconds is no longer read as one**
+  (#124). The Phoenix adapter took every numeric `start_time` / `end_time` as nanoseconds, so a
+  time in seconds, milliseconds or microseconds became a moment near 1970, with its sub-unit
+  digits truncated and no warning: a 500 ms span given in float seconds was recorded at
+  `1970-01-01T00:00:01.783987+00:00` with a duration of 0.0. A number is now read as nanoseconds
+  only from 10^17 (1973-03-03T09:46:40Z) up. Below that, seconds, milliseconds and microseconds
+  for any date before the year 5138 cannot be told apart, so the time is reported as unavailable
+  and disclosed as `otlp.unreadable_timestamp`, the code an unreadable time already uses, which
+  0.6.x readers know. That applies to numbers, digit strings, and strings `int()` reads with a
+  sign, surrounding whitespace or underscores. ISO strings are read as before, including compact
+  forms such as `20260714_123456`, and so are nanosecond values. Phoenix's own `trace get` export
+  uses ISO strings, so artifacts change only for exports that carried such numbers.
+
+  For an export that carries such numbers, the step sequence, the parent chosen among several
+  spans sharing a `graph.node.id`, and whether the export is accepted at all can also differ from
+  0.6.1, which read the numbers as nanoseconds and ordered spans by them. For example, take spans
+  `a` and `b` with `graph.node.id` `loop`, starting at 1783987200 and 1783987201, and a span `c`
+  starting at 1783987202 with `graph.node.parent_id` `loop` and no `parent_id`. 0.6.1 took `b` as
+  `c`'s parent and exited 0; now `ingest-phoenix` and `analyze` exit 2 and `phoenix diagnose`
+  exits 1.
+
 ## 0.6.1 - 2026-10-20
 
 ### Dependencies

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.6.1
+Version: 0.8.0
 Summary: Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph.
 Project-URL: Homepage, https://github.com/memtomem/tracegraph
 Project-URL: Repository, https://github.com/memtomem/tracegraph
@@ -38,7 +38,7 @@ tracegraph ingests agent execution traces that already exist (LangGraph checkpoi
 Phoenix CLI exports, and OpenInference/OTLP spans) into a **normalized causal graph**,
 then runs analyses the mainstream observability tools don't:
 
-- **`explain`** — walk backward from a failure over the *raw* causal graph to every real cause.
+- **`explain`** — walk backward from a failure over the *raw* causal graph to every recorded cause.
 - **`diff`** — exact structural regression diff between two runs (rooted-tree / AHU isomorphism).
 - **cross-trace pattern matching** — e.g. "tool X → retry → tool X → failure" across all runs.
 
@@ -201,8 +201,9 @@ trace. If none failed, it says so and diagnoses the newest trace, so a first suc
 still useful. Explicit ids bypass that selection. The command invokes only read-only
 `px trace list/get --include-annotations` exports, analyzes them in memory, and does not persist
 the raw Phoenix response. Phoenix connection details and credentials remain owned by `px`
-profiles or environment variables; tracegraph never accepts an API key option. For an already
-exported file or a shell pipeline:
+profiles or environment variables; tracegraph never accepts an API key option. Both commands exit
+1 when `px` is missing, cannot run, or returns a response tracegraph cannot use, and 2 for
+invalid arguments or output paths. For an already exported file or a shell pipeline:
 
 Automatic retry diagnosis intentionally requires an upstream `retry:` CHAIN marker. SyncMill's
 controlled retry telemetry emits this contract; generic OTLP and LangGraph-checkpoint producers
@@ -220,6 +221,15 @@ Phoenix exports preserve span parents but currently do not expose the original O
 links. These artifacts are explicitly marked `causal_fidelity=parent_only`; tracegraph warns
 that additional fan-in causes may be missing instead of claiming a complete DAG.
 
+Phoenix's own export gives times as ISO strings. A time given as a number is read as epoch
+nanoseconds only from 10^17 up; a smaller one (seconds, milliseconds, a relative offset) is in
+a unit tracegraph cannot tell, so it is reported as unavailable and disclosed as
+`otlp.unreadable_timestamp`. Such numbers still order spans for one purpose: when several
+spans carry the `graph.node.id` that a span names as its `graph.node.parent_id`, and that span
+and every candidate start at such a number, the nearest preceding candidate by those numbers is
+the parent. That assumes the export gives every time in one unit, and it is disclosed under
+`otlp.graph_parent_by_timing` with its own warning line, so `check` treats the edge as heuristic.
+
 The exact Phoenix CLI and server versions used by CI are centrally pinned. See the
 [Phoenix runtime pin maintenance runbook](docs/phoenix-cli-contract.md) for the controlled
 upgrade and contract-verification procedure, and the
@@ -237,8 +247,11 @@ identifiers, and credentials. Missing metrics are reported as `unavailable`, nev
 (identifier-shaped span names only, error messages dropped), but the OTLP and LangGraph
 adapters record the span name and error text they were given: OTLP keeps `status.message`
 and exception messages, and LangGraph stringifies the configured error state channel. Those
-values reach the artifact on disk and are printed verbatim by `inspect` and `explain`. If
-your producer puts prompt text or secrets in span names or error strings, treat artifacts
+values reach the artifact on disk and are printed verbatim by `inspect` and `explain`.
+`ingest-otlp --redact-errors` and `ingest --redact-errors` leave the error text out: a failed
+step keeps its `error` status and lists `error_msg` in `unknown_fields`, so a rule that reads
+the message (the `timeout` preset) reports it as unknown rather than absent. Names are still
+recorded as given. If your producer puts prompt text or secrets in span names, treat artifacts
 from those two adapters as sensitive, or ingest through Phoenix. See "Analysis and output
 guarantees" below.
 
@@ -253,14 +266,16 @@ tracegraph analyze full-dag.json
 ```
 
 `analyze` reads an OTLP span export (JSON or Collector JSONL) directly, with the same adapter
-settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact;
+settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact
+(one ingested with `--redact-errors` can differ where a rule reads the message);
 nothing is written unless `--json-out` asks for a report. The input is identified by shape alone
 (`schema_version` → artifact, `resourceSpans` → OTLP, `spans`/`traces`/`data` → Phoenix); a
 payload carrying both OTLP and Phoenix records is refused, naming the explicit ingest command
 for each format (or, for a list, JSONL or envelope, asking you to extract one format's records). Already have an export? The shortest offline first run is
 `tracegraph analyze your-export.otlp.json` (add `--trace <id>` when the file holds several), then
 copy the `explain` command it prints after saving the artifact it names. The artifact caveat
-above still applies: `ingest-otlp` keeps error text, reports stay `safe-v1`.
+above still applies: `ingest-otlp` keeps error text unless given `--redact-errors`, and
+reports stay `safe-v1`.
 
 The JSON analysis-report contract is versioned at
 [`contracts/analysis-report.schema.json`](contracts/analysis-report.schema.json).
@@ -391,7 +406,7 @@ Known limits:
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
-  producer's names and error messages.
+  producer's names, and its error messages unless ingested with `--redact-errors`.
 - CI covers Python 3.12 on Linux.
 
 Caveat for the checkpoint adapter: it is a **checkpoint-level** view (one node per
@@ -437,7 +452,8 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+error message (`--redact-errors` on `ingest` and `ingest-otlp` drops the message, not the
+name). Phoenix ingestion is the exception: it filters at the source, keeping span
 names and annotation names and labels only when they are identifier-shaped, and dropping
 status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`
@@ -449,6 +465,14 @@ origins, fidelity disclosures, and the digest of the exact artifact bytes. Logic
 comparison keys are JSON-encoded typed paths; consumers should treat them as opaque strings.
 Containment and unknown edges preserve all error investigation candidates, deeper first.
 Explicit causal ancestry supplies context, not proof that an exception propagated.
+When the artifact records that a causal parent was chosen heuristically at ingest
+(`otlp.graph_parent_by_timing` or `otlp.graph_parent_fallback`), `analyze` adds a warning for
+that side and the memo a fidelity disclosure. The record does not say which edge, so a memo of
+a trace with `otlp.graph_parent_by_timing` writes every `graph_parent` edge as "preceded by
+(graph parent, possibly chosen heuristically)" instead of "caused by". `inspect` prints the
+same caveat under its tree, and `explain` and `query --explain` under every chain that has at
+least one cause; there their fan-in note no longer calls the causes real or says to trust the
+chain.
 Explicit OTLP OK takes precedence over handled exception events on new ingestion; old
 artifacts are not reinterpreted.
 A span whose status is UNSET and that carries no exception event (one with a message or

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/README.md

@@ -7,7 +7,7 @@ tracegraph ingests agent execution traces that already exist (LangGraph checkpoi
 Phoenix CLI exports, and OpenInference/OTLP spans) into a **normalized causal graph**,
 then runs analyses the mainstream observability tools don't:
 
-- **`explain`** — walk backward from a failure over the *raw* causal graph to every real cause.
+- **`explain`** — walk backward from a failure over the *raw* causal graph to every recorded cause.
 - **`diff`** — exact structural regression diff between two runs (rooted-tree / AHU isomorphism).
 - **cross-trace pattern matching** — e.g. "tool X → retry → tool X → failure" across all runs.
 
@@ -170,8 +170,9 @@ trace. If none failed, it says so and diagnoses the newest trace, so a first suc
 still useful. Explicit ids bypass that selection. The command invokes only read-only
 `px trace list/get --include-annotations` exports, analyzes them in memory, and does not persist
 the raw Phoenix response. Phoenix connection details and credentials remain owned by `px`
-profiles or environment variables; tracegraph never accepts an API key option. For an already
-exported file or a shell pipeline:
+profiles or environment variables; tracegraph never accepts an API key option. Both commands exit
+1 when `px` is missing, cannot run, or returns a response tracegraph cannot use, and 2 for
+invalid arguments or output paths. For an already exported file or a shell pipeline:
 
 Automatic retry diagnosis intentionally requires an upstream `retry:` CHAIN marker. SyncMill's
 controlled retry telemetry emits this contract; generic OTLP and LangGraph-checkpoint producers
@@ -189,6 +190,15 @@ Phoenix exports preserve span parents but currently do not expose the original O
 links. These artifacts are explicitly marked `causal_fidelity=parent_only`; tracegraph warns
 that additional fan-in causes may be missing instead of claiming a complete DAG.
 
+Phoenix's own export gives times as ISO strings. A time given as a number is read as epoch
+nanoseconds only from 10^17 up; a smaller one (seconds, milliseconds, a relative offset) is in
+a unit tracegraph cannot tell, so it is reported as unavailable and disclosed as
+`otlp.unreadable_timestamp`. Such numbers still order spans for one purpose: when several
+spans carry the `graph.node.id` that a span names as its `graph.node.parent_id`, and that span
+and every candidate start at such a number, the nearest preceding candidate by those numbers is
+the parent. That assumes the export gives every time in one unit, and it is disclosed under
+`otlp.graph_parent_by_timing` with its own warning line, so `check` treats the edge as heuristic.
+
 The exact Phoenix CLI and server versions used by CI are centrally pinned. See the
 [Phoenix runtime pin maintenance runbook](docs/phoenix-cli-contract.md) for the controlled
 upgrade and contract-verification procedure, and the
@@ -206,8 +216,11 @@ identifiers, and credentials. Missing metrics are reported as `unavailable`, nev
 (identifier-shaped span names only, error messages dropped), but the OTLP and LangGraph
 adapters record the span name and error text they were given: OTLP keeps `status.message`
 and exception messages, and LangGraph stringifies the configured error state channel. Those
-values reach the artifact on disk and are printed verbatim by `inspect` and `explain`. If
-your producer puts prompt text or secrets in span names or error strings, treat artifacts
+values reach the artifact on disk and are printed verbatim by `inspect` and `explain`.
+`ingest-otlp --redact-errors` and `ingest --redact-errors` leave the error text out: a failed
+step keeps its `error` status and lists `error_msg` in `unknown_fields`, so a rule that reads
+the message (the `timeout` preset) reports it as unknown rather than absent. Names are still
+recorded as given. If your producer puts prompt text or secrets in span names, treat artifacts
 from those two adapters as sensitive, or ingest through Phoenix. See "Analysis and output
 guarantees" below.
 
@@ -222,14 +235,16 @@ tracegraph analyze full-dag.json
 ```
 
 `analyze` reads an OTLP span export (JSON or Collector JSONL) directly, with the same adapter
-settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact;
+settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact
+(one ingested with `--redact-errors` can differ where a rule reads the message);
 nothing is written unless `--json-out` asks for a report. The input is identified by shape alone
 (`schema_version` → artifact, `resourceSpans` → OTLP, `spans`/`traces`/`data` → Phoenix); a
 payload carrying both OTLP and Phoenix records is refused, naming the explicit ingest command
 for each format (or, for a list, JSONL or envelope, asking you to extract one format's records). Already have an export? The shortest offline first run is
 `tracegraph analyze your-export.otlp.json` (add `--trace <id>` when the file holds several), then
 copy the `explain` command it prints after saving the artifact it names. The artifact caveat
-above still applies: `ingest-otlp` keeps error text, reports stay `safe-v1`.
+above still applies: `ingest-otlp` keeps error text unless given `--redact-errors`, and
+reports stay `safe-v1`.
 
 The JSON analysis-report contract is versioned at
 [`contracts/analysis-report.schema.json`](contracts/analysis-report.schema.json).
@@ -360,7 +375,7 @@ Known limits:
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
-  producer's names and error messages.
+  producer's names, and its error messages unless ingested with `--redact-errors`.
 - CI covers Python 3.12 on Linux.
 
 Caveat for the checkpoint adapter: it is a **checkpoint-level** view (one node per
@@ -406,7 +421,8 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+error message (`--redact-errors` on `ingest` and `ingest-otlp` drops the message, not the
+name). Phoenix ingestion is the exception: it filters at the source, keeping span
 names and annotation names and labels only when they are identifier-shaped, and dropping
 status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`
@@ -418,6 +434,14 @@ origins, fidelity disclosures, and the digest of the exact artifact bytes. Logic
 comparison keys are JSON-encoded typed paths; consumers should treat them as opaque strings.
 Containment and unknown edges preserve all error investigation candidates, deeper first.
 Explicit causal ancestry supplies context, not proof that an exception propagated.
+When the artifact records that a causal parent was chosen heuristically at ingest
+(`otlp.graph_parent_by_timing` or `otlp.graph_parent_fallback`), `analyze` adds a warning for
+that side and the memo a fidelity disclosure. The record does not say which edge, so a memo of
+a trace with `otlp.graph_parent_by_timing` writes every `graph_parent` edge as "preceded by
+(graph parent, possibly chosen heuristically)" instead of "caused by". `inspect` prints the
+same caveat under its tree, and `explain` and `query --explain` under every chain that has at
+least one cause; there their fan-in note no longer calls the causes real or says to trust the
+chain.
 Explicit OTLP OK takes precedence over handled exception events on new ingestion; old
 artifacts are not reinterpreted.
 A span whose status is UNSET and that carries no exception event (one with a message or

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/SECURITY.md

@@ -42,19 +42,23 @@ prompts, inputs and outputs, tool arguments and results, raw errors and stacktra
 session/user/project identifiers. Other display text is replaced with a deterministic
 SHA-256 alias, and the report discloses in `warnings` when an alias actually reached it.
 
-The artifact on disk is a different thing. Phoenix ingestion filters at the source, but the
-OTLP and LangGraph adapters record what they were given:
+The artifact on disk is a different thing. Phoenix ingestion filters at the source, but by
+default the OTLP and LangGraph adapters record what they were given:
 
 - OTLP keeps `status.message` and exception messages;
 - LangGraph stringifies the configured error state channel, **and** the `repr` of an
   exception a node raised, which it reads from checkpoint pending writes.
 
-Those values reach the artifact and are printed verbatim by `inspect` and `explain`.
+Those values reach the artifact and are printed verbatim by `inspect` and `explain`, unless
+the trace is ingested with `--redact-errors` (`ingest-otlp` and `ingest` both take it), which
+leaves every error message out and marks it unknown on the step. Span and node names are
+recorded as given either way.
 `export-review-candidates` is likewise not passed through the report redactor: its
 `tool_key` is the raw endpoint span name.
 
 **So: if your producer puts prompt text, customer data, or credentials into span names or
-exception messages, those land in the artifact.** Treat artifacts with the same care as the
+exception messages, those land in the artifact** — the messages only when ingested without
+`--redact-errors`, the names always. Treat artifacts with the same care as the
 traces they came from. Reports, not artifacts, are the artifact you share.
 
 Identifiers are not anonymized in either form — trace and step ids are preserved by design,
@@ -64,12 +68,16 @@ because they are what makes a finding traceable back to the run.
 
 Artifact and span-export loading is a parsing boundary, not a trust boundary: input is
 validated, never executed. Malformed input raises a clean error rather than a traceback, and
-tree walks are iterative so a deeply nested document cannot exhaust the stack. **CLI inputs**,
-files named on the command line and `-` for stdin alike, are size-capped by default at 256 MiB
-(`TRACEGRAPH_MAX_ARTIFACT_BYTES` changes it, and `0` disables it). That cap is a property of
-the command-line entry points, not of the library: `artifact.load()` and
-`OTLPSpanAdapter.from_file()` read what they are given, so a library caller handling untrusted
-input should bound it themselves. Still, analyzing an artifact you did not produce means reading
+tree walks are iterative so a deeply nested document cannot exhaust the stack. **CLI JSON
+inputs** (artifacts and span exports), files named on the command line and `-` for stdin
+alike, are size-capped by default at 256 MiB (`TRACEGRAPH_MAX_ARTIFACT_BYTES` changes it, and
+`0` disables it). A LangGraph checkpoint database (`ingest --sqlite`) is not byte-capped: it
+is copied to a private snapshot under a deadline (30 seconds by default) before it is read.
+The cap is a property of the command-line entry points, not of the library:
+`artifact.load()`, `OTLPSpanAdapter.from_file()`, `PhoenixExportAdapter.from_file()`, and
+`InMemoryStore.load_artifact()` and `LadybugStore.load_artifact()` (which call
+`artifact.load()`) read what they are given, so a library caller handling untrusted input
+should bound it themselves. Still, analyzing an artifact you did not produce means reading
 strings an attacker may have chosen; render them as data.
 
 Subprocess use is limited to one call site, the Phoenix CLI (`px`), invoked as an argument

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # the schema `kind` constants and the TRACEGRAPH_* environment variables — those are package
 # identity, not distribution identity, and renaming them would break published contracts.
 name = "agent-tracegraph"
-version = "0.6.1"
+version = "0.8.0"
 description = "Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph."
 readme = "README.md"
 requires-python = ">=3.12"

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/adapters/langgraph_checkpoint.py

@@ -209,6 +209,7 @@ class LangGraphCheckpointAdapter:
         error_channel: str = "error",
         source_kind: str = "langgraph",
         schedule_graph: Any = None,
+        include_error_messages: bool = True,
     ) -> None:
         self._saver = saver
         self._error_channel = error_channel
@@ -216,6 +217,9 @@ class LangGraphCheckpointAdapter:
         #: A compiled LangGraph graph to ask which tasks are scheduled at the head; see the
         #: module docstring. ``None`` leaves scheduled-but-unwritten tasks unreported.
         self._schedule_graph = schedule_graph
+        #: Off, a failed step keeps its ERROR status but not the error channel's value or the
+        #: exception text, and lists ``error_msg`` as unknown, as OTLP's option of that name does.
+        self._include_error_messages = include_error_messages
 
     # --- TraceAdapter ---
 
@@ -388,14 +392,18 @@ class LangGraphCheckpointAdapter:
                 rewritten_errors += self._rewrote_error(checkpoints[step_id], history)
             if err is not None:
                 step.status = StepStatus.ERROR
-                step.error_msg = err
+                if self._include_error_messages:
+                    step.error_msg = err
+                else:
+                    step.unknown_fields.insert(0, "error_msg")  # sorts before kind and name
 
         # Derived task steps come last: everything above indexes `steps` by checkpoint id
         # (`checkpoints[step_id]`, `key_by_step_id[step_id]`), and a derived id has no entry
         # in either. Building them here also means they inherit each carrying step's *final*
         # seq, after `_topo_seq` may have re-sequenced the whole thread.
         disclosures = self._derive_task_steps(
-            trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges
+            trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges,
+            include_error_messages=self._include_error_messages,
         )
         disclosures.extend(
             self._derive_interrupt_steps(
@@ -463,6 +471,8 @@ class LangGraphCheckpointAdapter:
         original_seq: dict[str, int],
         writes_by_step: dict[str, dict[str, list[tuple[str, Any]]]],
         edges: list[Edge],
+        *,
+        include_error_messages: bool,
     ) -> Disclosures:
         """Add one ERROR step per failed task and return any ingestion disclosures.
 
@@ -506,8 +516,9 @@ class LangGraphCheckpointAdapter:
                         "in LangGraph's task-id algorithm would look like.",
                     )
                 unknown: list[UnknownField] = [] if name else ["kind", "name"]
-                if error is None and not cancelled:
-                    # _error_message's placeholder: the checkpointer kept no exception text.
+                if (error is None or not include_error_messages) and not cancelled:
+                    # _error_message's placeholder (the checkpointer kept no exception text),
+                    # or a message withheld on request.
                     unknown.insert(0, "error_msg")
                 derived_id = f"{step_id}#task:{task_id}"
                 if derived_id in steps or derived_id in derived_ids:
@@ -533,7 +544,7 @@ class LangGraphCheckpointAdapter:
                         # without claiming it failed, and leaves the trace status to the task
                         # that actually raised.
                         status=StepStatus.UNSET if cancelled else StepStatus.ERROR,
-                        error_msg=None if cancelled else message,
+                        error_msg=None if cancelled or not include_error_messages else message,
                         unknown_fields=unknown,
                     ),
                 ))

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/adapters/otlp_spans.py

@@ -376,11 +376,16 @@ class OTLPSpanAdapter:
         causal_fidelity: CausalFidelity | None = None,
         links_preserved: bool | None = None,
         evaluation_channel: str | None = None,
+        start_order_channel: str | None = None,
     ) -> None:
         self._doc = document
         #: Span key carrying pre-sanitized evaluation summaries. Only an adapter that builds
         #: the span dicts itself (Phoenix) sets it; raw OTLP input never supplies evaluations.
         self._evaluation_channel = evaluation_channel
+        #: Span key carrying a start time whose unit is unknown, as a plain number that orders
+        #: spans within one export. Only Phoenix sets it, for a number below the epoch-nanosecond
+        #: floor; the time itself stays unavailable.
+        self._start_order_channel = start_order_channel
         self._source_kind = source_kind
         #: Prefer ``graph.node.parent_id`` (logical agent graph) over ``parentSpanId``.
         self._prefer_graph_parent = prefer_graph_parent
@@ -423,6 +428,7 @@ class OTLPSpanAdapter:
 
     @classmethod
     def from_file(cls, path: str | Path, **kwargs: Any) -> "OTLPSpanAdapter":
+        """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
         return cls.from_json(Path(path).read_text(encoding="utf-8"), **kwargs)
 
     # --- TraceAdapter ---
@@ -461,8 +467,18 @@ class OTLPSpanAdapter:
             for sid, span in by_id.items()
             if _parse_nanos(_first(span, "startTimeUnixNano", "start_time_unix_nano")) is None
         }
+        # A unit-unknown start number orders spans that all carry one, with prerank's
+        # tiebreaks; it says nothing about how they relate to a span with a readable time.
+        channel = self._start_order_channel
+        order_key = {
+            sid: (value, depth[sid], sid)
+            for sid, span in by_id.items()
+            if channel is not None and (value := span.get(channel)) is not None
+        }
         disclosures = Disclosures()
-        causes, origins = self._causes(by_id, attrs, prerank, parent_span, untimed, disclosures)
+        causes, origins = self._causes(
+            by_id, attrs, prerank, parent_span, untimed, order_key, disclosures
+        )
         seq = self._topo_seq(by_id, causes, prerank)
 
         steps: list[Step] = []
@@ -724,6 +740,7 @@ class OTLPSpanAdapter:
         prerank: dict[str, int],
         parent_span: dict[str, str | None],
         untimed: set[str],
+        order_key: dict[str, tuple[Any, int, str]],
         disclosures: Disclosures,
     ) -> tuple[dict[str, list[str]], dict[tuple[str, str], EdgeOrigin]]:
         """Reconstruct ``effect -> [causes]`` from declared signals: one parent + links.
@@ -751,12 +768,13 @@ class OTLPSpanAdapter:
             causes[effect].append(cause)
             origins[(effect, cause)] = origin
 
-        by_timing = fallback = 0
+        by_timing = by_order = fallback = 0
         for sid in by_id:
             parent, parent_origin, resolution = self._resolve_parent(
-                sid, attrs, node_index, prerank, parent_span, untimed
+                sid, attrs, node_index, prerank, parent_span, untimed, order_key
             )
             by_timing += resolution == "by_timing"
+            by_order += resolution == "by_order"
             fallback += resolution == "fallback"
             if parent is not None:
                 add(sid, parent, parent_origin)
@@ -788,6 +806,16 @@ class OTLPSpanAdapter:
                 "the nearest preceding one by start time was taken as the parent.",
                 by_timing,
             )
+        if by_order:
+            # Same code as by_timing: a heuristic choice among candidates, which readers since
+            # 0.6 already treat as one.
+            disclosures.add(
+                "otlp.graph_parent_by_timing",
+                f"{by_order} span(s) declare a graph.node.parent_id that several spans carry; "
+                "the nearest preceding one was taken by start-time numbers whose unit is "
+                "unknown, assuming the export gives every time in one unit.",
+                by_order,
+            )
         if fallback:
             disclosures.add(
                 "otlp.graph_parent_fallback",
@@ -825,6 +853,7 @@ class OTLPSpanAdapter:
         prerank: dict[str, int],
         parent_span: dict[str, str | None],
         untimed: set[str],
+        order_key: dict[str, tuple[Any, int, str]],
     ) -> tuple[str | None, EdgeOrigin, str | None]:
         """The single chosen parent cause: the logical graph parent if resolvable, else the
         declared span parent.
@@ -834,7 +863,8 @@ class OTLPSpanAdapter:
 
         * a single span carries that ``graph.node.id`` → trust it outright (unambiguous);
         * several do (a loop) → pick the nearest *preceding* execution, but only when this
-          span and every candidate have a readable start time; otherwise there is no
+          span and every candidate have a readable start time, or else all carry a
+          unit-unknown start number (``order_key``) to compare; otherwise there is no
           evidence of order and the parent is ambiguous.
 
         If ``graph.node.parent_id`` is declared but resolves to no in-trace span, or is
@@ -845,7 +875,7 @@ class OTLPSpanAdapter:
         ``None`` only when the span truly has no declared parent of either kind.
 
         The third value says how a declared logical parent was resolved when that was not
-        unambiguous: ``"by_timing"`` or ``"fallback"``; otherwise ``None``.
+        unambiguous: ``"by_timing"``, ``"by_order"`` or ``"fallback"``; otherwise ``None``.
         """
         pid = parent_span.get(sid)
         if self._prefer_graph_parent:
@@ -858,6 +888,10 @@ class OTLPSpanAdapter:
                 preceding = [c for c in candidates if timed and prerank[c] < prerank[sid]]
                 if preceding:
                     return max(preceding, key=lambda c: prerank[c]), EdgeOrigin.GRAPH_PARENT, "by_timing"
+                ordered = not timed and all(s in order_key for s in (sid, *candidates))
+                preceding = [c for c in candidates if ordered and order_key[c] < order_key[sid]]
+                if preceding:
+                    return max(preceding, key=lambda c: order_key[c]), EdgeOrigin.GRAPH_PARENT, "by_order"
                 if pid is None:
                     detail = "no in-trace span" if not candidates else "multiple ambiguous spans"
                     raise ValueError(

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/adapters/phoenix_export.py

@@ -9,7 +9,13 @@ import re
 from typing import Any
 
 from tracegraph.adapters.base import Disclosures
-from tracegraph.adapters.otlp_spans import OTLPSpanAdapter, _attributes, _first, _span_array
+from tracegraph.adapters.otlp_spans import (
+    OTLPSpanAdapter,
+    _attributes,
+    _first,
+    _parse_nanos,
+    _span_array,
+)
 from tracegraph.input_validation import loads, object_field
 from tracegraph.model import RawTrace
 
@@ -30,27 +36,81 @@ _SAFE_ATTRIBUTES = {
 }
 
 
+#: The smallest number read as epoch nanoseconds: 1973-03-03T09:46:40Z. Seconds, milliseconds and
+#: microseconds for any date before the year 5138 all fall below it, so a smaller number is in
+#: some other unit, and which one cannot be told from its size.
+_MIN_EPOCH_NANOS = 10**17
+#: Handed on for a number below the floor. ``int()`` cannot read it, so the span builder reports
+#: the time as unavailable and counts it under ``otlp.unreadable_timestamp``. It is fixed text, so
+#: no producer code (a ``__repr__``) runs, and only the parsed time ever reaches the artifact.
+_NOT_EPOCH_NANOS = "not epoch nanoseconds"
+
+
+def _epoch_nanos(number: int) -> str:
+    return str(number) if number >= _MIN_EPOCH_NANOS else _NOT_EPOCH_NANOS
+
+
 def _nanos(value: Any) -> Any:
-    """Phoenix's time to OTLP nanoseconds. A value that cannot be converted is passed on
-    unchanged, so the span builder reports it as unavailable *and* discloses it."""
+    """Phoenix's time to OTLP nanoseconds. A value that cannot be converted, or a number too
+    small to be epoch nanoseconds, is handed on in a form the span builder cannot read, so it
+    reports the time as unavailable *and* discloses it."""
     if value is None:
         return None
     if isinstance(value, float) and not math.isfinite(value):
         return value
     if isinstance(value, (int, float)):
-        return str(int(value))
+        return _epoch_nanos(int(value))
     text = str(value)
     if text.isdigit():
-        return text
+        try:
+            return _epoch_nanos(int(text))
+        except ValueError:  # a non-ASCII digit, or past the interpreter's int-string limit
+            return text
     try:
         parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
     except ValueError:
-        return value
+        # Whatever the span builder would still read as a time (a sign, whitespace, underscores,
+        # bytes) is a number, so the floor applies to it too. Asking the builder's own parser
+        # keeps the two from disagreeing about what is a number.
+        number = _parse_nanos(value)
+        return value if number is None else _epoch_nanos(number)
     if parsed.tzinfo is None:
         parsed = parsed.replace(tzinfo=timezone.utc)
     return str(int(parsed.timestamp() * 1_000_000_000))
 
 
+def _start_order(value: Any) -> int | float | None:
+    """A start time below the epoch-nanosecond floor, as the number it is, or ``None``.
+
+    Its unit is unknown, so it is no time, but within one export it still orders spans: the
+    span builder uses it only to choose among several candidate loop parents, and discloses
+    that it did. It follows ``_nanos``'s branches, so an ISO string (a compact one such as
+    ``20260714_123456`` included) never reaches the number path. A bool or bytes value is not
+    taken as a number here, although ``_nanos`` refuses those as times too.
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, float):
+        return value if math.isfinite(value) and int(value) < _MIN_EPOCH_NANOS else None
+    if isinstance(value, int):
+        return value if value < _MIN_EPOCH_NANOS else None
+    if not isinstance(value, str):
+        return None
+    number: int | None
+    if value.isdigit():
+        try:
+            number = int(value)
+        except ValueError:  # a non-ASCII digit, or past the interpreter's int-string limit
+            return None
+    else:
+        try:
+            datetime.fromisoformat(value.replace("Z", "+00:00"))
+            return None
+        except ValueError:
+            number = _parse_nanos(value)
+    return number if number is not None and number < _MIN_EPOCH_NANOS else None
+
+
 _OPERATION_NAME = re.compile(r"[A-Za-z0-9_.:/#@-]{1,200}")
 
 
@@ -151,6 +211,7 @@ class PhoenixExportAdapter:
 
     @classmethod
     def from_file(cls, path: str | Path) -> "PhoenixExportAdapter":
+        """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
         return cls.from_json(Path(path).read_text(encoding="utf-8"))
 
     def discover(self) -> list[str]:
@@ -173,6 +234,7 @@ class PhoenixExportAdapter:
             include_error_messages=False,
             preserve_unset_status=True,
             evaluation_channel="_tracegraph_evaluations",
+            start_order_channel="_tracegraph_start_order",
         ).ingest(trace_id)
         if unreadable_scores:
             disclosures = Disclosures()
@@ -228,4 +290,5 @@ class PhoenixExportAdapter:
             "attributes": _attrs(span),
             "events": _span_array(span, "events"),
             "_tracegraph_evaluations": _evaluations(span),
+            "_tracegraph_start_order": _start_order(_first(span, "start_time", "startTime")),
         }

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/check.py

@@ -34,6 +34,7 @@ from tracegraph.analysis.diagnose import _ALIAS, _digest, _display_name, _safe
 from tracegraph.analysis.patterns import PRESETS, PathPattern, StepPredicate, build_index, find_matches
 from tracegraph.model import (
     CAPTURE_GAP_CODES,
+    HEURISTIC_EDGE_GAP_CODES,
     NormalizedTrace,
     Step,
     StepStatus,
@@ -66,7 +67,7 @@ _MAY_OMIT_STEPS = frozenset({
 #: is unaffected, so only the count rules read this set.
 _REWRITTEN_ERRORS = frozenset({"langgraph.rewritten_error_channel"})
 _MAY_HIDE_FAILURES = _MAY_OMIT_STEPS | _REWRITTEN_ERRORS
-_HEURISTIC_EDGES = frozenset({"otlp.graph_parent_by_timing", "otlp.graph_parent_fallback"})
+_HEURISTIC_EDGES = HEURISTIC_EDGE_GAP_CODES
 
 LANGGRAPH_LIMITATION = (
     "LangGraph checkpoint layouts this adapter does not recognize record no failure, so a "

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/diagnose.py

@@ -29,6 +29,7 @@ from tracegraph.model import (
     EXPLICIT_ORIGINS,
     MAX_COST_CHARS,
     CausalFidelity,
+    HEURISTIC_EDGE_GAP_CODES,
     EdgeType,
     NormalizedTrace,
     Step,
@@ -54,6 +55,16 @@ LANGGRAPH_FIDELITY_WARNING = (
 LINKS_PRESERVED_FIDELITY_WARNING = (
     "Link preservation covers valid in-trace links only; foreign or unresolved links are omitted."
 )
+HEURISTIC_PARENT_FIDELITY_WARNING = (
+    "Some causal parents were chosen heuristically at ingest, by start order or by falling back "
+    "to the span parent; a chain through them is inferred, not declared."
+)
+
+
+def has_heuristic_edges(nt: NormalizedTrace) -> bool:
+    """Whether the trace's capture record discloses a causal parent chosen heuristically."""
+    capture = nt.trace.capture
+    return capture is not None and any(gap.code in HEURISTIC_EDGE_GAP_CODES for gap in capture.gaps)
 
 
 def _clause(sentence: str) -> str:
@@ -677,6 +688,8 @@ def analyze(nt: NormalizedTrace, *, baseline: NormalizedTrace | None = None) ->
         if trace.trace.links_preserved:
             # Mid-sentence after the label, so the shared sentence starts in lower case here.
             warnings.append(f"{label}: {_clause(LINKS_PRESERVED_FIDELITY_WARNING)}")
+        if has_heuristic_edges(trace):
+            warnings.append(f"{label}: {_clause(HEURISTIC_PARENT_FIDELITY_WARNING)}")
     if primary or propagated:
         warnings.append(INCIDENT_FIDELITY_WARNING)
     if any(getattr(metrics, field) is not None for field in ("prompt_tokens", "completion_tokens", "total_tokens", "total_cost")):

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/analysis/memo.py

@@ -7,10 +7,12 @@ from pathlib import Path
 
 from tracegraph._atomic_write import write_text_atomic
 from tracegraph.analysis.diagnose import (
+    HEURISTIC_PARENT_FIDELITY_WARNING,
     INCIDENT_FIDELITY_WARNING,
     LANGGRAPH_FIDELITY_WARNING,
     LINKS_PRESERVED_FIDELITY_WARNING,
     PARENT_ONLY_FIDELITY_WARNING,
+    has_heuristic_edges,
     pattern_findings,
 )
 from tracegraph.model import (
@@ -43,7 +45,11 @@ def _format_origin(origin: EdgeOrigin | None) -> str:
     return f"origin: {origin.value}"
 
 
-def _relation_phrase(origin: EdgeOrigin | None) -> str:
+def _relation_phrase(origin: EdgeOrigin | None, *, timed_graph_parents: bool) -> str:
+    # The capture record says a graph parent was chosen by start order somewhere in the trace,
+    # not which one, so no graph-parent edge there is presented as a declared cause.
+    if origin is EdgeOrigin.GRAPH_PARENT and timed_graph_parents:
+        return "preceded by (graph parent, possibly chosen heuristically)"
     if origin in EXPLICIT_ORIGINS:
         return "caused by"
     if origin is EdgeOrigin.SPAN_PARENT_FALLBACK:
@@ -161,12 +167,16 @@ def build_incident_memo(
             if edge.src in reachable_step_ids
         ]
 
+        capture = nt.trace.capture
+        timed_graph_parents = capture is not None and any(
+            gap.code == "otlp.graph_parent_by_timing" for gap in capture.gaps
+        )
         if ancestry_edges:
             lines.append("### Causal Ancestry Graph")
             for edge in ancestry_edges:
                 eff_alias = alias_by_id[edge.src]
                 cause_alias = alias_by_id[edge.dst]
-                rel = _relation_phrase(edge.origin)
+                rel = _relation_phrase(edge.origin, timed_graph_parents=timed_graph_parents)
                 origin_str = f" [{_format_origin(edge.origin)}]"
                 lines.append(f"- `{eff_alias}` {rel} `{cause_alias}`{origin_str}")
             lines.append("")
@@ -182,6 +192,8 @@ def build_incident_memo(
         disclosures.append(LANGGRAPH_FIDELITY_WARNING)
     if nt.trace.links_preserved:
         disclosures.append(LINKS_PRESERVED_FIDELITY_WARNING)
+    if has_heuristic_edges(nt):
+        disclosures.append(HEURISTIC_PARENT_FIDELITY_WARNING)
 
     lines.append("## Fidelity Disclosures")
     for d in disclosures:

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/artifact.py

@@ -243,6 +243,7 @@ def save_atomic(nt: NormalizedTrace, path: str | Path, *, replace: bool = True)
 
 
 def load(path: str | Path) -> NormalizedTrace:
+    """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
     return loads(Path(path).read_text(encoding="utf-8"))
 
 

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/cli.py

@@ -33,7 +33,8 @@ from tracegraph import artifact
 from tracegraph.input_validation import loads as load_json
 from tracegraph.analysis import PRESETS
 from tracegraph.analysis import check as regression_check
-from tracegraph.analysis.diagnose import AnalysisReport
+from tracegraph.analysis.diagnose import HEURISTIC_PARENT_FIDELITY_WARNING, AnalysisReport
+from tracegraph.analysis.diagnose import has_heuristic_edges
 from tracegraph.analysis.diagnose import analyze as build_analysis
 from tracegraph.analysis.diagnose import save_atomic as save_analysis_report
 from tracegraph.analysis import motifs
@@ -1278,6 +1279,16 @@ def _render_tree(nt: NormalizedTrace) -> None:
         f"\n[dim]{len(nt.steps)} steps · {n_tool} tool · "
         f"{n_err} error · {n_lossy} lossy-projection{paused}{scheduled}[/]"
     )
+    # The tree projects CAUSED_BY, so a heuristic parent can place a step whether or not
+    # any step is lossy.
+    if has_heuristic_edges(nt):
+        console.print(f"[yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
+
+
+_REDACT_ERRORS_HELP = (
+    "Leave error messages out of the artifact: a failed step keeps its error status and "
+    "lists its message as unknown. Step names are still recorded as given."
+)
 
 
 @app.command()
@@ -1300,14 +1311,18 @@ def ingest(
             "module, and the graph's state callbacks while reading; never a node."
         ),
     ),
+    redact_errors: bool = typer.Option(False, "--redact-errors", help=_REDACT_ERRORS_HELP),
 ) -> None:
     """Ingest a LangGraph thread's checkpoint history into a portable artifact."""
     from tracegraph.sqlite_snapshot import ingest_snapshot
 
     target = out or artifact.default_path(thread)
     _distinct_paths([sqlite], [target])
-    # Passed only when given, so an ingest without --graph makes exactly the call it always has.
+    # Passed only when given, so an ingest without --graph or --redact-errors makes exactly the
+    # call it always has.
     extra: dict[str, Any] = {}
+    if redact_errors:
+        extra["include_error_messages"] = False
     if graph is not None:
         from tracegraph.graph_ref import load_graph
 
@@ -1328,6 +1343,7 @@ def ingest_otlp(
     file: str = typer.Option(..., "--file", "-f", help="OTLP JSON/JSONL span export (resourceSpans), or '-' for stdin."),
     trace: str = typer.Option(None, "--trace", "-t", help="traceId to ingest (default: the file's only trace)."),
     out: Path = typer.Option(None, "--out", "-o", help="Artifact path (default <traceId>.json)."),
+    redact_errors: bool = typer.Option(False, "--redact-errors", help=_REDACT_ERRORS_HELP),
 ) -> None:
     """Ingest one trace from an OpenInference/OTLP span export into a portable artifact."""
     from tracegraph.adapters import OTLPSpanAdapter
@@ -1336,7 +1352,9 @@ def ingest_otlp(
         # Bounded read through the common size-limited boundary (from_file would
         # read_text the whole file with no ceiling). KeyError joins the usual load
         # errors: the adapter raises it for an unknown/missing trace id.
-        adapter = OTLPSpanAdapter.from_json(_read_source(file))
+        adapter = OTLPSpanAdapter.from_json(
+            _read_source(file), include_error_messages=not redact_errors
+        )
         trace = _select_trace(adapter, trace, what="file")
         nt = _normalize_read(adapter.ingest(trace))
     except (*_LOAD_ERRORS, KeyError) as exc:
@@ -1511,7 +1529,10 @@ def phoenix_diagnose(
                 )
         baseline_nt = _px_trace(baseline, project=project) if baseline else None
     except _PxError as exc:
-        raise typer.BadParameter(str(exc)) from exc
+        # Phoenix or `px` is unavailable or answered unusably: report it as `doctor` does
+        # (exit 1), keeping 2 for an invalid invocation.
+        err_console.print(f"[bold red]FAIL[/] {escape(str(exc))}")
+        raise typer.Exit(1) from exc
     report = build_analysis(nt, baseline=baseline_nt)
     _render_analysis(report, limit=limit)
     if save_artifact:
@@ -1610,7 +1631,9 @@ def explain(
     """Trace a step's raw causal chain back toward its root cause."""
     store = _store_from_artifact(artifact_path, backend)
     try:
-        steps = store.trace().steps_by_id()
+        trace = store.trace()
+        steps = trace.steps_by_id()
+        heuristic = has_heuristic_edges(trace)
         # An exact full-id match always wins — even when that id is also a *suffix* of a longer
         # namespaced id (e.g. "abc" vs "ns:abc"). Only fall back to suffix matching when the
         # input isn't itself a full step id, so a valid id is never rejected as "ambiguous".
@@ -1635,11 +1658,20 @@ def explain(
     for s in result.chain:
         flag = " [yellow]⚠ projection-lossy[/]" if s.projection_lossy else ""
         console.print(f"  ← {escape(s.name or s.kind.value)} (step {s.seq}){flag}")
-    if result.is_lossy:
+    # Where the capture record says a parent may have been chosen heuristically, the chain is
+    # not called real or trustworthy; elsewhere the wording is unchanged.
+    if result.is_lossy and heuristic:
+        console.print(
+            "\n[yellow]Some steps had more than one recorded cause; the single-parent tree view "
+            "drops some of them, and this raw chain lists every recorded ancestor.[/]"
+        )
+    elif result.is_lossy:
         console.print(
             "\n[yellow]Some steps had multiple real causes; the single-parent tree view "
             "is lossy for them — trust this raw chain, not the tree.[/]"
         )
+    if heuristic and result.chain:
+        console.print(f"\n[yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
 
 
 @app.command()
@@ -1770,16 +1802,26 @@ def query(
                     # Same fallback label as `tracegraph explain` and the tree renderers.
                     console.print(f"    ← {escape(s.name or s.kind.value)} (step {s.seq}){flag}")
                 # Causal-honesty signal: when the matched effect (or anything in the chain)
-                # has more than one real cause, the single-parent tree projection dropped
+                # has more than one recorded cause, the single-parent tree projection dropped
                 # at least one. `tracegraph explain` surfaces this same warning — `query
                 # --explain` must too, or a fan-in effect's lossiness becomes invisible
                 # (target lossiness doesn't show up in the per-step ⚠ flags above, since
                 # we only flag chain ancestors there).
-                if result.is_lossy:
+                # A lossy step can be an ancestor outside the matched path, hence "chain".
+                heuristic = has_heuristic_edges(traces_by_id[m.trace_id])
+                if result.is_lossy and heuristic:
+                    console.print(
+                        "    [yellow]⚠ some steps in this chain had more than one recorded cause — "
+                        "the single-parent tree drops some of them; this raw chain lists every "
+                        "recorded ancestor.[/]"
+                    )
+                elif result.is_lossy:
                     console.print(
                         "    [yellow]⚠ some steps in this match had multiple real causes — "
                         "trust this raw chain, not the tree.[/]"
                     )
+                if heuristic and result.chain:
+                    console.print(f"    [yellow]⚠ {HEURISTIC_PARENT_FIDELITY_WARNING}[/]")
 
         n_traces = len({m.trace_id for m in matches})
         suffix = f" — truncated from {total}" if truncated else ""

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/model.py

@@ -284,6 +284,10 @@ CAPTURE_GAP_CODES = frozenset(
         "phoenix.unreadable_evaluation_score",
     }
 )
+#: The gaps that say a causal parent was chosen heuristically at ingest: among several spans by
+#: start order, or by falling back to the span parent. ``check``, ``summarize``, ``analyze`` and the
+#: incident memo read this set.
+HEURISTIC_EDGE_GAP_CODES = frozenset({"otlp.graph_parent_by_timing", "otlp.graph_parent_fallback"})
 
 
 class CaptureGap(BaseModel):

{agent_tracegraph-0.6.1 → agent_tracegraph-0.8.0}/src/tracegraph/sqlite_snapshot.py

@@ -36,7 +36,13 @@ def _inert_serde():
 
 
 def ingest_snapshot(
-    source: Path, thread: str, *, error_channel: str, timeout: float = 30, graph: Any = None
+    source: Path,
+    thread: str,
+    *,
+    error_channel: str,
+    timeout: float = 30,
+    graph: Any = None,
+    include_error_messages: bool = True,
 ) -> RawTrace:
     from langgraph.checkpoint.sqlite import SqliteSaver
 
@@ -64,7 +70,10 @@ def ingest_snapshot(
             with closing(sqlite3.connect(str(snapshot), check_same_thread=False)) as conn:
                 saver = SqliteSaver(conn, serde=_inert_serde())
                 return LangGraphCheckpointAdapter(
-                    saver, error_channel=error_channel, schedule_graph=graph
+                    saver,
+                    error_channel=error_channel,
+                    schedule_graph=graph,
+                    include_error_messages=include_error_messages,
                 ).ingest(thread)
     except sqlite3.Error as exc:
         raise ValueError("cannot read SQLite checkpoint snapshot") from exc