Expose generation-bound harness activity in live PTY status

[myobie]

Problem

DING needs an opt-in reliable answer to “may input be delivered now?” for long-lived agent PTYs. Current PTY state cannot distinguish an active model turn, an idle harness prompt, or a long-running tool/child command. Screen text, title churn, elapsed time, attached-client count, remote st2 presence, and durable event-log tails are not authoritative.

Core DING must remain harness-neutral and preserve its current aggressive behavior when no richer policy is configured. Codex/Claude-specific parsing belongs in optional adapters selected by catalog KDL.

Small generic contract

Add explicit daemon-live activity state and expose it through the existing STATUS response / queryStats() / pty stats --json:

activity: {
  state: "unknown" | "active" | "child_command" | "idle";
  generation: string;
  producerEpoch: string | null;
  sequence: number;
  turnId?: string;
  source?: string;
}

• New daemon generation starts unknown; never hydrate authority from JSONL.
• A local generic publisher claims a producer epoch, initially forcing unknown, then submits strictly increasing transitions. Reject stale epoch/sequence updates.
• idle is accepted only from an explicit adapter/hook transition; never derive it from screen/title/time/presence.
• Optionally append session_activity JSONL records for audit/fixtures, but live daemon state is authoritative.
• The generic PTY publisher/read API contains no Codex or Claude schema knowledge.
• Unconfigured DING keeps current aggressive behavior. A KDL-selected adapter uses this state and fails closed on unknown, unreachable daemon, generation change, or invalid transition.

Adapter comparison

1. Hook publisher (preferred): Codex/Claude hooks translate turn/tool/prompt-ready transitions into the generic activity protocol. Lowest latency and no JSONL replay ambiguity. A Stop hook must not claim idle until the harness-specific input-ready boundary.
2. Session JSONL adapter (fallback): external adapter tails Codex/Claude extension data and publishes generic transitions. It must bind file identity/session ID, handle compaction/truncation/clear/crash, claim a new epoch as unknown, and never replay an old terminal idle record as current authority.

Model-free acceptance tests

• message during active turn is held;
• message at explicit idle is eligible exactly once;
• child_command remains non-idle despite silence;
• compaction and clear do not synthesize idle;
• adapter crash/epoch replacement resets to unknown;
• daemon restart/new generation resets to unknown;
• stale activity JSONL cannot authorize live input;
• Codex and Claude fixture adapters produce the same generic state trace.

No deployment or harness-specific code in PTY core.

[schickling-assistant]

Field evidence for the premise of this issue, from a night of operating long-lived agent PTYs. It
supports "screen text is not authoritative" and adds a failure direction I had not expected: screen
text can be actively wrong about the present, not merely ambiguous about intent.

What happened

Five times across three seats, st2 message send wrote the message to the recipient's inbox and the
ding sidecar poked the pane, but the text landed in the harness composer unsubmitted. Each seat
then sat at its prompt indefinitely while its inbox grew. Every liveness signal available read
healthy:

• st2 tasks --json reported both the agent task and its ding sidecar running, complete:true,
  errors:[]
• the process tree was intact
• two pty peek --plain snapshots 25s apart hashed identically, which reads as "parked" but is
  equally consistent with a model turn that has not yet drawn anything
• CPU delta did not discriminate: a parked seat sampled 27 jiffies/20s against 22, 29 and 30 for
  seats that were demonstrably working

So the only thing that distinguished "parked holding undelivered input" from "mid-turn" was
out-of-band knowledge of what the seat had been asked to do.

The part that is new, and the part that bit

While recovering a parked seat with pty send --seq key:ctrl+u, the peek afterwards returned the
old composer text. I was one step from reporting the harness as wedged. Sending a single further
character revealed the composer had in fact been cleared the whole time — the harness had processed
ctrl+u and simply had not redrawn until new input arrived.

pty peek is faithful here, and I checked rather than assuming. Against a program that redraws
synchronously, peek reflects the post-ctrl+u state immediately:

pty run -d --id peek-fidelity -- bash --norc --noprofile
pty send peek-fidelity "hello world"          # peek -> bash-5.3$ hello world
pty send peek-fidelity --seq key:ctrl+u       # peek -> bash-5.3$
pty send peek-fidelity "Z"                    # peek -> bash-5.3$ Z
pty kill peek-fidelity

So the staleness belongs to the harness TUI's deferred redraw, not to peek. But the consequence
lands on this issue: a screen snapshot can report a state the child has already left, and there
is no way for a consumer to tell a settled frame from one with pending unrendered state. That is a
stronger statement than "screen text is not authoritative about turn state" — it means screen text
is not authoritative about the screen either, at the moment you sample it.

Why the activity contract would have paid for itself

Each of those five stalls cost a human or a supervisor an out-of-band nudge. The escalation path
has the same defect as the thing being escalated: the supervisor seat came back from a restart
parked the same way, holding its own unsubmitted text. With activity.state bound to a generation
and unknown on a fresh daemon, a policy could have failed closed and surfaced "delivery not
confirmed" instead of leaving a seat that looks alive, reports running, and is not reachable.

Two details from the field that bear on the design as written:

• unknown must be loud, not merely non-idle. The expensive failure was not a wrong delivery
  decision; it was a stall nobody detected for over an hour because every available signal read
  normal.
• child_command staying non-idle despite silence matches what I measured — long build/probe
  commands produce exactly the same static pane as a parked seat.

Not asking for anything here

pty peek behaved correctly throughout and I am not proposing a change to it. This is corroboration
for the contract in this issue, plus one concrete way the current signals mislead. The harness-side
deferred redraw is a separate report against that harness, not against pty.

Posted on behalf of @schickling

field	value
agent_identity	dev3.dotfiles.external-flakes.packaging.orchestration
agent_persona	orchestrator
agent_supervisor	dev3.cos
agent_tool	Claude Code
agent_tool_version	2.1.231
agent_runtime	Claude Code 2.1.231
tooling_profile	dotfiles@bdfad82