Integrate with Herdr

Herdr support is optional and host-dependent. When the host does not provide it, xcsh terminal operation is unaffected.

How is the host protocol negotiated?

The integration checks the available socket protocol and media or graphics capabilities before it requests a workspace. Missing negotiation support leaves ordinary xcsh terminal operation intact.

How is a conversation-owned workspace launched?

A workspace is tied to the conversation identity supplied at startup. Terminal-management actions create or address panes within that workspace, and lifecycle reporting stays anchored to the same startup context. Do not reuse an unrelated workspace merely because its socket is reachable.

How do I recover from socket failure?

Connection and framing failures surface as integration diagnostics. The client must not open an inbound listener as a fallback. Close conversation-owned resources through the supported lifecycle and preserve unrelated Herdr workspaces.

What lifecycle state does xcsh publish?

xcsh publishes native turn phases rather than inferring completion from terminal idleness or process exit. With a supported Herdr protocol through 26 and the advertised agent_turn_journal capability, a tracked execution publishes a persisted session/turn identity and a bounded semantic result to Herdr’s durable journal. The existing 80-character metadata preview remains display-only and is never completion evidence. Commentary, prompt content, tool data, and failed or cancelled partial output are excluded.

External execution driver contract

The supported producer is the normal xcsh executable launched by Herdr’s execution backend; it is not a mock or a no-provider/offline actor. For a journal-tracked invocation, that backend must inject the exact allocated HERDR_EXECUTION_ID and decimal safe-integer HERDR_EXECUTION_GENERATION into the child environment before it starts xcsh.

xcsh never guesses a generation: without both values it retains ordinary pane lifecycle reporting but emits no semantic journal event. A continuation must be launched with its newly allocated generation.

Protocol 26 is the current producer-native contract. Herdr injects a one-time HERDR_NATIVE_CAPABILITY into the child. xcsh includes it only in authenticated turn-report and action requests; it is never written to the session journal, logs, diagnostics, or receipts. Herdr does not authorize actions until the first starting report has been durably journaled and bound to the owned PTY, pane, session, generation, and turn.

Each semantic report has a five-second deadline. xcsh retries exactly once only when timeout, EOF, or a transport error leaves admission ambiguous. The retry preserves the method and complete semantic payload and changes only the transport request ID. Either correlated receipt marks the event delivered; protocol, validation, malformed-response, and explicit remote errors are definitive and are not retried. Degraded tracking is shown only after both ambiguous attempts fail.

The producer wire shapes align with Herdr PR #49 at cancellation-settlement commit 2c838cf545ed06439b4988cedb3e044f1d436264, starting-replay recovery commit edd5611cfd7685c0f069f244ceee0ac6c0a0678e, and native-argv alignment commit 3397302960593a552fb37ceb71053cf99f2619a3. Those commits are an integration contract under independent review, not released-backend evidence.

After that registration, xcsh polls agent.turn.action.get with the same immutable provenance. A cancel action dismisses an active managed UI prompt and calls the real AgentSession abort path. xcsh persists the requested action and local safe point before sending the exact agent.turn.action.ack; it emits cancelled only after Herdr confirms that safe point. A lost ACK response is retried with the same action ID and revision, including after reporter restart. A backend timed_out action never triggers a late abort. PTY exit alone is not semantic cancellation.

Session shutdown releases pane authority. It does not convert an unfinished turn into a successful completion.

Producer-native acceptance driver

xcsh lifecycle --json prints the version 3 machine-readable producer contract. To execute a source or installed producer check, supply a fresh absolute session directory, a normally configured model, and one scenario:

xcsh lifecycle --json \
  --scenario await-continue \
  --model openai-codex/gpt-5.6-luna \
  --session-dir /absolute/fresh/xcsh-lifecycle-session

Supported scenarios are success, failure, await-continue, cancel, managed-cancel, managed-working-cancel, and reply-loss-replay. The driver first uses the prompt-free JSON session contract to persist one canonical 16-character lowercase hexadecimal session header, then reopens that exact path in an ordinary interactive xcsh child. It generates a random mode-0600 fixture for successful reads. await-continue pauses in the real ExtensionUiController input surface before the configured model runs; cancel sends SIGINT through PtySession.interrupt() and requires xcsh’s native cancelled transition. managed-cancel uses a local protocol-26 control fixture to request the action and requires the executable child to acknowledge its safe point before its native cancelled report. That fixture validates the producer adapter only; it is not evidence for Herdr’s durable action journal, manager generation replacement, or consumer deduplication. managed-working-cancel requests the same cooperative action after the real child reports working, without opening the acceptance prompt, and verifies cancellation through the active AgentSession path.

The reply-loss scenario owns a temporary local protocol-26 socket that acknowledges ordinary reporter traffic but drops both bounded agent.turn.report attempts. xcsh creates and persists the semantic event before transport, runs the configured provider and read tool, then a second xcsh process resumes the exact session path. The scenario passes only when the reporter redelivers the byte-equivalent execution, pane, session, turn, generation, event revision, and state fields. The socket never authors a lifecycle frame or substitutes an offline model.

The receipt’s evidenceClass is source_native_child. This proves the measured source or executable behavior only; the Control Manager remains responsible for its own admission, authenticated execution binding, generation changes, consumer receipts, and installed-artifact acceptance. The command does not install or release xcsh or Herdr and does not change normal launch defaults.

The verified contract is:

Concern	xcsh signal	Herdr disposition
Session start and identity	Persisted native session ID/path	Herdr resume reference plus stable semantic session identity.
Turn start/progress	Persisted UUID and normalized turn_phase	starting/working journal events with producer revision and server revision.
Waiting for input/approval	awaiting_user and closed prompt kind	waiting_input with fixed safe reason; private prompt content is excluded.
Successful completion	Settlement-aware idle after agent_end	completed with at most 8,000 UTF-8 bytes and a matching SHA-256 digest.
Failure/cancellation	error or cancelled	Distinct terminal state and bounded safe reason; no partial result.
Managed cancellation	Persisted action receipt, Extension UI signal, and AgentSession.abort()	Authenticated safe_point precedes and is linked to the native cancelled report.
Resume/fork	Session events and persisted custom turn entries	Resume preserves identity; unfinished recovered work becomes interrupted; fork has separate session lineage.
Reconnect/order	Serialized queue and persisted event revision	Exact duplicates are idempotent; stale/conflicting revisions fail; terminal state is immutable.
Application exit	session_shutdown	Active turn becomes interrupted, then pane authority is released; never success.

The protocol-26 native-interaction update is tracked by issue #4161; its producer lifecycle foundation is tracked by issue #3791 and issue #3768. The active protocol and lifecycle behavior is described on this page; obsolete delivery checklists are not part of the runtime contract.

Herdr lifecycle reconciliation is tracked by issue #5 in the F5 Herdr fork. Current source already recognizes the exact ("herdr:xcsh", "xcsh") resume pair; deployed build provenance and live resume/fork acceptance remain required before feature acceptance.

Treat the negotiated protocol and the pane lifecycle as separate checks. First confirm that the Herdr socket and protocol version are compatible, then launch one conversation-owned workspace and observe its published state through exit. xcsh owns only workspaces it created for that conversation; it must not close unrelated panes. After a forced socket failure, reconnect and verify that stale workspace state is reconciled before another launch.