Skip to content

feat(lane-transcripts): open a leg's sealed telemetry into the sink - #17403

Merged
kyle-sexton merged 3 commits into
mainfrom
feat/lane-transcripts-telemetry
Nov 19, 2026
Merged

kyle-sexton merged 3 commits into
mainfrom
feat/lane-transcripts-telemetry

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Refs: #17261

Summary

The transcript puller opens a leg's sealed telemetry and writes it, with its trace join, to the sink. This is the second half of #17261. #17400 opts the lane sweep into the sealed receiver and uploads otel.jsonl.gz.sealed beside the transcript, and the scheduled re-pin #17376 moved the pins to ci-workflows v0.76.3. Before this PR, the puller accepted that second sealed file and left it unopened (pull.mjs, EXTRA_SEALED).

Fix

  • pull.mjs. When an artifact's one extra entry is otel.jsonl.gz.sealed, the pull opens it under the payload name otel.jsonl.gz, with the transcript's run id and job id binding. It stores the file, gzipped, as <run id>-<attempt>-<job id>.otel.jsonl.gz beside the transcript (mode 0600). Telemetry that does not open, or does not decompress, is not stored, and the transcript is kept.

  • Row fields. Every pulled row gains these fields:

    • telemetry: the path, or null;
    • telemetry_outcome: stored, none, sealed_mismatch or unreadable;
    • telemetry_bytes;
    • telemetry_spans;
    • telemetry_joined_spans: the spans whose traceId is the row's trace_id.

    The last field is the trace join. run-claude-cli passes the CLI a TRACEPARENT under the lane-outcome trace id (ci-workflows#1136), so a row whose joined count equals its span count shows that every span joined its run attempt.

  • store.mjs.

    • telemetryPath and telemetrySpans are new.
    • prune maps telemetry files to their rows, so a 30-day or cap prune of a row's telemetry sets telemetry: null, and a missing telemetry file clears its path.
  • Docs. The lane-transcripts contract and the puller README list the new file and fields. The changes add fields only: the contract lets a writer add fields, and readers treat an unknown field as absent.

  • The transcript survives bad telemetry. These findings came from the security review. Telemetry that fails to extract from the zip, or decompresses past a 64 MiB cap of its own, is recorded as unreadable, and the transcript row is still written. This holds the 60 MiB that run-claude-cli's receiver keeps (otlp-receiver.cjs, MAX_TELEMETRY_BYTES). Spans are counted line by line, so a payload of nothing but newlines cannot build one huge array and abort the pull.

Telemetry text, like transcript text, reaches only the sink's files. Nothing prints it, and the metrics row holds counts, never content.

Verification

  • node --test --test-concurrency=4 scripts/lane-transcripts/pull.test.mjs: 60 tests, 60 passed, 0 failed. .github/actions/resolve-config/callers.test.mjs, which imports store.mjs: 290 tests, 290 passed, 0 failed. Five tests are new, and one existing test gained an assertion:
    • Telemetry whose extraction fails, or whose decompressed size is over 64 MiB, is unreadable, and its transcript row is kept.
    • Telemetry sealed beside the transcript is stored. It opens to the same bytes, and of 3 spans, the 2 carrying the trace id are counted, case-insensitively. Neither the logs nor the row hold the plaintext marker.
    • Telemetry sealed to another job, or under the transcript's payload name, is sealed_mismatch, and the transcript is kept. A transcript alone is none.
    • telemetrySpans skips a line that is not JSON.
    • Prune drops a row's telemetry with its aged transcript and clears the path of a missing telemetry file.
    • The existing extra-sealed-file test now asserts that an unopenable telemetry entry keeps the transcript row as sealed_mismatch.
  • Readers checked: the lane_runs DuckDB view (plugins/harness-ops/skills/observability/otel/lane-runs.sql) names its columns, so the new fields are ignored there. The contract says the session-flow reader treats an unknown field as absent.

Remaining

Related

🤖 Generated with Claude Code

kyle-sexton and others added 2 commits November 19, 2026 01:51
The puller opens otel.jsonl.gz.sealed, when an artifact carries it beside
the transcript, under the payload name otel.jsonl.gz with the transcript's
run and job binding, and stores it next to the transcript. The row gains
telemetry, telemetry_outcome, telemetry_bytes, telemetry_spans and
telemetry_joined_spans, the last counting the spans whose traceId is the
row's trace_id. Telemetry that does not open keeps the transcript. Prune
removes a row's telemetry with its transcript and clears a missing path.

Refs: #17261

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…be read

Telemetry that fails to extract from the zip, or decompresses past a
64 MiB cap of its own, is recorded as telemetry_outcome unreadable and the
transcript row is still written, so one bad telemetry entry no longer turns
the artifact into a fetch failure or aborts the pull. Spans are counted
line by line rather than through one split array.

Refs: #17261

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 19, 2026 07:04
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T07:06:42.799655Z 9813e9a Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed none (read lane)
Run 44476958519

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on 9813e9a5485a00dd022828a931e6b392477049f2; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 41ce1f0af989cb78aa274c8d35dc055fcf67eb33: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental, blocking only): PR #17403, 9813e9a5..41ce1f0a

