sessiontransport

type Capabilities struct {
	// Kind names which shipped transport this matrix describes. It exists
	// so a Capabilities value carries its own identity when logged or
	// compared in a test, never so a caller branches on it directly —
	// REQ:single-transport-interface reserves that judgement for transport
	// selection, not for call sites above [Transport].
	Kind Kind

	// LiveStatus reports whether this transport can ask, right now, whether
	// the owning session is idle, working, blocked, or done. herdr's
	// `agent list`/`agent get` supply this; tmux structurally cannot.
	LiveStatus bool

	// EmptyInputEvidence reports whether this transport can produce
	// positive evidence that a pane's input box is empty. No shipped
	// transport declares this true today: the mechanism is Deferred in the
	// Feature (see "Empty-input evidence mechanism"), so
	// REQ:delivery-guards-enforced-and-rechecked's guard can never be
	// satisfied yet — by construction, not by circumstance.
	EmptyInputEvidence bool

	// AdvisoryDelivery reports whether this transport can paste unsubmitted
	// text into a live pane (herdr's `pane send-text`) for a
	// daemon-originated event outside the session's own-PR-outcome class.
	// tmux declares this false by default
	// (REQ:tmux-record-only-for-daemon-events): it has no live status and
	// no input evidence at all, so there is nothing to guard even an
	// advisory paste against a mid-typing human. This field governs only
	// daemon-originated delivery ([EventOwnPROutcome], [EventAdvisory]); it
	// has no bearing on [LineageSubmit].
	AdvisoryDelivery bool

	// LineageSubmit reports whether this transport submits the pre-existing
	// successor-messaging path — `wb session send`'s and `recall`'s
	// target-side write ([EventSuccessorMessage],
	// REQ:existing-successor-messaging-binding-path) — guarded by that
	// receipt's lineage rather than by the daemon wake's own-PR-outcome
	// restriction. tmux declares this true: its paste-buffer payload
	// already ends in a newline today
	// (internal/sessionmove/types.go:622's marshalJSON) and
	// REQ:tmux-parity-preserved keeps that unchanged. herdr and none
	// declare it false: no herdr submit path is built in this iteration
	// (Deferred: "Successor messaging's herdr submit path"), and none never
	// submits anything. LineageSubmit is never consulted for
	// [EventOwnPROutcome] or [EventAdvisory] — only [EventSuccessorMessage]
	// — so a transport declaring it true still never submits a
	// daemon-originated event (AC:tmux-never-delivers-unguarded's guarantee
	// extends to this field too).
	LineageSubmit bool

	// PaneEnumeration reports whether this transport can enumerate live
	// panes/agents to resolve a session's identity to a unique target
	// (REQ:pane-resolved-by-session-identity-match). Resolving to zero or
	// to more than one candidate is never treated as a target — see
	// [Transport.ResolvePane] and [ErrNoUniqueTarget].
	PaneEnumeration bool
}

type Delivery struct {
	Operation Operation
	Class     EventClass
	// Key is the idempotency key a keyed delivery mechanism needs — tmux's
	// buffer name is `wb-message-<Key>` (internal/sessionmessage/receive.go:189,
	// asserted by receive_test.go:97). Required for [OperationMessage];
	// [OperationWake] leaves it empty.
	Key string
	// Text is the exact bytes to deliver.
	// REQ:facts-only-templates governs what Text may ever contain for a
	// daemon-originated event; this package does not compose message text,
	// it only carries whatever the caller already built.
	Text string
}

type DeliveryMode string

type EventClass string

type Identity struct {
	Kind Kind
	// WBSessionID is this session's own opaque WB identity (session.NewID).
	// tmux's ResolvePane resolves this to a live pane by its deterministic
	// session-name convention, "wb-session-" + WBSessionID
	// (internal/sessionlaunch/launch.go:482); [Transport.MatchesReceiptIdentity]
	// checks the identical convention against a receipt-carried name.
	WBSessionID string
	// HarnessSessionID is the harness's own session identifier —
	// CLAUDE_CODE_SESSION_ID for Claude Code — the value herdr's
	// ResolvePane must match uniquely against a live candidate's
	// `agent_session` (REQ:pane-resolved-by-session-identity-match). Empty
	// on tmux and none, which have no such live-status API to match
	// against.
	HarnessSessionID string
	// Socket is the herdr socket path this identity's coordinates are
	// scoped to (herdr's IDs are scoped to one server). Empty on tmux and
	// none.
	Socket string
}

type Inspection struct {
	// Live reports whether the target's process is running right now. PID
	// is meaningful only when Live is true.
	Live bool
	PID  int
	// Terminated reports whether the transport found terminal evidence — a
	// dead-but-still-inspectable pane, on tmux — distinct from the target
	// never having existed, or already having been cleaned up. ExitStatus
	// and Diagnostic are meaningful only when Terminated is true.
	Terminated bool
	ExitStatus int
	Diagnostic string
}

type Kind string

type LaunchRequest struct {
	SuccessorWBSessionID string
	// Cwd is the working directory the successor's process starts in.
	Cwd string
	// Executable is the absolute path to the process to start.
	Executable string
	// Args are the executable's own arguments, in order.
	Args []string
}

type LookPath func(file string) (string, error)

type NoneTransport struct{}

type Operation string

type OverrideConfig struct {
	Transport Kind `yaml:"transport"`
}

type PrerequisiteCheck func(kind Kind) error

type Receipt struct {
	Operation Operation
	Outcome   DeliveryMode
	Target    Target
	At        time.Time
}

type Target struct {
	Kind Kind
	// ID is the transport-native pane identifier used to address a live
	// send call: herdr's pane ID (e.g. "w1:p2") for `pane send-text`, or
	// tmux's own pane ID (e.g. "%7") for `paste-buffer -t` — see
	// internal/sessionmessage/tmux.go's Pane.ID, PasteBuffer's paneID
	// argument.
	ID string
	// Name is tmux's session name, "wb-session-" + a WB session ID
	// (internal/sessionlaunch/launch.go:482,
	// internal/sessionmessage/receive.go's handoffReceipt.TmuxName). Empty
	// on herdr and none, which have no equivalent deterministic name.
	Name string
	// PID is the resolved target's live process ID — tmux's
	// list-panes `#{pane_pid}` (internal/sessionlaunch/tmux.go's PanePID,
	// internal/sessionmessage/tmux.go's Pane.PID). Zero when unknown.
	PID int
	// Socket is the herdr socket path this Target's ID is scoped to —
	// herdr's IDs are scoped to one server. Empty on tmux and none.
	Socket string
}

type Transport interface {
	// Kind reports which shipped transport this is. It exists for logging
	// and for a Capabilities().Kind cross-check, never for a caller to
	// branch on — that would violate REQ:single-transport-interface.
	Kind() Kind

	// Capabilities reports this transport's declared, fixed capability
	// matrix (REQ:transport-capability-matrix). An implementation returns a
	// constant value; [ResolveDeliveryMode] is the only place that
	// interprets it into a delivery decision.
	Capabilities() Capabilities

	// ResolvePane resolves identity to a live [Target]. It MUST return
	// [ErrNoUniqueTarget] — never guess, and never fall back to a stale
	// recorded target — when zero or more than one live candidate matches
	// (REQ:pane-resolved-by-session-identity-match). See
	// [ErrNoUniqueTarget]'s own doc for exactly which callers must treat
	// that as record-only today, and which pre-existing caller does not yet.
	ResolvePane(ctx context.Context, identity Identity) (Target, error)

	// Launch starts a brand-new terminal for a successor session and
	// returns the [Target] it resolves to (internal/sessionlaunch's
	// StartDetached, moved behind this method by Task 3). It derives the
	// terminal's own name itself, via
	// AddressFor(request.SuccessorWBSessionID) — see [LaunchRequest] for
	// why that field does not exist on the request instead.
	Launch(ctx context.Context, request LaunchRequest) (Target, error)

	// Inspect reports target's current liveness and, when it is not live,
	// whatever terminal evidence is available — replacing tmux's separate
	// PanePID/PaneFailure poll (internal/sessionlaunch's waitReady,
	// waitExecSuccess, selectAttemptForStart, failedAttemptRetryable,
	// validateAbandonment all poll this repeatedly).
	Inspect(ctx context.Context, target Target) (Inspection, error)

	// AddressFor returns the deterministic address this transport would use
	// to reach wbSessionID's live terminal, in this transport's own naming
	// scheme. tmux's is "wb-session-" + wbSessionID
	// (internal/sessionlaunch/launch.go:482,
	// internal/sessionmove/route.go:428,
	// internal/sessionmove/store.go:521,
	// internal/sessionpark/protocol.go:167,
	// internal/sessioncourier/receiver.go:121,
	// internal/sessioncourier/message.go:106,
	// internal/worktrees/session_custody.go,
	// internal/worktrees/session_park_custody.go — every one of those
	// builds or checks the identical "wb-session-"+id string today; Task 3
	// routes them all through this one method instead). [Transport.Launch]
	// derives a new terminal's own name by calling this itself, rather than
	// accepting a name from its caller (see [LaunchRequest]). herdr and
	// none have no address derivable purely from a WB session ID — herdr
	// resolves a live pane by `agent_session` match instead
	// (REQ:pane-resolved-by-session-identity-match) — so they return "".
	AddressFor(wbSessionID string) string

	// Deliver sends delivery to target. It recomputes the delivery mode
	// itself from Capabilities(), delivery.Operation and delivery.Class via
	// [ResolveDeliveryMode] — it MUST NOT trust a caller-supplied mode,
	// because none exists on [Delivery] to trust: the resolved mode could
	// otherwise go stale between a caller's own check and this call.
	// [ModeRecordOnly] MUST NOT touch a live pane at all, [ModeAdvisory]
	// MUST NOT submit (REQ:advisory-mechanism-and-newline-boundary governs
	// herdr's exact mechanism), and [ModeSubmit] is reachable only for
	// [EventSuccessorMessage] paired with [OperationMessage] on a transport
	// declaring [Capabilities.LineageSubmit] (tmux, unchanged,
	// REQ:tmux-parity-preserved) or, once Deferred work lands, for
	// [EventOwnPROutcome] paired with [OperationWake].
	//
	// The returned [Receipt] reports the mode that was actually used, which
	// MUST NOT exceed ([DeliveryModeExceeds]) what [ResolveDeliveryMode]
	// computed — a transport MUST NOT claim to have advised or submitted
	// when its own declared capabilities (or the Operation/Class pairing)
	// forbid it (REQ:none-transport-is-first-class's "a supported, expected
	// outcome... instead of failing the calling command" generalizes to
	// every transport through this contract, not only none). It MAY report
	// a strictly less binding mode: whenever target [Target.IsZero] is
	// true — there is nowhere to advise or submit into — Outcome MUST be
	// [ModeRecordOnly] regardless of what [ResolveDeliveryMode] computed.
	Deliver(ctx context.Context, target Target, delivery Delivery) (Receipt, error)
}