schema

type ActivityRecord struct {
	Action      string    `json:"action"`
	DeviceID    string    `json:"device_id"`
	OperationID string    `json:"operation_id"`
	SessionID   string    `json:"session_id,omitempty"`
	Outcome     string    `json:"outcome"` // OutcomeApplied, or "refused"
	Code        ErrorCode `json:"code,omitempty"`
}

type AgentInstanceRef struct {
	ShimPID       int   `json:"shim_pid"`
	ShimStartTime int64 `json:"shim_start_time"`
}

type ApproveReq struct {
	Session       string           `json:"session"`
	AgentInstance AgentInstanceRef `json:"agent_instance"`
	InteractionID string           `json:"interaction_id"`
	ContentHash   string           `json:"content_hash"`
	ExpiresAt     *time.Time       `json:"expires_at,omitempty"`
	// Decision is the id of the decision the owner chose, in the CLI's OWN vocabulary
	// (interaction-schema.md §3.5: spike-SB captured Codex offering accept |
	// acceptWithExecpolicyAmendment | cancel). The card labels its buttons from
	// decisions[].label and answers with the matching id; the daemon refuses an id the
	// request never offered.
	//
	// It is DELIBERATELY UNSIGNED (IS-LIFE-4). ContentHash is the signed tuple's one
	// content slot and ADR-007 D7 spends it on the interaction content, which the phone
	// echoes verbatim (IS-APR-2) and so cannot fold a choice into. The field rides inside
	// the epoch-sealed frame -- unforgeable by the relay, alterable only by the gateway,
	// which is the documented D4/D5 owner-uid residual and not a new one.
	Decision string `json:"decision,omitempty"`
}

type ComposerSendReq struct {
	Session         string `json:"session"`
	SessionInstance string `json:"session_instance,omitempty"`
	ExpectedTurn    string `json:"expected_turn,omitempty"`
	Text            string `json:"text"`
}

