Repository navigation
OpenTelemetry tracing for the CLI - #306
Closed
davidabram wants to merge 35 commits into
Closed
davidabram wants to merge 35 commits into
davidabram wants to merge 35 commits into
Conversation
Define the PR3 dead-code cleanup, reconciliation disposition gate, async simplification, blocking and future-size audits, and final validation workflow. Preserve the diff-trace compatibility surface while deferring ref reconciliation until an explicit decision is recorded. Plan: cli-async-persistence-cleanup-pr3 Tasks: T01, T02, T03, T04, T05, T06 Co-authored-by: SCE <sce@crocoder.dev>
Record the authoritative PR2 dead-code baseline, diagnostic counts, symbol-level classifications, and reconciliation dependency analysis completed for T01. Preserve the evidence and follow-up dispositions needed by the remaining cleanup tasks. Plan: cli-async-persistence-cleanup-pr3, T01 Co-authored-by: SCE <sce@crocoder.dev>
Delete the T02-classified unused CLI APIs, wrappers, fixtures, tests, and broad dead-code allowances while preserving live runtime behavior and retained compatibility surfaces. Refresh the affected service contracts and completion record with the resulting API and verification state. Plan: cli-async-persistence-cleanup-pr3 (T02) Co-authored-by: SCE <sce@crocoder.dev>
Add staged patch histories and expected trace documents for agent-trace reconstruction scenarios. Exercise file lifecycle, renames, mixed changes, and poem fixtures through shared golden-output assertions. Co-authored-by: SCE <sce@crocoder.dev>
The async-persistence cleanup keeps ref reconciliation available for future wiring without leaving a module-wide dead-code suppression. Scope allowances to the reconciliation dependency cluster and document the retained-but-unwired status, including orphaned pin accumulation; remove the unused worktree lock path. Plan: cli-async-persistence-cleanup-pr3, T03 Co-authored-by: SCE <sce@crocoder.dev>
Simplify post-async persistence code by deleting the unused synchronous retry variant and flattening forwarding async blocks in database migration and sync services. Retain the distinct cancelling and non-cancelling async retry semantics, and preserve the hand-rolled concurrent join behavior that protects in-flight completion and credential persistence. Update the glossary and resilience patterns to document the current retry API and record completion of T04 in the async persistence cleanup plan. Plan: cli-async-persistence-cleanup-pr3 (T04) Co-authored-by: SCE <sce@crocoder.dev>
Complete plan T05 by documenting the retained blocking sites, measured future sizes, recursion-limit decision, temporary-index cleanup limitation, and platform-specific guarded-shell descriptor race. The audit found no safe code reduction or sweeper protocol, so the known limitations and follow-up boundaries are recorded without changing CLI behavior. Ref: context/plans/cli-async-persistence-cleanup-pr3.md#t05 Co-authored-by: SCE <sce@crocoder.dev>
Document the completed post-migration cleanup audit, including removed dead code, retained declaration-level exceptions, measured diagnostic and LOC deltas, and Linux-only limitations. Update the related context map, overview, pattern guidance, and stale runtime-test references so the durable documentation matches the cleaned implementation. Record the completed T06 evidence and defer the full repository checks to the plan's final validation gate. Ref: context/plans/cli-async-persistence-cleanup-pr3.md#T06 Co-authored-by: SCE <sce@crocoder.dev>
Require the remote state response to include a valid diff-traces cursor, keep the zero-upload diff-traces stream in JSON reports, and verify that sync uploads only messages, parts, and agent traces. Generalize sync helpers over credential stores so these contracts can be exercised with deterministic control-plane fixtures. Ref: context/plans/cli-async-persistence-cleanup-pr3.md (AC1–AC12) Co-authored-by: SCE <sce@crocoder.dev>
Capture the fixed-stripe synchronization design, concurrency and fallback requirements, documentation updates, and validation work for bounded log-lock memory. Plan: observability-log-lock-striping Tasks: T01, T02, T03 Co-authored-by: SCE <sce@crocoder.dev>
Reduce lock-registry overhead by hashing log paths across a fixed set of static mutexes. Scope the primary lock so fallback writes occur only after it is released, while retaining retention cleanup and poisoned-lock behavior. Plan: observability-log-lock-striping, T01 Co-authored-by: SCE <sce@crocoder.dev>
Exercise the real log persistence paths under concurrent writers, independent logger instances, fallback failures, poisoned locks, retention, file permissions, and redaction. Isolate same-stripe fallback and lock poisoning in bounded child processes so regressions fail deterministically without contaminating shared test state. Replace the stripe-index truncating cast with a checked conversion for clippy without changing behavior. Plan: observability-log-lock-striping Task: T02 Co-authored-by: SCE <sce@crocoder.dev>
Document the fixed 64-stripe in-process locking model, fallback lock ordering, poisoning semantics, and absence of cross-process coordination. Record the completed acceptance criteria and validation evidence for the lock-striping work. Plan: observability-log-lock-striping (T03) Co-authored-by: SCE <sce@crocoder.dev>
Document how to make the existing mutation-cursor ref reconciler operational through shared mutation-scope maintenance and `sce doctor --fix`, including automatic throttling, safety constraints, tests, and context synchronization. Plan: mutation-cursor-ref-reconciliation-wiring (T01-T06) Co-authored-by: SCE <sce@crocoder.dev>
Document the verified lock ownership, production call graph, advisory-only hook design, durable maintenance-state rules, and database-opening constraints needed to implement mutation-cursor ref reconciliation safely. Cite the completed audit and its findings so the follow-up implementation tasks have explicit scope and evidence. Plan: mutation-cursor-ref-reconciliation-wiring, T01 Co-authored-by: SCE <sce@crocoder.dev>
Add explicit reconciliation and hook advisory entrypoints that share one held worktree lock, persist bounded maintenance state, and record successful and failed passes. Add verified-existing agent-trace DB opening so maintenance does not create or migrate databases, while preserving the existing deletion path. Plan: `mutation-cursor-ref-reconciliation-wiring.md` (T02) Co-authored-by: SCE <sce@crocoder.dev>
Ensure explicit reconciliation uses the production-resolved, verified read-only database and reports state-persistence diagnostics without losing reconciliation errors. Distinguish pre-rename failures from post-rename durability uncertainty, require confirmed writes for advisory results, and add deterministic coverage for open races, WAL coexistence, lock ownership, and persistence failures. Plan: mutation-cursor-ref-reconciliation-wiring (T02) Co-authored-by: SCE <sce@crocoder.dev>
…scopes Completed mutation-scope boundaries now run the advisory-only ref reconciliation check after coordination returns, while preserving hook results and avoiding reconciliation, Git, or database work on the hook path. The injected report is mapped to stable debug or warning logs, including durability and state failures, and is limited to Close and Flush boundaries. Ref: context/plans/mutation-cursor-ref-reconciliation-wiring.md (T03) Co-authored-by: SCE <sce@crocoder.dev>
Expose actionable reconciliation advisory outcomes through an injected diagnostic writer while retaining structured logging. Add outcome-specific diagnostics for durability and state-write failures, keep advisory delivery independent of mutation results, and cover the seven outcome shapes with focused tests. Ref: context/plans/mutation-cursor-ref-reconciliation-wiring.md (T03) Co-authored-by: SCE <sce@crocoder.dev>
Make `sce doctor --fix` execute one explicit snapshot-ref reconciliation pass and report typed outcomes, while plain `sce doctor` remains read-only and reports when maintenance is recommended. Add a runtime facade and injected seams to preserve doctor testability and expose counts, failure kinds, warnings, and busy results. Update the `mutation-cursor-ref-reconciliation-wiring` plan and related context for T04. Co-authored-by: SCE <sce@crocoder.dev>
Cover retention of durable roots across worktrees, fail-closed handling of malformed namespace refs, and advisory busy behavior while an explicit pass holds the lock. Parameterize the durable-root fixture so the production-path tests exercise foreign worktree roots without repairing missing pins. Plan: mutation-cursor-ref-reconciliation-wiring (T05) Co-authored-by: SCE <sce@crocoder.dev>
Add CLI, linked-worktree, cross-process, lock-contention, state-recovery, and cancellation tests for the ref reconciliation path, using narrow coordinator and snapshot seams to exercise real behavior without changing production semantics. Cover database verification and fail-closed behavior, durable state normalization and uncertain persistence, hook/advisory ordering, and doctor outcomes. Plan: mutation-cursor-ref-reconciliation-wiring.md (T05) T05 remains in progress for the explicitly recorded S9, S14, and S26 production-path gaps and guard-removal checks. Co-authored-by: SCE <sce@crocoder.dev>
Remove obsolete dead-code allowances now that snapshot-ref reconciliation runs through `sce doctor --fix`, keep only justified single-event loader exceptions, and make unreachable checkout-identity outcomes and test-only wrappers explicit. Synchronize the reconciliation, doctor, storage, and overview context with the single-lock maintenance entrypoint, verified-existing DB contract, advisory boundary, typed outcomes, and deferred cleanup limitations. Plan: `context/plans/mutation-cursor-ref-reconciliation-wiring.md` — T06 Co-authored-by: SCE <sce@crocoder.dev>
Expand doctor CLI coverage to assert successful exit status for reported reconciliation outcomes and to exercise recovery from failed, stale, invalid, corrupt, oversized, and unreadable maintenance state. Record the remediation evidence and completed coverage status for the reconciliation wiring plan. Plan: mutation-cursor-ref-reconciliation-wiring (T05) Co-authored-by: SCE <sce@crocoder.dev>
Preserve the persistence failure phase when advisory anchor or normalization writes complete replacement but cannot confirm directory durability. Render a durability-specific diagnostic for those outcomes, while retaining the existing write-failed wording for pre-rename failures and adding regression coverage for visible post-rename state. Update the reconciliation plan's T05 durability semantics and scenario coverage to match the outcome mapping. Plan: mutation-cursor-ref-reconciliation-wiring (T05) Co-authored-by: SCE <sce@crocoder.dev>
Add regression coverage proving that maintenance opening of a missing Agent Trace database returns the typed missing-database error without creating state-root entries. Mark the mutation-cursor reconciliation plan's acceptance criteria complete and record validation evidence for the completed implementation. Plan: mutation-cursor-ref-reconciliation-wiring Tasks: T05, T06 Co-authored-by: SCE <sce@crocoder.dev>
The doctor reconciliation CLI test sandbox assumed a `state` directory under the temporary home, but on macOS the CLI resolves its state root to `Library/Application Support`. Resolve the sandbox state root per platform so the tests locate the same Agent Trace database and maintenance state as the CLI under test. Co-authored-by: SCE <sce@crocoder.dev>
Consolidate redundant reconciliation, advisory, doctor, and maintenance-state tests into table-driven cases while strengthening assertions for exit statuses, ref inventories, pin preservation, typed failures, and read-only database behavior. Remove obsolete test-only lock-acquisition wrappers and align the CLI/context coverage documentation with the retained scenarios. Plan: mutation-cursor-ref-reconciliation-wiring Tasks: T05 Co-authored-by: SCE <sce@crocoder.dev>
davidabram
added this pull request to stack #302
October 9, 2026 10:11
Reintroduce opt-in OpenTelemetry tracing in five sequenced phases while first closing the existing unredacted tracing path. Define metadata-only export, bounded OTLP/HTTP delivery, W3C propagation, managed telemetry credentials, and instrumentation for critical operations without changing CLI durability or lock semantics. Plan: sce-opentelemetry-tracing Tasks: T01-T13 Co-authored-by: SCE <sce@crocoder.dev>
Tracing subscribers can observe raw event fields and error chains, so classify event IDs and typed operational values before they reach tracing while preserving the existing local log output. Add Boundary A and Boundary B policies, capture tests, and a source inventory that prevents new unclassified tracing fields or dynamic messages. Update the observability contract and telemetry plan with the boundary, hook-gate, and feature-enabled test constraints. Plan: sce-opentelemetry-tracing (T01, T03, T04, T05, T07, T09, T10, T11) Co-authored-by: SCE <sce@crocoder.dev>
Admit OTel attributes only through closed enums and route all SCE tracing through typed boundary emitters, preventing secret-like strings and unclassified values from reaching telemetry. Add a syn-based audit that rejects tracing bypasses and unsafe messages or fields, and update the observability contract and T01 completion evidence. Ref: plan sce-opentelemetry-tracing (T01) Co-authored-by: SCE <sce@crocoder.dev>
Keep telemetry disabled by default while enabling an environment-selected standalone OTLP/HTTP runtime for permitted commands. Resolve the mode from `SCE_TELEMETRY`, gate hooks through typed command classification, scope a private subscriber across every future poll, enforce the Boundary B exporter allowlist, and propagate the subscriber to the audited spawned task. Record the dependency, build-impact, and runtime contract details for the completed implementation. Plan: `context/plans/sce-opentelemetry-tracing.md` (T03) Co-authored-by: SCE <sce@crocoder.dev>
Ensure telemetry teardown cannot block command completion by moving provider shutdown to a detached thread with a bounded flush budget, while preserving command output and failure behavior. Add the feature-gated loopback test receiver, lifecycle markers, subprocess latency coverage, and lock-isolation tests for the controlled export path. Add counted default and feature-enabled test passes, packaged-binary exclusion checks, cargo test-count guard coverage, and the required Flatpak vendor sources. Update the observability contracts and record the completed implementation and measurements for T04. Ref: context/plans/sce-opentelemetry-tracing.md T04 Co-authored-by: SCE <sce@crocoder.dev>
Measure typed hook invocation latency across disabled, reachable, blackhole, and refused loopback receiver modes with the feature-enabled benchmark script and lifecycle markers. Record roughly 4-5 ms healthy/refused overhead and roughly 105 ms blackhole overhead at the candidate 100 ms budget, then select 100 ms as the candidate hook flush budget. Keep production hook export disabled pending shutdown testing at that budget, gate verification, and an explicit user-owned enablement policy. Add the reproducible benchmark script and context evidence, and update T05 in the `sce-opentelemetry-tracing` plan. Co-authored-by: SCE <sce@crocoder.dev>
Honor valid TRACEPARENT/TRACESTATE environment values when creating the `sce.command` span so subprocess telemetry preserves its remote trace relationship. Use SDK extraction with validation, apply the parent through OpenTelemetry, and fall back to an independent root for absent or malformed values while honoring unsampled parents. Add focused extraction and propagation coverage and update the observability contracts and completed plan task. Plan: `sce-opentelemetry-tracing` T06 Co-authored-by: SCE <sce@crocoder.dev>
davidabram
removed this pull request from stack #302
October 10, 2026 08:24
davidabram
force-pushed
the
ref-recon
branch
2 times, most recently
from
October 10, 2026 12:27
7240db3 to
51df9e4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.