Sync Issue Traceability#

When decant sync ingests session transcripts, parse failures and cross-message linkage anomalies are recorded as ingest issues. The traceability system connects those issues back to the affected sessions — surfacing them in the CLI via a health recommendation, exposing them through the REST API, and rendering badges in the UI.

Issue Codes#

Five issue codes are defined in src/model.ts:

Each session summary exposes two derived counts: ingest_issue_count (actionable, unparsed_line only) and informational_ingest_issue_count (sensors) 1.

Detection Layers#

Issues are detected at two points during ingest:

1. Parse-time — JSON failures in per-source parsers produce unparsed_line records stored directly in ParsedSession.issues.
2. Post-parse linkage — src/diagnostics.ts scans cross-message tool references and emits orphan_tool_result, duplicate_tool_use_id, and duplicate_tool_result codes.

All results land in the ingest_issue table, keyed by source_path (the transcript file path), not by session ID. Sessions are joined to their issues via this path column.

API Endpoint: GET /api/sessions/:id/issues#

The endpoint is registered in src/server.ts and delegates to sessionIngestIssues() in src/query.ts.

Response: an array of SessionIngestIssue objects:

{ code, line_no, error, raw_line, created_at }

• Returns [] if the session has no source file or no issues.
• Returns a session_not_found error envelope when the session ID is unknown.
• raw_line is included for local debugging but is never logged server-side.

CLI Hints#

decant sync --json includes issues (total count) and issues_by_code (per-code breakdown) in its output 2. When issues > 0, the JSON output also includes issues_hint, a shell command string for inspecting affected sessions. This is the recommended way to get a machine-readable snapshot immediately after a sync.

Stderr hint — when issues are detected and output is not in JSON mode, decant sync prints a hint to stderr showing how to filter decant ls --json output with jq to find sessions with ingest issues:

inspect affected sessions with: decant --db '/path/to/db' ls --json | jq '[.[] | select(.ingest_issue_count + .informational_ingest_issue_count > 0)]' (issue detail: GET /api/sessions/:id/issues under `decant serve`)

The hint includes:

• The --db flag if DECANT_DB is set or --db was passed (omitted when using the default archive)
• A jq filter selecting sessions where ingest_issue_count + informational_ingest_issue_count > 0
• A reference to the GET /api/sessions/:id/issues endpoint under decant serve for detailed issue information

The database path is shell-quoted (via shellQuote()) to handle special characters safely, so the hint remains copy-pasteable even when the archive lives under a directory with a space in it.

Health recommendation — when diagnostics exceed a threshold across recent sessions, the recommendations engine in src/recommendations.ts emits a signal:

"N recent sessions ingested with diagnostics"

The detail explains what percentage of the last 30 days' sessions carry issues, and the suggestion directs users to file an issue with decant sync --json output. The count is computed via a SQL join on session → ingest_issue (excluding unparsed_line from the informational tally):

SELECT COUNT(DISTINCT s.id) AS affected
FROM session s JOIN ingest_issue ii ON ii.source_path = s.source_path
WHERE <30-day window> AND <visible sessions> AND ii.code != 'unparsed_line'

Surface this recommendation with decant recommendations ls.

UI#

Session detail views display an ingest issue badge rendered by src/ui/ingest-issues.ts. Unknown record type summaries are grouped and shown inline, letting users see format-drift signals without leaving the session view.

Key Files#