08 — IPC Schema (signaltty/1)

Transport: Unix domain socket at $XDG_RUNTIME_DIR/signaltty/signaltty.sock (mode 0700 dir, 0600 socket, owned by user). Framing: newline-delimited JSON (JSONL), one request per line, one response per line on the same connection; server→client events are JSONL messages with type: "event". Binary PTY data inside events is base64. Max line 16 MiB (PTY bursts are chunked).

Envelope

Request:

Response (ok):

Response (error):

Event:

Rules: protocol mismatch → BAD_PROTOCOL error, connection stays open. Unknown method → UNKNOWN_METHOD. Unknown fields ignored (forward compat); present-but-mistyped fields → BAD_PARAMS (missing and explicit null still mean "absent" for optionals). Every mutating result returns opaque ids. seq is a monotonic server counter; clients can subscribe {from_seq} to replay.

Methods

until accepts any lifecycle or attention state, plus seen and attention_cleared; a nonempty array matches any alternative in caller order. Without after, an already matching current state succeeds immediately.

task.start requires agent or argv (else BAD_PARAMS) and runs cap → base → worktree → spawn synchronously: over-cap starts are refused with RATE_LIMITED before creating anything. Validation and base/worktree failures before the checkout exists return synchronous errors and create no task. Once the checkout exists, workspace/tab/parent/spawn failures persist a failed task and leave its worktree available for inspection or discard. The error includes details: {task_id, stage}. Background ready-wait and prompt-write failures also persist failed tasks with {stage: ready_timeout|submit_refused, …} evidence (ready_timeout adds screen_tail, the pane's last screen lines). The background step waits for the worker pane to reach idle/done (default ready_timeout_s: 30), writes the composed prompt with submit_delay_ms (default 300, the same paste/Enter delay as pane.submit), and runs the same activity gate: a newer working or blocked transition within stall_timeout_s (default 5) moves the task to working; a stall (after one Enter retry halfway through the gate) parks it at input_required with {reason: submit_unconfirmed, stage: activity_gate}, and the worker turning working later resumes it. Closing a worker from task.finish/task.cancel clears its attention; any pane exit drops input_required/permission_required to unread. A repeated client_request_id returns the existing task and pane instead of creating another; without it retries create new tasks. The merge target defaults to the recorded target_branch; when the start ran on a detached HEAD an explicit target_ref is required at finish, and the resolved target must be the branch currently checked out in the source repo (BAD_PARAMS with details: {expected, actual} otherwise).

pane.submit rechecks decisions immediately before its delayed Enter. If a permission request or pending decision arrived after paste, it returns AGENT_BUSY with details: {stage: "delayed_enter", paste_delivered: true} without writing Enter. The pasted text is already in the worker input box; inspect and resolve the decision before sending more input. Automatic Enter retries hold the same store read guard for the decision check and Enter write. For a task's background first submit, a refusal after paste uses recoverable input_required rather than failing the task. A current decision is recorded as decision_required; when no decision remains, existing submit-unconfirmed recovery applies. The pane's decision remains unanswered. If a decision arrives after Enter but before submit confirmation, the task commit preserves input_required and its decision_required evidence, for both the background first prompt and a follow-up.

task.wait takes exactly one of task_id / context_id (both or neither → BAD_PARAMS); until accepts task states plus the pseudo-states terminal (any of completed/failed/canceled/rejected) and settled (terminal OR input_required, the default). A context wait ends when every task in it matches (an empty context matches immediately); unknown tasks → NO_SUCH_TASK, expiry → TIMEOUT (default timeout 3600 s). Unknown until strings and an empty until array return BAD_PARAMS. Like pane wait, task.wait is connection-bound and single-flight: client disconnect or server shutdown cancels the waiter. Task state persists independently of the waiter.

task.finish records disposition through a store transition that emits task.updated with a top-level task_id. Conflict file names and a cleanup failure are stored on task.finish_error. A second finish is BAD_PARAMS once the recorded worktree is gone; while that path still exists the second finish retries removal and does not merge again. A foreign live pane blocks finish only when its canonical cwd is the worktree or a directory inside it (PANES_ALIVE); comparison is on whole path components, so a sibling such as …/proj-other does not match and a symlink to the worktree does.

subscribe accepts an optional task_ids[] server-side filter alongside events/from_seq: only events whose payload carries a matching task_id are delivered (other events still pass the glob match).

pane.read modes: screen returns the current grid as plain text (no scrollback). tail (default, lines default 200, max 5000) returns the last content lines from the rendered ring — cursor-correct (CR overwrites, repaints and alternate-screen grids resolved), same {text, truncated} shape as before. rendered adds the incremental cursor: pass after_seq (default 0 = oldest retained) and lines (default 200, max 5000); the reply's seq is the oldest retained line in the reply (or the head when empty), next_seq is the current head (pass back as the next after_seq), dropped means after_seq is older than retained scrollback, ahead of the head, or from before a restart (cursors are runtime-only, like output_offset — re-read from scratch), and truncated means the new range exceeded lines (the newest lines are returned, still cursor-continuous). Unknown pane → NO_SUCH_PANE. Reads are passive: never refused on agent state, never move the viewport. While a full-screen TUI owns the alternate grid, reads return the current alt grid; repaints bump the touched rows' sequences (poll again with next_seq for deltas) and nothing is appended to history. See docs/05 (rendered ring).

pane.wait_for_output re-reads the pane every 100 ms, with the same mode, lines and strip_ansi as pane.read, until one line contains match (or matches it as a regex when regex is true; timeout_s defaults to 3600). In screen/tail mode a line already on screen matches at once. In rendered mode only lines newer than after_seq match and the cursor advances between polls: capture next_seq before submitting work, then wait from it. Each rendered poll reads up to the 5000-line cap whatever lines says, so a burst cannot step the cursor past a match; only output that outruns the whole retained ring between two polls (more than 5000 lines in 100 ms) can be missed. A pane whose process has exited is read once more and then fails with PANE_EXITED.

pane.clear writes ESC[H ESC[2J ESC[3J into the pane's output stream, in order with the program's output, so the server grid and every attached view clear at one output_offset; the server also drops its scrolled-off history, and rendered cursors from before the clear read as dropped. The program is not told: a full-screen TUI stays blank until it repaints. ED clears the active screen only, so while a TUI holds the alternate screen, the main screen's text comes back when it exits.

pane.get adds wait_baseline {pane_id, process_instance, agent_session_id, session_generation, lifecycle_seq, attention_seq}. Capture it before submitting new work and pass the whole object as wait.after. A matching outcome requires a newer transition on its own axis; attention changes cannot validate an old Done. Fast work completed before wait arrival still matches, including brief outcomes that have already moved on. outcome/transition_seq identify the matched transition; lifecycle/attention report the current pane state. Repeated same-state hooks do not create a new transition. A baseline does not identify individual concurrent input writers; serialize submissions when turn attribution matters.

Process replacement (resume or server restart) and known session replacement return IDENTITY_CHANGED before considering state. Exit retains process identity so until:exited can succeed. First session discovery is allowed; subsequent replacement, even replacement back to the original value, invalidates the baseline. Missing panes remain NO_SUCH_PANE; malformed/ahead baselines and empty outcomes are BAD_PARAMS. Wait uses a dedicated single-flight connection: EOF, another request on that connection or shutdown cancels it immediately. Runtime schema advertises these capabilities. See ADR-0018. Glob subscriptions: *, agent.*, pane.*, workspace.*, tab.*, attention.*, notification.*, decision.*, worktree.*, git.*, pty.*, task.*.

Worktree methods accept a source workspace ID or handle. Git owns registrations; these methods do not fetch a remote or delete a branch. Close the worktree workspace before removal. Live pane references return PANES_ALIVE; invalid, dirty, main, locked, or otherwise open targets return BAD_PARAMS. A path reservation prevents concurrent workspace creation or pane launch into a checkout being removed. Git operations have a bounded execution deadline.

hook-event also accepts wait_for_answer?:bool and wait_timeout_s?:1..120. The waiting mode requires a supported native PermissionRequest payload with session_id, tool_name and object tool_input, and no explicit decision. It registers a live answer route, publishes generated Allow once/Deny choices and returns {accepted:true, native_verdict} when answered. Cancellation returns native_verdict:null and a reason. The default timeout is 120 seconds. This mode uses a dedicated single-flight connection; EOF, another request on that connection, or server shutdown cancels it. Ordinary reporting remains an immediate call. A timeout or cancelled reporter never means Allow.

Every workspace_id param accepts a workspace id or its handle: ids match first, then handles (namespaces are disjoint — handles never contain _). Handles are immutable slugs derived at create (My API!! → my-api, collisions → my-api-2); renames change only the name.

Every state event appends to $XDG_STATE_HOME/signaltty/audit.jsonl ({seq, event, payload, at}; rotation keeps one .1 predecessor, 8 MiB threshold each plus the crossing record). The audit record is synced before publication. event-sequence.json reserves blocks of 4096 numbers using synced temporary write, rename and parent-directory sync before issuance. Restart skips unused reservations; PTY output and filtering also leave valid numeric holes. Journal/reservation write failure stops the server; corrupt reservations fail startup. Snapshot durability is separate. A legacy audit seeds the first reservation from its maximum retained number; uncertain legacy/corrupt history requires recovery.

subscribe {from_seq} captures file/ring history, coverage and the handoff fence in one Store read. The in-memory ring retains 1024 state events. Replay filters before its 4096-event cap, deduplicates by seq, and returns in ascending order before live events. The reply adds replay {status, requested_after, retained_after, through, returned, recovery?}. complete proves all matching state events in (requested_after, through]; numeric adjacency is not evidence of completeness. history_lost, truncated, unavailable and cursor_ahead return subscribed:false, zero replay frames and recovery:snapshot_then_resubscribe, then close the connection. Retention metadata is persisted before discarding a generation and records expected file lengths before publication. Missing or truncated generations invalidate proof; uncertainty is checked before rotation and survives restart. Legacy journals remain unavailable for disk completeness; the new runtime ring proves recent intervals.

On incomplete replay, open a fresh subscription before fetching current workspace state and attaching panes. Queued state events through the handoff fence are suppressed. Lag or out-of-order live delivery closes the stream; a disconnected client must refresh state and reattach rather than assume no changes. GUI recovery keeps terminal widgets, preserves PTY size and restores the current visible screen. It does not promise offline scrollback. Mutating requests are never automatically resubmitted.

pane.spawn, pane.split and pane.resume include an optional integration {agent, status, changed, file?, notice?} for direct supported-agent launches. Status is configured, disabled, or error. Configuration precedes process execution; a setup error does not prevent launch. Clients show notice when present. configured is not proof of provider trust or event delivery. Direct interactive local Codex execution adds native --no-daemon when a bounded version probe confirms support; persisted argv remains unchanged. Unsupported clients and explicit remote endpoints retain their command and return a disabled integration notice (ADR-0014). Ordinary shell/arbitrary launches have no integration result; manually typed Codex needs --no-daemon.

pane.spawn rejects an explicit tab from another workspace with BAD_PARAMS. A failed process launch leaves no automatic tab or pane. Ownership validation, process launch and pane publication complete before a concurrent close can remove the target tab or workspace.

tab.set_layout requires every pane owned by the tab exactly once. Missing, foreign or repeated pane IDs return BAD_PARAMS without mutation. Split ratios must be finite and clamp to 0.05–0.95. Layout replacement arranges existing panes; pane.close deletes one.

pane.rename gives a pane a unique name: a lowercase slug ([a-z][a-z0-9_-]*, at most 32 bytes, herdr's agent-name rule). An invalid name, or one another pane holds, is BAD_PARAMS. Every request's pane_id, target_pane_id and parent_pane_id, and the leaves of a tab.set_layout tree, accept the name in place of the id. A real pane id always wins over a name. The name persists across restarts and emits pane.updated.

pane.swap and pane.move rearrange live panes without touching their processes. Both panes must be distinct, in one workspace and in their tab layouts, else BAD_PARAMS. Swap keeps the tree shape and ratios; across tabs each pane changes tab and the tab's focus stays on its slot. Move removes the pane (collapsing its parent; a tab left without panes becomes empty, as after pane.close) and splits the target, evening out the run like pane.split. Each touched tab emits tab.updated; a pane that changed tab emits pane.updated. Zoom stays a per-window GUI view, so there is no pane.zoom.

tab.set_ratio moves one divider: path holds 0 (first) / 1 (second) choices from the tab root ([] = root) and must resolve to a Split, else BAD_PARAMS. ratio is clamped to 0.05–0.95 so a client can never collapse a pane. The echo is tab.updated, like tab.set_layout. GUIs persist dragged dividers through this method rather than tab.set_layout: a targeted update cannot overwrite a layout another client changed concurrently.

workspace.file_diff reads one literal UTF-8 filename relative to the checkout root. It accepts workspace IDs or handles. Absolute, empty, NUL, ./.. and Git-private paths return BAD_PARAMS; wildcard-looking names remain literal. Known tracked files, deletions and unignored untracked files are supported. The comparison includes staged and unstaged edits against HEAD, or an empty tree before the first commit. It uses three context lines, no rename detection, and no external diff or textconv. It emits no event and issues no Git mutation command. The application issues no edit/stage operation. As with the existing summary, tracked reads retain canonical clean/process conversions from trusted local Git configuration; those helpers can have their own effects. The Git process-group deadline bounds them. Inherited GIT_DIFF_OPTS cannot override the context.

content is tagged by kind. Text contains hunks, truncated and optional notice. Each hunk has old_start, old_count, new_start, new_count, heading and lines. A line has literal text, optional old_line/new_line numbers and kind context, added, removed or no_newline. Other content kinds are binary, unchanged and unavailable with a literal reason. Metadata-only changes and empty new files can have text with no hunks and a notice. Untracked text is all additions and does not alter summary counts.

Preview bytes are capped at 512 KiB and lines at 10,000; stderr is bounded. Truncated text retains complete lines and declares its incompleteness. Unsupported content has an explicit unavailable state. The total server read deadline is eight seconds (TIMEOUT); process/read failures use IO_ERROR. File acquisition does not follow symlinks to read external content. See ADR-0016 and the selected-file contract.

Events (all carry seq)

workspace.turn_started {workspace_id, pane_id, started_at} follows an agent.working that does not come from blocked, once the server has recorded the workspace checkout as the latest turn baseline (ADR-0029). It is also emitted when that capture failed: turn-scoped reads then report the error.

worktree.changed {operation, path, workspace_id} records checkout creation, new workspace association or removal; operation is create, open or remove, and workspace_id identifies the source workspace. Creation remains observable if later convenience workspace binding fails and the checkout is retained. Reopening the same associated workspace is a no-op.

pty.data {pane_id, data_b64, output_offset} streams only to connections that ran pane.attach for that pane. output_offset is the cumulative end byte offset of this output chunk. The attach reply carries the offset covered by its snapshot, acquired atomically with terminal state. Streaming registration precedes the final snapshot, and its response precedes subsequent stream events. Clients discard or trim output already covered by that snapshot. A forward byte gap requires reattach/reconnect before feeding more bytes. Offsets are per-pane for the lifetime of the server and are not persisted. Repeated attach on one connection registers one viewer; detach removes it and preserves the process. Viewer registration survives a child exit and pane.resume, so existing connections receive resumed output without attaching again. All other events go to subscribers by glob match.

Error codes

BAD_PROTOCOL, UNKNOWN_METHOD, BAD_PARAMS, NO_SUCH_{SERVER,WORKSPACE,TAB,PANE}, NO_SUCH_TASK, NO_SUCH_DECISION, AGENT_BUSY, AGENT_NOT_READY, MERGE_CONFLICT, PANE_EXITED, PANES_ALIVE, SPAWN_FAILED, IO_ERROR, TIMEOUT, IDENTITY_CHANGED, RATE_LIMITED, FORBIDDEN, INTERNAL.

decision.created {pane_id, decision, prev?} fires on set (a supersede folds into one emit carrying the previous id). decision.answered {pane_id, decision_id, option_id} fires on delivery. decision.cleared {pane_id, decision_id, reason} fires when the bar drops unanswered (reason: attention_cleared | moved_on | pane_exited | native_cancelled). A pending decision clears on answer, when an agent transition clears its required attention or leaves blocked, or when the child exits. A still-unanswered decision at turn end (Stop/SessionEnd) is kept, never dropped. Clearing a decision never resumes a worker task: only an explicit answer or an accepted follow-up submit moves an input_required task back to working; timeout, disconnect, and turn-end drops park it in input_required. Reading, focusing, pane.mark_seen, and default attach preserve the decision and gate.

CLI mapping

Every CLI command is a thin wrapper over one method call with --json passthrough of result. Examples: signaltty new → workspace.create

• pane.spawn; signaltty pane read → pane.read; signaltty wait → wait; signaltty notify → notify. The CLI injects $SIGNALTTY_PANE context for notify/hook-event when run inside a pane (env set by the server at spawn).

Task orchestration CLI: signaltty task start --repo … --objective … … -- <argv…> → task.start (the worker command is trailing args, not a flag; returns {task, pane} at pending); signaltty task get/list/wait diff/file-diff/finish/cancel → the matching task.* method (wait defaults to --until settled; finish needs --merge or --discard); signaltty report --status … --summary … [--task …] [--pane …] → task.report (falls back to $SIGNALTTY_TASK / $SIGNALTTY_PANE); signaltty pane submit … --text … → pane.submit; signaltty pane read … --mode rendered [--after-seq N] → pane.read; signaltty pane wait-output <id> <pattern> [--regex] [--mode …] [--after-seq N] [--timeout S] [--raw] → pane.wait_for_output; signaltty pane clear <id> → pane.clear; signaltty pane rename <id> [name] → pane.rename; signaltty pane swap <id> <target> → pane.swap; signaltty pane move <id> <target> [--direction right|down] → pane.move; signaltty pane spawn … [--parent-pane …] [--label …] [--relationship …] → pane.spawn; signaltty attention [--limit N] → attention.pending. signaltty schema prints the live contract (same constants the router dispatches on); a sync test proves every listed method dispatches.

pane.resume retains a directly selected path-qualified executable when its basename matches the adapter's bare resume command, including older snapshots. Explicit manifest resume paths and the retained configuration environment remain authoritative. Launch options are not copied into resume arguments.

Relative executable paths supplied to pane.spawn or pane.split are anchored to their launch directory before spawning and stored as absolute paths. Later process directory changes therefore cannot redirect a session resume.

Legacy snapshots with a relative original executable keep the adapter command: they do not persist a reliable initial directory to anchor that relative path.