# Live activity buffer (PTY digest)

## Status

accepted (2026-06-01) · **source mechanism superseded by the 2026-06-12 amendment below** (product surface stands) · **implementation reconciled onto the log source in M9 (2026-06-13)** — the PTY-parse engine + `pty_digest` seam are retired; the digest is an on-demand projection of normalized session-log records · **source mechanism FULLY superseded by [ADR-0019](0019-digest-adapter-declared-extractor-session-spanning.md) (2026-06-13)** — the M9 "no manifest seam / rides `[history]`" stance is reversed: the digest gets its own adapter-declared `[digest]` extractor, thread-spanning, and a two-origin (activity + injected-context) merge. Only this ADR's product-surface framing survives (broadened from "recent activity" to "recent context").

## Context

We want a rolling, human-glanceable "what is this agent doing right now" view — the last ~N user turns + agent output between, with tool-usage sprints collapsed to a single `used: …` line — that a Shell, CLI, or GUI pane can render. The obvious implementation (spt-core parses the live PTY byte stream) looks like it **contradicts the history-subsystem decision** (CONTEXT §history subsystem), which deliberately refused to build per-harness parsers ("unbounded, version-fragile maintenance burden") and pushed parsing into adapters (Path A) or a native store the adapter writes (Path B). A future reader would reasonably flag the apparent reversal. This ADR records why it is *not* one, and the shape chosen.

## Decision

Add a **live activity buffer (PTY digest)** as a **distinct artifact** — not scrollback (raw bytes, R-TERM-2), not transcript history (full conversation behind communes/resume, Paths A/B). Its purpose is at-a-glance current activity, not replay.

The parsing-boundary distinction that resolves the tension:
- **The adapter supplies the patterns; spt-core only runs them.** The manifest provides `input_pattern` + `agent_pattern` (each opens a span capturing everything, newlines included, until the next pattern match of any kind) and `tool_pattern` (a **list** — one per tool, plus a final **catchall** for user-installed tools, capturing tool-name + arg fragment). This is exactly Path A's "adapter owns the parser" rule and the "spt-core owns the mechanism, adapter owns the pattern" principle (identical to opaque command templates) — **not** a built-in per-harness parser. The rejected maintenance burden stays in the adapter.
- **It parses the live PTY byte stream, not the harness transcript.** A light rolling regex over bytes the broker already holds is a categorically different artifact from locating + parsing version-fragile harness transcript files (the thing Path A/B exist to avoid).

Shape:
- **Broker-PTY-dependent → spt-hosted-primary.** Needs the broker-owned PTY (topology 2). **Harness-hosted (topology 1) is capability-gated:** an adapter that can feed spt-core the stream (e.g. a `pi`-style harness) opts in via a declared capability; harnesses that own their process tree opaquely (Claude Code) cannot, and the digest is simply unavailable there.
- **Structured, source-tagged output** (input / agent / collapsed-tool entries) so consumers render richly. Window depth N (~3) is a config knob; tool-arg truncation (~25 chars) is spt-core-controlled *presentation* (the template controls *extraction*).
- **Two access modes over one transport.** The digest is a parsed projection of the same PTY stream the broker streams for R-TERM-3, so: **snapshot pull** (`spt digest <[subnet:]id[@node]>`) and a **broker-pushed structured-delta stream** (subscribe; pushes only changes for near-realtime reflection). The delta-stream is a structured overlay riding the **same R-TERM-3 byte-stream substrate** (raw vs parsed = two channels on the one session surface). Access is **address-gated** (same as messaging; respects ADR-0006 visibility).
- **Optional "Option (C)" persistence:** opt-in per-endpoint, append digests to the native history store (Path B) as a coarse activity log — a third logging surface, off by default, not a replacement for A/B.

## Consequences

- New v1 requirement to register: the live activity buffer + the `input_pattern`/`agent_pattern`/`tool_pattern[]` manifest seam + `spt digest` (pull) + the digest delta-stream (push). Lands with **M3** (needs the spt-term broker + PTY); Shell consumption is M5; the GUI pane is the frontend milestone; persistence is M3+.
- The manifest schema (`docs/MANIFEST.md`) gains the `pty_digest` seam; the capability-declaration seam gains the harness-hosted stream-feed opt-in.
- Does **not** reverse the history-subsystem decision — the no-built-in-parser rule still holds; the digest honors it by running adapter-supplied patterns over the live byte stream rather than parsing harness transcripts.
- Builds on R-TERM-1/2/3 (broker, session surface, byte-stream) and ADR-0006 (address-gating).

## Amendment — source mechanism superseded: normalized session logs, never PTY parsing (2026-06-12)

**What changes:** the digest's *source*. The original decision parsed the live PTY byte stream; the digest is now a **rolling tail-projection of the endpoint's normalized session logs** — the same normalized history the echo-commune consumes (history subsystem Path A locate+normalize / Path B native store). One pipeline, two consumers. Harnesses with no usable logs push entries directly via a new **`api digest-entry`** verb.

**Why (the Gateway grill, 2026-06-12):** the PTY byte stream of an alternate-screen TUI is a **rendering protocol, not a content log**. Scroll and resize trigger full repaints — the same content re-enters the stream and corrupts delta computation — and semantic turn boundaries drown in repaint traffic. The original §Decision rationale ("a light rolling regex over bytes ≠ fragile transcript parsing") proved **backwards in practice**: the byte stream is the *more* fragile surface, and transcript parsing carries **zero new burden** because Paths A/B already pay for it — the digest just consumes their output. The governing split: **render surfaces read the PTY** (R-TERM raw byte ring, unchanged); **content surfaces read the logs**.

**What stands (the product surface, unchanged):** the formula (N-turn window, collapsed tool sprints, presentation-vs-extraction split), structured source-tagged output, both access modes (snapshot pull + structured-delta stream, deltas now keyed to log records), address-gating, Option-C persistence. The no-built-in-parser rule **still holds** — normalization remains adapter-owned (Path A) or adapter-pushed (Path B).

**Improved consequence:** the digest becomes **topology-independent** — harness-hosted endpoints (Claude Code's per-session JSONL is Path A's worked example) get digests too; the original "unavailable under opaque harnesses" limitation dissolves. Freshness = file-watch + adapter hook nudges; a near-realtime **incremental** normalize story is design-phase work for the implementing milestone.

**Implementation debt recorded:** `spt-daemon::digest` (`DigestEngine` + the manifest `pty_digest` pattern seam) implements the superseded shape; reconciliation + the `docs/MANIFEST.md` schema revision land with the implementing milestone.

**Debt discharged (M9, 2026-06-13):** the PTY-parse engine (`spt-term`'s `DigestParser` + `spt-daemon`'s byte-feed `DigestEngine`) and the `[pty_digest]` manifest seam are **retired**. The digest is now an **on-demand projection** of the endpoint's normalized session-log records: `spt-term::projection` folds the published **digest-record contract** (the spt-core-owned `{role, text, tool}` overlay an adapter targets in its `[history]` lines, or pushes via `api digest-entry`) into the same structured `Digest`; `spt-daemon::digest::project_endpoint_digest` projects on demand at the snapshot-pull / reproject handlers and `DigestHub::project_and_publish` drives the delta-stream. Topology-independent (a Claude-Code-hosted endpoint's Path A JSONL projects with no broker PTY — proven by the CC-fixture E2E). The **autonomous file-watch freshness nudge** and **Option-C persistence re-home** are deferred to the consuming-frontend milestone (`docs/DEFERRED.md`) — the delta-stream contract ships, driven by pull / `api digest-entry` publishes. REQ-TERM-4 re-titled + its evidence re-pointed onto the projection in the same change.