feat(client): client-owned navigation picker and presentation lease (#276)

* feat(client): own the navigation picker presentation

The navigation session picker becomes a typed client interaction that the
client presents itself while the daemon keeps mutation authority. This
consolidates the client-ownership work into one change on current main.

- protocol v44: `PickerOpen`, `PickerSnapshot`, `PickerSelection`,
  `PickerClose` (both directions), and `PickerFailure` with strict codecs,
  semantic validators, encoded bounds, and byte-for-byte tests; the client
  advertises the client-picker capability in `Hello`.
- daemon: capability-gated picker interactions with opaque row keys
  resolved to navigation targets under the session locks, lifecycle
  revalidation before commit, fail-closed snapshot sends, an authoritative
  full repaint when the client retires the interaction, and full-snapshot
  refresh on row-set and size changes. The overlay model stays untouched
  for every other attachment.
- client: snapshot admission, local cursor and search, typed commit and
  cancel, and a presentation lease that owns the terminal from the snapshot
  acquisition barrier to the daemon's release paint; suppressed daemon
  paints still advance the applied shadow, the acked window, and the
  published context boundary, and picker bytes never reach the PTY.
- client: async clipboard reads are fenced to the foreground owner.
- tests: lease state rules, picker loop and cancel release end to end
  through the real attach attempt, palette frame admission, navigation
  transaction boundaries, and the UI-driver acceptance scenarios.
- acceptance: `client-picker-navigate` for local IPC and direct remote
  (UDP and stdio), driven by the observed picker text instead of row order.
- docs: keep the preferences/status contracts as proposals, describe the
  shipped picker contract in the architecture and session-navigation docs,
  and drop the executed pilot plan, approval record, stack coverage maps,
  and completed-migration checkpoints.

* fix(client): give the navigation picker exclusive input ownership

The client-owned picker was reachable only through the ui-driver automation path: physical keystrokes bypassed it and reached the session while the modal owned the screen. Close that hole and the paths it opened.

- client: a shared pickerConsumer publishes who owns terminal input; the stdin pump decodes physical bytes and admitted automation batches into identified operations, and the attach loop, its only model writer, applies them. Unknown, oversized and paste-sized batches are consumed instead of falling back to the session pipeline, a multi-key batch never acts as a command, and an ambiguous escape prefix is bounded by a 20 ms clock timer.
- client: the release window consumes and drops input until the daemon's authoritative repaint lands, replacing the input-gate hold that never engaged without a ui-driver.
- client: terminal rejections and superseding interactions send PickerClose, retire the interaction permanently against late snapshots, and resolve the superseded lease instead of aborting the newly installed one. Release now requires a full paint accepted after the close boundary.
- daemon: a client-owned interaction drops raw key and mouse input for its attachment before the mouse scanner and the key router, and a selection must carry exactly the displayed revision.
- daemon: the client picker keeps the directory-refresh path alive even though it installs no overlay model.
- protocol v45: PickerOpen is removed; it had no emitter and the interaction opens on palette execution.
- remove dead surface: the test-only lease and interaction helpers, the empty s/x key branches, and the UI-side consumer accessors.
- tests: physical-input decoding and ownership, no-replay release, daemon key and mouse drops, revision equality, retirement and supersession, plus the existing suite.
- docs: architecture and session-navigation describe the corrected ownership.

* fix(client): order picker release behind the daemon close

The release boundary compared against the locally applied output state, which cannot tell a paint already in flight from the post-close restore, and a paste was still guessed from batch size. Both are replaced by explicit state.

- client: a release is only accepted once the serving daemon's own close has been observed, at the boundary current when it arrived; a Full in flight before it no longer releases the terminal.
- client: a terminal rejection is idempotent: a second failure for an interaction already draining neither cancels the release nor re-sends a close.
- client: a superseding interaction retires the replaced one, and input stays owned until the replacement displays, so the replaced picker frame cannot leak keystrokes to the session.
- client: paste is decoder state, not a heuristic. Bracketed-paste content is dropped across reads, incomplete UTF-8 prefixes are withheld instead of lost, and events keep their arrival order, so a read carrying several legitimate keystrokes is applied in order rather than discarded.
- client: the escape deadline is armed once per withheld prefix and an expired deadline resolves before a later suffix can complete it.
- client: the outcome queue is bounded and blocks the producer, and a batch that changes nothing no longer composes a frame.
- daemon: the interaction is retired before the selection handoff, so the destination paint is the paint the client's release waits for; a failed handoff still publishes a restore. The clipboard image path is blocked while the interaction owns input.
- remove dead surface: the unused consumer predicate, the pump's unread UI field, the unused lease size epoch, and the presentation predicate superseded by the ownership check.
- tests: release ordering and the daemon-close barrier, interaction retirement and supersession, clipboard blocking, a real catalogue change for the refresh, ordered multi-keystroke batches, fragmented paste and UTF-8, and a no-ui-driver composition.

* test(client): pin the picker paths the review left unproven

Close the three gaps the review flagged and the environment-dependent suite failure behind them.

- picker: bracketed paste is enabled with the first frame and reset exactly once when the interaction ends, so a paste arrives marker-wrapped and the decoder drops it as a unit instead of it looking like fast typing.
- tests: the no-ui-driver composition now waits for the drawn picker and asserts the committed row, the mouse drop has a positive control proving the same report reaches the pane without the interaction and resumes after the close, and the decoded-operation scope pins that a retired generation or superseded interaction never applies stale input.
- uidriver: the socket fixture creates its directory under the system temporary directory. Building it under the checkout made the test fail whenever the checkout path was long enough to overflow the unix socket limit, which is why make test reported a failure unrelated to the code under test.

* refactor(client): drop the picker helpers left unused by the input rework

The consumer rework removed the last callers of one lease predicate, and two test helpers became dead once the headless and paste tests were fixed: the harness fires deadlines through awaitAfterAmbiguityDeadlines instead. golangci-lint unused now reports no symbol on this branch that is not already unused on main.

* wip(picker): unify the picker contract on v46 structured lines

Foundation slice of the picker unification: the protocol carries one
structured line model and one typed action set (navigate, move, kill)
per source; the pure picker model renders lines instead of rebuilding
fake session views from wire rows; and the serving daemon computes
destination eligibility and publishes lines for every intent.

Incomplete: the daemon overlay deletion, the client presentation of move
intents, the home-picker removal, and the preview service still need to
land before the branch compiles.

* wip(picker): present every picker intent from the client

The serving daemon now publishes structured lines for navigation, move-pane,
and move-tab intents, offers the interaction with its acquisition barrier, and
resolves typed navigate/move/kill selections; the client owns the model,
cursor, search, sort, and per-row action choice for all three intents.

Removes the daemon overlay picker, its input routing, its render branch, its
preview subscriptions, and the startup-overlay entry, along with the picker
search input handler and the parked-overlay generation plumbing.

Production code compiles; the test suites that drove the overlay still need to
be rewritten against the typed interaction.

* test(wire): pin the v46 picker codecs and version

Replaces the opaque-row codec tests with offer/begin/source-snapshot/
selection/result/closed byte-level coverage, including truncated-prefix and
trailing-garbage checks, and moves the protocol version goldens to 46.

* test(sessionwire): cover the v46 picker message directions

Pins the begin/offer/close/closed/selection/result/failure frame types, their
payload round trips, and the wrong-direction rejections for both adapter
directions.

* test(picker): pin the line model contract

Replaces the session-view driven model tests with table-driven coverage of the
line model: cursor restore by key, section-aware movement, local recency and
grouped ordering, in-place refresh, search visibility, nearest-row snapping,
layout boundaries, preview blitting, and status badges.

* test(daemon): drive the picker suite through the typed interaction

Rewrites the picker interaction tests against v46: offer and snapshot
publication, per-source revisions, navigate/move intents, foreign-source and
stale-revision rejections, close confirmation ordering, and input ownership.
Drops the overlay-driven suites the deleted presentation owned and moves the
tab-with-context helper into a shared test file.

* test(daemon): adopt the typed kill in the effect-gate and policy suites

The remote activation policy suite now drives the daemon-private view type, and
the picker-delete gate tests send a typed kill selection through the same
resolution path the client uses. Kill holds its admission until it finishes so
a replacement initiator cannot leave the destructive action unattributed.

* test(daemon): drop the picker cases from the raw-input precedence suite

The daemon no longer routes raw input to a picker model, so the precedence
suite keeps only the prompt, palette, and copy layers. Picker input ownership
is covered by the typed interaction suite.

* test(daemon): move the picker suites onto the typed interaction

Rewrites the move-picker suite around typed move selections and typed opens,
adapts the remote picker view/availability/handoff suites to the daemon-private
view and line-set types, and drops the suites that drove the removed overlay
preview subscriptions, parked picker generations, and daemon-side picker
rendering.

* test(daemon): compile the remaining picker suites against v46

Drops the picker modal from the composition, paint-invalidation, and damage
fixtures, opens typed interactions where the suites used the overlay entry, and
teaches the typed-connection test double the v46 offer/closed/result frames.
The daemon test package now builds; several move-picker expectations and one
picker cancel expectation still fail and one picker test hangs.

* fix(picker): publish per-tab remote targets and keep previewed tabs renderable

Each remote tab row now carries its own restore target (stable tab ID when
known, ordinal fallback otherwise) instead of the session-level selector, and a
fresh interaction starts on a session's active tab. A rejected move reports the
same precise user notice the palette path does, the retired-target gate now
applies to navigation only, and a headless tab stays renderable while a preview
subscriber watches it so the preview service can compose from it.

The daemon test package is green.

* test(client): drive the picker suites through v46 offers and typed actions

Replaces the overlay-era fixtures with offer plus per-source snapshot
publication, typed navigate/move/kill commits, per-source revision admission,
and close confirmations carrying the restore barrier. Fixes two client bugs the
rewrite exposed: a background refresh of a superseded interaction replaced the
open model instead of the retired one, and a search keystroke did not mark the
frame dirty.

* test(perf): keep the compact storage budgets measurable under -race

The performance fixtures built a 10k-row history for every scenario, which the
race detector turned into most of the suite's runtime while the allocation and
byte budgets they feed are calibrated without it. Derive the fixture depth and
its expectations from one constant, shrink it under -race like the existing
copy-entry budget gate, and skip the byte-eviction budget there.

Cold make test drops from 149s to a level dominated by real work.

* test(remote): assert the bounded store lane by outcome, not by winner

Two cache stores admitted back to back race for the lane's single extra slot:
which one is accepted is admission timing, so the test now follows the reported
lane-busy endpoint and checks that the payload the lane accepted is the payload
it reported success for. This removes the intermittent failure seen under full
suite load while keeping the bounded-lane contract pinned.

* refactor(picker): delete the home-picker and parked-route presentation path

The picker no longer parks a route: every attached client presents it, so the
daemon never asks a client to open a home picker. Removes the client home-picker
entry and its transient attachment, the parked-route lease state machine, the
navigation directives, and the protocol surface they needed (startup overlay,
home-picker and back capabilities, open-home action, parked-route request and
response), with the Hello layout losing its overlay byte at v47.

Attachment parking and resume stay: they carry the UDP and hybrid handoff.
Inline picker capability advertisement goes too, since v46 admits the picker on
every attachment.

* fix(client): start the foreground pump before the receive loop

Removing the parked-route helpers also dropped the unconditional
startForeground call that preceded the receive loop, leaving the client
without a reader until the first full output frame. Terminal palette
replies were never read and keypresses never reached the session, so
attachments stalled before the first paint.

Restore the call where the helper block ended: the foreground owns
terminal input from attach start, and the same-peer and picker paths
suspend it through the input gate instead of starting it late.

* fix(client): bind navigation capabilities to the intent that serves them

The client validated an attach request against the capability bit set
alone, so a capability the serving daemon rejects on Hello could still
dial. Inventory is the one negotiable feature under v47, and only the
intents whose attachment owns a relay can serve it.

Share one intent-aware rule between the Hello validator and the client's
pre-dial validation, and cover the ephemeral case that now fails closed.

* test(client): drive the hybrid route switches through the client picker

The parked-route suites that covered same-host reuse and cross-host
fallback were removed with the mechanism they drove. Re-drive both
journeys at the runner boundary: the client opens the picker from the
serving daemon's offer, commits a row with a real keypress, and then
either confirms the same-host target on the authenticated transport or
dials the target endpoint and closes the source.

Teach the external typed-connection bridge the picker messages so those
journeys can cross it.

* fix(daemon): republish an open client picker on the attention pulse

A bell raised while a client presents the picker never reached it: the
client owns the modal, so the daemon's repaint is suppressed and only a
newer picker source updates the rows.

Republish the serving source for every attachment whose picker
interaction a client presents, on the same attention pulse that already
refreshes the status bar while a bell rings. Cover the notification
content the client renders and the pulse-driven refresh, including that
a retired interaction is never reopened.

* feat(protocol): carry a typed picker preview pair at v48

The client owns picker presentation, so the row preview must cross the
wire instead of being painted by the daemon: the client names the row it
displays and the serving daemon answers with a bounded styled-cell
viewport.

Add PickerPreviewRequest and PickerPreview with their strict codecs,
share the cell layout and style block with the remote preview, and bump
the session protocol to v48 for the new frame types.

* feat(sessionwire): carry the picker preview pair across the wire

Map the client's preview request and the daemon's preview answer in both
directions, mark the new messages, and reject each in the wrong
direction so a malformed peer cannot smuggle one through the other
codec.

* feat(daemon): serve picker row previews on request

The client names the row it displays and the serving daemon captures it,
reusing the navigation preview facts already in place: previewTarget and
snapshotPickerPreview for local sessions, the remote preview cache for
remote rows. A newer request supersedes the previous render subscription
and the retirement of the interaction tears it down, so only the
displayed row keeps publishing and a delayed capture cannot replace it.

The capture is fitted to the requested bounds, blanking a double-width
cell whose continuation column was cropped so the published cell run
stays valid.

* feat(client): request and render the displayed row preview

The picker modal asks the serving daemon for the preview of the row the
cursor rests on, debounced so scrolling does not ask for every row it
passes, and renders the published viewport in its preview pane. One
request is in flight per interaction: a row already requested is never
asked twice, a late answer for a row the user left is discarded, and a
status-only answer clears the viewport.

* refactor(daemon): name the serving source through the protocol constant

* feat(ports): add the client host registry seams

The client must resolve a remote endpoint without importing an adapter:
add the endpoint binding it reuses across handoffs, the factory the
composition root implements from transport mode and launch policy, and
the runner-scoped registry that also exposes the discovery projection.

* feat(remotes): add the runner-scoped endpoint registry

One runner resolves each remote endpoint once and reuses that binding for
every later handoff, while projecting the discovery directory it drives.
A failed resolution is never cached, so a refused endpoint retries
through the same single authority instead of falling back to another
resolver, and returned bindings are defensive copies that keep a nil
environment distinct from an explicitly empty one.

* feat(app): compose the client host registry and endpoint policy

The launching client gets its own discovery composition: the same store,
catalogue client, and monitor the daemon uses, over a runner-local
catalogue cache that seeds from the durable snapshot and never writes it,
so the two monitors cannot race the same file. Endpoint resolution
applies the configured allowlist, transport mode, and endpoint
environment in one place, and an explicitly empty environment stays
distinct from an absent one.

* feat(client): resolve handoffs through the runner host registry

The runner no longer takes a per-target handoff callback: it resolves the
endpoint through the host registry it also drives, so the endpoint binding
(typed dialer and environment) is created once and reused for every later
handoff, and one discovery loop serves the whole run instead of one per
connection.

The composition root keeps exactly the policy it owned: it validates the
transport mode, the launch allowlist, and the per-endpoint environment
behind the registry, and the runner derives each handoff request from the
validated target plus that binding, including the picker environment rule
a locally launched client follows.

* test: pin the client registry beside daemon-owned remote picker data

Cover the two owners together: a remote picker row is still captured
through the daemon's own remote viewport client, and a client route that
crosses serving peers resolves each endpoint through its registry and
dials a fresh connection through the binding it already has.

Document the current shape: the picker is client-presented on every
attachment, previews and attention are daemon-published data, and remote
discovery has a daemon owner and a runner-scoped client owner with
separated catalogue writers.

* refactor(client): drop the retired handoff callback type

The registry seam replaced it, so the type only invited a second endpoint
authority back in.

* fix(daemon): key remote picker rows by their owning endpoint

One machine can be registered under more than one target, a pinned alias
and one learned by attach, and both endpoints legitimately expose the
same session lifecycle and name. The picker keyed rows by incarnation and
name alone, so those rows collided, the snapshot failed validation, and
the session picker never opened at all: the palette reported "invalid
navigation" and the user saw nothing.

Qualify a remote row's key with its endpoint through a bounded digest,
which keeps the key opaque and unique per endpoint, and pin the case.

* fix(client): present the picker as a floating modal

The client drew the picker into a full-terminal frame, so opening it
wiped the session and the modal looked nothing like the daemon-owned
overlay it replaced. Resolve the same 80% centred box the daemon used,
render the rows into its inner rectangle, and write only the box's own
cells: the session stays on screen around it until the daemon's
authoritative repaint after the close.

The box now lives in the picker package because both sides need it: the
client draws it and the daemon sizes the preview it captures from it, so
the client asks for exactly the pane it will blit into instead of the
whole terminal.

* fix(daemon): give remote picker rows their session incarnation

A remote row left its incarnation zero, so every live session on one host
shared one row identity. Two sessions on that host then produced the same
row key, the snapshot failed validation, and the picker never opened:
two sessions on a remote host were enough to break it. Use the session
lifecycle, exactly like local rows, and cover two live sessions on two
endpoints of the same host.

* fix(protocol): say which row made a picker snapshot invalid

A refused snapshot reported only "invalid navigation", which left a
silently closed picker with nothing to debug. Wrap the reason with the
offending row, and log the rejected snapshot with both colliding rows and
the offer rejection with its cause.

* feat(protocol): carry picker row focus eligibility

The daemon computes selectability and focusability separately, but the
published picker row only carried actions: the client rebuilt focus as
"anything but a section header" and let the cursor rest on rows the source
had deliberately skipped, where Enter silently does nothing.

Publish the decision instead. PickerLine gains Focusable, with the
invariants that an action row is always focusable, a section header never
is, and a focusable row without actions is inspection-only. A malformed
snapshot is rejected before it reaches the wire.

Remote host status rows are published as PickerLineHost rather than a
session row: they carry no session identity and exist for inspection.

The row flag byte gains the focus bit and the protocol version moves to
49, since the line layout changed.

Fixtures across protocol, adapters, client, and daemon set the flag so
every published snapshot stays valid.

* feat(picker): keep the cursor on rows the source authorises

The cursor visited every row that was not a section header, including
session headers the daemon had published without focus, so Enter on such a
row did nothing and the footer still promised "Enter open".

Place the cursor only on rows the source marked focusable, narrowed by the
client's own query, and let every placement path agree: arrow movement,
nearest-row selection, restoration by key after a refresh, sorting, and the
search editor. A query with no matches clears the cursor instead of leaving
a visible one that cannot commit, and rows the query hides are refreshed
before the cursor is restored by key, so an index-keyed match map can never
describe a rebuilt row list.

The footer derives its hints from the effective selection, so a row kept
for inspection reports "Enter unavailable" while still showing its status
detail.

* fix(daemon): revalidate remote picker targets in the handoff

Selecting a remote session closed the picker, then reported a retired
target and switched nowhere: the freshness gate resolved every committed
row against the daemon's local session table, and a remote row names an
endpoint-qualified session that table never holds.

Remote targets carry their own route, so the handoff is their lifecycle
gate: it revalidates the exact endpoint, session, lifecycle, and tab
against the remote catalogue and reports its own precise rejection. The
local gate keeps guarding local rows.

* fix(remotes): publish the first registry read even when it is empty

A host with no registered remote hosts never published its directory: the
first successful registry read only marked the state dirty when the
registration list changed, so an empty registry looked like an unfinished
check. Every reader then showed a permanent "checking remotes" placeholder
where there was simply nothing configured.

Publish that first read: an empty registry is a known state. The picker on
such a host no longer carries a phantom remote section.

* feat(picker): move session navigation to client authority

* fix(picker): revalidate home selections by target

* fix(picker): avoid move selection self-deadlock

* fix(picker): follow moved tab to destination

* fix(picker): atomically follow moved content

* fix(picker): harden authority refresh and completion

* test(uidriver): resolve macOS temporary directory symlinks

* fix(palette): relay only supported local inventory

* fix(status): restore remote attention indicators

* fix(navigation): complete cross-daemon picker presentation

commit

7091acbe9b6afcba1933290ccf81b0899332e241

author

bnema · 40d ago · 2026-09-12 14:08 UTC

committer

GitHub · 40d ago · 2026-09-12 14:08 UTC

parent

0dec724

signature

GPG UnverifiedB5690EEEBB952194 The key is unknown