type Control struct {
	Op              string `json:"op"`
	EndpointID      string `json:"endpoint_id"`
	SessionID       string `json:"session_id,omitempty"`
	ProtocolVersion int    `json:"protocol_version,omitempty"`
	// BuildVersion is the daemon's internal/version.Version, carried on the hello
	// reply (E13.2). It is ADDITIVE: unlike ProtocolVersion (the wire skew gate,
	// unchanged by this field), a mismatch here is not fatal to the handshake — it
	// lets a client notice it is talking to a different-build daemon and nudge
	// `swarm daemon restart` even when the wire protocol still matches.
	BuildVersion string   `json:"build_version,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
	Generation   uint64   `json:"generation,omitempty"`
	SnapshotLen  int      `json:"snapshot_len,omitempty"`
	Cols         int      `json:"cols,omitempty"`
	Rows         int      `json:"rows,omitempty"`
	// Name is the new session label carried on a rename op (v0.5). It is re-validated
	// and sanitized server-side (sanitizeName) before it reaches the daemon, exactly
	// like the label in a launch request. Restored in the 2026-08-02 merge: the schema
	// split forked before rename landed on main and the port predated the field.
	Name string `json:"name,omitempty"`
	// Tag is the manual grouping label carried on set_tag. Empty clears it.
	Tag      string        `json:"tag,omitempty"`
	Launch   *LaunchReq    `json:"launch,omitempty"`
	Sessions []SessionView `json:"sessions,omitempty"`
	Session  *SessionView  `json:"session,omitempty"`
	Error    string        `json:"error,omitempty"`

	// Remote-tier additive fields (R-PROT.2/.3/.7, amendments D.0-A1/A3/A6/A11).
	// Every field is omitempty so an existing-shape Control serializes
	// byte-identically (GG-7); the daemon-authoritative times are pointers so a zero
	// Control emits no new key (a zero time.Time is NOT omitted by encoding/json).
	OperationID     string          `json:"operation_id,omitempty"`      // idempotency key of a remote mutating op
	InteractionID   string          `json:"interaction_id,omitempty"`    // the agent interaction being approved (A6)
	DeviceID        string          `json:"device_id,omitempty"`         // pairing device id (never trusted alone, A1)
	DeviceSig       string          `json:"device_sig,omitempty"`        // detached Ed25519 over the canonical op tuple (D4)
	Cursor          uint64          `json:"cursor,omitempty"`            // journal cursor (journal_read/journal_event)
	JournalMaxBytes int             `json:"journal_max_bytes,omitempty"` // journal_read request: opt into bounded response pages
	JournalMore     bool            `json:"journal_more,omitempty"`      // journal_read response: more pages from this atomic read follow
	IssuedAt        *time.Time      `json:"issued_at,omitempty"`         // daemon-authoritative issue time
	ExpiresAt       *time.Time      `json:"expires_at,omitempty"`        // daemon-authoritative expiry
	Approve         *ApproveReq     `json:"approve,omitempty"`           // remote approval request (A6)
	ErrorCode       ErrorCode       `json:"error_code,omitempty"`        // machine-readable refusal reason (R-PROT.7)
	Journal         []JournalRecord `json:"journal,omitempty"`           // journal records (journal_read/journal_event)
	Roster          []JournalRecord `json:"roster,omitempty"`            // live sessions as-of Cursor on a journal_read snapshot (R-JRN.4)
	FullResync      bool            `json:"full_resync,omitempty"`       // the caller's cursor fell below the retained floor
	Devices         []DeviceView    `json:"devices,omitempty"`           // paired-device roster, carried on the device_list reply
	Policy          *PolicyView     `json:"policy,omitempty"`            // remote launch policy, carried on the policy_query reply
	TargetDeviceID  string          `json:"target_device_id,omitempty"`  // device_revoke: the device to REVOKE, distinct from the caller DeviceID (A3.2)
	Pairing         *PairingControl `json:"pairing,omitempty"`           // owner-tier pairing payload (pair_start/pair_pending/pair_confirm/pair_result, A3.3-a)
	TTLSeconds      int             `json:"ttl_seconds,omitempty"`       // take_control: caller-requested control-session lifetime (seconds), clamped server-side (A5-b)
	GateToken       string          `json:"gate_token,omitempty"`        // take_control: one-shot gate token bound into the device signature via content_hash and made single-use (A5-c)
	RemoteControl   *bool           `json:"remote_control,omitempty"`    // remote_set_control: the DESIRED remote-control master state (true=on, false=manual off). Pointer so false is transmittable and a zero Control emits no key (A4)

	Terminal *TerminalSnapshot `json:"terminal,omitempty"` // server-rendered terminal snapshot, carried on terminal_snapshot (A7 slice B)

	// TerminalView is the SAME snapshot, versioned (ADR-017 T4/T4-a/T8-a). It rides the SAME
	// terminal_snapshot op beside Terminal rather than on an op of its own, which is the
	// smallest step that puts view_epoch, revision, reset, session_instance and rendered_at on
	// the wire: an old gateway ignores an unknown key, a new one prefers this body, and no
	// RemoteProfileV1 version has to move (ADR-016's profile-version coordination is parked).
	//
	// WITHOUT IT THE FIELDS WERE PRODUCED AND NEVER SENT. `RenderTerminalView` minted the epoch
	// and the daemon threw it away; a phone watching a session REPLACED under the same id read
	// the new incarnation as a seamless continuation of the old screen, which is exactly what
	// T4-a and T8-a exist to prevent (closing review, finding 5).
	TerminalView *TerminalViewV1 `json:"terminal_view,omitempty"`

	SendInput *SendInputReq `json:"send_input,omitempty"` // owner-tier one-shot steering message, carried on send_input (ADR-010 A2)

	// BodyVersion is the per-op body-version tag the R1 refusal-ops vocabulary requires
	// (playbook §6.3, ADR-017 T5): the phone binds every session_launch/composer_send/
	// operation_status/turn_interrupt/terminal_control_begin/terminal_control_end to the
	// profile version it read from RemoteProfileV1. There is no body version 0: a Control
	// that omits this key is refused identically to a wrong version, never treated as an
	// implicit "version 1".
	BodyVersion int `json:"body_version,omitempty"`

	// Wave R5 launch-preset additive fields (ADR-007 B144(b), playbook "Wave R5").
	// SessionLaunch is the session_launch body: the phone's confirmed preset selection,
	// bound into the device signature via SessionLaunchContentHash.
	SessionLaunch *SessionLaunchReq `json:"session_launch,omitempty"`
	// Presets + PresetPolicyRevision ride the launch_presets reply: exactly the
	// machine-authored list (empty custody answers empty, never an invented default,
	// ADR-007 B135) plus the revision of the policy that produced it.
	Presets              []LaunchPresetView `json:"presets,omitempty"`
	PresetPolicyRevision string             `json:"preset_policy_revision,omitempty"`
	// SubjectOperationID is operation_status's QUERY SUBJECT -- the operation being
	// asked about -- distinct from the query's own OperationID exactly as ADR-007 D7
	// separates operation_id from interaction_id: the asking op and the asked-about op
	// are different coordinates.
	SubjectOperationID string `json:"subject_operation_id,omitempty"`
	// OperationOutcome rides the operation_status reply: applied (authoritative, with
	// the session id), outcome_unknown (honest undecidability), or unknown_operation
	// (no record; never invented).
	OperationOutcome *OperationOutcomeView `json:"operation_outcome,omitempty"`
	// Wave R6 complete-chat additive fields (Mirror M2.4 / M3.1 / M3.3, ADR-009 (8)).
	// ComposerSend is the composer_send body: one structured message plus the turn it was
	// rendered against, bound into the device signature via ComposerSendContentHash.
	ComposerSend *ComposerSendReq `json:"composer_send,omitempty"`
	// TurnInterrupt is the turn_interrupt body (Wave R6 review fix-pack B7): the session
	// plus the turn the phone RENDERED the Stop against, bound into the device signature
	// via TurnInterruptContentHash. See schema/chat.go for why the op stopped being
	// bodyless.
	TurnInterrupt *TurnInterruptReq `json:"turn_interrupt,omitempty"`
	// History is the interaction_history body (M3.1, ADR-014); the reply rides the
	// existing Journal carrier plus HistoryFloor.
	History *InteractionHistoryReq `json:"interaction_history,omitempty"`
	// Detail is the interaction_detail body (M3.3, IS-CAP-2's unsigned read); the reply
	// carries exactly one Journal record whose Item is the full pre-truncation body.
	Detail *InteractionDetailReq `json:"interaction_detail,omitempty"`
	// The Wave R8 terminal-fallback bodies (ADR-017 T6). TerminalControlBegin is the
	// SIGNED begin, bound into the device signature via TerminalControlBeginContentHash;
	// TerminalInput is one UNSIGNED raw-input frame naming the generation it was
	// authorised under. ControlGeneration rides the begin's REPLY (the minted, non-
	// transferable generation) and every keepalive.
	TerminalControlBegin *TerminalControlBeginReq `json:"terminal_control_begin,omitempty"`
	TerminalInput        *TerminalInputReq        `json:"terminal_input,omitempty"`
	ControlGeneration    string                   `json:"control_generation,omitempty"`
	// HistoryFloor rides the interaction_history reply: nothing older than the returned
	// page is retained, so the phone renders a retention floor instead of a spinner.
	HistoryFloor bool `json:"history_floor,omitempty"`
	// DeviceCapability rides the launch_presets reply: the SIGNING device's own
	// authorization tier ("full"/"read_only"/"read_approve") as pinned machine-side in
	// the device registry at enrollment (round-2 fix-pack). It is the phone's only
	// honest wire source for its own tier -- capability is never read FROM the wire
	// (deviceauth's rule), but nothing forbade the machine STATING it, and without it
	// the launch screen's tier-denied state had no data source. Empty when the backend
	// exposes no capability seam: absent fact, never an invented tier.
	DeviceCapability string `json:"device_capability,omitempty"`
}

type DeviceCommandAuth struct {
	DeviceID    string    // registry lookup key; never trusted alone (A1)
	Action      string    // canonical action string (also selects the capability class)
	Machine     string    // endpoint id
	Session     string    // namespaced session id ("" for launch, which creates one)
	OperationID string    // idempotency identity; single-use, binds the signature
	ExpiresAt   time.Time // daemon-authoritative expiry; a past value is refused
	ContentHash []byte    // optional 32-byte hash binding op content (e.g. a launch spec)
	Sig         string    // detached Ed25519 signature (device_sig) over the tuple
}

type DeviceView struct {
	DeviceID   string    `json:"device_id"`
	Name       string    `json:"name"`
	Capability string    `json:"capability"`
	PairedAt   time.Time `json:"paired_at"`
}

type ErrorCode string

type InteractionDetailReq struct {
	Session string `json:"session"`
	ItemID  string `json:"item_id"`
}

type InteractionHistoryReq struct {
	Session    string `json:"session"`
	BeforeItem string `json:"before_item"`
	Limit      int    `json:"limit"`
}

type JournalRecord struct {
	Cursor    uint64       `json:"cursor"`
	SessionID string       `json:"session_id"`
	Type      string       `json:"type"`
	Group     status.Group `json:"group,omitempty"`
	// Agent is the session's agent identity (persist.Meta.AgentType), carried so the
	// phone can label a session with the CLI running it. Like Group it is omitempty
	// because most record types do not carry it: the roster snapshot does, and a bare
	// event may not. An absent agent means the record does not carry one -- readers must
	// not read the empty string as an agent named "".
	Agent string `json:"agent,omitempty"`
	// Item is one unit of the phone's chat transcript (ADR-009,
	// docs/specifications/interaction-schema.md §1 and §2). It is populated when Type is
	// "interaction" or "structured_gap", where the daemon payload IS transcript content;
	// every other type's payload stays daemon-internal, except the separately validated
	// capability-transition record below. In all cases,
	// internal/skeleton/api.go's toWireJournalRecord is the sole producer of this field.
	//
	// It is carried raw. The gateway seals and forwards items and parses none of them
	// (interaction-schema.md §10), so the item's `kind` discriminator is only ever read
	// inside the AEAD-covered plaintext and never reaches SenderKeyID or EpochID
	// (IS-LAYER-2, PB-SYNC-1). An unknown kind or an unknown field costs a consumer a skip,
	// not a decode failure (IS-COMPAT-1/-2). omitempty keeps every record type that
	// predates the field byte-identical.
	//
	// Documenting it is a PROCEDURAL obligation, not a fenced one: GG-7's drift check
	// (internal/protocol/protocolmd_test.go) reflects Control, SessionView, LaunchReq and
	// TerminalSnapshot only, so no build fails on a missing row. Its row lives in
	// docs/specifications/protocol.md under "The JournalRecord message" and was written in
	// the same change as this field.
	Item json.RawMessage `json:"item,omitempty"`
	// Name is the session's user-given label (persist.Meta.Name), carried so the phone can
	// head a row with what a person called the session rather than the random local id.
	// Like Agent it is omitempty because most record types do not carry it, and because most
	// sessions are never labelled at all: an absent name means the record carries none --
	// readers must fall back to the id and must never fabricate a label (ADR-007 B135).
	//
	// A daemon predating this field simply omits the key, and the phone then renders exactly
	// what it renders today (mobile/namefacade_test.go pins that compatibility).
	Name string `json:"name,omitempty"`
	// Capabilities is the session's daemon-authored capability record (ADR-017 T2),
	// carried on ROSTER records and on the cursor-ordered "capability_transition" event.
	// A transition carries its own historical value; it is never reconstructed from a
	// current roster lookup. The phone reads this record rather than inferring support.
	//
	// It is a POINTER with omitempty because absence is wire-distinguishable ON PURPOSE
	// (T2-a): "no record" and terminal_fallback=false take ONE code path, and a reader
	// that could not tell them apart would have to guess about every pre-R8 session. A
	// daemon predating this field simply omits the key, and the phone then renders the
	// status card, which is the honest answer for a session whose machine cannot say what
	// it supports.
	Capabilities *SessionCapabilities `json:"capabilities,omitempty"`
	// TS is the daemon's own stamp of when this record was appended (journal.Record.TS),
	// carried so the Activity screen can show a time that a MACHINE clock produced
	// (phone-refit-playbook W7.4). A roster record is never appended and carries none.
	// omitzero: a zero stamp is absent on the wire, never the epoch, and every record written
	// before this field existed serialises byte-identically.
	TS time.Time `json:"ts,omitzero"`
	// StateSince is the MACHINE's stamp of when the session entered its CURRENT state
	// (persist.Meta.EffectiveGroupEnteredAt()), carried on roster records and the four
	// journalworthy transitions so an Inbox row can say how long the session has been in the
	// state it shows (W7.1). It is the session's stamp, not this record's, and it is not
	// LastActivity, which moves only at launch and exit; a record whose meta carried no
	// instant omits it, for TS's reason.
	StateSince time.Time `json:"state_since,omitzero"`
}

type JournalReseed struct {
	// Roster is the machine's COMPLETE live session set as of Cursor. It replaces the
	// phone's cached set; a session absent here has gone away while the phone was not
	// listening, and leaving it behind is how a killed session stays on the roster forever.
	Roster []JournalRecord `json:"roster"`
	// Events are the journal records after the phone's last known cursor and up to Cursor,
	// applied ON TOP of Roster -- the "atomic roster+events snapshot" of PB-SYNC-2.
	Events []JournalRecord `json:"events"`
	// Cursor is the snapshot boundary the roster is current as of. It REPLACES the phone's
	// cache cursor (PB-SYNC-8); it is never merged, never max'd.
	Cursor uint64 `json:"cursor"`
	// DiscardRecoveryToken echoes the exact token from the sealed roster-refresh command
	// whose explicit mailbox discard requested this fast-forward snapshot. An absent or
	// different token is an ordinary reseed and cannot complete durable discard recovery.
	DiscardRecoveryToken string `json:"discard_recovery_token,omitempty"`
}

type LaunchPresetView struct {
	ID          string            `json:"id"`
	DisplayName string            `json:"display_name"`
	Agent       string            `json:"agent"`
	Root        string            `json:"root"`
	Options     map[string]string `json:"options,omitempty"`
	Worktree    bool              `json:"worktree,omitempty"`
	Revision    string            `json:"revision"`
}

type LaunchReq struct {
	Agent         string            `json:"agent"`
	Name          string            `json:"name,omitempty"` // optional user-provided session label; re-validated + sanitized server-side (E6.6)
	Cwd           string            `json:"cwd"`
	Options       map[string]string `json:"options"`
	Env           []string          `json:"env"`
	Cols          int               `json:"cols"`
	Rows          int               `json:"rows"`
	InitialPrompt string            `json:"initial_prompt"`
	// Worktree opts this session into launch-time git-worktree isolation (Epic 12):
	// the daemon runs the session's agent in a fresh isolated worktree/branch. It is
	// carried to the daemon's PreLaunch/PreDelete hooks by the assembly (skeleton),
	// which registers worktree.Create/Remove gated on this flag; the protocol layer
	// only transports it.
	Worktree bool `json:"worktree,omitempty"`
	// SpawnedFrom, when non-empty, is the LOCAL id of the session that requested this
	// launch (ADR-010 D4), mirroring the ResumedFrom pattern: a daemon-launched session
	// is no process-group descendant of its spawner (S-4), so lineage must be explicit
	// metadata. SpawnIntent tags the link and is one of SpawnIntentHandoff or
	// SpawnIntentDelegate, valid only alongside a SpawnedFrom. Both omitempty: an
	// un-lineaged launch is byte-identical to the pre-lineage shape.
	SpawnedFrom string `json:"spawned_from,omitempty"`
	SpawnIntent string `json:"spawn_intent,omitempty"`
	// Supervision is the supervision mode of a handoff child (ADR-010 Amendment 3
	// C1): one of SupervisionPassive, SupervisionManual or SupervisionNone, valid only
	// alongside SpawnIntentHandoff -- a mode names how the SOURCE follows its child,
	// so it is meaningless on any other launch. omitempty: an unsupervised launch is
	// byte-identical to the pre-supervision shape.
	Supervision string `json:"supervision,omitempty"`
}

type OperationOutcomeView struct {
	State     string `json:"state"`
	SessionID string `json:"session_id,omitempty"`
}

type PairingControl struct {
	Capability   string     `json:"capability,omitempty"`
	TTLSeconds   int        `json:"ttl_seconds,omitempty"`
	QR           string     `json:"qr,omitempty"`
	RendezvousID string     `json:"rendezvous_id,omitempty"`
	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
	// ShortCode is the pair_start reply's human-typeable spelling of the same ceremony
	// (ADR-007 B140). Additive and omitempty on both sides of the version skew.
	ShortCode  string   `json:"short_code,omitempty"`
	SAS        []string `json:"sas,omitempty"`
	DeviceName string   `json:"device_name,omitempty"`
	Allow      bool     `json:"allow,omitempty"`
	DeviceID   string   `json:"device_id,omitempty"`
	Name       string   `json:"name,omitempty"`
	// Failure is why a pair_result enrolled nothing (ADR-007 B71(1)): one code from
	// protocol.PairFailure's closed vocabulary, empty on success. It is a CODE and never
	// the daemon's error text -- the pairing path parses attacker-influenced bytes, and
	// the client normalises anything it does not recognise, so no wire-supplied string
	// can reach the owner's terminal.
	Failure string `json:"failure,omitempty"`
}

type PolicyView struct {
	AllowedCwdRoots []string `json:"allowed_cwd_roots"`
}

type PushPrefs struct {
	Version    uint64 `json:"version"`
	NeedsInput bool   `json:"needs_input"`
	Finished   bool   `json:"finished"`
}

type ReconcileRecord struct {
	Machine          string `json:"machine"`            // endpoint id the authorities belong to
	EpochID          uint32 `json:"epoch_id"`           // epoch the content key (and both seq buckets) belong to
	InboundHighWater uint64 `json:"inbound_high_water"` // (a) the gateway's durable inbound accepted high-water (PB-GW-1)
	JournalCeiling   uint64 `json:"journal_ceiling"`    // (b) highest seq ISSUED on the shared journal/terminal bucket
	ReplyCeiling     uint64 `json:"reply_ceiling"`      // (b) highest seq ISSUED on the command-reply bucket
	GrantEpoch       uint32 `json:"grant_epoch"`        // (c) the daemon's grant-issuance epoch
	GrantSeq         uint64 `json:"grant_seq"`          // (c) the daemon's grant-issuance seq
	IssuedAt         int64  `json:"issued_at"`          // unix millis, the SAME value the envelope header carries

	// Profile is the machine's sealed RemoteProfileV1 (ADR-017 T5), riding this EXISTING
	// record rather than a new mailbox frame kind. It carries no omitempty for the same
	// reason as every authority above: a struct-typed field is never "empty" to
	// encoding/json anyway (omitempty would be a silent no-op here), but the tag is kept
	// off deliberately so a reader never mistakes it for a field that may legitimately be
	// absent -- enforced as a source-level convention by
	// TestReconcileRecord_ProfileFieldTag_NoOmitempty.
	Profile RemoteProfileV1 `json:"profile"`
}

type RemoteCommand struct {
	DeviceCommandAuth
	// PushPrefs is the push_prefs body (PB-PUSH-8). It is deliberately NOT bound by
	// ContentHash the way a launch spec is, and the difference is load-bearing: a launch
	// spec is forwarded through the gateway IN CLEARTEXT (Control.Launch), so the hash is
	// what stops the gateway altering it, whereas a preference body never leaves the
	// gateway -- it arrives sealed under the epoch content key, which the relay cannot
	// forge, and the gateway is itself the custodian that decides delivery. A hash it
	// recomputed against its own file would protect nothing it could not simply overwrite.
	PushPrefs *PushPrefs `json:"push_prefs,omitempty"`
	// Approve is the approve body (IS-LIFE-4): the ApproveReq the gateway reconstructs
	// Control.Approve from. It is the ONE wire field this spec adds, and it adds no signed
	// action -- ActionApprove already exists.
	//
	// It is bound to the signature the way a launch spec is, and only in part. ContentHash is
	// the digest of the INTERACTION CONTENT the phone echoes verbatim (IS-APR-2, ADR-007 D7),
	// so a gateway that swaps the hash to redirect the approval breaks the signature. The
	// remaining fields are not covered, and do not need to be: agent_instance, interaction_id
	// and expires_at are checked against the daemon's own stored binding tuple, so altering
	// any of them yields CodeStaleApproval rather than a misapplied decision. The DECISION is
	// deliberately unsigned (IS-LIFE-4) -- the signed tuple has one content slot and D7 spends
	// it on the content -- riding instead inside the epoch-sealed frame, unforgeable by the
	// relay and alterable only by the gateway, which is the documented D4/D5 owner-uid
	// residual and not a new one.
	Approve    *ApproveReq `json:"approve,omitempty"`
	Launch     *LaunchReq  `json:"launch,omitempty"`
	GateToken  string      `json:"gate_token,omitempty"`  // take_control: one-shot gate token; the gateway reconstructs Control.GateToken from it. Bound into the signature via ContentHash=SHA256(GateToken), not carried in the signed tuple.
	TTLSeconds int         `json:"ttl_seconds,omitempty"` // take_control: caller-requested control-session lifetime (seconds), clamped server-side. Not signed (cosmetic like Cols/Rows).
	// ResyncCursor is journal_resync's from-cursor: the boundary the phone's session cache
	// currently stands at. The gateway's journal_read(from) answers with the complete roster
	// as-of a new boundary plus the events in between, which is exactly JournalReseed's
	// {Roster, Events, Cursor} -- so without it the gateway must read from 0 and re-send
	// every event the machine has ever journalled to repair one hole.
	//
	// Not signed, like TTLSeconds, and it does not need to be: the frame is sealed under the
	// epoch content key, which the relay cannot forge, and the worst a wrong value can do is
	// make the reseed carry more or fewer events than needed -- the roster it replaces the
	// cache with is complete either way.
	ResyncCursor uint64 `json:"resync_cursor,omitempty"`
	// RosterOnly distinguishes an authoritative roster refresh from PB-SYNC-2's full
	// journal repair. The gateway still reads one atomic daemon snapshot, but publishes
	// only its roster at ResyncCursor, leaving every later backlog event admissible on the
	// phone. Additive + omitempty keeps ordinary resync frames byte-compatible.
	RosterOnly bool `json:"roster_only,omitempty"`
	// DiscardedBacklog is the explicit recovery proof attached to a roster-only refresh
	// after the phone has successfully discarded its own stale relay mailbox generation
	// and durably adopted the relay's replacement cursor. It tells the gateway to publish
	// the bounded roster reseed at the daemon snapshot's FINAL cursor, so the next live
	// journal record is contiguous with the phone's new authoritative boundary. A healthy
	// roster refresh omits it and keeps ResyncCursor, preserving unread backlog.
	//
	// The bit is meaningful only with RosterOnly. It is sealed under the epoch content key
	// with the rest of RemoteCommand, so the relay cannot invent destructive recovery.
	DiscardedBacklog bool `json:"discarded_backlog,omitempty"`
	// DiscardRecoveryToken is the opaque durable recovery generation the phone created
	// BEFORE asking the relay to delete anything. A supporting gateway echoes it only on
	// the authoritative fast-forward JournalReseed that answers this command. The phone
	// clears its pending recovery only when that exact echo commits contiguously.
	DiscardRecoveryToken string `json:"discard_recovery_token,omitempty"`
	// SessionLaunch is the session_launch body (Wave R5): the phone's confirmed preset
	// selection. It rides beside the signed tuple under launch's own rule -- the body is
	// bound into the signature via ContentHash = SessionLaunchContentHash(SessionLaunch),
	// which the daemon recomputes from the forwarded body, so a gateway that alters the
	// preset id, revision or prompt breaks the signature.
	SessionLaunch *SessionLaunchReq `json:"session_launch,omitempty"`
	// TerminalControlBegin is the terminal_control_begin body (ADR-017 T6). It rides
	// beside the signed tuple under launch's own rule -- bound into the signature via
	// ContentHash = TerminalControlBeginContentHash(it), recomputed daemon-side, so a
	// gateway that re-points a valid begin at another session, another INCARNATION or
	// another profile breaks the signature.
	TerminalControlBegin *TerminalControlBeginReq `json:"terminal_control_begin,omitempty"`
	// TerminalInput is the terminal_input body (ADR-017 T6): one UNSIGNED raw-input frame.
	// It carries no content hash because the op carries no device signature at all --
	// sealing under the epoch content key is already proof the asker is the paired device,
	// and the authority that matters is the generation, which the daemon re-evaluates per
	// frame alongside the kill switch, the device registration and the capability record.
	TerminalInput *TerminalInputReq `json:"terminal_input,omitempty"`
	// ControlGeneration rides terminal_control_keepalive, which has no body of its own:
	// the generation IS the frame.
	ControlGeneration string `json:"control_generation,omitempty"`
	// SubjectOperationID is operation_status's query subject (the asked-about op), copied
	// by the gateway onto Control.SubjectOperationID. It IS bound into the signature
	// (round-2 fix-pack, MAJOR 2): ContentHash = OperationStatusContentHash(subject),
	// recomputed daemon-side from this forwarded field, so a gateway that re-points a
	// valid signature at another operation id breaks it. The earlier reading ("the worst
	// a swapped subject yields is the honest outcome of a different op this device
	// already owns the ids of") was wrong across devices: operation_status is READ class,
	// so ANY paired tier could read back another operation's namespaced session id.
	SubjectOperationID string `json:"subject_operation_id,omitempty"`
	// ComposerSend is the composer_send body (Wave R6, IS-LIFE-5): the structured message
	// the phone authored, riding beside the signed tuple under launch's own rule -- the
	// body is bound into the signature via ContentHash = ComposerSendContentHash(it),
	// which the daemon recomputes from the forwarded body, so a gateway that alters the
	// text or re-points expected_turn breaks the signature.
	ComposerSend *ComposerSendReq `json:"composer_send,omitempty"`
	// TurnInterrupt is the turn_interrupt body (Wave R6 review fix-pack B7). The op was
	// bodyless until finding B7 proved a Stop with no turn coordinate lands the cancel
	// sequence in whatever turn is current when it ARRIVES. The body is bound into the
	// signature via ContentHash = TurnInterruptContentHash(it), recomputed daemon-side,
	// on composer_send's exact pattern.
	TurnInterrupt *TurnInterruptReq `json:"turn_interrupt,omitempty"`
	// History and Detail are the two UNSIGNED M3 read bodies (ADR-014). They carry no
	// signature binding because the ops carry no device signature at all -- sealing under
	// the epoch content key is already proof the asker is the paired device, and the
	// daemon gates them on the negotiated journal capability and the kill switch
	// (handleInteractionHistory / handleInteractionDetail), exactly as journal_read is.
	History *InteractionHistoryReq `json:"interaction_history,omitempty"`
	Detail  *InteractionDetailReq  `json:"interaction_detail,omitempty"`
	// BodyVersion binds this command to the R1 profile version the phone selected
	// (RemoteProfileV1.AcceptedBodyVersions, ADR-017 T5 / playbook §6.3: "every durable
	// semantic mutation binds the selected profile ... signs a canonical hash of its full
	// body"). It rides UNCHANGED from here through the gateway to Control.BodyVersion --
	// the gateway is a blind conduit and does not alter it. NOT YET content-hash bound (a
	// compromised gateway could alter it in flight); that gap closes as each R1 op's real
	// body lands and folds BodyVersion into ContentHash. There is no body version 0: an
	// absent value is refused identically to a wrong one.
	BodyVersion int `json:"body_version,omitempty"`
}

type RemoteProfileV1 struct {
	Version                  int            `json:"version"`
	AcceptedActions          []string       `json:"accepted_actions"`
	AcceptedBodyVersions     map[string]int `json:"accepted_body_versions"`
	InteractionSchemaVersion int            `json:"interaction_schema_version"`
	TerminalViewVersion      int            `json:"terminal_view_version"`
	CapabilityRecordVersion  int            `json:"capability_record_version"`
	// The three ADR-016 W1 fields: the machine's authoritative relay TLS policy, joining
	// this same R1 profile version rather than bumping it (ADR-016:194). RelayTLSPolicy and
	// RelaySPKIPin are INDEPENDENT -- a pin's presence never implies pinned_spki and a
	// pin's absence never implies webpki -- and none of the three carries omitempty: this
	// struct rides EVERY reconcile, and an absent key must stay distinguishable from a
	// legitimately-zero one (W9 step 6's compatibility-pin withdrawal depends on exactly
	// that distinction being resolvable).
	RelayTLSPolicy string `json:"relay_tls_policy"`
	RelayHost      string `json:"relay_host"`
	RelaySPKIPin   []byte `json:"relay_spki_pin"`
	// The three ADR-017 T5 TerminalView bounds: "size, line and rate bounds declared in
	// the remote profile, so a phone knows the ceiling it is rendering under rather than
	// discovering it". Zero on any of them means CLAMP TO THE PHONE'S CONSERVATIVE
	// BUILT-IN, never "unlimited" (T5-a), and none carries omitempty for the same reason
	// nothing else here does. TerminalViewBounds() is the one resolver.
	TerminalViewMaxLineBytes int `json:"terminal_view_max_line_bytes"`
	TerminalViewMaxRows      int `json:"terminal_view_max_rows"`
	TerminalViewMaxRateHz    int `json:"terminal_view_max_rate_hz"`
}

type SendInputReq struct {
	Text   string `json:"text,omitempty"`
	Submit bool   `json:"submit,omitempty"`
	Key    string `json:"key,omitempty"`
}

type SessionCapabilities struct {
	Provider         string `json:"provider"`          // adapter identity: claude, codex, opencode, agy, ...
	ProviderVersion  string `json:"provider_version"`  // the DETECTED version of the installed CLI
	AdapterRevision  string `json:"adapter_revision"`  // the revision of the Swarm adapter that produced the record
	SessionInstance  string `json:"session_instance"`  // the per-incarnation identifier every generation and snapshot binds to (ADR-017 T8-a)
	StructuredChat   bool   `json:"structured_chat"`   // true only when every T3 row passes against provider_version
	TerminalFallback bool   `json:"terminal_fallback"` // whether the sanitized terminal view may be offered at all
	TerminalControl  bool   `json:"terminal_control"`  // whether raw input may be entered on that view (ADR-017 T6-b)
	Interrupt        bool   `json:"interrupt"`         // whether a semantic interrupt reaches the current turn
}

type SessionLaunchReq struct {
	PresetID string `json:"preset_id"`
	// PresetRevision is the staleness binding (playbook:447-448): the phone echoes
	// exactly the revision it displayed, so a machine-side re-authoring between the
	// list and the confirm answers stale_preset instead of silently launching
	// different policy.
	PresetRevision string `json:"preset_revision"`
	InitialPrompt  string `json:"initial_prompt,omitempty"`
	Cols           int    `json:"cols,omitempty"`
	Rows           int    `json:"rows,omitempty"`
}

type SessionView struct {
	EndpointID     string        `json:"endpoint_id"`
	ID             string        `json:"id"` // namespaced: <endpoint_id>/<local>
	Agent          string        `json:"agent"`
	Name           string        `json:"name,omitempty"` // user-provided label; empty (or absent, from an older daemon) falls back to Agent at display
	Tag            string        `json:"tag,omitempty"`  // user-assigned grouping label; empty means untagged
	Cwd            string        `json:"cwd"`
	Status         status.Status `json:"status"`           // the three raw dims
	Group          status.Group  `json:"group"`            // precomputed server-side (E6.9)
	GroupEnteredAt time.Time     `json:"group_entered_at"` // when the session entered Group; drives newest-first ordering
	LastActivity   time.Time     `json:"last_activity"`
	CreatedAt      time.Time     `json:"created_at"`
	Summary        string        `json:"summary"` // V-4 one-line last-output summary
	// SpawnedFrom / SpawnIntent expose the session's lineage (ADR-010 D4) so the
	// roster can show where a session came from. Both are omitempty: an ordinary
	// session's row serializes exactly as it did before the fields existed.
	SpawnedFrom string `json:"spawned_from,omitempty"`
	SpawnIntent string `json:"spawn_intent,omitempty"`
	// BackendPlanError is the persisted reason this session launched with no backend
	// although its adapter declared one (persist.Meta.BackendPlanError): the agent's
	// PTY runs but nothing serves the attach channel. Surfaced on the roster so the
	// degradation is visible where the user looks (`swarm ls`, the TUI) instead of
	// one daemon.log line. omitempty: a healthy row serializes exactly as it did
	// before the field existed, and an older daemon simply never populates it.
	BackendPlanError string `json:"backend_plan_error,omitempty"`
	// Supervision is the persisted supervision mode of a handoff child (ADR-010
	// Amendment 3 C1/C5) and SupervisionPending reports that an attention event of
	// that child awaits its source: LIVE daemon state, sampled at stamp time exactly
	// like RemoteControlled, so the board can show a supervisor pending or gone. Both
	// omitempty: an unsupervised row serializes exactly as it did before the fields
	// existed.
	Supervision        string `json:"supervision,omitempty"`
	SupervisionPending bool   `json:"supervision_pending,omitempty"`
	// RemoteControlled reports that a PAIRED DEVICE is driving this session: it holds
	// the remote-tier controller lease, OR it sent a message recently
	// (skeleton.phoneRecentlyActive). The second clause is what keeps the field
	// meaningful once take-control leaves the product -- composer_send never needed a
	// lease, so a lease-only answer would be false for every phone there is.
	//
	// THE CLAIM THAT USED TO STAND HERE IS WITHDRAWN. It read: "a TUI attach and a phone
	// take_control compete for the SAME single shim subscriber slot, so the two are
	// mutually exclusive and no live in-attach indicator is possible". M0.1 disproved it
	// (docs/verification/mirror-m0.md): production runs two protocol Servers over one
	// coreAPI with separate lease maps, and coreAPI.Attach subscribes to the SHARED
	// per-session tap, so the shim's single-subscriber slot is claimed once and both live
	// streams survive in both orders. The roster row is still where this is shown, but
	// because a live in-attach indicator needs a side channel attach.Session does not
	// have -- not because the two states cannot coexist.
	//
	// omitempty: an uncontrolled row serializes exactly as it did before the field
	// existed, so the released 0.8.0 gateway -- which relays these frames verbatim
	// and is untouched by this change -- sees no new bytes.
	RemoteControlled bool `json:"remote_controlled,omitempty"`
	// RemoteActivityAt is WHEN a paired device last delivered a message to this session,
	// carried only while that instant is still inside the daemon's horizon
	// (skeleton.phoneActiveHorizon). It is what the terminal's marker SAYS -- "phone sent
	// 09:41" -- and it is an instant rather than another flag because the row has to state
	// an EVENT: a bare noun sitting beside "supervisor pending" reads as a CONDITION, "a
	// phone is on this session", which is precisely the presence claim nobody on this wire
	// measures (conversation surface, plan G.5).
	//
	// A POINTER with omitempty, like Capabilities and for the same reason in a different
	// key: encoding/json does not omit a zero time.Time, so a value field would stamp
	// "0001-01-01T00:00:00Z" onto every row that has never seen a phone. Absent means no
	// message is in the window -- there is no in-band way to say "never" as opposed to
	// "not lately", and the marker needs no such distinction because both draw nothing.
	RemoteActivityAt *time.Time `json:"remote_activity_at,omitempty"`
	// Capabilities is the daemon-authored per-session capability record (ADR-017 T2): a
	// pointer with omitempty, so an absent record (an older daemon, or a session the
	// daemon has not stamped yet) is wire-distinguishable from a stamped record that says
	// structured_chat=false. The phone renders from this record and infers nothing from
	// whether a transcript happens to be empty (T2 rule 3).
	Capabilities *SessionCapabilities `json:"capabilities,omitempty"`
}

type TerminalControlBeginReq struct {
	Session         string     `json:"session"`
	SessionInstance string     `json:"session_instance"`
	Profile         int        `json:"profile"`
	ExpiresAt       *time.Time `json:"expires_at,omitempty"`
}

type TerminalInputReq struct {
	Session           string `json:"session"`
	SessionInstance   string `json:"session_instance"`
	ControlGeneration string `json:"control_generation"`
	Bytes             []byte `json:"bytes"`
}

type TerminalSnapshot struct {
	Session string   `json:"session"` // namespaced session id the snapshot is for
	Lines   []string `json:"lines"`   // sanitized plain-text grid rows, top to bottom
	Cols    int      `json:"cols"`    // grid width the snapshot was rendered at
	Rows    int      `json:"rows"`    // grid height the snapshot was rendered at
}

type TerminalViewBounds struct {
	MaxLineBytes int
	MaxRows      int
	MaxRateHz    int
}

type TerminalViewV1 struct {
	Session         string    `json:"session"`
	SessionInstance string    `json:"session_instance"` // T8-a: which incarnation this screen belongs to
	ViewEpoch       uint64    `json:"view_epoch"`       // minted per render-loop start (T4-a)
	Revision        uint64    `json:"revision"`         // strictly increasing within one epoch
	Reset           bool      `json:"reset"`            // true on the FIRST snapshot of every epoch, on every path
	Cols            int       `json:"cols"`
	Rows            int       `json:"rows"`
	Lines           []string  `json:"lines"`       // machine-sanitized, one string per grid row (vt.SnapText)
	RenderedAt      time.Time `json:"rendered_at"` // the MACHINE's clock: T4-b's staleness is derived from the snapshot's own age
}

type TurnInterruptReq struct {
	Session      string `json:"session"`
	ExpectedTurn string `json:"expected_turn"`
}