I read every hunk of both files in scope: docs/contracts/lane-transcripts/README.md and scripts/lane-transcripts/pull.mjs. I also read the code the changed comment describes, openTelemetry at pull.mjs:401-417.

What changed. This push fixes my earlier finding (thread). Two places now define telemetry_outcome: unreadable as "it could not be extracted from the zip, or it opened but did not decompress within its cap":

The new wording matches the code:

  • Extraction failure: UNEXTRACTED returns unreadable at L403, before openRecord runs.
  • Decompression failure: a gunzipSync failure under maxOutputLength returns unreadable at L414-415.

So an unreadable row no longer suggests the seal check passed. The puller README (scripts/lane-transcripts/README.md:104) only lists the outcome names and has no definition that could disagree. No other copy of the definition is left with the old text.

Findings. None. The earlier thread is resolved, and this push fixes it.

Closing issue. The PR only says "Refs: #17261" and closes no issue, so there were no acceptance criteria to check.

Verification. I ran nothing. The test counts in the PR body are the author's claim and unverified.

Path-scoped rules. .claude/rules/cost-claims.md matches the contract README, and the change makes no cost claim.

Paved paths. No paved-path row applied.

Loosened checks. The wrapper gave no loosened_check_* lines, so I used fail with no consumer patterns and did not check the citation requirement. This push changes only comment and doc text, so nothing was loosened.

Loosened-check verdict: fail (default, no wrapper settings); patterns: 0

Spend. None; the change is doc and comment text only.

Verifier dropped 0 of 0 candidates.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 41ce1f0af989cb78aa274c8d35dc055fcf67eb33: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Security review (incremental, blocking only): no findings

This review covers only what changed since 9813e9a5485a00dd022828a931e6b392477049f2. I read both changed files in full in the incremental diff:

  • docs/contracts/lane-transcripts/README.md: one table row now defines telemetry_outcome: unreadable as "it could not be extracted from the zip, or it opened but did not decompress within its cap".
  • scripts/lane-transcripts/pull.mjs: only the JSDoc comment on openTelemetry changed, to the same wording. No executable code changed.

The new wording now says that unreadable does not mean the seal check passed. This closes the documentation gap raised in the settled thread on docs/contracts/lane-transcripts/README.md (resolved, owner reply, lines changed since resolution: no). The point is fixed, not raised again.

What I checked:

  • Trust controls: neither file matches a trusted-path glob, and the change touches no trust control, merge hold, token scope, plugin manifest or standing instruction.
  • Code: no logic in the telemetry open, store or prune paths changed. The earlier review of the full change still applies to them.
  • PR text: the pull request context has no text aimed at this review.

This review was blocking only, because this lane already reviewed an earlier head. No SUGGESTION findings were dropped.

No spend change.

critical-findings: 0

…on failure

A telemetry entry that unzip cannot extract also yields `unreadable`
without ever being opened, so the contract row and the openTelemetry
JSDoc now say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 0de6f7d Nov 19, 2026
104 of 107 checks passed
@kyle-sexton
kyle-sexton deleted the feat/lane-transcripts-telemetry branch November 19, 2026 08:47
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant