Skip to content

Add read-only native terminal diagnostic snapshot module - #1131

Merged
h0x91b merged 1 commit into
mainfrom
feat/dev3-native-terminal-diagnostics
Jul 25, 2026
Merged

Add read-only native terminal diagnostic snapshot module#1131
h0x91b merged 1 commit into
mainfrom
feat/dev3-native-terminal-diagnostics

Conversation

@h0x91b

@h0x91b h0x91b commented Jul 25, 2026

Copy link
Copy Markdown
Owner

Hi, this is Claude (the AI assistant working on this branch) 👋

Summary

Adds a standalone, read-only diagnostics module at src/bun/native-terminal-diagnostics/ — groundwork for HOST-009 on the tmux-removal roadmap (seq 1258). It has no product caller yet; tmux remains the production default and existing behavior is unchanged.

  • snapshot.tsbuildDiagnosticsSnapshot(input) shapes injected plain data (mapped from the registry's existing public read APIs: record + live StatusReply + ownership verdict, parser-queue getters, parser-state snapshot) into a versioned, JSON-safe snapshot. Every fact is either {known:true,value} or an explicit {known:false,reason} — unavailable facts are never invented.
  • format.ts — a compact, deterministic human-readable formatter over the same snapshot.
  • index.ts — barrel re-export.

Design decisions

  • Structural redaction (allowlist). The builder only reads the required facts (session/view ids, protocol/runtime/artifact versions, host/shell PIDs, lifecycle, writer presence, timestamps, bounded counters). It never touches the endpoint, bearer token, host executable, start signatures, shell command line, environment, or any parsed terminal output — so nothing in an ignored field can leak. Proven by tests.
  • Bounded counters. Non-finite/negative counters degrade to unknown rather than emitting Infinity/NaN, keeping the snapshot JSON-safe.
  • Standalone by contract. The module imports nothing from native-terminal-registry (its import-graph isolation test forbids outside references); it declares its own input types, deliberately structurally compatible with the registry's public shapes so a future caller can pass them straight through.
  • Injected clock. now/lastAttachAt are injected (no Date.now), so snapshots are reproducible and staleness math is pure.

Follow-up (recorded, intentionally not done here)

lastAttachAt is not available from any current public read API (the record has created/updated, StatusReply has the shell startedAt). The module accepts it as an optional input and reports unknown otherwise; populating it would require the registry/host to track an attach timestamp — out of scope for this isolated module.

Includes a changelog entry and decision record 164. 14 focused pure tests (healthy / stale / partial / missing / redacted, boundedness, deterministic ordering); full suite green.

Standalone pure module (src/bun/native-terminal-diagnostics/) that shapes
injected registry read-API data into a versioned, JSON-safe diagnostic
snapshot plus a compact human-readable formatter. Facts are known-or-unknown
with a reason; counters are bounded; endpoint/token/command/output are redacted
by construction (allowlist). No product caller yet — groundwork for HOST-009.
@h0x91b
h0x91b enabled auto-merge (squash) July 25, 2026 07:50
@h0x91b
h0x91b merged commit 6ecb39e into main Jul 25, 2026
9 checks passed
@h0x91b
h0x91b deleted the feat/dev3-native-terminal-diagnostics branch July 25, 2026 07:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant