ADR-002: PTY Cassette Transport for Harness Golden Masters

Context

Current-State Research

This decision was re-reviewed against local and current external terminal-agent managers on 2026-04-20.

The current ecosystem trend for human multi-agent operation is tmux. That is not the right baseline for Fizeau. Fizeau needs a reusable direct PTY library because cassettes need raw bytes, structured service events, deterministic replay, credential-free playback, and process cleanup without depending on global tmux server state. tmux evidence is useful for understanding common TUI failure modes, but it must not be part of the core harness capability story.

Decision

Fizeau will own direct PTY lifecycle in-process using Go os/exec plus a small reusable PTY library. That library includes cassette recording and playback as a first-class layer; recording/replay is not a separate harness helper bolted on beside the PTY code. tmux is not part of the core harness execution, model-list probing, quota probing, cassette recording, cassette replay, cancellation, or inspection design.

Existing tmux quota helpers are legacy experiments. They can remain only as temporary diagnostics while direct PTY replacements are being built, and their results do not promote a capability to final supported status. Any capability that can only be proven through tmux is gap until direct PTY evidence exists.

If a future operator project wants tmux attach/switch UX, it must live outside the core service/cassette path and consume Fizeau outputs like any other client. The Fizeau baseline is direct PTY only.

SPIKE-002 clarified the only acceptable success criteria for this area: Fizeau must control Claude/Codex well enough to extract TUI-only quota, available-model, reasoning-level, and related status facts; and it must replay cassettes well enough that client-side parsers and terminal assertions run without live Claude/Codex binaries, credentials, or network. Per-run token usage remains a core capability, but it should stay on native stream or batch JSON evidence unless a future harness path makes it TUI-derived. tmux’s human attachability is useful operator UX, but it is not in the current baseline and is not the accepted replay or capability-evidence path.

The baseline live process is a small background probe, not a general terminal control plane. It may periodically start Claude, Codex, or another harness, drive the minimum TUI flow required to read quota/status/model/reasoning facts, write a scrubbed snapshot/cache, and exit. If a harness’s batch prompt mode later stops working for normal execution, the same PTY wrapper may be promoted to drive an interactive session, but that is a future fallback decision rather than the first implementation target.

The cassette recorder and player remain part of internal/pty for the baseline implementation, subject to the build-vs-buy gate in ADR-004. The project will adopt PTY, terminal-emulator, and recording concepts where existing libraries fit. If reuse appears later, extract the mature PTY library as a whole rather than splitting cassette playback from session and terminal modeling prematurely.

Key Points: Direct PTY only | tmux helpers are legacy diagnostics | cassettes are versioned evidence artifacts

Module Boundaries

The direct PTY work must land as a reusable terminal library with narrow package boundaries. Harness-specific code consumes the library; it does not live inside it.

No package below internal/pty may import internal/harnesses. The PTY library must be testable with synthetic programs and ordinary Unix TUIs before Claude or Codex are involved. Claude and Codex quota/model probes are acceptance tests for the harness adapters, not proof that the PTY library is complete by themselves. The terminal rendering decision is detailed in ADR-003. The build-vs-buy boundary and extraction triggers are detailed in ADR-004. The terminal rendering decision is supported by the top spike in SPIKE-001. The recorder/driver build-vs-buy pressure test is captured in SPIKE-002.

Data Flow

The cassette layer observes the PTY library; it does not replace or wrap harness-specific parsing.

internal/pty/session raw bytes and input events
  -> internal/pty/terminal frame derivation and screen normalization
  -> internal/harnesses/<name> adapter parsing and service-event emission
  -> internal/pty/cassette CassetteTee writes raw output, timed input, frames,
     opaque service-event JSON, final metadata, and scrub reports

internal/pty/cassette may store and replay opaque service-event JSON, but it must not import harness adapters or CONTRACT-003 typed-event decoders. Service assertions stay above the cassette library. Harness adapters hand timed opaque events to the cassette layer through a narrow CassetteTee-style interface so the dependency direction stays internal/harnesses/<name> -> internal/pty, never the reverse.

Cassette Data Contract

Every cassette is a single versioned directory or archive with a manifest and append-only event streams. Version 1 contains:

Because the child process runs under a PTY, stdout and stderr are normally merged by the terminal slave and recorded together in output.raw. If a future harness exposes a separate non-PTY stderr stream, that stream must either be normalized into service events or added as an explicit optional artifact; it must not be silently dropped.

Timing is event-driven. The recorder writes a monotonic seq and monotonic t_ms timestamp on every observed input event, raw output chunk, resize, signal, derived frame, service event, and final event. Fixed-interval frame sampling is optional and derived; it is not the authoritative recording model. This keeps recordings compact while preserving the exact timeline needed to test terminal emulation, buffering, delays, and interactions.

Timestamps are stored as monotonic milliseconds from cassette start, quantized to manifest.timing.resolution_ms. Version 1 uses resolution_ms: 100 by default so replay preserves the shape of a real TUI session without pretending to be nanosecond-accurate. Recorders may use a finer capture resolution in version 1 when a TUI or test needs it; replay mode remains orthogonal to capture resolution. Replay supports three timing modes:

• realtime: sleep according to recorded t_ms values at the recorded resolution; this is the default for human inspection and visual playback.
• scaled: multiply recorded delays by a caller-provided factor while preserving event order and relative pacing.
• collapsed: ignore sleeps and replay in event order for fast deterministic CI assertions.

Replay must preserve event order, raw output chunk boundaries, resize ordering, process exit, final service metadata, and the recorded timing relation within one timestamp resolution. Terminal emulator tests replay output.jsonl at full speed under a virtual clock, so assertions run at the same logical place in the timeline without waiting on wall-clock sleeps.

Event order is authoritative by seq, not by t_ms alone. Multiple events may share the same quantized timestamp. Replay and assertion evaluation must process same-t_ms events in ascending seq order. seq is global across all cassette streams, assigned at observation time, and must be contiguous after merge. If a reader needs a deterministic merge for older diagnostic artifacts that lack seq, the fallback ordering is resize/signal, input, output chunk, derived frame, service event, final; accepted version-1 cassettes must not rely on that fallback.

Nondeterministic terminal content normalization is separate from secret scrubbing. Scrubbing removes sensitive values. Normalization handles volatile screen facts such as clocks, PIDs, elapsed durations, and animation counters so semantic frame assertions remain stable without weakening raw evidence storage.

Default scrubbing and normalization rules are part of the cassette contract. Version 1 starts with: explicit environment allowlist, HOME and worktree path rewriting, bearer/API token patterns, account identifiers where configured, UUID/request/session identifiers, RFC3339 and local timestamp values, elapsed durations, PIDs, transient socket/file names, and animation counters. Harness adapters may register extension rules, but the scrub report must list every rule applied and every intentionally preserved volatile field.

Schema Evolution

Version 1 readers reject cassettes with a manifest.version higher than the reader supports, missing required artifacts, missing required fields, or unknown required feature flags. Readers may ignore unknown optional fields within the same major version. Additive optional fields do not require a schema bump; renaming, removing, or changing the meaning of required fields requires a new major version. Writers stamp the supported manifest.version and refuse to overwrite a cassette written with a newer major version.

Recorders must compute timing from a monotonic elapsed clock such as time.Since(recordingStart) or an injected monotonic test clock. They must not derive t_ms from wall-clock timestamps after serialization. Tests must cover a wall-clock jump during recording without changing monotonic event order.

Record Mode

Record mode runs the real harness binary through the direct PTY transport. It fails before writing a cassette when:

• the harness binary is missing or not executable;
• authentication is missing, expired, or for the wrong account;
• subscription or quota state cannot be confirmed for subscription harnesses;
• requested model, reasoning, permission, or workdir capability is unsupported by the harness capability matrix;
• the run exits before producing a final service event.

If a failure happens after cassette creation starts, the recorder writes an explicit failed-run artifact only under a diagnostic path, never as accepted golden-master evidence.

Replay mode is parallel-safe. Record mode is not assumed to be parallel-safe for authenticated harnesses. Recorders must serialize per harness account and fail fast on lock contention rather than running two Claude or Codex record jobs against the same credential, quota window, or session store.

Accepted authenticated cassettes must carry freshness metadata sufficient for the capability matrix: captured_at, harness binary version, auth/account class, and any freshness window used for a supported claim. Stale cassettes remain useful parser fixtures, but they cannot promote or retain live capability support without a documented refresh policy.

Replay Mode

Replay mode never uses credentials and never contacts a provider. It feeds the recorded input/output/frame streams through the same parser, service-event decoder, and typed drain assertions used by live mode. Replay can prove parser, event-shape, timing behavior, cancellation, cleanup, and PTY transport behavior; it cannot prove that a live external harness still works today.

output.raw plus output.jsonl is the authoritative replay input for terminal emulator assertions. frames.jsonl is stored for human review, debugging, and fast smoke checks, but correctness assertions that validate terminal rendering must be able to re-derive frames from output.raw/output.jsonl through the manifest-pinned emulator. When the emulator backend or version changes, the reader must either reject stale frame-derived assertions with a clear emulator mismatch or require cassette re-recording/regeneration.

Replay is deterministic by default:

• CI uses collapsed timing unless a test explicitly asks for realtime or scaled playback;
• environment is reconstructed only from the cassette allowlist;
• terminal size and resize events come from manifest.terminal;
• service-event assertions compare typed payloads after documented scrub rules, not raw secrets or machine-specific paths.

Realtime and scaled replay exist to validate the cassette replay scheduler: given a recorded event sequence and timestamp resolution, the scheduler must emit events in seq order, sleep according to recorded deltas within one resolution tick for realtime, multiply deltas by the requested factor for scaled, and avoid wall-clock sleeps in collapsed mode while preserving the same logical t_ms positions for assertions.

Automated Cassette Assertion Framework

All PTY/cassette acceptance tests must be automated. Manual inspection is useful for debugging, but it is never a promotion gate for supported capability status. The default go test ./... path must run replay-only tests that are credential-free, provider-free, parallel-safe, and fast. Live record mode and Docker conformance mode may be opt-in because they need binaries, credentials, or containers, but when enabled they must still run without human keystrokes or manual TUI observation.

The project will build a test-only cassette assertion framework on top of internal/pty/session, internal/pty/terminal, and internal/pty/cassette. That framework owns:

• scenario definitions that name the cassette, terminal size, replay mode, fixture driver, environment policy, expected artifacts, and expected manifest.id/manifest.content_digest values;
• time-coded assertions over frames, raw output chunks, input events, resize events, service events, final metadata, exit status, and timing gaps;
• a virtual clock for collapsed replay so time-coded tests run quickly while preserving recorded event order;
• realtime and scaled replay modes for tests that explicitly validate scheduler behavior;
• parallel fixture isolation: read-only cassette inputs, per-test temp dirs, per-test HOME/config roots for record mode, no global tmux/session state, unique artifact output paths, and deterministic cleanup;
• structured failure reports that include the failed assertion, nearest frame timestamps, relevant screen excerpts, and service-event context.

Assertion specs must bind to the cassette they were authored against by manifest.id and content digest. CI must fail when an assertion file points to a different cassette ID or digest, even if the current predicates happen to pass.

Assertion specs must support at least these predicate families:

The initial scenario set is:

1. top through Docker conformance, with initial paint, refresh, input-driven change, and resize-driven layout change.
2. claude authenticated record mode plus replay cassettes for quota/status, model list, and reasoning levels.
3. codex authenticated record mode plus replay cassettes for quota/status, model list, and reasoning levels.

The framework must be extensible before those scenarios are marked complete. Adding a new weird terminal case should require adding a scenario fixture and assertion spec, not writing one-off sleeps or parser-specific test plumbing. Required synthetic fixture families include partial ANSI/VT escape sequences, one-byte chunking, alternate screen, cursor addressing, screen clears, SGR style changes, OSC title, OSC 8 hyperlinks, OSC 52 clipboard writes, bell, DECRQM/mode-query responses, line-drawing and alternate character sets, bracketed paste, SGR mouse mode, focus-in/out, Unicode wide and combining characters, resize during output, resize during an escape sequence, rapid redraw/spinner frames, delayed output, no-newline prompts, PTY backpressure or large buffered output, final output burst at process exit, EOF during redraw, cancellation, and timeout. Sixel and image protocols are out of scope for the first implementation unless a selected primary harness emits them; if observed, they become explicit gap fixtures rather than silently ignored behavior.

PTY Library Test Strategy

The PTY library is not complete until it proves useful behavior against real terminal programs, not only fake sessions and happy-path harness probes. These tests are layered on the automated cassette assertion framework above; they do not rely on manual inspection, arbitrary sleeps, or terminal text scraping outside the selected emulator.

Inspection

Live inspection attaches to a read-only mirror of the direct PTY stream. Inspectors may watch frames and output bytes but cannot write to stdin, resize the authoritative PTY, or mutate cassette files. Recorded-run inspection reads frames.jsonl and output.raw through a viewer that opens files read-only and never normalizes or rewrites the evidence.

Alternatives

Consequences

Risks

Validation

Concern Impact

• Resolves inspectable harness execution concern: Selects direct PTY ownership as the canonical service evidence path and rejects tmux in the core harness/cassette design.
• Supports harness capability matrix: Future supported harness capabilities can cite versioned cassette evidence produced by this transport.

References

• CONTRACT-003 Fizeau Service Interface
• Concerns
• Architecture
• ADR-003 PTY Terminal Rendering and Screen Model
• ADR-004 Terminal Harness Build-vs-Buy Boundary
• SPIKE-001 Direct PTY Rendering With Unix Top
• gastown local tmux wrapper
• dun local harness spike
• Named Tmux Manager
• Claude Squad
• dmux
• creack/pty
• Netflix/go-expect
• asciinema

Review Checklist

• Context names a specific problem
• Decision statement is actionable
• At least two alternatives were evaluated
• Each alternative has concrete pros and cons
• Selected option’s rationale explains why it wins
• Consequences include positive and negative impacts
• Negative consequences have mitigations
• Risks are specific with probability and impact assessments
• Validation section defines review triggers
• Concern impact is complete
• ADR is consistent with governing feature spec and PRD requirements