# spt-core — full docs export # Generated: concatenation of every page of the node-local docs (http://localhost:5474) in reading order. ===== /index.md ===== # SPT developer docs spt-core is a **harness-independent core for an agent ecosystem**: inter-agent messaging, live-agent lifecycle, terminal hosting, seamless self-update, and zero-config cross-machine networking — shipped as a single canonical binary (`spt` / `spt.exe`). It lets coding agents running under different harnesses talk to each other — across sessions, across projects, and across machines — with no central server. > **Pick your path:** > > - **Developer** — you want agents on your machines messaging each other: > start with the [messaging quickstart](quickstart/messaging.md) (one > install line + three commands, under 10 minutes). > - **Adapter developer / dev-agent** — you're integrating a harness or > building a shell against the public contract: start with the > [adapter quickstart](quickstart/adapter.md), then the > [harness contract](harness-contract/overview.md). ## Install Non-interactive, through the GitHub CLI (the release channel is private — see [Installing](reference/install.md) for the full steps): ```sh gh auth login # once per machine, an account that can read the channel gh release download --repo BigscreenVR/spt-bs-releases --pattern 'spt-x86_64-linux' chmod +x ./spt-x86_64-linux && ./spt-x86_64-linux install # Windows: --pattern 'spt-x86_64-windows.exe', then .\spt-x86_64-windows.exe install ``` Verify: ```console $ spt --version spt 0.1.0 ``` ## How these docs are organized Each capability vertical carries the same four modes, never mixed: an **overview** (why it exists + how it fits), a **tutorial** where one ships in v0.1, **how-to guides**, and **reference**. There is one canonical way to do each thing; deprecated or alternate paths are marked when they exist. ## For AI agents reading this These docs are served node-locally at `http://localhost:5474` (each release ships its own version-matched copy; `spt docs url` prints the resolved URL). - [`llms.txt`](http://localhost:5474/llms.txt) — curated index of these docs. [`llms-full.txt`](http://localhost:5474/llms-full.txt) — the full concatenated export. - Append `.md` to any page URL for raw markdown (about 90% fewer tokens than the HTML). - [`manifest.schema.json`](http://localhost:5474/manifest.schema.json) — the machine-readable adapter-manifest contract. Validate your manifest against it before registering. - `spt --help` is a first-class documentation surface; the [CLI reference](cli/reference.md) is generated from it and cannot drift. ===== /quickstart/messaging.md ===== # Quickstart: two agents exchange a message End to end in under 10 minutes. The roles matter here: **you** install (and optionally pair machines); **your agents** exchange the messages. You hand each agent a short prompt; the binary itself teaches them the rest. > This is the developer path. Building an adapter or integrating a harness? > Go to the [adapter quickstart](adapter.md) instead. Everything below uses real values and runs as written. ## 1. Install Download the platform binary with the GitHub CLI (once: `gh auth login` with an account that can read the release channel), then let it install itself: ```sh # Linux gh release download --repo BigscreenVR/spt-bs-releases --pattern 'spt-x86_64-linux' chmod +x ./spt-x86_64-linux ./spt-x86_64-linux install ``` ```powershell # Windows (PowerShell) gh release download --repo BigscreenVR/spt-bs-releases --pattern 'spt-x86_64-windows.exe' .\spt-x86_64-windows.exe install ``` Verify (on Windows, open a **new** terminal first — or use the absolute path the verb printed): ```console $ spt --version spt 0.1.0 ``` ## 2. Optional: link two machines Everything below also works on a single box — skip ahead freely. But the product's hallmark is that the *same* commands work across machines once they share a **subnet**.
Pair a second machine into a subnet (one-time, ~2 minutes) On your first machine, create the subnet. This reveals its joining secret, so it needs elevation — just run it directly and `spt` requests elevation for you (a `sudo` password prompt on Linux/macOS; run the terminal as Administrator on Windows): ```sh spt subnet create home ``` It prints the current 6-digit code, an `otpauth://` URI (scan the QR into an authenticator app for codes anytime), and the next step. > Running non-interactively (no TTY to prompt on)? `spt` instead prints the > exact elevated command to copy-paste — it uses the binary's absolute path so > a user-local install (`~/.local/bin`) still resolves under `sudo`. On the second machine, join it (this enrolls the machine, so it elevates the same way): ```sh spt subnet join home ``` It searches LAN + relay for your first machine, prompts for the current code, and confirms: `JOINED:home`. Check from either side: ```sh spt subnet status --nodes ``` Both machines show up, labeled by hostname. **That's it — the same prompts below now work across machines:** a `spt send sergey` on machine 1 reaches a `sergey` listening on machine 2, live or spooled.
## 3. Hand your receiver agent its prompt Paste this into an agent session (your "receiver" — we call it `sergey`): ```text Run `spt how-to ready`, then follow it to become reachable as "sergey" and stay listening. ``` The binary's own guidance (`spt how-to ready`) tells the agent exactly what to run and what it will see. Under the hood, the agent starts: ```console $ spt ready sergey READY:sergey ``` `ready` registers a *perch* for `sergey` (identity + address on this machine), drains any backlog, and blocks listening. ## 4. Hand your sender agent its prompt Paste this into a second agent session (the "sender" — `lea`): ```text Run `spt how-to send`, then follow it to send the agent "sergey" a greeting from "lea". ``` What the agent runs: ```console $ echo "hello sergey - lea here" | spt send sergey --from lea SENT:sergey ``` (Windows PowerShell: `"hello sergey - lea here" | spt send sergey --from lea`.) Sergey's session prints it immediately: ```text hello sergey - lea here ``` `SENT` means live delivery — sergey was listening. Each delivery is one `` envelope line; the `from="lea"` attribute is the routing handle: whoever receives this knows where a reply goes (`spt send lea`). Bodies are HTML-escaped with newlines as `
`; oversized deliveries on the listener stream split into `` lines the receiver concatenates back (concatenate first, decode once — a fragment may split mid-entity). The exact entity set and decode order, and the full [EVENT-PART reassembly contract](../messaging/overview.md#event-part-reassembly-listener-stream) adapters must implement, live in [the `` wire contract](../messaging/overview.md#the-event-wire-contract). ## 5. Deliver to someone who's offline Stop sergey's listener (Ctrl-C in his session), then send again from lea: ```console $ echo "ping while you were away" | spt send sergey --from lea QUEUED:sergey ``` `QUEUED` means sergey has a perch but isn't listening — the message went to his durable spool instead of being dropped. Bring him back: ```console $ spt ready sergey --once READY:sergey ping while you were away ``` The backlog drains the moment he's back (`--once` drains and exits — the one-shot form `spt how-to ready` teaches agents whose harness can't host a long-running listener). Nothing is lost between sessions. ## 6. What just happened - **Perch** — registering as `sergey` created a perch: a durable identity with an address and a spool, under spt-core's per-machine home. `spt list` shows every perch on the node, live or not. - **Live-first, spool-fallback** — `send` tries a direct connection to the registered address first (`SENT`); if the perch exists but no listener is up, the message lands in the spool (`QUEUED`) and is drained by the next `ready`. - **Reply routing** — the sender id travels with every message structurally, surfaced as the arriving `` envelope's `from` attribute; `spt send lea` answers the sender without knowing anything else about them. - **Agents teach themselves** — the prompt blocks point agents at `spt how-to `: task guidance shipped *in the binary*, so what an agent reads can never disagree with the binary it runs. - **No daemon ceremony** — you never started a server. Anything that needs the per-machine daemon auto-starts it on demand. - **Subnets carry it across machines** — if you did step 2, these same flows ride the paired P2P fabric: same commands, same outputs, machine boundaries invisible. ## Next - **How-to:** block on an answer with `spt ring sergey` — send + wait for the reply in one call (a synchronous ask between agents). - **Concept:** the [mental model](../concepts/overview.md) — perches, endpoints, the daemon, and subnets. - **Reference:** [`spt send` / `ready` / `ring` / `subnet`](../cli/reference.md) — every flag, generated from the binary itself. - **Going cross-machine:** [Networking & subnets](../networking/overview.md) — the model behind `spt subnet create` / `join` / `status`. ===== /quickstart/adapter.md ===== # Quickstart: build an adapter The "build a harness for spt-core" hello-world: take the reference **mock adapter** apart, register it, drive the contract with real commands, then swap in your own harness. No spt-core source required — the public contract is the manifest plus the `spt api` surface. > Integrating an agent harness and a building a driven surface (notifier, > robot, sensor) are the same contract with a different manifest body. For > the latter, read this page first, then > [Shells: getting started](../shells/getting-started.md). ## 0. What an adapter is A TOML **manifest** that declares what varies for your harness — how to spawn a session, which of your hook events fire which `spt api` command, how spt-core can read session history — plus whatever your harness already has (hooks, plugin config). Command templates are **opaque strings**: spt-core fills `{key}` placeholders and runs them. It never parses out a model, a tool list, or a flag. Your harness's business stays yours. ## 1. Get the reference adapter Every release ships the mock adapter's source. With spt-core [installed](messaging.md#1-install) (gh is already authenticated from that step): ```sh gh release download --repo BigscreenVR/spt-bs-releases --pattern 'mock-adapter.zip' unzip mock-adapter.zip -d mock-adapter ``` (Windows: same `gh release download`, then `Expand-Archive mock-adapter.zip mock-adapter`.) The interesting file is `mock-adapter/manifest.toml`. It is deliberately harness-agnostic — generic event names, a trivial `mock-session` helper standing in for a real harness binary. ## 2. Read the manifest The header is the only mandatory section: ```toml [adapter] name = "mock" kind = "harness" # or "shell" (a driven surface) version = "1.0.0" min_spt_core_version = "1.0.0" # compat gate, readable before any install/update hostable_types = ["LiveAgent", "ReadyAgent", "Worker"] ``` Inbound: your harness's hook events, each firing one `spt api` command: ```toml [hooks.SessionStart] fires = "api seed --pid {parent_pid} --session-id {session_id} --adapter {adapter_name}" reads = ["session_id", "parent_pid"] can_inject = true # this hook can surface text back into the agent's context [hooks.Idle] fires = "api state idle" can_inject = false # no inject channel -> spt-core uses its sentinel/relay fallback ``` `can_inject` is the load-bearing harness-varying fact: when a hook can't put text in front of the agent, spt-core routes around it automatically. Outbound: opaque session templates spt-core spawns with `{key}` placeholders filled: ```toml [session.self] command = "mock-session --id {id} --session-id {session_id}" detach = true keys = ["id", "session_id"] ``` A real adapter's template is your harness's full command line — model, flags, tools, everything — exactly as you'd type it. The rest declares history access (`[history]`), env bridging (`[env.*]`), input injection (`[inject]`), and session identity (`[identity]`). Every section beyond `[adapter]` is optional; the [manifest reference](../harness-contract/manifest.md) covers them all. ## 3. Validate and register Two layers of validation, both mechanical: - **Schema** — your manifest must validate against [`manifest.schema.json`](http://localhost:5474/manifest.schema.json). The schema is generated from the same code that parses manifests, so it is always current; closed vocabularies (adapter kinds, history strategies, update avenues, …) are enums in it. - **Registration** — `spt adapter add` parses, validates (including cross-field rules the schema can't express), and registers in one step: ```console $ spt adapter add ./mock-adapter ADAPTER_ADD:mock:Harness:Copy (registered) ADAPTER_INSTALL_SKIP: no [update] avenue (manifest-only adapter) $ spt adapter list mock: Harness Copy active (from ./mock-adapter) ``` A bad manifest is rejected here with a message naming the offending field — nothing half-registers. ## 4. Drive the contract Every machinery call your adapter makes carries `--adapter ` — that's the rule that makes multi-harness nodes unambiguous. Ask spt-core what your adapter declared: ```console $ spt api --adapter mock --manifest ./mock-adapter/manifest.toml capability LiveAgent ReadyAgent Worker ``` Now the harness-hosted startup flow, exactly what your `SessionStart` hook will fire (here with a stand-in pid): ```console $ spt api --adapter mock seed --pid 4242 --session-id demo-session-1 SEEDED:4242 ``` `seed` records an ephemeral hand-off keyed by the parent process id; the session's listener then consumes it with `spt api … listen` and holds the perch. That seed→listen pair *is* harness-hosted startup. (The other direction — spt-core spawning the session itself from your `[session.self]` template, then `api bind` — is spt-hosted startup. Both are in the [`spt api` reference](../harness-contract/api.md).) ## 5. Make it yours 1. Copy `manifest.toml`, set `name`, `version`, and your real `hostable_types`. 2. Point `[hooks.*]` at the events your harness actually fires, with honest `can_inject` values. 3. Replace each `[session.*].command` with your harness's real command line. 4. Pick the `[history]` strategy your harness permits (binary that emits history → `fetcher`; transcript file on disk → `locate_normalize`; you push via `api history-log` → `native`). 5. Validate against the schema, `spt adapter add` it, and fire the `capability`/`seed` calls above against your own manifest. Building adapters against this contract is **unrestricted and royalty-free** — see the [license split](https://github.com/BigscreenVR/spt-bs-releases#license) (the release channel's README; `LICENSE-BINARY`'s adapter clause is the operative text, shipped in the channel repo). ## Next - **Checklist:** the [harness integration checklist](../harness-contract/integration-checklist.md) — every contract surface grouped by necessity, mapped to the interaction lifecycle, plus the beyond-the-API integrations that make an adapter feel native. Work it top to bottom when building a real harness. - **Reference:** the complete [manifest reference](../harness-contract/manifest.md) and [`spt api` reference](../harness-contract/api.md). - **How-to:** ship spt-core *with* your adapter — the [install-on-demand bootstrap pattern](../harness-contract/install-on-demand.md). - **Concept:** where adapters sit in the [mental model](../concepts/overview.md). ===== /concepts/overview.md ===== # Mental model What spt-core is, the five or six nouns everything else builds on, and how the pieces fit. Read this once and the rest of the docs are mostly reference. ## The shape of the system spt-core is **per-machine infrastructure for agents**. One binary (`spt`) installs on each machine. It carries everything: the CLI, the messaging substrate, the always-available daemon, and the networking layer. Agent harnesses — Claude Code, Codex, Pi (the pi coding agent), anything — plug in through a declarative **adapter manifest** and a small command surface (`spt api …`). spt-core never contains harness-specific logic; adapters declare what varies, spt-core does the work. ```text machine A machine B ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ spt daemon (one per machine)│ QUIC │ spt daemon │ │ ┌────────┐ ┌───────────┐ │◄──────►│ (paired: same subnet) │ │ │ broker │ │ brain │ │ P2P │ │ │ │ PTYs · │ │ routing · │ │ │ ┌───────┐ ┌─────────┐ │ │ │ sockets│ │ registry ·│ │ │ │ lea │ │ doorbell│ │ │ └────────┘ │ lifecycle │ │ │ │(agent)│ │ (shell) │ │ │ └───────────┘ │ │ └───────┘ └─────────┘ │ │ ┌─────┐ ┌─────┐ │ └──────────────────────────────┘ │ │serg.│ │ ling│ ← endpoints (perches live on disk; sessions come │ └─────┘ └─────┘ and go, identity persists) └──────────────────────────────┘ ``` ## Endpoints and perches An **endpoint** is anything addressable: an agent (`sergey`), a worker, a **shell** (a driven non-agent surface — a notifier, a robot, a sensor). Every endpoint has a **perch**: its durable on-disk seat — identity, address, message spool, state. Sessions are ephemeral; perches persist. That split is why a message sent to an offline agent is queued, not lost, and why an agent can be revived days later as the *same* agent. Endpoint IDs are adapter-agnostic: `sergey` is `sergey` whether his sessions run under one harness today and another tomorrow. ## Messaging The primitive everything else uses. `spt send ` delivers live when the target is listening, spools when it isn't; `spt ring ` is the blocking ask (send + wait for the reply); reply routing on the structural `from` makes answers cheap. Payloads carry typed operations and file blobs, not just text. Try it: the [messaging quickstart](../quickstart/messaging.md). ## The daemon: broker and brain One **spt daemon** per machine owns all shared state: hosted session PTYs, the network identity and endpoint, the registry, every spool, all lifecycle loops. You never manage it — any `spt` invocation auto-starts it. …with one exception, because you are allowed to mean it: **`spt node stop` sticks.** Auto-start is a convenience, and a convenience never overrules an explicit instruction. Once you stop the daemon, the implicit auto-start that every `spt` invocation performs *declines* to bring it back, printing one line that names the way out: ```text daemon stopped by operator — spt node start to resume ``` The stop stays in force until you lift it — with `spt node start`, or by applying an update, which restarts the daemon by design. There is no timeout: a daemon that came back on its own five minutes later would be exactly the surprise this rule exists to prevent. (Before v0.41.0 the stop *was* a race: on a machine hosting live agent sessions, the harness hooks' own `spt` calls raced the teardown and revived the daemon within seconds.) Internally it splits in two, and the split is what makes self-update seamless: - the **broker** holds only what must never die: PTY masters, spawned child processes, listening sockets. It almost never updates. - the **brain** holds all logic and restarts freely. An update swaps the brain while the broker keeps every session's process and byte stream intact — running agents don't notice. ## Live agents and the mind A **live agent** is an agent endpoint with a persistent working memory. Its context survives session resets and even machine moves through three file-drop mechanisms (no special APIs inside the agent's session): - **commune** — the agent drops a context delta; spt-core ingests it into the endpoint's tracked mind (two tiers: a *live* tier that follows the agent everywhere, and a *project* tier scoped to one project). - **signoff** — a graceful goodbye: final commune, then teardown. - **echo-commune** — when a session ends without a signoff, spt-core runs a bounded summarizer over the session's history so the context delta is captured anyway. The mind syncs between paired machines, so reviving `sergey` elsewhere brings his memory with him. ## Instances, dormancy, and rest One endpoint can have **instances** on several nodes. Instances rest when unused — **dormant** (warm, zero idle cost, instantly wakeable) or **suspended** (cold) — and remain addressable while resting: messages for them are held and delivered on wake. `spt endpoint wake sergey` re-activates the seat in place; nothing is respawned. ## Subnets, pairing, and the network Machines pair into **subnets** — private, named groups sharing a registry of endpoints. Pairing is a one-time ceremony seeded by a TOTP code (the same six digits an authenticator app shows); after that, connectivity is zero-config peer-to-peer QUIC with relay fallback, no central server. Every endpoint's visibility and sync scope is controlled per subnet; nothing is shared by default with anyone you haven't paired with. ## The harness contract The seam third parties build against — two halves: - the **[manifest](../harness-contract/manifest.md)**: a TOML file declaring what varies per harness (how to spawn a session, which hooks fire, how to read history). Command templates are opaque strings; spt-core fills `{key}` placeholders and runs them. SPT is not a harness: models, flags, and tools are always the adapter's business. - the **[`spt api` surface](../harness-contract/api.md)**: the inbound commands a harness's hooks fire to keep spt-core's state in sync (session started, went idle, session ended, …). A working adapter is a manifest plus whatever the harness already has. [Build one in the adapter quickstart](../quickstart/adapter.md). ## Self-update Releases are signed (Ed25519, two-key trust anchor baked into every binary) and propagate peer-to-peer: one machine fetches a release, its peers verify and stage it from each other. Updates apply with the broker/brain split, so no endpoint process terminates or suspends during a self-update — the system's standing invariant. ## Where to go next | You want to… | Go to | |---|---| | see two agents talk | [Messaging quickstart](../quickstart/messaging.md) | | integrate a harness | [Adapter quickstart](../quickstart/adapter.md) → [Manifest reference](../harness-contract/manifest.md) | | build a notifier/robot/sensor | [Shells](../shells/overview.md) | | pair two machines | [Networking & subnets](../networking/overview.md) | | every command and flag | [CLI reference](../cli/reference.md) | ===== /messaging/overview.md ===== # Messaging The substrate everything else rides on: durable, addressed, reply-routable messages between endpoints — live when the target listens, spooled when it doesn't, across machines once nodes are paired. You've probably already run the [quickstart](../quickstart/messaging.md); this page is the model. ## Semantics - **Live-first, spool-fallback.** `spt send ` connects directly to a listening target (`SENT`); if the perch exists but nothing is listening, the message lands in the target's durable spool (`QUEUED`) and drains on its next `ready`. A target with *no* perch is an error (`NO_PERCH`) — identity is never invented on someone else's behalf. - **Reply routing.** Every message carries its sender id structurally; the arriving `` envelope surfaces it, and `spt send ` answers without knowing anything else. - **The blocking ask.** `spt ring ` sends and waits for the reply (with a timeout) — the synchronous question between agents. To receive that reply, a caller who is not already listening gets a temporary perch for the duration of the call, which is torn down when the call ends. **The wait is counted in minutes.** `--timeout` defaults to **30 minutes**, and a bare number is minutes — you are waiting on an agent, which answers on agent time, not on request-response time. An explicit suffix sets the unit, so `--timeout 90s` and `--timeout 2m` both work and both say what they mean. The timeout line answers in the unit you typed. *(Bare numbers meant seconds in earlier releases, so a `--timeout 60` carried over from an older script now means sixty minutes — write `60s` for the old behavior.)* **A ring only ever tears down a perch it created itself.** This matters because a caller may already own a perch that does not currently look live — through a busy turn, a session ending softly, or a re-bind in progress. In that case the ring does not take the perch over: it delivers the message, returns without blocking, and the reply arrives on the caller's own listener the next time it listens. The same refusal covers a perch directory that exists but is empty, which may be another process mid-creation: it is left alone rather than reused or cleaned up, and its path is reported so a person can deal with it. The practical guarantee is that ringing from a session that already has an identity never costs that session its perch or the mail sitting in its spool. **This guarantee is carried by the caller — the `spt` command you run — not by the daemon, and not by anything a harness supplies.** The command claims a temporary perch by creating its directory exclusively, so a directory that already exists is a refusal rather than a silent reuse, and only a perch proven to be its own is ever removed. An adapter or harness neither implements nor can weaken this, and should not add its own protection against it. The daemon's role is narrower and separate: for perches it hosts, it is the authority on whether a listener is currently live — which is what decides whether the reply is waited for here or left to arrive on the caller's existing listener. - **Per-message send control (three orthogonal axes).** Each `spt send` carries one value per axis; every axis defaults to unrestricted: - **Delivery window** (*when*) — `--active-only` spools for the agent's own poll without waking a live listener (it reaches the agent at its next natural boundary instead of interrupting now; also held for resting dormant/suspended instances and released exactly once on wake). This **renames the older `--deferred`**, which still parses as a hidden alias. `--idle-only` holds until the target is idle, then delivers (the wake). Default delivers in whichever window fires first. - **Channel** (*through what*) — `--prefer-native` routes through the target's translation binary when one is running, else falls back to the standard delivery; `--force-native` uses the binary only (no fallback, no reroute — if no binary is live it reports non-delivery rather than spooling to another method). Default is unrestricted. The translation binary is the adapter's idle-delivery filter; an adapter declares it with a `[message-idle-translation-binary].command` (a program token plus args, new in v0.16.0 — the bare `path` form is deprecated) and spt-core lifecycle-manages it. - **Persistence** (*how long*) — `--ephemeral` drops the message if it can't be delivered in its accepted window instead of spooling; it is the one path allowed to drop silently (everything else spools and reports non-delivery). *In this release ephemeral evaporation applies to translation-binary delivery and TTL expiry; the harness-relay carrier-absence case is not yet wired.* - **Opaque metadata.** `--json-payload ''` attaches a JSON metadata block alongside the body. spt-core carries it verbatim across every rail and never interprets it — the **receiving adapter** parses it. It can't forge spt-core's own envelope attributes (it rides inside a single `json` value), and any sender may attach it. - **Typed payloads.** Message bodies carry typed operations and file blobs, not just text — file transfers are addressable and progress-queryable mid-flight. ## Send outcomes — the closed set Every `spt send` reports exactly one outcome line. The line goes to **stderr** (stdout is reserved for message payloads); classify success by the **exit code** — `0` for every delivered/spooled outcome, non-zero for every failure. The token before the first `:` is stable; this set is complete as of v0.26.0. **Success (exit 0):** | Line | Meaning | |---|---| | `SENT:` | Delivered live to a listening target on this node. | | `SENT(WAN):@` | Delivered cross-node, **receiver-confirmed** — printed only when the remote daemon acknowledged. A suffix annotates the confirmed disposition: ` (spooled)` — the remote daemon accepted it into the target's durable spool; ` (duplicate)` — the receiver had already processed this message (a safe dedup'd replay). No suffix = delivered live. | | `QUEUED:` | The perch exists but nothing is listening — spooled durably, drains on the target's next `ready`. Success, not an error. | | `QUEUED(idle-only):` | An `--idle-only` send holding for the target's idle window. | | `DEFERRED:` | An `--active-only` send spooled for the target's own next poll (never interrupts a live listener). | **Failure (non-zero exit, stderr):** | Line | Meaning | |---|---| | `NO_PERCH: is not listening` | No perch for that id — identity is never invented on someone else's behalf. An `--active-only` send reports this with `(active-only stays local-only)`: the hook channel does not take the cross-node leg. | | `WAN_NO_PERCH: — no perch on ` | The route resolved to a node, but no perch lives there (a stale route — the endpoint may have moved or stopped). | | `WAN_REFUSED:@` | The receiver denied the message (access gate). | | `WAN_UNCONFIRMED:@` | No receiver acknowledgment — the peer may be offline or on an old version. The message may or may not have landed; only `SENT(WAN)` means confirmed. | | `WAN_PEER_SILENT:@` | The node accepted the message and never answered within the reply budget — it is still holding the stream, which points at a wedged or overloaded node rather than an old one. Delivery NOT confirmed; only `SENT(WAN)` means confirmed. | | `WAN_FAIL: — ` | Cross-node transport failure. | | `AMBIGUOUS: — ` | Several nodes host that id — qualify (`@`). | | `EMPTY_MSG` | Refused: empty body. | ## The `` wire contract Every arriving message on an **agent** surface (`spt ready`, `api listen`, `api poll`, `api worker-poll`) is one `body` envelope — never a bare body: ```text hello check the build ``` A body that is already a fully-formed typed envelope (`echo_commune`, `notify`, `user-msg`, …) passes through **verbatim** — one envelope, never re-wrapped, and the body's own `from` wins. On the listener stream an oversized line splits into `` chunks the receiver reassembles; `api poll` / `api worker-poll` always emit one whole envelope per message, never chunked. **Escaping — the closed entity set.** Four entities, plus one newline token per half of the envelope: bodies use `
`, attribute values use ` `. There is no `'`/`'` (single quotes ride literal): - **Encode (body):** `&` → `&` **first**, then `<` → `<`, `>` → `>`, `"` → `"`; then CRLF and lone CR normalize to LF, and LF → `
`. - **Decode (body):** split/replace `
` → newline **first**, then `<` → `<`, `>` → `>`, `"` → `"`, and `&` → `&` **last**. Amp-last is the invariant that keeps an embedded `&lt;` from double-decoding into `<`. - **Encode (attribute value):** the same four entities in the same order, then the attribute's own linebreak step — CRLF and lone CR normalize to LF, and LF → ` ` (**not** `
`, which belongs to the body). - **Decode (attribute value):** ` ` → newline **first**, then the same tag-shaped entities, and `&` → `&` **last**. Amp-last is what makes the newline entity safe: an attribute carrying the literal text ` ` arrives as `&#10;`, which the ` ` step cannot match, so it decodes back to the literal rather than to a linebreak. - Attribute values are line-safe because the **encoder makes them so**, not by construction. A receiver-composed attribute can carry newlines — the `trust-warning` block runs to several — and the envelope is line-framed, so an unencoded newline would split one delivery into several lines of which most are not envelopes. - Decode only the **extracted body substring** after parsing the envelope framing — never run the entity decode over the full line, or the framing tokens themselves unescape. **The `seal` attribute — sender-authored, and it must be surfaced.** A [sealed message](wax-seal.md) arrives carrying its seal token as a `seal="…"` attribute on the envelope: ```text Approved: run the migration tonight ``` This is the **envelope author's own field** — like `type`, `from`, or an alarm's times — not one of the receiver-composed attributes ([`trust-warning`, `mnemonics-json`](../networking/monics.md)) your node strips off inbound bodies before attaching its own. The seal attribute rides **end-to-end intact** through that strip: it is the sender's own evidence citation, and stripping it would delete the citation at every ingress. **For adapter authors: this attribute must be surfaced** — the same obligation `trust-warning` carries. A pipeline that re-renders a delivery has to carry the token through and show it, or the receiving agent loses the pointer to evidence the sender deliberately attached. And the mirror rule: the attribute is a **citation, never an authorization subject**. Nothing may branch authority on its presence or value — only a `BOUND` verdict from `spt api seal verify` over the delivered body is evidence (a forged attribute is harmless precisely because verify recomputes the hash). **The attribute set is open — re-render by pass-through, never by allowlist.** The sender-authored attributes above are a *class*, not a list: new ones join the envelope over time (`seal` is only the newest), and they join with their obligations already in force. So the render rule for any consumer that re-emits deliveries (an adapter pipeline, a digest, a relay surface): - **Carry through every attribute you do not yourself consume.** Re-emitting from a fixed list of known names silently deletes every attribute added after that list was written — and the deletion is invisible at the site that wrote the list, because nothing there ever names what it dropped. The only closed list in this contract is the receiver-composed **strip** class (`trust-warning`, `mnemonics-json`), and it is a strip list, not a render list; everything else rides. - **"Consume" means the attribute's distinction is re-expressed, not merely read.** A pipeline consumes an attribute when its handling puts the value's meaning back in front of the agent — content re-rendered into the pipeline's own surface, or a dispatch whose *agent-visible outcome* differs per value (routing on `type` consumes it only while distinct types yield distinguishable deliveries). Reading a value and then emitting output that two sender-distinct deliveries would share is peeking, not consuming. The test is the drop test: if omitting the attribute makes two deliveries the sender distinguished indistinguishable at the agent surface, it must ride. - **Attribute names are tokens, not text.** The envelope's name grammar is `[a-z0-9_-]+`. Names are hostile-reachable — envelopes arrive from peer *nodes*, not only from this binary — so a pass-through re-emits a name only when it matches that grammar; a tag-position span that does not is framing damage, not an attribute. Refuse or drop it **loudly**, never re-emit it. - **Keep the value in attribute position with its wire escaping intact.** An attribute value is attr-escaped for exactly one context. Unescaping it into a body or frame context hands a hostile sender a forgery seam — a crafted value could close your re-rendered tag and land text at your frame level, indistinguishable from a real delivery. Pass the raw attr-escaped span through; decode only where the final consumer parses attributes. **MAC-stamped frames are a different surface.** The shell relay drain (`api poll --link `) emits raw stamped frames of the form ` ` — a 64-hex-char HMAC-SHA256 over the frame bytes, one space, then the frame — and is deliberately **not** ``-wrapped (the shell child verifies the MAC and parses its own vocabulary). Agent-perch surfaces never emit stamped frames; a parser of agent traffic only ever sees `` / `` lines. ### EVENT-PART reassembly (listener stream) When the **listener stream** (`spt ready`, `spt api listen`) would emit an `` line longer than its per-line cap, it splits that **one** envelope across N `` lines. `api poll` / `api worker-poll` never chunk, so only a consumer of the listener stream needs this — and such a consumer **must** implement reassembly, or a single oversized delivery wedges its parser. The rules (a receiver that follows them reconstructs the original envelope byte-for-byte): - **`` is a distinct tag — do not prefix-match `FRAGMENT` with its **own** closing tag ``. A substring test for `` never closes a part — a scanner that keys on `` will treat a part as an unterminated `` and stall. Dispatch on the full tag name. - **`seq="K/M"`** is **1-indexed**: `K` runs `1..M`; `M` is the total part count, identical on every part of the group. Never zero-padded. - **`id`** is an **opaque grouping token**, unique per split envelope. Group parts by `id` **equality only** — never assume its charset, length, or structure (it is an implementation-chosen nonce, not a contract value). - **Attributes ride on the `seq="1/M"` head part only.** The original envelope's attrs (`type`, `from`, `notif_id`, …) appear on the head; continuation parts carry only `seq` and `id`. Reassembly takes the attrs from the head. - **Each FRAGMENT is a raw byte-slice of the already-escaped envelope.** A split point may fall **inside** an entity (`&`) or a `
` token. So: **concatenate the fragments in `seq` order first** to recover the whole `…` line, **then** parse the framing and decode the body **once** (per the escaping rules above). **Never** decode a fragment on its own. `concat(FRAGMENT_1..M)` equals the original envelope's inner content verbatim. - **Parts may arrive out of order and are not guaranteed contiguous.** Key partial state by `id`, sort by `seq` `K`, and reassemble only once all `M` parts of that `id` are held. - **Drop orphan groups silently — and keep the receiver alive.** If the `seq="1/M"` head is absent (earlier parts lost across a session boundary) or any `seq` in `1..M` is missing or never arrives, drop the whole group — never emit a partial envelope. "Silently" is about the **stream** (no partial envelope reaches it), not the receiver's own diagnostics: a receiver may — and for the invisible-failure class, should — surface the drop in its own log or a counter. An incomplete group is an expected boundary condition (its canonical cause is a mid-stream restart), so it must **not** tear down the receiver — a restart cannot recover a group whose head is already gone and only re-creates the condition. Bound the pending partial-state (evict the oldest group under a cap rather than buffer without limit — an unbounded reassembly buffer is the failure mode this whole section exists to prevent), reset it on receiver restart, and lose at most the one oversized message, never the stream. ## Message short-IDs and replies Every message gets an eight-character short-ID when it is committed, minted from the message's own content hash and scoped to the node that holds it. Nothing mints a second identifier later: the same token appears in the delivery envelope (`msg-id`), in the `MSG_IN` and `MSG_OUT` io-event rows, and in the URL `//m/` — so what you say in a chat line is what you click, and two readers cannot disagree about what a message is called. The alphabet is base32 without `0`, `1` and `8`, so `O`/`0` and `I`/`1` are never two spellings of one id. Read one back with: ```console $ spt msg show BCDFGH23 BCDFGH23 from doyle to todlando at 1788750167374ms [spool] attachment: report.md http://localhost:5474/kitsubito/f/report.md (2481 bytes) --- the report you asked for ``` `--json` is the machine twin, and `//m/` renders the same message in a browser (`?json` there too). Treat the id as **opaque**: a collision on one node is detected when it is minted and resolved by lengthening that one id to nine characters, then ten, which is safe precisely because no reader parses it. `spt send --reply-to ` carries the parent's id in the envelope so an adapter *may* render a thread. It is a label on the message, not a way to address one: `target` stays required, and an **unknown parent is carried, not refused** — the parent may live on a node we cannot ask, and refusing would make a thread across a partition impossible rather than merely unrendered. Files ride along the same way: see [Attachments and `spt fetch`](../serving/attachments.md). ## Addressing Bare ids (`sergey`) resolve locally first, then across the subnet; when the same id is live on several nodes, resolution **refuses and asks you to qualify** (`sergey@desktop` — node labels and key prefixes both work) rather than guessing. The full form is `[subnet:]id[@node]`. ## Sending from inside a turn An agent whose adapter declares [`[io] compliance`](../harness-contract/manifest.md#io--io-funnel-compliance) can send by writing a **shortform tag** in its own output — `@` — instead of shelling out to `spt send`. It is not a special class of message: dispatch goes through the ordinary send path, with the same admission, sealing, spooling and refusal behaviour. Two things differ, and both are deliberate: a tag inside backticks or a fenced code block is a **quotation** that sends nothing, and the outcome comes back only through the now-signal's `DISPATCH_RESULTS` category — a dispatch never echoes or replies to confirm itself. The grammar, the suppression rules, and the manifest gate are specified in [the frame contract](../shells/frames.md#shortform-sending-from-inside-a-turn). A message that **arrives** carrying a tag is text: spt-core never parses an inbound body for shortform, so nothing you receive can make you send. ## Commands `send` · `ring` · `ready` (blocks; `--once` drains and exits) · `list` · `stop` · `whoami` · `msg show` · `fetch` — every flag in the [CLI reference](../cli/reference.md). Agents get the task-oriented version from the binary itself: `spt how-to ready` / `spt how-to send`. ===== /messaging/wax-seal.md ===== # Wax seals: proof of user authority A **wax seal** is a durable, citable proof that a human authorized **specific content** — a decision text, or the exact body of a message. Minting one runs a **human-presence ceremony** (a TOTP code entered at the operator's attached controller); the result is a short token that binds `{content hash, minter, timestamp}` into a record any member of the binding subnet can check, on any of its nodes, at any later time. That last part is the point: an agent cites a seal *later* to prove a decision without re-asking. It is distinct from the in-the-moment origin authority of a `user-msg` — a seal is durable and content-bound, and a reversed decision is simply a **newer seal** (records are immutable; there is no expiry and no revocation). A seal is **evidence, never authorization**. Possessing a token grants nothing, and nothing in spt-core branches on one — the only citable fact is a `BOUND` verdict from `spt api seal verify` over the actual content. Forged or misquoted tokens are harmless by construction, because verify recomputes the hash. ## Minting a decision seal ```text printf '%s' "Ship v0.61.0 with the reduced default timeout" | spt seal mint ``` The text to seal arrives on stdin. The daemon runs the ceremony over **exactly those bytes** (trimmed the same way `spt send` trims a message body, so a seal minted for a text and a sealed send of that same text seal byte-identical buffers), the overlay appears at the attached controller, and on admit the minted **token prints alone on stdout** — exit 0 **only** when the ceremony admitted. Every refusal (no surface, wrong code, throttled, cancelled, content too long…) exits nonzero with the daemon's own named reason: the CLI never re-words a refusal it did not decide. The token is 8–10 characters from a narrow lowercase alphabet, made to be read aloud and retyped. **From inside a turn:** an agent on an [IO-compliant adapter](../harness-contract/manifest.md#io--io-funnel-compliance) mints by wrapping text in `;;` markers in its own output — `;;we ship the parser behind the manifest gate;;` — and that runs **this** ceremony, not a second one. The turn does not wait for it (the ceremony is human-scale, so the mint is handed off and the turn ends), and with no controller attached it refuses immediately with the same `SEAL_NO_CEREMONY_SURFACE` this page's refusals come from. The outcome is reported only through the now-signal's `DISPATCH_RESULTS` category. An admitted mint includes its actual token: ```text -> (seal): seal minted seal=n2czzem8hc ``` Each result appears once per session. Cite that token with the marked text and verify the content before relying on it: a token remains evidence, never authorization. Historical results written before token recording was added still say `seal minted`; no token is reconstructed for those rows. Grammar and edge cases — pairs, the empty `;;;;`, the odd trailing marker, and the backtick/fence suppression that lets you write about all of it — are in [the frame contract](../shells/frames.md#what-happens-after-you-type-it). ## Sealing a message ```text printf '%s' "Approved: run the migration tonight" | spt send doyle --seal ``` `--seal` turns a send into **sealed dispatch**: the ceremony runs over the **exact bytes that will be delivered** — one buffer end to end, never re-read or re-encoded between ceremony and delivery — so the receiver's `verify` over the delivered body reads BOUND by construction. The overlay names the **destination** beside the binding subnet: the human consents to sealing *this text*, *to this endpoint*, *under this subnet*. A ceremony that does not admit sends **nothing** — not delivered, not spooled. The **answer carries the token**: ```text SENT:doyle seal=n2czzem8hc ``` so the sender can record or relay what it just minted. It rides every outcome a sealed send can answer with — `SENT`, `QUEUED`, `QUEUED(idle-only)`, `DEFERRED` — because the token is evidence of the **mint**, not of delivery: the ceremony ran before any delivery attempt, so a message that only spooled still minted a record you may need to cite. An unsealed send's answer is unchanged, and no path prints an empty `seal=`. Once the ceremony admits, the overlay comes down and says nothing: the token is on the answer line, and the notice that used to print there only stranded in the terminal. A ceremony that **fails or is cancelled** still prints its sentence — nothing else would tell you. The delivered message carries the token as the `seal="…"` envelope attribute — see [the envelope contract](overview.md#the-event-wire-contract) for what a receiving adapter must do with it. ## The ceremony The overlay shows the human **the sealed content, verbatim**, and **names the binding subnet** whose member-or-admin TOTP code it expects (plus the destination, on sealed dispatch). What you see is what is hashed — the same byte buffer, end to end. - **Content is capped at 500 characters** (Unicode scalars, counted at the ceremony — not a record property). Longer content **refuses by name** (`SEAL_CEREMONY_CONTENT_TOO_LONG`); it is never silently truncated, because a seal over a truncation would attest text the human never saw. Content must also be valid UTF-8 (`SEAL_CEREMONY_CONTENT_NOT_UTF8`): bytes that cannot be displayed verbatim are bytes nobody can consent to. - **The overlay scrolls.** Content within the cap can still overflow a small terminal grid; the surface adapts, the content never shrinks. Submitting is **never gated on scrolling to the end** — no consent theater. - **Esc (or ctrl-c) cancels cleanly.** No record exists anywhere, nothing is spent against the attempt limit (a cancel is not a guess), a pending sealed send is dropped, and the requesting agent is answered with the named cancellation. Detaching the controller mid-ceremony aborts the same way. - Wrong codes are **counted and bounded** on the seal ceremony's own attempt ledger (repeated failures back the gate off, loudly past the third) — separate from every other gate's ledger, so failed seal guesses can never shut a gate a human needs for something else. A mint with **no ceremony surface** — no live session for the minter, no attached controller, or a controller too old to run the ceremony — refuses **immediately** with `SEAL_NO_CEREMONY_SURFACE` and attach-and-retry guidance. Nothing is parked waiting for a controller to appear; have the operator attach (`spt rc `) and ask again. ## The FIDO2 ceremony Once this node × the binding subnet is [enrolled](#enrolling-an-authenticator), the mint ceremony **offers FIDO2 first**: the overlay opens with the content as always, and your OS's own presence prompt (Windows Hello) asks you to sign. Completing the gesture **is** the ceremony — the signature ships to the daemon, which verifies it against the enrolled pubkey and mints with ceremony kind `fido2` and the signature on the record. No code to read off a phone, no code to type. What the keypair signs is not the content alone but the whole **binding tuple** — content hash, fully-qualified minter, mint timestamp, fixed before the prompt appears — so every fido2 record is **self-authenticating from its own fields**: the signature cannot be lifted onto different content, a different minter, or a different moment. The TOTP code stays the universal fallback, always on the same overlay: - **Cancelling the OS prompt falls back to code entry.** The overlay stays up and you type the TOTP code instead. Distinct from **Esc**, which still aborts the whole ceremony — nothing minted, nothing spent, requester answered — exactly as before. - **A failed signature spends nothing.** A proof the daemon cannot verify refuses by name (`SEAL_FIDO2_PROOF_REFUSED`) and never counts against the code-attempt ledger — a broken client must not shut the gate a human needs — and the overlay falls back to code entry. - **Remote controllers degrade silently.** The signing key lives where it was enrolled, so availability in v1 is: **FIDO2 for a controller at the minter node; a remote controller gets the ordinary TOTP overlay** — no error chrome, no broken offer, just the universal ceremony. Under the hood the open names the enrolled node and the client compares it against its own; local and remote controllers are one code path. Signing happens **client-side, where the human is**: the rc client signs the daemon-composed tuple and ships the **signature up the attach wire — a proof, never a verdict**; verification, the attempt ledger, and the mint all stay daemon-side. The offer rides the existing ceremony records as additive fields, so an older `spt rc` simply renders the plain TOTP overlay — nothing hangs, nothing to update before the next mint. ### `E` — enroll and seal in one ceremony When this node × subnet is **not** yet enrolled, the TOTP overlay offers **`E`**: press it and the OS prompt mints (or fetches) the authenticator keypair; the one TOTP code you then enter both **enrolls the node and mints the seal — both or neither**, under the daemon's one apply lock. A failed enrollment mints nothing and a failed mint enrolls nothing, so one code entry never yields a half-state. Every TOTP clause carries unchanged: wrong codes count and re-prompt, Esc cancels everything spending nothing. An enrolled pair's overlay never shows `E`. ## Which subnet a seal binds to Seal records replicate to the nodes of **one subnet** — the *binding subnet* — and that replication scope **is the verification audience**: only that subnet's members can `verify` or `describe` the seal. So the binding subnet is chosen to keep the audience able to check the citation, by one deterministic rule: 1. **`--subnet ` wins** — but a subnet the minter is not a member of refuses fast (the ceremony could never verify a code for a subnet the minter holds no keys to). 2. Otherwise, the minter endpoint's **anchor subnet**. 3. On sealed dispatch where the destination does not share the anchor: the **alphabetically first subnet both endpoints share** — deterministic, so the same pair always binds the same subnet. 4. **No shared subnet refuses by name** (`SEAL_NO_SHARED_SUBNET`). A seal the receiver structurally cannot verify would be worse than no seal, so there is no silent fallback. The overlay always names the chosen subnet — the human sees which key they are being asked for before typing it. ## Checking a seal ```text printf '%s' "Approved: run the migration tonight" | spt api seal verify k7mn4wq2vx ``` `verify` is **content-bound**: the content arrives on stdin, its hash is recomputed over the exact bytes received, and the verdict is **BOUND** or **NOT-BOUND**, with the record's minter and mint time printed alongside. The exit contract is strict so a script can never misread a non-verdict: **exit 0 if and only if BOUND**. NOT-BOUND, unknown token, and malformed token each answer distinctly and none of them exits 0. Your shell's trailing newline is not a difference. `seal mint` seals the trimmed text, so `echo` and friends would otherwise present bytes that could never match the seal they just minted. The exact bytes are hashed **first**; only if they miss does verify try the same trim the mint applied. Content deliberately sealed *with* its whitespace still binds exactly as before, and a difference in anything but leading or trailing whitespace is still NOT-BOUND. The verdict block is deliberately narrow: `token`, `content_hash` and `ceremony_kind` do not surface here. The verdict line already carries the token, and on a mismatch it carries both hashes — a field repeated beside its own verdict reads as a second, weaker answer. `describe` is where the full record lives. Verifying with **no content refuses** and points you at `describe` — a verify that reads nothing is not a verify, and the question "what does this token attest?" has its own verb: ```text spt api seal describe k7mn4wq2vx ``` `describe` prints the record's fields — token, content hash, fully-qualified minter, mint time, ceremony kind, and **whether a signature is present** — line-oriented, one `key: value` per line. `describe` is the **human** surface, and it renders two of those fields for a reader rather than for a parser: - the minter's node half is **named** where this node can name it — `SPT_DEV:lia@HFENDULEAM (14efb80c…)`, the name beside the key prefix it resolved from. A record stores that node as a short key prefix, so the lookup is a prefix match and it answers only when the prefix identifies **exactly one** known node. If nothing matches, or more than one does, the prefix stays as it is: a name guessed from an ambiguous prefix would attribute a decision to a machine nobody named. - the mint time renders `YYYY-MM-DD HH:MM TZ` in **your host's** timezone. Both renders come from *this* node — its roster and its clock — so two nodes may legitimately render one record differently, and the block is not something to parse. The record itself is the machine-readable answer, and nothing rendered here reaches verification: the signature check recomposes its tuple from the record's stored spellings, untouched. Both verbs are read-only, take no auth gate, and answer on **any member node** of the binding subnet. For a **fido2 record**, BOUND is stricter: the content hash must match **and** the record's signature must verify. The verifier recomposes the signed tuple from the record's own stored fields — any divergence is NOT-BOUND, never a second canonical form — and checks it against the pubkey enrolled for **exactly** the record's minter node × binding subnet in the replicated enrollment records, which is why it answers on any member node: the enrollment replicated there on the same feed as the seal. No enrollment at that slot refuses by name (`SEAL_VERIFY_NO_ENROLLMENT`) rather than pretending a verdict; an unknown backend kind refuses by name (`SEAL_VERIFY_UNKNOWN_BACKEND` — a newer spt knows that backend); and a fido2 record **missing its signature is NOT-BOUND** — a self-declared FIDO2 mint that cannot be checked is not evidence. Non-fido2 records verify exactly as before. Exact-bytes discipline matters when quoting: a trailing newline is a different content. Both `seal mint` and sealed dispatch trim the way `spt send` trims, so sealing and delivering the same text agree — but verify what was **delivered** (the `` body), not a retyped approximation. ## What arrives on the other side The receiver sees the seal on the delivered envelope: ```text Approved: run the migration tonight ``` To act on it as evidence: `describe` the token to see what it attests, or pipe the delivered body into `verify` for the BOUND verdict. Treat the attribute as a **citation to check, never a credential** — its presence or absence must never move an authorization decision on its own. ## Enrolling an authenticator The TOTP code is the universal ceremony; an **enrolled platform authenticator** is the faster one — [the FIDO2 ceremony](#the-fido2-ceremony): a keypair gated by your OS's own presence check signs the seal payload, verifiable by any member node. Enrollment is what turns it on, per node × subnet: ```text spt seal enroll-authenticator [--subnet ] ``` Enrollment is **per node × subnet** and gated by the **same TOTP ceremony** a seal mint runs — the overlay shows an enrollment brief (the node's key short form, the subnet, the backend, and the pubkey's SHA-256 fingerprint) and a member-or-admin code of the binding subnet admits it. The subnet resolves the way a plain mint's does: `--subnet` wins (refusing a subnet this endpoint is not a member of), otherwise the endpoint's anchor. The verb refuses fast, by name, **before any ceremony opens** when the enrollment could not complete anyway: no platform authenticator on this OS (`SEAL_AUTHENTICATOR_UNAVAILABLE` — Linux names libfido2 as its future backend and refuses honestly this milestone), or the node × subnet pair already enrolled (`SEAL_ENROLL_ALREADY_ENROLLED`). Enrollment records are **immutable in v1** — like seal records there is no expiry and no revocation, so re-enrolling a node needs an operator ruling, not a retry. Every ceremony refusal rides through verbatim; exit 0 means enrolled, and the record prints line-oriented for citation. **Backends.** One seam, per-OS backends. Windows Hello is the first backend (`hello-kcm-rs256`): the keypair lives in the Hello key store, creation and every future signature are gated by your Hello gesture, and the private key never leaves the store. Linux is a named refusal until its libfido2 backend lands — run the enrollment on a Windows node today. **The record.** An enrollment writes `{pubkey_hex, node, subnet, enrolled_at, backend_kind}` into the subnet's security material — the node half is the node-key short form (never a hostname), and the record replicates **subnet-scoped on the same feed as seal records**, so every member node holds the pubkey it will verify FIDO2 seals against. Records are grow-only and **first-enrolled wins everywhere**: a conflicting claim for an enrolled slot is dropped with the existing record kept. ===== /lifecycle/overview.md ===== # Live-agent lifecycle What makes an agent endpoint a *persistent being* rather than a disposable session: identity that survives resets, a working memory that follows it across machines, and graceful endings that never lose context. ## The pieces - **Perch** — the durable seat (identity, spool, state). Sessions attach to it (`api bind`/`listen`), reset across it (`api boundary`), and end without destroying it (`api session-end`). Each of those edges is **observable**: a bind emits `boot`, an `api boundary` emits `clear` or `compact`, as a [`boundary` frame](../shells/frames.md#boundary--the-endpoints-session-edges-durable) to a linked shell and on the `spt api io-events` poll to an adapter. One event per real edge — re-reporting the session already current crosses nothing and emits nothing. - **Bringup states** — `spt endpoint create` writes the perch, `spt endpoint start` (or `spt go`) starts the harness session, and the harness calls `api bind` to bring it **online**. Between the session starting and that bind the endpoint is **unbound**: a live, attachable session — `spt rc ` connects to it to watch or clear a bringup prompt *before* bind — that is not yet message-addressable (a `send` waits for online). The picker and `spt endpoint list` show it as a distinct **unbound** row — see the status-square legend below — not a true offline one. *(since v0.14.0)* - **The mind, in two tiers** — a *live* tier (who the agent is, what it's doing) that follows the endpoint everywhere, and a *project* tier scoped to one project. Both are versioned, tracked storage, synced to paired machines with the same scoping. - **Commune** — the agent drops `-commune.md` into the adapter's watched directory; spt-core ingests the delta into the right tier. A file-drop, not a command — any harness that can write a file can commune. Ingest is **observable**: consuming a drop emits a `COMMUNE` [IO event](../shells/frames.md#communes-commune-and-commune_fail) carrying the file's bytes verbatim, and a *failed* ingest emits `COMMUNE_FAIL` with a named reason and **leaves the file on disk**. That failure used to be silent, which is how an agent could carry on believing its context had been rebuilt when it had not. - **Signoff** — the graceful ending: final commune, then teardown (`spt endpoint shutdown` / `api shutdown`). The echo-commune fires **before** teardown, always. - **Echo-commune** — sessions that end *without* a signoff keep their delta: spt-core runs the adapter's bounded summarizer template over the session history and ingests the result. The **echo gate** is what marks the need, and it has two arms: an *edge* arm (attention changed — detach, attention shift, suspend) that fires at once, and a *work* arm (armed by every idle report) that fires only once fifteen minutes of turn ends have accumulated. A graceful signoff clears both. A session **boundary** also leaves one owed, keyed to the session that ended. - **Psyche** — the endpoint's persistent-context companion, driven as a **bounded per-event turn** (not a resident process): the daemon runs one `[session.psyche_resume]` turn per event (`[session.psyche_init]` is the go-live gate, never spawned). ## Rest and wake Endpoints rest instead of dying: **dormant** (warm — zero idle compute, instantly wakeable) or **suspended** (cold), explicitly via `spt endpoint suspend` or on attention-shift. Resting instances stay addressable; deferred messages are held and released exactly once on wake (`spt endpoint wake`). Every active→resting edge fires a **transition echo** so the final context delta lands before the lights go out. ## Reading the picker The picker (bare `spt`) and `spt endpoint list` mark each endpoint with a status square. **A filled square means you can act now** — control it if it is online, or wake it if it is suspended; **a hollow square means you cannot** (no control seat, or the machine is gone). Endpoints on other machines in the subnet now render with the **same** square as local ones, so a remote row tells you everything a local row does. *(remote parity since v0.17.0)* | Square | State | What it means | |---|---|---| | green ■ | online · free | bound and message-addressable; you can control it | | blue ■ | online · controlled | someone is driving it (the detail pane names the controlling node) | | red ■ | online · unbound | a live session not yet message-bound — attachable with `spt rc`, needs attention | | amber ▢ | online · harness-only | visible but has no control seat, so it cannot be controlled | | gray ■ | suspended | cold but its machine is up — wakeable | | gray ▢ | offline | the machine is down (only ever seen for remote endpoints) | ### Rows that carry no square Two things under `spt endpoint list` are deliberately outside that table. **Your nested perches.** When the caller is itself an endpoint, the list ends with its own nested children — the perches that live *inside* its perch directory and are therefore invisible to the flat scan every other row comes from. Bound children render as ordinary rows, squares and all. A **psyche companion** does not: it is named and marked `psyche companion (status not recorded)`, with no glyph. That absence is the honest answer rather than a missing feature — a companion's custody record holds no status and no pid, so any square would be invented liveness, and an ephemeral psyche is routinely down at the instant you look. The section is structural, not name-matched, so a nested perch called anything at all still appears; the per-node `Total:` counts top-level rows only, so these children never inflate it. **Joined vs Shared.** The subnet line under **This node** reads *Joined subnets* — the memberships this machine holds. A remote node's header keeps *Shared subnets*, which is a genuinely different fact: the subnets that node gossips through, intersected with yours. Two labels, because reading your own membership list as an intersection with yourself invites the question of what it was intersected against. ## Commands `spt endpoint shutdown` · `endpoint suspend` · `endpoint wake` · the `api` lifecycle calls ([reference](../harness-contract/api.md#session-lifecycle)). Agents bringing themselves up live read `spt how-to live` — the in-binary, always-current bringup guidance (the persistent listen relay, the Psyche seam, ready-vs-live). *Deeper tutorial coming with the docs' next tier; the contract above is complete and current.* ===== /terminal/overview.md ===== # Terminal hosting spt-core can *own* agent sessions in its own terminal layer: the daemon's broker holds a real PTY per hosted session, which is what makes sessions supervisable, attachable from other machines, and immune to self-update. ## What the broker holding the PTY buys - **spt-hosted startup** — spt-core spawns sessions itself from the manifest's `[session.self]` template and binds them (`api bind`), instead of waiting inside someone else's process tree. - **Remote attach** — a byte-stream viewport onto a live session from any paired node (compute and files stay on the hosting node). Restart-safe: reconnects resume the stream without gaps or duplicates. - **Input injection** — `send-keys`/`send-line` style injection per the adapter's declared `[inject]` methods, respecting activity state (never disrupt a working agent). - **The live digest** — `spt endpoint digest ` shows an at-a-glance view of what a session is doing now (`--follow` streams changes), **projected from the endpoint's normalized session logs** (the digest-record contract over `[history]`), never the PTY byte stream. Topology-independent — it works for a harness-hosted endpoint with no broker PTY. For scripted, turn-end consumption, `--json` adds an incremental cursor (v0.16.0): `--last ` reads the last N turns; closed-turn transcript entries (`Agent`/`ToolSprint`) carry a stable `seq` and each turn its `input_seq` — `Boundary`/`Context` entries never carry one, and a `partial` trailing turn's entries carry none until it closes; `--after ` cursors over `seq`/`input_seq` and returns only what is newer. See the [integration checklist](../harness-contract/integration-checklist.md#incremental-digest-consumption--the---json-cursor). - **Update immunity** — PTYs live in the broker, logic in the brain; a self-update swaps the brain while every hosted process and byte stream stays intact. Activity and idleness are always **reported** (`api state busy|idle`), never inferred from terminal quiescence — quiet terminals lie. ## When nobody is watching An spt-hosted terminal can run for a long time with no controller and no viewer attached — the agent keeps working, and everything it says goes to a screen nobody is reading. So spt tells it. - After **five minutes** with no controller *and* no viewer attached, the owner agent receives a notice: proceed, but do not assume the user can see your output, and **withhold user-aimed information** until somebody attaches. It is told it will be notified when that happens. - When **anybody** attaches again — a controller or a viewer, from any node — it receives a short return notice and the withholding lifts. Two properties are worth relying on: - **The return notice only ever follows an away notice.** An agent that was never told nobody was watching is never told someone came back — the second message is meaningless without the first. - **The notices cannot wake the agent.** They ride the spool-only hook channel, with no live delivery, so they arrive at the agent's next turn boundary — which is the only moment it could act on them anyway. A message about nobody watching must not itself be the thing that starts a turn. Only endpoints the broker actually hosts a terminal for are in scope: an endpoint with no hosted session cannot be attached to, so there is nothing to be away from. Shells linked to the endpoint see the same fact from the other side, as [`attach` frames](../shells/frames.md#attach--who-is-attached-to-the-owners-terminal). ## Running attach clients after an update An open attach client keeps running the binary it started with. Updating the installed binary does not replace that client process, and the broker's version does not tell you which client code is rendering your terminal. `ATTACH_CLIENT_STALE` is a client advisory, not a warning about every version difference. Its release-maintained policy names a minimum recommended client, the affected platform and attach role, and the concrete function that is degraded. Controller and read-only viewer roles are evaluated separately. Unknown client versions do not trigger the advisory. The notice recommends reopening the client when a sufficient binary is already installed on the client node; otherwise it recommends updating that client and then reopening it. It never forces a detach or prescribes a daemon restart for client-only skew. Unchanged advice is not repeatedly printed. ## Commands `spt endpoint digest` · the attach surface · [`spt api` injection-adjacent calls](../harness-contract/api.md). *Deeper tutorial coming with the docs' next tier.* ===== /networking/overview.md ===== # Networking & subnets Zero-config, no-central-server connectivity between your machines. Join two nodes into a subnet once with a six-digit code; from then on, the same `spt send sergey` works whether sergey is local or three networks away. ## The model - **Node identity** — each machine holds an Ed25519 keypair; the public key *is* its network identity. Connections are mutually authenticated QUIC, end-to-end encrypted, peer-to-peer with NAT hole-punching and public-relay fallback (you can self-host the relay, or disable it for LAN/air-gapped use — the default relays carry only encrypted traffic they cannot read). Nodes also carry a human **label** (the hostname by default): views render `HFENDULEAM (bcead52b…)`, and `@node` qualifiers accept the label or a key prefix — several machines sharing a label are never guessed between. - **Subnets** — machines join into named groups. A subnet shares: the endpoint registry (who exists, where, what state), context sync for its endpoints, notifications, and staged self-updates. Nothing is shared with nodes outside the subnet, ever. - **Joining** — a one-time, code-authenticated ceremony. On a member machine, `spt subnet show-code` prints the current six digits (and an `otpauth://` URI — put the seed in your authenticator app); on the new machine, `spt subnet join ` finds a member over LAN + relay, then prompts for the code and runs the exchange. Finding a member happens *before* you enter the code, so the code you type is always fresh at the moment of pairing — a slow search never causes a just-read code to be rejected, and re-entering a code after a typo retries the pairing only (it does not restart the search). The search shows elapsed time while it runs, and on failure reports why (add `--verbose` for a full diagnostic dump); `--code ` skips the prompt for non-interactive use. The code bootstraps a PAKE key exchange — the code is never the key, and a wrong guess learns nothing. Both sides pin each other's node keys on success (trust-on-first-use; key changes warn and never auto-apply). Every member machine answers join attempts automatically — no arming step on the existing fleet. *(two-phase join since v0.17.0)* - **Elevation gates** — `subnet create` (reveals a fresh subnet's joining secret) and `subnet join` (enrolls the whole machine) require an elevated terminal; `subnet status` is read-only and ungated, and never prints secrets. - **Visibility & sync scope** — per endpoint, per subnet: an endpoint can be hidden from a subnet (neither advertised nor routable) and its mind syncs only to subnets on its membership list. Both default conservative; unconfigured means *not shared*. - **Anchor subnet** — an endpoint is *anchored* to exactly one subnet when it is created, and that anchor is permanent (it sets where the endpoint's identity lives and its default sync scope). On a node in a single subnet the anchor is chosen automatically; on a node in **more than one** subnet, `spt endpoint run` requires `--subnet ` — interactively it proposes a most-recently-used default and asks you to confirm, and non-interactively it refuses with the subnet list rather than guessing. *(since v0.14.0)* - **Resource registry** — endpoints may advertise a free-text service blurb (`spt endpoint description set` to author; `spt endpoint list --detail` to browse) — an agent yellow-pages over visible rows only. ## The walkthrough ```sh # Machine 1 (elevated): mint the subnet — prints the code, an otpauth:// # URI, and a terminal QR. spt subnet create home # Machine 2 (elevated): join it — searches LAN + relay, prompts for the code. spt subnet join home # Either side: who's in, and who's online. spt subnet status --nodes ``` The [quickstart's pairing section](../quickstart/messaging.md) runs this same flow inside the two-agent demo. ### Two keys, and what each one is for `subnet create` shows you two secrets, minutes apart, and each screen leads with the label of the key it is showing — so you always know which one you are scanning. **`--- ADMIN KEY (create) ---`** comes first, and it is shown once, here, and never again. It is what reaches any `spt endpoint engine-room` linked to the subnet, so you can tell that engine room to update the node's security mode, manage the access rules for the node and its endpoints, and grant other agents the rules they need. It also **doubles as a member key** — you can join new nodes with it. You prove you captured it by typing the current code back before anything is written. **`--- MEMBER KEY ---`** comes last. It joins new nodes to the subnet from anywhere, it is the one to share with people whose nodes need to join, and unlike the admin key you can see it again at any time with `spt subnet show-code []` — or by scanning the QR on that screen into your authenticator app, which lets you pair again later without the command. `spt subnet show-code` prints the member key alone and carries no header — there is only one key on that screen, and no admin material is ever shown by it. ## Troubleshooting a join A join searches for a member over every IP family your machine can actually reach. At startup the daemon probes IPv4 and IPv6 once and uses only the families that work — so a network that resolves IPv6 addresses but cannot reach them (a common half-broken setup) no longer silently consumes the whole search window. *(since v0.17.0)* - **See what happened.** `spt subnet join --verbose` prints, on failure, which IP families were usable, the time window it searched, how many attempts it made, and the last concrete error — enough to tell a dead subnet from a wrong code from a network problem. - **Force an IP family off.** Set `SPT_DISABLE_IPV6=1` (or `SPT_DISABLE_IPV4=1`) to make the daemon skip that family regardless of the probe — a deterministic override for a misbehaving network. Setting both is an error. The probe is automatic; reach for these only to pin behaviour. - **Quick discriminator.** If a join hangs only over the wider internet, check whether IPv6 reaches the relay: a working IPv4 path with a dead IPv6 one is the classic case the per-family probe handles for you. ## What rides it Cross-machine `send`/`ring`, registry replication, two-tier mind sync, remote attach, remote suspend/wake, file transfer, notification replication, and peer-propagated self-update — all over the same subnet substrate. ## Commands `spt subnet` (`status` · `create` · `join` · `show-code` · `notify` · `attach`/`detach` · `leave` · `prune`) · `spt endpoint list --detail` · `spt endpoint description` · the qualified addressing forms (`[subnet:]id[@node]`, where `@node` is a label or key prefix) — [CLI reference](../cli/reference.md). ===== /networking/inbound-reachability.md ===== # Inbound reachability A subnet join, a pairing ceremony, and every peer dial toward this machine arrive as **inbound UDP** (QUIC, plus mDNS on the LAN). If something drops that traffic, the node still looks healthy from the inside — the daemon runs, the endpoints list, outbound sends work — and joins toward it simply never arrive. That silent shape has a name in this project's history: the `NO_SEED_HOLDER` dead-end. The daemon therefore checks its own inbound reachability at every startup and records the verdict. **What it then says depends on who is reading.** `spt subnet status` and the coming-online banner speak **only when there is something to warn about**: a node that was positively verified and a node whose probe could not answer both print nothing at all. That silence is deliberate, not an oversight — a view that announces "inbound is fine" on every healthy run is one an operator has stopped reading by the run where it is not. A program cannot work from silence the way a person can, so the machine surface says the verdict in every state instead; see [reading the verdict from a program](#reading-the-verdict-from-a-program). Three layers can block the traffic, and they are not equally fixable from inside the machine. ## Windows: the firewall rule is checked against the running binary The installer registers a **program-scoped** inbound-UDP allow rule when it is run elevated. Program-scoped means the rule admits one executable path, and that is the detail that matters: - A rule can exist and still block you, if the binary that binds the socket has moved, been reinstalled elsewhere, or is a development build running from a different directory. - So the check is not "does a rule with that name exist" — it is **does the rule admit the binary that is actually running the daemon**. A rule naming some other build fails the check and says so, naming both paths. When the check fails and the daemon is running elevated, it repairs the rule onto its own path. Unelevated, it reports the exact command instead and changes nothing. If no daemon is resident, the check reports that it cannot say — it never guesses which binary would have bound the socket. Re-checking at every daemon start is deliberate. An unelevated install prints a warning and continues, so the rule may simply never have landed; nothing would have re-examined it otherwise. ## Linux: the host firewall is verified and reported, never modified On Linux the daemon detects an active host firewall (`ufw`, `nftables`, `firewalld`), works out whether inbound UDP to the port it actually bound is permitted, and renders the command that would permit it. It **does not write firewall rules**. The reason is that spt's QUIC endpoint currently binds an *ephemeral* UDP port, so a rule written for today's port would be stale after the next restart while still reading as "fixed". A durable rule needs a pinned port, which is a separate change with its own security implications; until then, verify-and-tell is the honest behaviour. If a firewall **manager** is running — `ufw` or `firewalld` — the check reports that manager and its commands, never `nftables`. nftables is the backend those tools write into, so on a managed host its rules are the manager's: editing them directly would be overwritten, and it is not the language you administer that box in. `nftables` is named only when no manager is active. Two answers are worth distinguishing: | What you see | What it means | |---|---| | *"… does not admit inbound UDP to the port this daemon bound"* | An active firewall was read and it does not permit the port. Run the printed command. | | *"… could not read its ruleset (it needs root) … unverified"* | A firewall is active but the daemon is unprivileged and could not inspect it. Not known blocked, not known open — run the printed check. | Silence means the check had nothing it could positively determine. It is not a guarantee of reachability; see the next section for why nothing local could be. ## Cloud providers: inbound UDP is your requirement to satisfy A provider-level firewall — a cloud vendor's security group or network firewall, e.g. a DigitalOcean droplet's — sits **outside** the machine. No installer and no local probe can see it or change it, by design. **If you run a node on cloud infrastructure, inbound UDP must be allowed to it at the provider.** This is a hosting requirement, not something spt can arrange for you. Unsatisfied, it produces exactly the symptom above: joins and pairings toward the node time out with nothing to see locally, while the node itself reports healthy. When a node is unreachable and the local checks are silent, the provider firewall is the first thing to check. ## Reading the verdict from a program `spt subnet status --json` carries the verdict as an `inbound` object — in **every** state, and never omitted. The `--nodes` form of the same command carries it on the same terms, because a field that appears and disappears with an unrelated flag is one no consumer can depend on. ```json { "daemon_running": true, "inbound": { "verdict": "path_mismatch", "rule_path": "…", "running_path": "…", "fix": "…" } } ``` The state is the `verdict` key, and it spells itself the way the daemon's own record does: | `verdict` | what it means | also carries | |---|---|---| | `ok` | inbound UDP was positively verified to reach the binder | — | | `missing` | no firewall rule covers the binder at all | `fix` | | `path_mismatch` | a rule exists but names a different binary than the one holding the socket — green by name, blocked in fact | `rule_path`, `running_path`, `fix` | | `blocked` | an active host firewall was read and does not permit the bound port | `firewall`, `fix` | | `unverified` | a firewall is active but its ruleset could not be read — neither blocked nor fine | `firewall`, `check` | | `unknown` | cannot say: the probe failed, the platform has no firewall story, the record is stale, or no daemon is running | — | **`path_mismatch` carries `running_path`, not `binder_path`, and it is worth saying why the name is what it is.** The daemon's on-disk record wraps the verdict in an envelope that carries a `binder_path` of its own; while the variant used the same name, the two serialized to a duplicate key, the record failed to parse, and the verdict fell back to `unknown` (releases#172). So until that fix, `path_mismatch` could not reach this field at all — a consumer reading `binder_path` here was reading a shape the daemon had never once emitted. `running_path` means exactly what the old name did: the image the daemon that holds the socket is actually running. Two properties are worth relying on: **`unknown` is a real answer, not a missing one.** With no daemon running the read resolves no live binder and answers `unknown` on its own — there is no special case for it, and no state where the field is simply absent. So a consumer never has to tell "verified fine" from "cannot say" from "this build did not emit the field" by looking at what is *not* there. **The `fix` and `check` commands are built by the process that knows the real binary path and bound port** — render them verbatim rather than reconstructing them. A command rebuilt from the outside drifts from the thing the daemon actually checked, which is the same class of failure as `path_mismatch` itself. This is the deliberate asymmetry with the human views above, and neither side should be "harmonised" into the other: silence is right for a person reading a status view, and useless to a program reading a field. ===== /networking/engine-room-setup.md ===== # Engine room: first-time setup Every node has room for exactly one **engine room**: a locked-down agent endpoint that is the node's governance surface — the one place its access posture (which machines and agents may reach what) gets set. It is an ordinary hosted agent in substrate, and an extraordinary one in lifecycle: it comes online only for a human who proves a subnet code, and it is never reachable the way other endpoints are. Setting one up is three steps: **ceremony → bring-up → briefing**. ## 1. The ceremony — bind an anchor subnet and an adapter ```text spt endpoint engine-room --adapter ``` This creates the engine-room record (or resets an existing one), binding the two facts nothing else can change: its **anchor subnet** (whose codes will gate bring-up) and its **harness adapter** (the agent runtime that hosts its mind). - The subnet must already be joined on this node, and the adapter registered (`spt adapter list`) — the ceremony refuses otherwise, because an engine room bound to material it cannot verify or run would only fail later. - **Creating** a first record needs no elevation — run the ceremony early in a node's life; the unelevated window closes permanently at the first run. - **Resetting** an existing record must run in an elevated shell (it rebinds a live governance surface). - Neither form can be run by a hosted agent. The ceremony refuses when it detects one — this is a surface reserved for the human at the machine. ## 2. Bring-up — attach with a subnet code ```text spt rc engine-room ``` A bare attach opens an interactive prompt for the anchor subnet's current six-digit code — either the member code or the admin code is accepted (read it from your authenticator app), though which of the two you use decides one further thing, [below](#bringing-up-with-the-admin-code-empowers-the-seat). The prompt names the node whose engine room is coming up and the subnet whose code answers it, so an operator holding codes for several subnets can see which one to reach for. Esc cancels. `--code ` passes it directly, with one caveat: a code typed on the command line is readable by other processes on the machine while it is still valid, so prefer the prompt. Wrong codes are counted against a persistent, exponentially backing-off ledger, and repeated failures raise a notification — the gate cannot be quietly brute-forced. ### Bringing up with the admin code empowers the seat Which of the two codes you use decides one further thing. Pass the **admin** code and the seat is **empowered for the engine room's anchor subnet** the moment it is taken — you can set that subnet's control-surface modes (`spt api access-refresh engine-room`) without proving the same admin code a second time through `spt api empower`. Pass the **member** code and nothing is granted: the room comes up exactly as it always did. This is not a new authority. It is the same credential, proved once instead of twice — the admin key you just typed at the gate is the admin key `empower` would have asked you for. - **Scope: the anchor subnet only.** Any *other* subnet still needs an explicit `spt api empower engine-room --admin-code `. Bringing the room up never grants authority over a subnet it is not anchored in. - **Lifetime: identical to an explicit `empower`.** It lasts until the session ends or the controller detaches; detaching drops it, and re-attaching re-proves it. There is nothing extra to revoke. - **Attach or take, same gate, same grant.** A local `--take` passes the same code gate the incumbent did, so it earns the same empowerment. - **It is never silent, and it is never early.** The grant is written when the seat is actually taken — the bring-up first says only that the room is up, and the sentence about holding its controls (with the grant) follows once your attach is established. An empowered seat that said nothing would be indistinguishable from an ordinary one until a mode change unexpectedly succeeded; a seat that announced a grant before anyone was at the controls would be worse, because that sentence would sometimes be false. Bring-up fails closed if the bound adapter is missing: an engine room that cannot host its own mind does not come online half-formed. ## 3. The briefing — what you are holding The moment a controller is *seated* — not a moment earlier — the engine room's session receives a system-authored briefing message: what the engine room can do, what it is answerable for, the node's exact current access posture, any pending subnet-mode declarations, and the full ruleset table. If the bring-up that admitted you proved the **admin** code, the briefing opens by saying so — the grant is stated **before** the capability list, because it changes what that list means for this seat: `access-refresh` is spendable here without an `empower` first, and a reader who met that fact after the menu would already have decided it needed a code it does not need. An ordinary bring-up says nothing at that point, which is the absence itself rather than a reassurance. Both surfaces — the attach line and this briefing — state the grant in one shared sentence, so they cannot drift into two accounts of one fact. While your terminal is attached the engine room is **online**; detaching drops its access posture (inbound refused, every empowerment revoked, no longer advertised) while the hosted session keeps running for the next attach. A local take-over of the controls passes the same code gate the incumbent did, and is loud. ## What the engine room refuses, always - Remote attach, from any node. - Read-only viewing (`--view`), even locally. - All inbound messages except replies to its own outbound, and knocks, which land in its inbox and wait there whether or not it is online. - Deletion: purging it resets the record instead (elevated shells only) — a node can never be left without a way back to a governance surface. ===== /networking/access-viewing.md ===== # Viewing access rules and posture Access views are **roster-first**: instead of one flat dump of every rule, each view lists the *access entities* — the subnets, machines, and endpoints that rules or modes actually name — grouped by type, each with its rule count and (for a subnet or this machine) its mode. The granular rule list is readable only per named entity, because reading a posture is a comparison per entity, not a scroll. ## Per-endpoint: `spt endpoint access` ```text spt endpoint access # every ruled endpoint's roster spt endpoint access wanda # one endpoint's roster ``` A roster line per ruled entity, grouped subnets → machines → endpoints: ```text access entities ruled for 'wanda': bignet - mode: closed (DISCOVER open (default)) - 2 access rules quietnet - mode: open HFENDULEAM - mode: open flynn@kitsubito (bignet, quietnet) - 1 access rule ``` - A subnet appears when rules name it **or** when its captured mode decides the endpoint's fallback posture — a mode source is part of the picture even with zero explicit rules. - A `closed` mode names what it does **not** close. `DISCOVER` — being found — is on by default, and no blanket posture reaches it, so a closed table renders `closed (DISCOVER open (default))`. Where someone has written an explicit open for it the line reads `DISCOVER open (pinned)` instead: a pin outlives a change of the default and is a different fact from the default itself. The only things that close it are a deny row naming the surface (per subject) and, node-wide, `spt api access-node-surface-mode DISCOVER closed` from this node's engine room. - `WEB` — a served file fetched by another subnet member — is also on by default within the subnet: registering a file is already a deliberate act of exposure, so a blanket closed posture does not close it. A deny row naming `WEB` (per subject) or the node-wide surface mode does. The owning node checks the row under the fetching node's handshake-proven identity and answers `403` with a body naming `WEB`. The two sides of a `WEB` rule: its **origin** matches the fetching node or that node's subnet (no sender endpoint exists to name yet); its **subject** is the endpoint that registered the file, or the node itself for the index and the docs. - This machine (colored like it is in `spt endpoint list`) appears with its own mode when one is set. - A ruled endpoint resolves to `id@machine (shared subnets)` where this node can see it, and renders bare where it cannot — being unresolvable does not hide the rule. - Entities with no rules for the target are omitted entirely. Drill down to the granular rules of one named entity: ```text spt endpoint access wanda --subnet-rules bignet spt endpoint access --endpoint-rules flynn spt endpoint access --node-rules ``` Each prints the matching rules as a **markdown table** (subject, surfaces, deciding tier, verdict) — the same renderer the engine room's session briefing uses, so the grid you are briefed with and the grid you can ask for again never drift. Markdown because a briefing is read wherever an agent relays it: a space-aligned grid is reflowed into a run-on by a chat surface, and a table that stops being a table in transit is not one. Cells stay padded, so the same render is still column-aligned in a terminal. A **node subject reads as the node's name**, not its pubkey: ```text | SCOPE | TIER | SUBJECT | SURFACE | ORIGIN | DECISION | FROM | | -------- | ------------- | -------------- | ------- | ------ | -------- | ------ | | node | node-rule | subnet:bignet | DISCOVER| - | allow | manual | | sparrow | endpoint-rule | node:ENLYZEAM | MSG | - | deny | manual | ``` A node this machine cannot name — no roster entry, no advertised label — keeps its **full** pubkey hex instead. Never blank, never an error, and never shortened: a truncated hash is the thing that was unreadable in the first place, and the full one is at least pasteable into a rule. The name is a rendering only; `--json` keeps the full hex as the row's `subject` and carries the resolved name beside it, so anything keying on the pubkey is unaffected. One naming caveat: an endpoint literally named `allow`, `revoke`, or `open` parses as the editing subcommand, so it has no positional path — reach its rules through the drill-down flags instead. ## Node tier: `spt node access` ```text spt node access ``` The node-tier roster: the entities the node-wide rules name, this machine's own mode (with per-surface exceptions, e.g. `closed (MSG open, DISCOVER open (default))`), and the captured subnet modes — the tier every hosted endpoint falls through to when nothing more specific matches. This is also the tier the engine room's per-surface verb writes, so a node that has closed being found reads `closed (DISCOVER closed)` here. ## Governing this node's own traffic A rule whose subject is **this node's own id** governs traffic authored *here* — one agent on this machine reaching another. It is an ordinary rule at the tiers you already have: no separate tier, no separate command, no schema of its own. You never type your own 64-character pubkey for it. `--node` takes three spellings and they are tried in this order: ```text spt node access deny --surfaces MSG --node self spt endpoint access allow ling --surfaces MSG --node KITSUBITO spt endpoint access allow ling --surfaces MSG --node 6e4abfa9aa08... ``` | spelling | means | |---|---| | a 64-hex pubkey | that node, exactly — tried first, so nothing can shadow it | | `self` | this node; a reserved word, so a machine *labelled* `self` cannot take it | | a node name | the node carrying that name, as `spt subnet status --nodes` shows it | **The rule stores the hex, whichever you typed.** A name is presentation and a lease that can move to another machine; the identity is the key. If a name is carried by two machines the command refuses and names both, rather than picking one and writing a rule about a node you did not mean. In every view the stored subject renders like any other node subject — `node:` when the name resolves, the full hex otherwise — never as `self`: `self` is something you type, not something a rule is. Written at **node scope** it governs intra-node traffic for every endpoint hosted here. Written on **one endpoint** it governs what other same-node endpoints may do to that endpoint, and endpoint rules are consulted before node-wide ones, so a per-endpoint allow re-opens one target through a node-wide deny. Two things it deliberately does not do. **Modes still abstain for local traffic** — a `closed` posture is about who may reach this machine from outside it, and closing the node has never meant stopping the agents on it talking to each other; only a rule that *names* the local origin speaks about local traffic. And a **correlated reply is still admitted** with no rule of its own, own-node deny included, so an agent you messaged can always answer you. **On a node with no identity yet, `--node self` refuses** rather than minting one. Writing an access rule must not create the identity that rule is about. Give the node an identity with `spt subnet create ` or `spt subnet join` first. > **Coverage, as it stands today.** A rule naming a specific *sender* endpoint > is matched from the sender the delivery path supplies, and the notify path > supplies it in a different shape from `spt send` and `spt ring` — so a > sender-subject rule written for `ling` does not match traffic arriving by > notify. Rules whose subject is a **node** (including `self`) are unaffected. > Tracked as releases#215. ## Subnet modes: `spt subnet status` A subnet is a *subject* of rules and a *source* of modes — never a rule-holding target, so there is no `spt subnet access`. Its mode facts live on its own view: ```text spt subnet status bignet ``` states three things, in words even when absent: - **declared by subnet** — the posture the subnet declares, as this node knows it; - **captured here** — what this node actually enforces as its fallback (captured at join or at mint, changed only through the engine room's refresh); - **PENDING** — a declared change this node has seen but not adopted, with when it was seen. Your posture does not change until the engine room adopts it. The **bare** `spt subnet status` — no subnet named — carries the first two of those facts for every subnet it lists, as a `MODE` and a `CAPTURED HERE` column. Both views state an absence in words rather than leaving a cell blank: a subnet that declares `closed` while this node captured nothing is enforcing **open**, and that is exactly the state a membership-only table would have shown as an ordinary healthy row. ### The node that mints a subnet captures its own declaration Creating a subnet is the consenting act, so `spt subnet create` records the mode it just declared into this node's access store — the same capture a joining node performs at join. Without it a `--closed` subnet is asymmetric by construction: every joiner enforces the posture while the minting node, having nothing captured, falls through to implicit open on every surface. A subnet minted by an **older build** captured nothing, and nothing back-fills it silently: a subnet record carries no "minted here" marker, so *declared present and captured absent* cannot be told apart from *joined before subnet modes existed* — and retro-capturing the second would close a running mesh without anyone asking for it. Heal such a node explicitly, from its engine room: ```text spt api access-refresh bignet ``` The create ceremony prints that remedy itself, so the state is discoverable from the command that produces it. ## No remote rule-read Rules are **node-sovereign**. There is no verb, on any surface, that reads another node's access rules — viewing a node's rules means running the CLI on that node. What a subnet *declares* travels as an advisory; what a node *enforces* is its own, and only its own console will tell you. ===== /networking/knocking.md ===== # Knocking: asking to be let in A **knock** asks an endpoint to let you reach it. It is a request, never a grant: answering it is what writes an access rule, and the answer belongs to the endpoint being asked. ```text spt knock wanda --surfaces MSG --send-only # ask spt knock list --for wanda # see what is waiting for you spt knock approve k-4f2a --approve-requested spt knock deny k-4f2a ``` **A knock asks for `MSG` by default** — only use `--surfaces` if you need more than MSG. The commonest knock is "let me talk to you", and asking for every surface would put a whole-machine grant in front of someone who only meant to answer a message. `--surfaces ALL` still asks for everything, out loud. `spt knock ` **is** `spt knock send ` — the same command by a shorter name, with the same flags, the same defaults and the same knocker. Use whichever reads better. The one place they differ is a name collision: a **subcommand always wins over the target**, so an endpoint whose id happens to be `send`, `list`, `approve`, `deny`, `new-code` or `redeem` cannot be reached by the bare form. Knock it as `spt knock send `. Knocks work between machines as well as within one. If the endpoint you name lives on another node, the knock travels there and lands in that node's inbox. **Surface names are case-insensitive**, and what you type is stored in the table's own spelling: `msg`, `Msg` and `MSG` all become `MSG`, and `all` in any case is the every-surface sentinel rather than a surface literally named "all". You do not have to remember the vocabulary. Every verb whose invocation names a surface prints a **`Control surfaces:`** section in its own `--help`, composed from the surface table at render time — `spt knock` and its `send`, `approve`, `new-code` and `list` forms; `spt endpoint access` (the listing and its `allow`/`deny`/`remove`); `spt node access` and the same three; and `spt subnet create`, whose open/closed choice is a posture over that whole vocabulary. Each line names the traffic and what granting it **admits**: a surface that carries a proven sender binds a grant to that single sender, and one that does not admits the sender's whole machine. `spt knock redeem` and `spt knock deny` print no such section on purpose — by then the surfaces are already fixed by the code, or by the knock you are answering, so offering the vocabulary there would suggest a choice you do not have. A token that matches no known surface is **refused where you typed it**, naming the surfaces that do exist — before the knock is sent, so a typo costs nothing rather than travelling to another machine, waiting to be read, and being approved into a grant nobody asked for. ## Nobody is interrupted A knock lands in a **queryable inbox** and is never pushed at the receiving agent. Somebody has to look — you, or another agent asking on your behalf. That is deliberate: an unsolicited request that could interrupt an agent's work would be a channel worth spamming. The inbox is owned by the daemon, not by a perch, so a knock survives the target's agent being asleep, detached, or absent entirely. Purging the *knocker's* endpoint does not invalidate a knock they already sent. Two things do notify, and only these two, because each is invited by something you did yourself — each is an **answer to a request you sent**: - an approval notifies the knocker — they asked; - a redemption notifies the code's minter — they minted it. A **knock-back** does not notify. It is a new request from the other side, not an answer to yours, and new requests land in the inbox like every other. ## Who you knock as There is no `--from`. The knocker is classified at invocation and stamped by the daemon: - an **agent** knocks as its own endpoint, and an approval whitelists exactly that endpoint; - a **person at a terminal** knocks as *the humans on their machine* — the request is `subject , origin user`, deliberately narrower than admitting the whole machine, so the commonest approval admits people and not their agents. `--for ` knocks on behalf of an endpoint that lives on **your** machine. Naming one that does not exist here is refused rather than sent. ## Two-way reach is offered, never imposed **You say which way reach runs when you ask for it**, and only then. Every reach-*requesting* command — `spt knock `, `spt knock send` and `spt knock redeem` — requires **exactly one of `--send-only` or `--send-receive`**. There is no default: a bare invocation refuses and names both, and passing both refuses too, because they are opposite answers to the same question. The flag describes **your own side**, never theirs: - `--send-only` asks to reach them, and deliberately not the reverse. It is the explicit decline, and it is **recorded**, so a decision to keep reach one-directional reads back later as a decision and not as a flag nobody typed. - `--send-receive` also pre-authorizes the reverse **on your own side**. Nobody writes another endpoint's rules; your daemon writes it if and when they answer. It is consumed exactly once, and an unanswered knock leaves it unconsumed — a conditional intention, not a standing grant. **What `--send-only` does not bar: replies.** A reply needs no rule of its own, on any endpoint. The access gate implements a stateful firewall: a message correlated to the receiving endpoint's **own outbound** is admitted on that correlation, before any rule or mode is consulted — and this holds even when the access store cannot be read, because the exemption precedes the store. The engine room is the strictest consumer of the same rule, not its owner: even the seat that refuses all inbound still answers replies to its own outbound. So a `--send-only` grant means the far side cannot *initiate* traffic toward you; it can always *answer* the traffic you start. Declining reverse reach declines unsolicited sends, never the conversation you open. **Answering carries no directionality at all.** `spt knock approve` and `spt knock new-code` take no directionality flag, because accepting *is* your own side's act — there is nothing further to declare. If you approve someone and want to reach *them* as well, **knock back**: ```sh spt knock send flynn --surfaces MSG --send-only ``` That is the same verb anybody else uses to ask for reach, which is the point: one instrument, one grammar. > **Renamed in v0.54.0.** `--mutual` is now `--send-receive` and `--one-way` is > now `--send-only`, and both moved from the answering verbs to the asking ones. > The old spellings are **parse errors** that name their replacement — there are > no aliases. Pre-authorizations you armed under the old flags are untouched and > still honored. **Two-way reach works across machines.** A pre-authorization is still consumed only on the node that armed it — nobody writes another endpoint's rules — and what crosses is the answer, not the rule: - an approval or denial travels back to the knocker's node as an **answer receipt**, and their own daemon writes the reverse rule (approval) or retires the intention (denial). A receipt acts only on a record bound at knock time to the node being knocked, so nothing else on the network can fire or destroy it; - a **knock-back** is an ordinary knock and rides the wire any first-order knock rides, into the other side's inbox on their own machine. If the far machine never answers, nothing opens and nothing closes: the pre-authorization stays armed and expires with the knock, and every surface says so rather than claiming an outcome. ## Invite codes A code is a **pre-approval** you can hand to someone, with the granted surfaces baked in at mint. Presenting it reaches your endpoint even if it is undiscoverable, and auto-approves with exactly those surfaces. ```text spt knock new-code --surfaces MSG # mint (from that endpoint's session) spt knock redeem --send-only # present one you were given ``` **A code carries its target.** Possessing one tells you nothing about any other endpoint, so a code can never be used to enumerate what exists on a node. Codes are single-use and expire. A redemption whose grant fails to write does **not** spend the code — repair the problem and redeem the same code again. ## Redeeming from another machine A code can be presented from any machine in the subnet it was sealed to, not only from the one that minted it. You do not have to be able to see the minting machine first, and you never name it yourself: ```text spt knock redeem sptkc_... ``` **A sealed code carries its own route.** Sealed inside the `sptkc_` string, alongside the secret, is the machine that minted it. Opening the seal takes a key only members of that subnet hold — so opening it is itself the proof that you belong there — and what comes out names both the subnet to look in and the machine to carry the redemption to. Your machine then finds that minter among the subnet members it already knows of. It never looks the *endpoint* up, and that is the point: the endpoint you are redeeming against is usually one that cannot be looked up at all. Being unreachable by discovery is the ordinary reason somebody hands you a code in the first place, so a redemption that depended on discovery would fail exactly where it is needed. Codes minted before sealed codes existed are plain strings with no route inside them. They still work, and they still redeem on the machine that minted them. ### What you can be told | outcome | what it means | |---|---| | **redeemed** | the grant is written. The reply names the target, the surfaces you were granted, and whether reach is now one- or two-directional | | **refused** | the code was seen and turned down. **One message covers every cause** — unknown, expired, already used, too many attempts — because saying *which* would let a stranger learn from refusals which codes exist | | **unconfirmed** | **no answer came back at all** | | **peer silent** | **the machine took the redemption and then said nothing** — it is still holding the exchange open, which points at a machine that is wedged or overloaded rather than one too old to understand redemptions. Nothing was decided and **the code was not spent** | The last two rows are the ones to remember: **silence is not a refusal.** The minting machine may be off, unreachable, running a version old enough that it does not understand redemptions, or wedged mid-exchange, and an answer can simply be lost. Nothing was decided about your code and **it was not spent**, so it is still worth presenting again. A presenter told "refused" here would throw away a good code that was never even seen. Two refusals arrive before anything is sent, and both are about the route rather than the code: - **it cannot be opened** — no subnet this machine belongs to holds a key that opens it. Either it was sealed to a subnet you are not in, or the string is damaged; nothing else about it can be told apart from here. - **there is no route** — the code names a machine this subnet has not seen yet. That machine has to appear in the subnet before it can be reached. A code whose route is ambiguous is refused rather than guessed at — presenting a live code to the wrong machine is not a mistake worth risking to save a prompt. ### Opening your own side, when you redeem `--send-receive` arms the reverse on **your own** side, against the code you are presenting, and it does that whether the code was minted on this machine or on another one. Nobody writes another endpoint's rules here either: what the flag buys you is a rule your own daemon writes, and only once the far side has actually let you in. - **the code was minted on the machine you are redeeming from** — the arm is consumed in the same invocation, so reach is two-directional immediately. - **the code was minted elsewhere** — the arm is recorded before the redemption is sent, and written only when the **redeemed** reply comes back node-proven. That reply is also what fills the rule in: the subject and the surfaces are the ones the answer carried, never a guess made here from a code that says nothing about who will answer it. It is armed before the send rather than after because an intention written only once the answer arrives could not survive an answer that never comes. So the three outcomes in the table above are told apart on your own record and not merely in the sentence printed beside them: a redemption consumes the arm, **a refusal disarms it**, and **silence leaves it armed** — the same "silence is not a refusal" rule the table keeps, applied to your side of the exchange. ## Limits that stop knocking being a nuisance These are enforced by the **receiving** node, against its own store and clock — a limit the sender honoured would only bind the honest: | limit | value | why | |---|---|---| | one pending knock per (knocker, target) | — | re-knocking updates your request in place instead of queueing another, so an inbox cannot be filled by repetition | | time to live | **24 hours** | an unanswered knock expires; the expiry is checked **when you answer**, so a stale listing can never make an expired knock approvable | | inbound knocks per machine | ~10/hour | a flood from one node is refused before it reaches anyone's inbox | | code redemption attempts | rate-limited per machine | guessing a code is bounded by this together with the TTL | An expired knock reads as **expired**, not as though nobody ever asked. ## What an approval may and may not write Approving names the surfaces you are granting — either `--approve-requested` to grant what was asked, or `--surfaces` to grant less. **An approval can narrow a request, never widen it.** Which subject the grant binds depends on whether the surface can identify its sender: - on a surface whose traffic carries a **proven sender** (today `MSG`), the grant names exactly that endpoint; - on a surface that carries none, the only subject that can match is the knocker's **whole machine**. Approving such a surface therefore admits every endpoint on it, whatever the knock named, so it requires `--admit-node` and is gated by the node's policy. When a single knock mixes both kinds and the policy forbids the widening half, the approval is **partial**: the identifiable half is granted, the rest stays pending, and the output names the engine room as the seat that can answer it. A partial approval is reported as partial — never as approved, and never as denied. ## Imparting a note about whoever you admit An answer can also record what you have decided about the person it lets in — a [monic](monics.md), which is what stops them arriving as a stranger: ```text spt knock approve k-4f2a --approve-requested --monic "flynn's field-verify seat" spt knock new-code --surfaces MSG --monic "whoever redeems this is a courier" ``` The code path is deferred by necessity, not by design: at mint there is nobody to write a classification *about* yet, so a note typed at mint is imparted when the code is **redeemed**, once the redeemer's identity is stamped and real. **The note is about a daemon-stamped id, never a supplied one** — the same id the grant is written for, so a note can no more be planted on an innocent peer than a grant can. A knocker with no endpoint id — a bare-terminal human, stamped as their node — **cannot** be classified: the note is refused loudly and the grant stands, because a classification filed under a node id would be a record no delivery ever matches while reading back as though somebody had been classified. **A note you already hold wins.** An approval must not silently rewrite what you already decided about a peer, and a note typed at code-mint hours earlier certainly must not. You are told which happened, and given the command to replace it if that is what you meant. A record that is present but unreadable is not a classification, so imparting replaces it. **The note rides the grant and never changes it.** It is imparted only after the grant has committed, is skipped entirely on a refusal, and a mind that cannot be opened costs a loud diagnostic rather than a retracted approval. A knocker admitted **without** a note still gets in — they simply arrive as an unclassified peer, and their first message carries the [trust warning](monics.md#the-trust-warning). ## Refusals you can predict These exist so that a rule you can read back is a rule that actually governs. **A rule about nobody is refused when you type it.** Every mutation names a subject — `--endpoint`, `--node`, or `--any-of`. The error arrives before any store is touched. **A rule that could never match is refused rather than stored.** Naming a sender endpoint on a surface that carries no proven sender is rejected at the CLI: such a rule would sit in the view looking like protection while matching nothing. Rule about the machine instead, or drop that surface. **A rule naming no surfaces must satisfy the node policy on _every_ surface.** Omitting `--surfaces` (or passing `ALL`, in any case) covers all of them, so if any single surface is closed to that kind of grant, the whole blanket rule is refused — otherwise the widest possible grant would be the easiest one to slip past a closed posture. ## Where rules end up Everything a knock produces is an ordinary access rule, visible in the usual views with its origin recorded — `knock-approve` or `code-redeem` — and with the exact command to remove it printed beside it. Rules born of a knock have no special lifecycle afterwards; they are removed like any other. See [Viewing access rules and posture](access-viewing.md). ===== /networking/monics.md ===== # Monics and the trust warning A **monic** is a **reactionary string**: a set of **triggers** plus a **body** that is revealed when something in your session matches one of them. A monic is **not inherently about a peer** — classifying a peer is one thing you can do with one kind of trigger, not what a monic is. Classifying a peer is still the headline use, and it is what the **trust warning** reads: an access rule says a peer **may speak**; a monic that matches their id says what you have concluded about them. Those are different questions, and the gap between them is what the trust warning exists to close. ```text spt endpoint monic # what do I hold? spt endpoint monic add --target my-gater \ --triggers '[{"kind":"sender","pattern":"doyle"}]' <<'EOF' my gater — his rulings are authoritative EOF spt endpoint monic update --target my-gater \ --triggers '[{"kind":"sender","pattern":"doyle"}]' <<'EOF' my gater, and the seat that closes waves EOF spt endpoint monic remove --target my-gater ``` The body arrives on **stdin** because a body is prose — it carries newlines, quotes and shell metacharacters, and passing it as an argument hands all of that to whatever shell is in the middle. ## A monic lives in your mind, one file per record Monics are **mind**, not node state. They sit in the agent's own tracked mind tier beside its role, on the same branch, syncing over the same path — so a monic you wrote on one node holds wherever you sit next. There is no second store to keep in step, and two instances of you cannot disagree about what you wrote because a side-store failed to travel. A monic is addressed by **its own id**, which is not necessarily any of its triggers, and lives at `monics/`. That separation is the point: a record named `escalation-policy` can classify `mallory`, one record can classify several peers, and several records can classify one peer. None of that was expressible when the peer *was* the filename. There is **one file per record**, and that is load-bearing rather than a layout taste. The mind's merge resolves **per file path** and never merges contents, so the path granularity *is* the conflict granularity. With every monic in a single file, two instances of you writing *different* monics at the same time would collide on that one path and hand you a conflict about nothing — between two facts that never disagreed. Per-record files make those writes invisible to each other and confine a real conflict to the one record both instances actually wrote. (Per-record is strictly finer than per-peer, so this addressing *improves* conflict behaviour rather than trading it away.) Each record also carries its id **inside** it, not only in its filename, so a record recovered from a merge artifact, a bundle, or a hand copy still knows what it is. Looking a monic up is a **scan** of that directory, and it is deliberately un-indexed: an index is a cache with an invalidation seam, and none is minted until a measurement asks for one. ### Records written before the re-key Monics written before the 2026-08-03 re-key were filed under a peer id, with that peer carried in the body. They keep working with no action from you: such a record reads as a monic whose **id** is that peer id and whose trigger set is a single `sender` trigger on it — which is exactly what it always meant. spt also rewrites them in place, so the stored bytes come to say the same thing. ## `add` and `update` refuse opposite things `add` refuses when the id is already taken. `update` refuses when nothing is there. That is deliberate: a mistyped id or a re-run script cannot quietly overwrite a monic you already wrote, and it cannot invent one you never wrote either. Each refusal names the other verb. An update states the record **whole** — a monic is one reactionary string, not a log you append to. `remove` is idempotent. ### Writing several at once One stdin payload can carry several monics. Pass `--batch` and hand it a JSON array, each element carrying its own id, triggers and body: ```text spt endpoint monic add --batch <<'EOF' [ {"id": "my-gater", "triggers": [{"kind": "sender", "pattern": "doyle"}], "text": "my gater — his rulings are authoritative"}, {"id": "on-deploys", "triggers": [{"kind": "content", "pattern": "deploy"}], "text": "check the release lane before answering"} ] EOF ``` `--batch` is a **separate input shape**, not a reinterpretation of the flags: with `--target` the flags name the record and stdin is its body, so a payload that also carried ids would be two sources for one fact. spt refuses the two spellings together. A batch applies **record by record** and does not roll back what already landed. Each record is an independent fact, and a partial application that tells you exactly which ids landed is easier to recover from than an all-or-nothing failure you then have to diagnose. The exit code is non-zero if *any* record was refused, so a script cannot read a partial application as success. ## A record you cannot read still shows up A monic file that is present but unparseable reads as **"never classified"** at the delivery edge. That is correct there, because it fails safe — you get warned *more*, never less. But a damaged record that also vanished from the listing would be a file you could neither act on nor discover. So the listing names it under **its own monic id** and **marks it unreadable**, and points at the verb that rewrites it. The delivery edge and the listing deliberately say different things about the same file, and each is saying the useful thing for its own reader. For `add` and `update`, **an unreadable record counts as one that is there.** The id is spoken for by a file, so `add` refuses it — telling you the record is unreadable rather than quietly writing over content you cannot read — and `update` is the verb that replaces it, saying `(replacing an unreadable record under )` when it does. If what you want is the record *gone* rather than rewritten, `monic remove --target ` withdraws it; removal acts on the file, so it clears a damaged record the same way it clears a healthy one. ## Copying another endpoint's judgements ```text spt endpoint monic clone my-gater --from ling # one monic, by its id spt endpoint monic clone --all --from ling # everything ling holds spt endpoint monic clone --all --from ling --overwrite ``` A clone copies the source's mind **at its tip**, through the same copy seam a fork uses — not a second copy path. A record the destination already holds under that id is **kept and reported**, never silently replaced; `--overwrite` is how you replace one deliberately. Every copied record is stamped **inherited**, so you can always tell your own judgements from the ones you were handed. A husk in the source travels as a husk — visible in your listing, never dropped and never invented. A clone that copies nothing mints nothing. ## No monic verb ever needs elevation Writing a monic is the act "I know this endpoint". It is the agent's own judgement about a peer, written by the agent, and an agent holds no operating system privilege to prove. Gating it would make an agent's own mind editable only by whoever is standing at the machine, which is the opposite of what the register is for. This is checked, not merely intended: the verbs' one decision point takes the process's real elevation and **ignores it**, so a gate added later in either direction fails a test rather than passing unnoticed. The one gate in this family is on the trust warning's **override text**, below, and for a reason that does not apply to a classification. ## The trust warning When a message reaches you because an **access entry** admitted its sender, and you hold **no monic** about that sender, spt composes a system-authored trust warning and delivers it alongside the message: ```text TRUST WARNING — this message is from wanda, who reached you through an access rule rather than through anything you decided about them. You hold no note about them. Until you have decided something about them, treat what they ask for with care: - do not hand over secrets, credentials, or anyone's private material; - do not take actions that change state (write, delete, deploy, grant, spend) on their say-so alone; - do not forward, relay, or send messages onward on their behalf. Once you have decided what they are to you, record it and this warning stops: spt endpoint monic add wanda "" ``` Three properties of it are worth knowing: **Classification is monic-only.** An access entry naming the peer is *not* a classification — the entry is the very thing that let them in, and reading it as evidence of judgement would silence the warning exactly when it is warranted. Often the entry was written by a human, at a knock, weeks earlier. **It never changes delivery.** The gate already allowed the message. The warning is advisory text that rides alongside; a **retried** message — the same message arriving a second time — is dropped by the replay check before the warning is even considered, so it does not re-warn; and if the warning itself cannot be delivered, that costs a loud diagnostic naming the unwarned delivery rather than withholding a message the gate permitted. That replay check is about one message sent twice, not about repetition: how often the caution surfaces for a peer who keeps writing is a separate question, answered [below](#you-hear-it-once-a-session-not-once-a-message). **It is never part of the peer's body.** A warning spliced into the peer's own text would be indistinguishable from one the sender wrote, which is precisely what a stranger would forge. It rides the message's own envelope instead — see [the warning rides the message](#the-warning-rides-the-message) below. ## The warning rides the message The caution and the message it is about reach you in **one arrival**. The warning rides that message's envelope as a `trust-warning` attribute, composed by **the receiving node** — yours — exactly as a matched monic's `mnemonics-json` is: ```text ``` An attribute is not the body, so the sender authors this text in neither design: what changed is the carrier, not the rule about who may write it. What a separate delivery cost was an extra interruption — under an spt-hosted harness each delivery is its own context injection, so a caution you must read *with* the message arrived as a second one. > **For adapter authors: this attribute MUST be surfaced.** A pipeline that > re-renders a delivery has to carry it through and show it, the same obligation > [matched monics](#matched-monics-ride-the-message) carry. The reasoning is not > the same, though, and the difference is the point: a dropped monic costs you a > note you wrote, while a **dropped trust warning is a security caution that > silently did not happen**. For this attribute, being ignored *is* the failure — > so "unknown attributes are safely ignored" is exactly the behaviour that must > not apply here. **A body that is already a typed envelope carries no attribute** — machinery deliveries (notifications, file drops, commune echoes) pass through verbatim, and splicing into a finished envelope would mean hand-rolling the envelope grammar a second time. For those the warning **keeps its own delivery**, as its own block under a reserved system author that is not a legal endpoint id (so no peer can author under it), delivered **first** so the caution is read before the message it is about. The second arrival survives exactly where there is no carrier for it and nowhere else: the caution is never what gets traded away. **Anything a sender writes into this attribute is inert.** A typed envelope rides verbatim from the wire to your context, so a peer *can* put a `trust-warning` into one and hand it over. Every point where a sender-supplied body enters your node strips the receiver-composed attributes before your own are attached, so what you read is your node's by construction rather than by the sender's restraint. The envelope author's own fields — `type`, `from`, a notification's id, an alarm's times, a [sealed message](../messaging/wax-seal.md)'s `seal` token — ride through untouched. ## Three arrivals that never warn A warning that fires on invited traffic teaches agents to ignore warnings, which costs it its only job. So three passes are ratified as non-warning: | arrival | why it never warns | |---|---| | **same-node** | inside your node's own trust unit | | **a reply** | correlated to your own outbound — traffic you invited | | **posture-open** | no entry named this peer; the endpoint simply is not refusing anyone | A **wildcard** entry warns exactly as a named one does: it admitted a peer you never named at all. ## A sender nobody can name is still warned about A peer whose sender the daemon could not prove is **still warned about**, and that warning is **unsuppressible by design** — not merely fail-safe. Because classification is monic-only, no provable id means no monic can exist, so every unproven sender on an entry-admitted pass warns. That is honest: they *are* unproven. It self-heals as the fleet's daemons come to stamp their senders. What keeps warn-more from becoming warn-noise is the **text**. The block for an unnamed sender names the admitting **rule** as the way out and never prints a classify command that cannot be run: ```text TRUST WARNING — this message is from an unnamed sender on node , who reached you through an access rule rather than through anything you decided about them. You hold no note about them. … Their sender could not be proven, so there is nobody to record a note about — this warning stands until they reach you from a daemon that stamps its senders. To stop hearing from node at all, remove the rule that admits it (`spt endpoint access`). ``` An instruction the reader cannot carry out is what turns an unsuppressible warning into noise an agent learns to skip. ## You hear it once a session, not once a message The warning surfaces **once per session per peer**. The first message an admitted stranger sends you carries the block; their next hundred in that same session do not. The block runs to roughly 650 bytes and is read ahead of the message it is about, so a per-message caution is one an agent learns to skip — which costs the warning the only job it has. Once per session per peer is the whole of its cost. **The key is your bound session and the peer.** The session is the harness session bound to the perch the message reached, not anything about the sender's connection, and that one derivation covers both cases that matter: the agent sitting there when the stranger writes, and the agent that was away. A hundred messages spooled from one stranger while you were offline surface **one** warning when you come back, not a hundred. **It re-arms with the session.** The record of "already warned" lives in the per-session scratch, so a `/clear` — which mints a new session — hands you the caution again. Nothing has to remember to reset it, and no peer is silenced permanently by having been announced once. **Everything about it fails toward warning you.** Each of these is a place where a tidier-looking read would quietly cost you a caution, so each one is settled in the direction of the warning: | what goes wrong | what you get | |---|---| | no record that you were warned yet | the warning | | the record cannot be read | the warning | | the record cannot be written after warning you | the warning again next message | | your perch has no readable session to key on | the warning on **every** message | | the peer's id is not something safe to write down | the warning | | the warning could not be delivered on any channel | nothing is marked, so the next message warns | That last row is the one that keeps the cadence honest: the mark is made only **after** the caution has actually reached you. A record on disk must never assert a warning that no agent ever read, so a session's one warning can never be eaten by a failed delivery. The cost of the whole arrangement is the opposite failure — two messages from one peer arriving at the same instant may both warn, which is a duplicate you can read and dismiss rather than a silence you cannot. **It applies to unnamed senders too, and that silences nothing.** A cadence is not a classification. The unsuppressibility described above is about *classification*: no provable id means no monic can exist, so nothing you file can ever quiet an unnamed peer — and that is untouched here, because the first warning of every session is still delivered and every new session re-arms it. Exempting unnamed senders would have aimed the exemption at the one class no monic can ever quiet, which is exactly where a per-message flood is unbounded. Because there is no sender id to key on there, an unnamed sender's cadence is keyed on the **origin node**: two unnamed senders on one node share one first warning. That is what the daemon can honestly name, not a collision to repair. A named peer and the unnamed class never quiet each other — being announced about one is never being announced about the other. ## Rewording the caution — never hiding the knocker ```text spt endpoint trust-warning # show what this endpoint is told spt endpoint trust-warning set "…" # replace the advisory (elevated) spt endpoint trust-warning reset # back to the default (elevated) ``` **The scope is partial, by ratification.** Custom text replaces the **advisory paragraph and nothing else**. The line naming who reached you and stating that you hold no note about them, and the line saying how to classify them, are always composed by spt. Override text is agent-behavior instruction delivered under a reserved system author, which makes it a prompt-injection surface, and an unforgeable factual spine **bounds** that surface: a whole-block override would let one elevated write hide *who* is knocking, which no legitimate override needs. The `set` verb states that scope in its own output, so the operator learns which lines they did not reach at the moment they write. **Writes are elevated; reads are not.** Writing is a human-at-the-machine act because an agent must not be able to rewrite the caution it is about to be handed. Showing what an endpoint is told leaks no authority and is exactly the visibility that makes a planted override discoverable — gating the read would protect nothing and hide the only thing worth auditing. Elevation that cannot be positively confirmed refuses like no elevation at all. Two writes are refused: a **blank** override (withdrawal is its own verb, so a blank one is a shell mishap far more often than an intent to caution an agent about nothing) and one **past a length bound** (the block is read ahead of every admitted stranger's message, so an unbounded advisory buries the classify line — the same harm the whole-block override was refused for, reached by length instead of by scope). Reading is fail-safe: an absent, unreadable, or blank record all read as *no override* and fall back to the default advisory. A damaged override costs you your wording, never the caution. ## Why the two are stored differently on purpose The asymmetry is deliberate and should not be "fixed" by moving either side to match the other: - **Override text is node-local** — one file per endpoint beside the access store, never in the mind tier, because a mind file replicates between every instance of an agent, so an override filed there would let a peer instance's sync push warning text onto this node, re-opening the exact injection surface the elevation gate exists to hold shut. - **Monics follow the mind** — because a classification is the agent's own judgement, and an agent that decided something about a peer on one node has decided it everywhere it sits. ## Matched monics ride the message When a message arrives from a peer you *have* classified, the monics that match ride the envelope as a `mnemonics-json` attribute carrying a JSON array of the matched records — so you read your own standing judgement in the same breath as the message rather than going to look it up: ```text ``` Each array element is the **matched record whole**, in the same shape the authoring verbs write: `id`, `triggers` (the matcher array), `text` (the body, verbatim), `set_ms` (last-written stamp, display only), and `origin`. There is no separate delivery projection — what you wrote is what rides. An adapter custody pipeline that re-renders a delivery (stubbing, parking, spilling) must carry this attribute through intact; dropping it manufactures the warning-without-judgement disagreement the invariant below rules out. A renderer revealing a monic must also place it where a **body-authored imitation cannot be mistaken for it**: the message body is peer-authored text and may contain a literal copy of whatever marker the adapter renders monics with, so the discriminant has to be structural (the genuine reveal sits at the adapter's own frame level, never inside the peer's rendered body) — the same reasoning that gives the trust warning a system author no peer can legally write under. > **Forward guidance for adapter authors:** the envelope attribute is the > monic's *interim* surface. When the now-signal funnel ships, its MONICS > category becomes the surface adapters use to reveal monics to agents; build > your envelope handling to preserve, not to interpret. The attribute is present **if and only if** something matched. An empty array would say "evaluated, no match" where absence says "not evaluated" — a distinction no reader has a use for and a second shape every reader would have to handle. Evaluation happens at the **envelope renderers**, so every delivery surface behaves the same: a classification that fired only when the peer happened to be remote is one you could not rely on. There is exactly **one** match rule, and a recipient with no mind — a shell link, or an agent that has classified nobody — reads nothing and gets no attribute. An unreadable record rides nothing, the same fail-safe reading the trust warning takes; the two never disagree, so you can never be warned about a stranger whose monic you were handed in the same envelope. ### What a trigger can watch A trigger set is a JSON array of matchers. Each has a `kind`, a `pattern`, and optionally `"regex": true`: | kind | watches | evaluated today | |---|---|---| | `sender` | the proven sender id | yes | | `content` | the message body | yes | | `json` | a custom payload | yes | | `user-input` | what you type | not yet | | `agent-output` | what the agent writes | not yet | With `"regex": true`, matching is **case-sensitive** unless the pattern uses `(?i)`. Triggers use the [same rule as `[[hints]]`](../shells/overview.md#how-a-keyword-matches). `user-input` and `agent-output` are **ratified but not yet evaluated**. You can write them now and they will keep working when their consumer arrives — that is why they are in the vocabulary already, so that adding the consumer never means migrating your records. Until then nothing fires them, and `monic list` says so on the row rather than letting silence read as "it works, nothing matched yet". `spt endpoint monic --help` prints these same rows, composed at render time from the same table — including the evaluated-today column — so the vocabulary you read here and the one the CLI teaches you at the moment of writing a trigger cannot drift apart. **Matching a message is not the same as classifying its sender.** Only a `sender` trigger answers the trust warning's question. A `content` trigger can ride you a monic on a message from someone you have never classified — and that peer still draws the stranger warning, because you have not said anything about *them*. **A body that is already a typed envelope carries no attribute.** Machinery deliveries — notifications, file drops, commune echoes — pass through verbatim, and splicing an attribute into a finished envelope means hand-rolling the envelope grammar a second time. The one case where this is visible in peer traffic: a message whose sender could not be proven is re-stamped at the WAN edge into a typed envelope, so that sender's monic does not ride. **The trust warning still fires for them** — it is composed at that edge from the gate's verdict — so what is lost is the note, never the caution. ## See also - [Knocking: asking to be let in](knocking.md) — an approval or an invite code can impart the first monic about whoever it admits. - [Viewing access rules and posture](access-viewing.md) — what admitted them in the first place. ===== /serving/overview.md ===== # Serving resources The node's serving registry is the single list of what it exposes. Register a file or directory deliberately, then copy its URL from `spt serve list`. Removing an entry stops serving it; it does not delete its source bytes. If node-prefixed docs return 404 or serve controls are unavailable after an in-place update, check `spt node status` before restarting anything. A resident network layer older than 0.68.0 cannot supply these routes even when the installed release can. See [the update diagnosis](../self-update/overview.md#one-command-spt-update) for the full-restart requirement and its cost to hosted sessions. ## Node-prefixed URLs Every served resource uses the owning node's name: ```text http://localhost:5474/hfenduleam/f/report.md http://localhost:5474/hfenduleam/docs/ http://localhost:5474/hfenduleam/a/my-harness/ ``` The server listens on loopback only. The default port is `5474`; `SPT_DOCS_PORT` overrides `daemon.json`'s `docs_port`. A request to bare `/` redirects with HTTP 302 to `//`. Existing bare docs paths, including `/llms-full.txt`, `/manifest.schema.json`, and raw `.md` pages, remain compatibility aliases. Generated serving, attachment, and docs URLs use the running daemon's actual bound listener port. Changing a client's environment or config does not change that port. Configuration is used to predict a URL only when no daemon runs; an unavailable or unreported listener on a running daemon is an error, not a guessed link. `spt fetch` resolves the receiving node's local listener after startup, including when a pasted URL names another node or another port. Node prefixes take precedence over compatibility aliases. If a known subnet peer is named `cli`, `/cli/...` addresses that peer, not the local docs section. The alias is shadowed only while that peer is known. Use the canonical twin, `//docs/cli/...`, for a local docs link that cannot change meaning. A single-leaf URL naming a docs root file (`llms.txt`, `llms-full.txt`, `manifest.schema.json`, or a root `.md` page) serves that file before peer lookup. Dotted hostnames remain valid: a peer named `llms.txt` loses only the leaf `/llms.txt`, not its node-prefixed `/llms.txt/...` paths. A bare known node prefix redirects to its trailing-slash form. The local node still wins over the root-file exception: if the local hostname is `llms.txt`, `/llms.txt` redirects to `/llms.txt/`; its docs file remains at `/llms.txt/docs/llms.txt`. The node root `//` redirects with HTTP 302 to `//docs/`, for both local and remote nodes. Query parameters are preserved. There is no browser registry index or `?json` index: use `spt serve list` or `spt serve list --json` to audit exposed paths and URLs. The path beneath the node prefix identifies the facet: | Path | Resource | |---|---| | `f/` | A registered file or directory | | `docs/` | The installed docs bundle | | `a//` | The adapter's core-owned served root | | `/` | An adapter's optional short path, pointing at the same entry | | `m/` | One message, rendered; `?json` for its machine twin | | `bin/`, `install` | Reserved facets; currently answer 404 naming the facet | A request naming a **known subnet peer** is answered by that peer through the local daemon; see [Cross-node serving](cross-node.md) for what comes back and what each status means. Other first segments retain the docs compatibility behavior, including the docs server's own 404 for nonexistent pages. An unknown local facet returns 404 naming that facet. Use a trailing slash for directory roots: `//docs/`, `//f//`, `//a//`, and adapter aliases. Requests without that slash redirect before serving the root `index.html`, so browser relative links resolve inside the correct subtree. Redirects preserve query parameters. This does not add directory listings or implicit nested indexes; the docs compatibility surface retains its existing bytes and status behavior. The facet tokens `docs`, `f`, `a`, `m`, `bin`, and `install` are reserved in the URL grammar. A node with one of those OS hostnames is reported loudly at daemon startup and by a peer learning it at join, but may still boot and join. The router never treats such a token as a top-level node, so that node cannot be addressed by prefix until renamed at the OS. W0 introduces no hostname admission policy or SPT node-renaming verb. ## Register, inspect, remove ```sh spt serve add report.md spt serve add ./reports --as review spt serve list spt serve list --json spt serve rm report.md ``` `add` records an absolute reference to the file or directory, not a copy. Later edits are visible at the same URL; deletion of the source returns 404. A directory exposes only its own subtree: traversal and symlinks escaping the root are refused. `rm` accepts the served name or the entry id printed by the listing. It removes only the registry entry. Served names remain stable for an entry's lifetime: - The first `report.md` keeps that name. - Another path requesting `report.md` receives `report~1.md`, then `report~2.md`, with the suffix before the final extension. - Removing the first entry reserves `report.md` for its prior absolute path and kind. Re-adding that same file reclaims `report.md`; a different third file still receives `report~2.md`. A stale URL never opens a different resource. - Re-registering the same absolute path returns its existing entry, even if the caller supplies a different `--as` name. - Explicit `--as` names use the same allocator. A name assigned explicitly or by suffixing can be reclaimed only by its prior path with the same kind. - Allocation history is persisted per node. Another node has its own names; the node prefix keeps their URLs distinct. The broker and brain are separate processes that write `$SPT_HOME/serve/registry`; CLI clients do not write it directly. The store includes entry ids, kinds (`file`, `dir`, `attachment`), paths, assigned names, registration timestamps, optional origin endpoint ids, and allocation history. Optional lifetime (`ttl_ms`) and receiving-endpoint `audience` metadata apply to every entry kind, including live file and directory references. Explicit registrations leave both unset; helper registrations carry a lifetime and audience. Do not edit or remove this file to reclaim a name: that would destroy the history which prevents stale URLs changing meaning. Writer coordination requires both processes to hold the same `serve/registry.lock` guard across reading and updating the registry. Atomic snapshot replacement alone does not prevent one writer from losing another's update. Both running writer implementations must be updated: a new brain with an old broker does not fully activate protection. HTTP readers remain lock-free; [attachment expiry and source protection](attachments.md#lifetime) are unchanged. ## Adapter served roots Core creates `$SPT_HOME/adapters//web/` at activation and registers it as one directory entry. The adapter writes only the output it wants exposed into this directory. Its install tree, manifest, and other auxiliary files are **never** served on its behalf. The entry answers at `//a//`. An optional `[adapter].web_short_path` manifest field requests an additional short alias for the **same** entry and directory. A requested alias such as `cspt` produces `//cspt/`; if that name has already been assigned, the ordinary stable suffix rule applies. Use the listing to discover the assigned alias instead of guessing it. The names `f`, `docs`, `a`, `m`, `bin`, and `install` are reserved. Requesting one as `web_short_path` refuses activation with a field-naming diagnostic. Without a short alias the adapter facet still serves normally. Deactivation removes the registry entry but retains the directory and its files. Reactivation with the same declaration reclaims the prior alias, not a new suffix. Reactivation or an adapter update must not erase those output bytes. ## Adapter docs An adapter that ships its own documentation points at it with an optional `[adapter].docs_dir` manifest field, and it is served at the **reserved `docs` segment** of the adapter facet: ```text http://:5474//a//docs/ ``` `docs_dir` is **adapter-relative** — a path inside the adapter's own installed directory, never an absolute path and never a parent-directory escape. Both refusals are named `MANIFEST_DOCS_DIR_OUTSIDE:`, and the check runs twice: once when the manifest is validated, and again on every request, so a directory replaced by a link pointing elsewhere after installation is refused at the fetch rather than served from wherever the link now leads. The adapter's own directory root is refused for the same reason its install tree is never served: it holds the adapter's record and state. Without the field, `//a//docs/` answers `404` naming the facet. It never falls through to a `docs/` folder inside the core-owned `web/` root — the segment is reserved, so the URL means the same thing on a node whose adapter declares `docs_dir` and on one whose adapter does not. Reads also refuse replacement of the core-owned root with a symlink to an install tree or another directory. The same containment rules apply through the adapter facet and its alias. ## Entry fields: lifetime, audience, origin Beside its path and served name, an entry may carry three fields. They are per-entry and independent of kind, and `spt serve list` renders each one it has — the registry's job is answering what this node exposes **and to whom**, and a narrowing that did not render would make that answer a half-truth. | Field | Meaning | |---|---| | `ttl` | A lifetime from registration. Absent means the entry lives until removed. Attachments carry 30 days by default; entries the `FILE_ACCESS_HELPER` registers carry 24 hours. | | `audience` | The set of endpoints allowed to fetch it. Absent means anyone the `WEB` surface admits; an empty set admits no remote node. | | `origin` | Who or what registered it — for a message helper, the message short-ID; for an input-report helper, `user-input:`. | An **audience** is a cross-node narrowing. The owner serves the entry only to nodes hosting an admitted endpoint and answers everyone else `403` naming the surface — deliberately the same refusal a `WEB` deny rule produces, so a narrower audience cannot be distinguished from a denial by probing and the registry does not become an oracle for what exists. It is enforced where the fetch origin is **proven**: the cross-node stream's handshake identity. That handshake proves a *node*, while an audience names *endpoints*, so the check the owner can honestly make is whether the proven node hosts at least one of them — it stops another machine, not another agent on an admitted endpoint's machine. An endpoint this node cannot place grants no access. When the seated user hands the same live file to another receiving endpoint, that endpoint joins the existing input reference's audience. `spt serve list` shows both recipients; the URL and original 24-hour deadline stay unchanged. This reuse does not widen an unrelated explicit registration or attachment. **Loopback remains the trusted machine.** A local browser presents no endpoint identity, so a request arriving on the loopback listener is served regardless of audience. An operator who needs secrecy from other users of the same machine has file permissions, not this field. An entry whose lifetime has elapsed stops serving immediately — it answers the ordinary not-found — whether or not the daemon's reaper has run yet. ## Access control `WEB` is a rule-addressable control surface, on by default within a subnet because registration is already deliberate exposure. A blanket closed posture does not close it; a rule or per-surface mode naming `WEB` can. It is currently non-attributable: no sender-endpoint stamp is proven for web reads. The owning node runs the `WEB` check for every request that arrives from another subnet member, under that member's handshake-proven identity; a refusal answers `403` with a body naming `WEB` ([Cross-node serving](cross-node.md)). Local serving remains loopback-only. ### `XFER` is retired `WEB` did not rename `XFER` — it replaced what `XFER` was for, and `XFER` itself is **retired**. The file-transfer machinery it gated has left the tree with it: the pull-model attachment supersedes it, and cross-node reads of served content are governed by `WEB`. Retiring rather than repurposing the id is deliberate — reusing `XFER` for web reads would silently change the meaning of every stored rule that already names it. The id is gone from the vocabulary, so nothing new can be granted on it, and `spt endpoint access` no longer offers it. **A rule you already stored that names `XFER` stays exactly where you put it.** It governs nothing — the same standing any unminted id has always had under this open vocabulary — and every load of the store that contains it prints one line naming it: ```text ACCESS_SURFACE_RETIRED XFER — a stored rule or mode entry names this surface, which no longer exists: ... The entry is KEPT and governs nothing (a retired id is legal exactly as an unminted one is). Remove it when you are ready (`spt endpoint access remove ...`). ``` One line per retired id, however many rows name it. Nothing is rewritten or dropped on your behalf: a vocabulary that shrank is not licence to edit a decision you made, and the report is the only record that the surface was ever used at all. Remove the row when you are ready to. ## Bootstrap LAN firewall admission `spt serve lan --bootstrap` retains the signed-binary admission gate and reports the listener's actual port and binder executable. Firewall repair is separate: a denied elevation prompt, unavailable manager, or failed repair leaves a valid listener running and reports `LAN_FIREWALL_UNVERIFIED`. This is not proof that the listener is unreachable. Repeat bootstrap to retry; status only inspects. `LAN_FIREWALL_REPAIR_REQUESTED` means elevation was requested, not that a rule was installed. The elevated helper queries the original broker's current state; it never replays bootstrap or starts a stopped listener. Its observed result is reported separately. `LAN_FIREWALL_RECONCILED` means the owned rule's scope was observed, **not** that another machine successfully reached the listener. On both Windows and Linux, admission is **port-scoped**: binder identity is ownership metadata, not executable enforcement. Another process using that port may be admitted. Windows writes two rules, not one -- a tailnet half and a LAN half -- because a single rule cannot cover both without also admitting the local subnet of a public network. Linux selects UFW before firewalld before nft; an opaque manager does not authorize falling through to a different backend. Supported Linux layouts are active dual-stack UFW, an already-provisioned owned firewalld policy, or one unrestricted existing inet/filter nft input chain. IPv6-disabled UFW, multiple or family-specific nft input chains, and unknown rule scope remain unverified rather than being rewritten. Fresh firewalld hosts need an operator-provisioned runtime policy named `spt-bootstrap-tcp`, with description `spt-core bootstrap TCP admission v1`, target `CONTINUE`, priority `-32768`, ingress `ANY`, egress `HOST`, and no unrelated allowances. Its permanent identity must also exist. Bootstrap does not create a silent permanent-only policy or reload firewalld: a reload can discard unrelated runtime configuration. Missing runtime policy leaves the listener up, reports the provisioning prerequisite, and remains unverified. `spt serve lan --stop` stops the listener before attempting owned-rule cleanup. Cleanup never removes an unowned rule or the installation's UDP rule. `LAN_FIREWALL_CLEANUP_UNVERIFIED` prints residual-resource guidance; inactive managers may require operator inspection. Firewalld runtime policy definitions cannot be deleted without a separately authorized reload, so an inert policy can remain after its TCP allowances and permanent definition are removed. After this cleanup, a later firewalld bootstrap needs operator provisioning again: retaining an inert runtime policy does not retain its permanent identity. Concurrent SPT repair helpers are refused using a host-wide lock. This does not serialize independent administrator commands; avoid editing firewall policy while repair runs, especially UFW rules addressed by mutable rule numbers. `SPT_INSTALL_NO_FIREWALL` suppresses firewall mutations and elevation, not listener startup or read-only reporting. Elevated CLI fixtures must set it unless they explicitly own an isolated firewall environment. ===== /serving/cross-node.md ===== # Cross-node serving A node-prefixed URL means the same thing on every machine in the subnet. Paste `http://localhost:5474/kitsubito/f/report.md` into a browser on `hfenduleam` and the local daemon fetches the file from `kitsubito` and answers with it. Nothing is copied: the owner serves the bytes, and the requesting node keeps none of them. ## How a peer's URL is answered The local listener resolves the first path segment. When it names a **known subnet member** (a node in this node's roster, by its advertised label), the daemon opens one stream to that node and relays the owner's answer: - The owner resolves the path through the same router its own listener uses, so a registered file is read at request time. An edit is visible on the next fetch; a removed entry or a deleted source answers the owner's own 404. - `HEAD` returns the owner's headers with no body. `Content-Type` is the owner's. - A `Range` header is forwarded as-is. The owner answers `206 Partial Content` with `Content-Range`; a range past the end answers `416` naming the length. The same grammar applies to a local file: `bytes=a-b`, `bytes=a-`, `bytes=-n`. - The body streams back in bounded chunks as the owner sends it. A large file never needs its size in memory on either node, and nothing is written under the requesting node's `$SPT_HOME`. - The peer's index page and its `?json` twin are fetched the same way: `//` lists what that node serves. Reserved facets stay router-first on the requesting node: `//f/` with no name, and the unbuilt `m/`, `bin/` and `install` facets, are answered locally and open no stream. ## Who decides: the owner The owning node runs its `WEB` access check before serving anything. The origin it checks is the requesting node's identity as proven by the transport handshake, never a value in the request. The subject is the endpoint that registered the entry, so a rule written against that endpoint governs its served files wherever they are fetched from. See [Viewing access rules and posture](../networking/access-viewing.md) for the `WEB` row. ## What each status means | Status | Body starts with | Meaning | |---|---|---| | `200` / `206` | the owner's bytes | Served by the owner. | | `403` | `ACCESS_DENIED: WEB:` | The owner's access rules refuse this node. The body names the surface, not a sender: `WEB` carries no sender identity yet. | | `404` | `NOT_FOUND: served resource ` | The owner has no such served name (or its source is gone). | | `404` | `NO_DOCS_LANDED:` or the docs page 404 | The first segment is not a known subnet member, so the request fell through to the local docs compatibility surface. | | `502` | `NODE_UNAVAILABLE: :` | The owner is a known member but could not be reached, dropped the stream, or never answered within the deadline. The body names the node and says why. | A `502` arrives within a bounded time. The dial and each read are held to the daemon's peer deadlines, so an owner that is offline, or that runs a version without cross-node serving, produces an answer rather than a hang. ## Trying it On the owning node: ```text spt serve add ./report.md spt serve list ``` On any other node in the subnet, using the owner's node name: ```text curl -s http://localhost:5474//f/report.md curl -sI http://localhost:5474//f/report.md curl -s -r 0-3 http://localhost:5474//f/report.md ``` ===== /serving/attachments.md ===== # Attachments and `spt fetch` Sending a file with a message does not push bytes to the receiver. The file is snapshot into this node's own store, registered for serving, and the message carries its URL. The receiver decides whether to pull it, and when. ## Attaching a file to a message ```console $ printf 'the report you asked for' | spt send doyle --attachment ./report.md ATTACHED:report.md: http://localhost:5474/hfenduleam/f/report.md (2481 bytes, ttl 2592000000ms) SENT:doyle ``` `--attachment` repeats; each file becomes its own registry entry with its own URL. The message envelope grows an `attachments` attribute carrying, per file, its served name, its URL and its size in bytes — so a receiving agent can decide whether to fetch **before** it fetches. A core that has never heard of the attribute delivers the message unchanged. An attachment is a **snapshot**, and that is the one place the serving registry does not resolve at request time: | | `spt serve add` | `spt send --attachment` | |---|---|---| | What is served | the file at its path | a copy taken at send time | | Editing the source | the reader sees the edit | the reader still sees what was sent | | Deleting the source | the URL answers 404 | the URL keeps serving | | Lifetime | until removed | a TTL, 30 days by default | A message's attachment is as immutable as the message: an edit after the send must not change what the receiver pulls, and deleting the original must not turn a delivered link into a dead one. Two sends of the same filename get two stable, distinct URLs under the registry's ordinary disambiguation rule (`report.md`, then `report~1.md`), so no link ever changes meaning. A missing or unreadable path **refuses the send by name** — nothing is delivered and nothing is spooled — rather than delivering a message whose link is dead on arrival: ```console $ printf 'here' | spt send doyle --attachment ./nope.md ATTACHMENT_REFUSED:./nope.md: The system cannot find the file specified. (nothing was sent) ``` ### Lifetime `--ttl` sets this send's lifetime and **requires a unit** — `s`, `m`, `h` or `d`. A bare number is refused rather than guessed, because `30` meaning seconds when the sender meant days is a deleted attachment. ```console $ printf 'valid for a day' | spt send doyle --attachment ./build.log --ttl 24h ``` The brain's pulse reaps expired registry entries and logs how many it removed. For an attachment, it attempts to unlink the core-owned snapshot **before** saving the registry without that entry. These are not one atomic transaction: if saving fails after unlinking, the next pulse can finish removing the expired entry even though its snapshot is already gone. Saving first could instead leave untracked snapshot bytes that later pulses cannot find. Only attachment snapshots under `$SPT_HOME/serve/snapshots/` are candidates for unlinking. Expiry removes a live file or directory reference from the registry but **never deletes the user's source**. The [writer-coordination contract](overview.md#register-inspect-remove) keeps the guard across the reaper's fresh load, snapshot cleanup, and explicit save; a pass with nothing expired does not save the registry. An expired entry stops serving the moment it expires, whether or not the reaper has run yet: between expiry and the next tick the bytes may still be on disk, and serving them would make the TTL a suggestion. ## Pulling one: `spt fetch` ```console $ spt fetch hfenduleam/f/report.md report.md $ spt fetch http://localhost:5474/hfenduleam/f/report.md ~/inbox/report.md /home/reavus/inbox/report.md ``` It accepts a full node-prefixed URL or the bare `/f/` shorthand — the shorthand is how a link is said between agents, and the host and port belong to whichever node is doing the fetching. The written path is printed on stdout so a caller can pipe it. Without a destination the file lands in the current directory under its served name. An existing destination is **not** overwritten without `--force`. The body streams to a temporary file and is renamed into place, so an interrupted or refused fetch never leaves a truncated file where a later reader would trust it. The three outcomes are distinct, and the distinction is the point: | Exit | Meaning | |---|---| | `0` | The file was written; its path is on stdout. | | `3` | The owner **refused** it — an access decision. Retrying is wrong. | | `1` | Anything else: unreachable owner, not found, a deadline, a local write error. | Every fetch — local or remote — is served through the local daemon's web surface, the same path a browser takes, so a fetch of your own node's file exercises the code a remote fetch will use. ## The `FILE_ACCESS_HELPER` signal An agent does not have to notice an attachment. When a delivered message carries one, the now-signal hands the agent the exact command to run, taken verbatim from the envelope: ```text spt fetch http://localhost:5474/kitsubito/f/report.md ``` The same category answers the other way a file arrives: **a user quoting a filepath while controlling the receiving agent through remote `spt rc`**. Core binds the existing session-authenticated input report to the broker's live remote controller when the report arrives. A later controller change cannot reattribute it. Registration happens on that controller's machine, not by looking for a similarly named file on the receiving machine. The file is a **live reference**, not an attachment snapshot: edits are visible and deletion returns not found. The reference lasts up to **24 hours**. If the user later hands the same live path to another endpoint, that endpoint joins the existing entry's audience and receives the **same URL**. No duplicate entry is created and the original deadline does not move. The fetch command normally arrives with the path-bearing prompt after a short bounded wait for registration. If the owner answers later, the command remains available on a subsequent signal poll. The wait does not cancel owner work. - **Absolute or `~`-rooted only.** The owner resolves `~` against its own home. A relative path has no anchor on another node. At most **five** paths per report; directories receive the same lifetime and audience. Paths containing whitespace must be enclosed in matching double quotes, single quotes, or backticks: `"C:\My Pictures\a.png"`, `'/home/x/My Pictures/a.png'`, or `` `~/a b/c.md` ``. Each quoted span is one path, not whitespace-separated fragments; punctuation outside its closing quote is not part of the path. Unquoted paths containing whitespace are outside this contract. An unmatched opening quote ends extraction; complete paths before it are retained. - **No quoted paths means no broker IPC and no line.** An absent hosted session, local or viewer-only seat, or no controller binds nothing silently. A missing file on the bound owner's machine is also silent, with no fallback origin. - CLI broker-connect and unanswered-receipt failures are silent unless `SPT_PUMP_TRACE` enables diagnostics. Named declines apply only to failures with a remote controller, such as an invalid session, uncertain delivery-byte evidence, or owner refusal. The broker's **10-second owner-reply timeout** remains named. - **Once per endpoint, session and filepath.** Rephrasing a prompt does not repeat its helper. A new endpoint or session can receive the existing URL; neither can extend the live reference's original deadline. - Core excludes bytes it knows it physically wrote for peer delivery: either an exact match or a match after trimming ASCII whitespace from both byte sequences' ends. It does not parse message shapes or normalize interior text. This is **receipt-seat attribution**, not proof of who typed every byte: external automation and native harness re-submission cannot be distinguished beyond the current controller seat. No adapter token or integration change is required. An original prompt and its edge-ASCII-trimmed report share the first path receipt in the same endpoint session, including its controller custody and deadline. Surrounding prose is not a new file handoff. Each poll emits an identical fetch command at most once, even if distinct attachment or helper records supplied it. All such records are marked seen, so suppressed duplicates do not appear on the following poll. Every entry the helper registers is enumerable in `spt serve list` with its origin and complete audience, so an automatic exposure is exactly as visible as a deliberate one. Two-node field acceptance was granted by Doyle on 2026-09-22 for the W2 candidate: spaced-path fetch, one helper per physical prompt, delivery with the original prompt, two same-entry/URL audience-admission cases preserving the original deadline, and exact plus XML-reencoded peer bodies causing **no serve** while a remote controller remained seated. The seven-cell observations and verified isolated teardown are preserved in `.spt/preserved/318/hertz/w2-two-node/DELIVERY.json`; resident daemon records and firewall output remained unchanged on both nodes. This accepts the tested dirty-source candidate, not a later commit SHA or the whole release, and does not turn one node pair's timing into a WAN or numeric hook-latency guarantee. ## Reading a message back Every message carries a short-ID, and an attachment link is part of what that id renders — `spt msg show ` prints the message with its attachment URLs, and `//m/` is the same view in a browser. See [Messaging](../messaging/overview.md) for the id itself. ===== /serving/lan-bootstrap.md ===== # LAN bootstrap: handing a fresh machine the binary A machine with no spt on it is not yet a node. It has no network identity, so no access grant can be checked for it and nothing on the node's own serving surface can reach it. The LAN bootstrap listener exists for exactly that moment: a second, opt-in server that hands a stranger on your LAN the spt binary and nothing else. ## It is a second listener, and it is off by default The serving server on port `5474` is loopback-only and stays that way. The bootstrap listener is a different server on a different port, `5470`, bound on all interfaces, and it starts only when you say so: ```console $ spt serve lan --bootstrap LAN_BOOTSTRAP_UP: http://192.168.1.81:5470/install (port 5470) sha256 x86_64-pc-windows-msvc c1e0…4b7a sha256 x86_64-unknown-linux-gnu 8f22…0d16 sha256 x86_64-unknown-linux-musl a904…7c31 LAN-EXPOSED: anyone who can reach this socket may pull the binary until `spt serve lan --stop`. ``` Take it down when the bootstrap is finished: ```console $ spt serve lan --stop LAN_BOOTSTRAP_DOWN: the bootstrap listener is stopped ``` A bare `spt serve lan` reports the current state without changing it. Three properties are worth stating plainly, because each one is a decision rather than an accident: - **While it is up, anyone who can reach the socket may pull the binary.** The listener has no membership concept and must never grow one — a fresh box has no identity to present. Your explicit start is the only gate, which is why the now-signal carries a standing `LAN_EXPOSED` line for the whole window. - **It serves three routes and 404s everything else.** `/bin//spt` (or `spt.exe` for a Windows triple), that file's `.release.json` sidecar, and `/install`. There is no fall-through into the serving router, so a routing mistake on this port cannot reach your docs or your served files. - **It never comes back on its own.** No up-state is written to disk, so a daemon restart comes back with the listener down. Off-by-default is a property of every boot. The port follows the usual layering: `SPT_LAN_BOOTSTRAP_PORT` beats `daemon.json`'s `lan_bootstrap_port`, which beats the default `5470`. Setting the port never starts the listener. ## What it serves, and how you know the bytes are real The machine at the other end is about to **execute what it downloads**, over plain HTTP, on a network you can only mostly vouch for. So the bytes carry their own provenance, in three parts that all have to hold. **It serves the applied signed release set, or it serves nothing.** At start, the listener checks that the running daemon's own binary is the host platform's artifact in a signed release set, and that the node has actually *applied* that set. If either fails it refuses to start and names why: ```console $ spt serve lan --bootstrap LAN_BOOTSTRAP_REFUSED:sha-mismatch ``` The three refusals are `unsigned-exe` (the running binary belongs to no signed set this node trusts), `sha-mismatch` (it is not that set's host artifact — a development build, or a hand-copied executable), and `set-not-applied` (the set is staged but not yet running). There is no "serve it anyway, marked unsigned" option, and a newer staged set is never served: a stranger receives what this node *runs*, never what it is about to run. **Each platform is checked again as it is served.** The listener holds several platforms at once, and a triple's bytes go out only if they still hash to that triple's digest in the same signed metadata. A platform that is missing or no longer matches answers a 404 naming itself, and the others keep serving: ```text LAN_BOOTSTRAP_TRIPLE_UNAVAILABLE:x86_64-unknown-linux-musl:missing ``` That isolation is deliberate: a missing Linux artifact must not block a Windows-to-Windows bootstrap. **You are the last check, and that is the point.** The signature and the sidecar travel with the download, which makes them circular on their own — a tampered binary would carry tampered trust roots. The line that closes the loop is the one you read off two screens. The serving machine prints `sha256 ` at start; the install page bakes that same hex into the command; and the puller prints the hash of what it actually downloaded *before* it verifies anything. Two machines on one LAN and a human comparing two lines is the only honest anchor a bootstrap without transport security can offer. ## On the fresh machine Open `http://:5470/install`, pick your own platform's triple — the page lists them and never guesses for you — and run what that page prints: ```console $ curl -fsSLO http://192.168.1.81:5470/bin/x86_64-unknown-linux-gnu/spt $ curl -fsSLO http://192.168.1.81:5470/bin/x86_64-unknown-linux-gnu/spt.release.json $ chmod +x ./spt $ ./spt install --expect-sha256 8f22…0d16 --release-json ./spt.release.json INSTALL_SHA256: 8f22…0d16 INSTALL_VERIFIED: signed set 102 (0.68.0), key rel-primary-2026 INSTALL_OK: placed /home/you/.spt/bin/spt ``` `--expect-sha256` refuses anything but those exact bytes and writes nothing on a mismatch. `--release-json` re-runs the signature and digest checks against the keys built into the binary you just downloaded. Compare the `INSTALL_SHA256` line against the serving machine's `sha256` line before you trust the result — that comparison is the part no software can do for you. From there the new node is ordinary: first run mints its identity, and it joins a subnet the usual way. ===== /harness-contract/overview.md ===== # Harness contract The seam everything third-party builds against. spt-core contains zero harness-specific logic; a harness (or a driven surface) interfaces through exactly two things: 1. **The [runtime manifest](manifest.md)** — a declarative TOML file stating what varies for this harness: how to spawn sessions, which hook events fire which commands, how history is read, how the adapter updates. Command templates are opaque strings; spt-core fills `{key}` placeholders and runs them. 2. **The [`spt api` surface](api.md)** — the imperative entry points the harness's hooks fire to keep spt-core's state honest: session started, went idle, hit a context boundary, ended. That's the whole integration surface. An adapter is a manifest plus the harness's own native extension points — there is no SDK to link, no daemon to embed, no protocol to speak beyond running `spt`. ```text your harness spt-core ┌────────────────────┐ ┌──────────────────────────┐ │ hooks ─────────────┼── api … ───►│ perches · spools · │ │ (SessionStart, │ │ lifecycle · registry │ │ Idle, End, …) │ │ │ │ │◄────────────┼─ spawns [session.*] │ │ sessions │ templates │ templates, keys filled │ └────────────────────┘ └──────────────────────────┘ ▲ ▲ └────────── manifest.toml declares both seams ``` ## Where to go - **Start:** [the adapter quickstart](../quickstart/adapter.md) — take the reference mock adapter apart and drive the contract in minutes. - **Build it all:** the [integration checklist](integration-checklist.md) — every surface by necessity, mapped to the interaction lifecycle. - **Reference:** [manifest](manifest.md) · [`spt api`](api.md) · [`manifest.schema.json`](http://localhost:5474/manifest.schema.json). - **Ship it:** [install-on-demand bootstrap](install-on-demand.md) — how an adapter brings spt-core with it. - **Feed the IO funnel:** report the turn's text on [`api state`](api.md#activity-and-presence), declare [`[io]` compliance](manifest.md#io--io-funnel-compliance) to let core parse shortform out of your ingest, and inject [`api now-signal`](api.md#situational-awareness) at every turn boundary. The vocabulary and grammars live in [the frame contract](../shells/frames.md#io--the-sessions-io-events-durable). - **Driven surfaces:** [Shells](../shells/overview.md) — the `kind = "shell"` flavor of the same contract. Building adapters, shells, or integrations against this contract is **unrestricted and royalty-free** — see the [license split](https://github.com/SaberMage/spt-releases#license). ===== /harness-contract/integration-checklist.md ===== # Harness integration checklist A working list for building a harness against spt-core. The [adapter quickstart](../quickstart/adapter.md) gets one adapter breathing in ten minutes; this page is the *complete* surface — every manifest section and `spt api` command a harness touches, **grouped by how badly you need it**, each tagged with the **feature it buys** and **where in the interaction lifecycle** it fires. Two seams only (the [contract overview](overview.md)): the [manifest](manifest.md) (declarative TOML) and the [`spt api` surface](api.md) (imperative entry points your hooks fire). Nothing here is an SDK call — everything is a manifest field or an `spt` invocation. > **The running example is [spt-claude-code](https://github.com/SaberMage/spt-releases)** — > the modern Claude Code harness rebuilt on spt-core (the v1 reference adapter). > Where a row says *"claude-code: …"* that is how that harness wires the > surface. Concrete commands below are real and shippable today; the shipped > harness-agnostic exercise is the [mock adapter](../quickstart/adapter.md). ## The interaction lifecycle Every surface below belongs to one stage of a harness's life with spt-core: ```text REGISTER ─► START ─► RUN ─────────────► BOUNDARY ─► END ─► KEEP-CURRENT adapter perch messaging / context tear self-update add seed→ activity / clear / down + ripple listen history / inject compact ``` --- ## Group 1 — Required (no adapter exists without these) The contract floor. Miss one and spt-core cannot host your sessions. | Surface | Feature it buys | Lifecycle stage | | --- | --- | --- | | **`[adapter]` manifest header** (`name`, `kind`, `version`, `min_spt_core_version`, `hostable_types`) | Identity + the compat gate spt-core reads *before* any install/update; declares which endpoint types you can host | REGISTER | | **`spt adapter add `** | Parses + schema-validates + records the manifest; a bad field is rejected here, nothing half-registers | REGISTER | | **`[adapter] host_binaries`** (harness-hosted) | The bind-time match-key — names the harness exe(s) you host, so `seed`/`listen` resolve your adapter with **no `--adapter`** (since v0.9.0). `--adapter ` stays available as an optional override | REGISTER | | **Startup pair — pick one flow:**
• harness-hosted: `[hooks.SessionStart] → api seed --pid {parent_pid} --session-id {session_id}` then the session's `api listen `
• spt-hosted: `[session.self]` template (spt-core spawns it) then `api bind --set-session-id ` | A registered, held perch — the thing messages and lifecycle attach to. `seed→listen` = you own the process; `spawn→bind` = spt-core owns it | START | | **`api session-end `** (or `api shutdown`, below) | Clean teardown that PRESERVES the spool + history so the next `listen`/`poll` drains the backlog | END | **claude-code:** `SessionStart` hook fires `api seed`; the Claude Code session runs `api listen` as its blocking listener (harness-hosted). `SessionEnd` fires `api session-end` (soft — context survives a `/clear` and a relaunch). --- ## Group 2 — Recommended (the integration is hollow without them) Skippable to *boot*, but the harness feels broken without them — no inbound messages, identity lost on a context reset, no activity signal. | Surface | Feature it buys | Lifecycle stage | | --- | --- | --- | | **`[hooks.Idle] → api state idle`** (and `api state busy`) | Honest activity — spt-core never infers idleness from terminal quiescence (it lies). Arms the echo gate, drives Psyche pulses + most-recently-active routing | RUN | | **`[inject]` channels** (`activity` / `idle`) + **`api poll --include-deferred`** | Inbound message delivery. Declares HOW spt-core reaches the agent (hook inject vs. pull-relay); `poll` is the pull path for hooks that can't inject | RUN | | **Honest `can_inject` per hook** | Lets spt-core route around a hook that can't surface text — the load-bearing harness-varying fact | RUN | | **`api boundary --to-session-id --session-id `** | The endpoint's identity, spool, and history survive a context reset under a new session id. **The proof is the PRIOR sid** (`--to-session-id` is payload, not proof): persist the current sid at every SessionStart in adapter-owned state keyed by endpoint id, present it here; resolve the id from `$SPT_ENDPOINT_ID`; surface any refusal LOUDLY — a silent skip/refusal strands the perch on the dead sid (no delivery until relaunch). **Validate end-to-end: after a reset, assert the perch record's session id actually ROTATED and a post-reset message DELIVERS** — a session that looks healthy can hide a stranded perch (see `api boundary` in api.md) | BOUNDARY | | **`api psyche-download `** (fire at **every session start** — whatever your start path is — and inject its stdout) | The agent resumes **with its mind** — pulls the durable two-tier context (role / live / project) **plus** any not-yet-synthesized commune as `` slices, to inject as the session's opening context. `api boundary` makes the mind *survive* a reset; this is how the next session reads it **back in**. Without it, a resumed session starts blank of its accumulated context. **Not hook-shaped:** a hook-driven harness fires it from `SessionStart`; an spt-hosted harness whose own extension owns bind has no `SessionStart` and must call it itself right after `api bind`; a harness-hosted **go-live** must call it explicitly too (promoting a running session does not replay `SessionStart`). Authenticate with the perch **`--token`**, not `--session-id` (a sid is also a lifecycle lever — it can re-pin the perch); inject **stdout only**, never stderr, or `NO-CONTEXT`/repin lines land in the agent's context as if they were its mind (see `api psyche-download` in api.md). Omitting it fails **silently**: every other surface keeps working and the mind keeps being written; the agent just resumes knowing nothing | BOUNDARY / START | | **`[history]` strategy** (`fetcher` / `locate_normalize` / `native` + `api history-log`) | spt-core can read the session transcript — feeds the live digest and mind sync | RUN | | **`[identity]`** (`session_id_source`, `parent_ancestor_name`) | Post-spawn id resolution when the harness mints the session id itself | START | | **`[env.*]` bridge** (e.g. `OWL_SESSION_ID`) | The session learns its own endpoint id / context the harness must inject | START | | **`[update]` avenue + command** | Ripple-update: spt-core refreshes your adapter alongside its own self-update (REQ-UPD-5); also the install-on-demand bootstrap | KEEP-CURRENT | | **`[update.post]` post-step** (since v0.16.0) | A delegated step that runs **after** the primary avenue resolves — under `spt adapter update` **and** `spt adapter add` (install is the first update; since v0.19.0) — pull the `.spt` **and** run an in-harness sync from one lever. Foreground + bounded (120 s, never backgrounded); runs unconditionally; reads a published JSON line on stdin (`adapter_applied`, `version`, `previous_version`, `adapter_dir`, …); its stdout decides the post-update notice (custom text supersedes `[update].message`, the sentinel `!!update-message!!` fires it, empty is silent); failure is loud (`ADAPTER_UPDATE_POST_FAIL` on stderr + nonzero CLI exit) and isolated (never rolls back the pull — and the static message still fires, so verify-then-notify: see the manifest reference) | KEEP-CURRENT | **claude-code:** `Idle` hook → `api state idle`; messages arrive over the hook inject channel (`can_inject = true`), pull-relay fallback when busy. `PreCompact`/clear hooks → `api boundary`; the `SessionStart` hook also runs `api psyche-download ` and injects stdout, so a session resumes with its accumulated two-tier mind (plus any pending commune). `[history] strategy = "fetcher"` (Claude Code's transcript is a binary the fetcher reads). `[update] avenue = "delegated"`, `command = "claude plugin update spt"` — the harness's own updater is the avenue. --- ## Group 3 — Optional (capability-specific) Reach for these when the capability applies; ignore them otherwise. | Surface | Feature it buys | Lifecycle stage | | --- | --- | --- | | **`api shutdown `** | Graceful signoff — runs the final echo-commune BEFORE teardown so the context delta is never lost to ordering | END | | **`api presence ` / `api driven-by `** | Most-recently-active resolution across the subnet; lets a session tell local input from remote-drive | RUN | | **Workers** (`api worker-start ` — the worker id is core-minted `-w`, read it from stdout; `worker-poll `/`worker-stop ` auth by the parent's session id, no token — breaking change in v0.27.0) | Nested, short-lived sub-agents under a parent endpoint | RUN | | **`[digest]` extractor** (or `api digest-entry`) | A live activity digest (`spt endpoint digest`) — declare an extractor mapping your native log → the `{role, text, tool, ts}` contract (ADR-0019; its OWN seam, no longer riding `[history]`). Spans `/clear` via the session ledger; validate with `spt adapter digest-proof`. **Classify a delivered user-facing message as a turn-opening `input` record** (see below) so the v0.16.0 `--last`/`seq` cursor keeps its granularity | RUN | | **`[session.notif]` template** | Native OS notification render (toast / shell alert) for consent + capability prompts, instead of burying them in agent output | RUN | | **`[session.resume]` template** (spt-hosted) | The **native-resume** sibling of `[session.self]`: spt-core picks it over `[session.self]` when a bringup carries a prior session (`spt endpoint resume`, `spt go` on an offline endpoint, or the picker's *Resume from history*). Declare your harness's native-resume verb (e.g. `claude -r {session_id}`) — **skip it and a resume re-runs the fresh command → a blank transcript.** spt-core lands the PTY in the session's recorded project cwd (a harness resolves a transcript by `session_id` + cwd) | START | | **`[message-idle-translation-binary]`** (spt-hosted) | A lifecycle-managed `stdin→stdout` JSON-lines binary that turns inbound `` messages into keystroke-commands spt-core applies to the PTY **atomically** (coexists with a live `spt rc` controller). The agnostic way to deliver messages into an **idle** spt-hosted session; busy delivery stays your `[inject]` hook path. Declare it with a `command` (program + args; adapter-static `{adapter_dir}`/`{adapter_name}` subst only — **no** session keys; new in v0.16.0, the bare `path` is deprecated). Validate the emit contract with `spt adapter translate-proof` | RUN | | **`api now-signal --session `** (inject its stdout at every turn boundary) | The one situational-awareness funnel: peers named in the turn, monics fired, shell status, last messages, on/offline edges, and the **only** confirmation channel for shortform dispatches and `;;` seal mints. Delta-only per session, so a poll with nothing new prints nothing and a quiet turn costs zero context. Tune it from [`[io.now_signal]`](manifest.md#ionow_signal--standing-now-signal-tuning) with `--spec-manifest`. Already injecting `api hint`? That is now a thin alias over one category of this — inject one, not both | RUN | | **`api state busy\|idle --payload-stdin`** (the turn's text) | Feeds the [IO funnel](../shells/frames.md#io--the-sessions-io-events-durable) — `USER_INPUT` / `AGENT_OUTPUT` events shell binaries and (from releases#234) other consumers read. Purely additive: the same call with no payload behaves exactly as before. Report every payload span **exactly once across the turn** — core does not deduplicate. Add `--mid` to report a MID-TURN span of agent output on the `busy` arm (still an `AGENT_OUTPUT` event, carrying `mid`); spans and the `idle` remainder must be disjoint | RUN | | **`api io-events --session-id --json`** (optional; build behaviour on the session's own events) | Read back the [IO funnel](../shells/frames.md#io--the-sessions-io-events-durable) events — `USER_INPUT`, `AGENT_OUTPUT`, `MSG_IN`, `MSG_OUT`, `COMMUNE`, `COMMUNE_FAIL` — as a **delta-cursored poll** (an `AGENT_OUTPUT` row carries `"mid": true` when it is a mid-turn span rather than the turn's close), so you can act on what a session did without polling a digest and diffing it (wake-marker-class constructs over commune events are the motivating case). Same session id you pass to `api state` — it is both the **cursor key** and the **auth**, one flag. A new session's first poll returns nothing and seeds silently; `--after ` if you would rather carry your own cursor; `--limit` says when it capped. See [the api surface](api.md#api-io-events-id---session-id-sid----after-seq---limit-n---json-authenticated) | RUN | | **`[io] compliance = true`** | Lets core parse *your* ingest for [shortform](../shells/frames.md#shortform-sending-from-inside-a-turn) — the `@` dispatch tag and the `;;` seal mint — so an agent sends and seals from inside a turn without shelling out. **Declare it in the release that deletes your own tag parser, never before**: absent the declaration core parses nothing, which is what makes that handover free of a double-fire window | RUN | | **`[adapter] shortcut_basename`** | Names the picker-generated project-root launcher `-` (the picker's `s` keybind) — your harness's brand instead of the `spt-` default | START | | **Shell surfaces** (`kind = "shell"`: `api bind-shell --link`, `api emit`, `api owner-shutdown`, the `[shell]` body) | Driven surfaces — notifiers, sensors, power buttons — authenticated by the launch link token alone. See [Shells](../shells/overview.md) | START / RUN | **claude-code:** uses `api shutdown` for graceful `/signoff`; declares a `[digest]` extractor mapping its per-session JSONL → the digest-record contract so `spt endpoint digest` shows live tool calls and spans `/clear`; declares `shortcut_basename = "cc"` so the picker's generated launcher is `cc-` (vs the `spt-` default); declares `[session.resume]` as `claude -r {session_id} …` so a picker *Resume from history* reloads the real transcript (not a blank session); declares a `[message-idle-translation-binary]` (`cc-spt-idle-translate`) so inbound messages reach an idle session as proper keystrokes; no shell body (it is a harness, not a driven surface). --- ## Group 4 — Beyond the API: integrations that make it good Not contract surfaces — no `api` command, no required field — but the difference between an adapter that *works* and one that feels native. **Strongly recommended.** | Integration | What it is | Why it matters | | --- | --- | --- | | **Commune / signoff file-drops** | The agent writes `-commune.md` (delta context) or `-signoff.md` (final save) into the manifest's watched `commune_dir` / `signoff_dir`; spt-core's watcher ingests it. **Delivered as a file-drop by design.** | The two-tier mind: live + project context survives `/clear`, `/compact`, suspend, and cross-node resume. The single biggest continuity win — wire the directory watch and read the contract filename | | **Resource advertisement** (`[session] resources` blurb / `spt endpoint description`) | A free-text "what I can serve" string riding the endpoint's registry rows | Other agents discover the endpoint's capabilities (`spt resources list`) instead of guessing | | **Install-on-demand bootstrap** | Pack the check-and-install of spt-core into your harness's first run (the [bootstrap pattern](install-on-demand.md)) | Zero-friction first run — the user installs your harness, spt-core comes with it | | **Surfacing `spt how-to ` to the agent** | Let the agent read task-oriented spt-core guidance from the binary itself | The agent self-serves common operations (subnet join, sending) instead of asking the user | | **Presence-driven idle reporting** | Fire `api state idle` from a *real* user-inactivity signal, not a timer | Accurate dormancy → Psyche wakes on genuine activity, echo-communes fire at true boundaries | **claude-code (the worked example):** ships the modern two-tier mind end to end — the session drops `-commune.md` at every `/clear` and `/compact`, and a Self-authored `-signoff.md` at graceful stop, into the watched `commune_dir`; declaring `[session.psyche_init]` promotes the endpoint to a LiveAgent (a **go-live gate** — spt-core never spawns it), and the `[session.psyche_resume]` per-event turn (+ the `[session.echo_commune]` template) lets spt-core drive the Psyche that ingests them; `[update] avenue = "delegated"` makes the Claude Code plugin updater the ripple avenue. That is the bar a native-feeling harness clears. --- ## Patterns introduced in v0.16.0 ### Hook dispatch by resolve-not-execute spt-core never grows a hook-**execution** surface — `[hooks.]` stays purely outbound (the harness fires `fires`; spt-core never runs a hook handler). When your hook *logic* must live in an adapter binary (so it rides `spt adapter update`) but the harness loads hooks from a static plugin dir, use the two adapter-static substitution keys to resolve+run **your own** binary: - **`{adapter_dir}`** fills to your install dir (the registry `source_dir`) and **survives updates**; **`{adapter_name}`** fills to your adapter name. Both are available wherever substitution runs — including, new in v0.16.0, **inside `[strings]` values at `get-string` read time** (scoped to *just* these two adapter-static keys; `get-string` has no session context, so `{id}`/ `{session_id}` are not available there). - Store the dispatch command in `[strings]`: ```toml [strings] hook_cmd = "{adapter_dir}/claude-spt hook" ``` - A thin, static per-OS dispatch wrapper (the one plugin-resident piece) runs `spt adapter get-string hook_cmd` **once per session** (memoize the resolved string into an env var for a hot-path hook like PostToolUse), then executes the resolved command per-hook itself. spt-core only **resolves and returns** the string — it never executes it (ADR-0029). **claude-code:** the plugin ships a static `hooks.json` + a per-OS dispatch wrapper; the wrapper resolves `get-string claude-spt hook_cmd` → `/claude-spt hook` once per session and runs it per-hook, so all hook logic updates via `spt adapter update claude-spt`. ### Incremental digest consumption — the `--json` cursor `spt endpoint digest --json` supports turn-end incremental consumption (v0.16.0): `--last ` (the last N turns; `--last 1` = the latest turn), a stable per-entry **`seq`** (source-derived — re-projection yields the same `seq`; it does not renumber when the window slides), and `--after ` (entries newer than `seq` still in the window; a full-window refresh + a predates signal if `seq` has fallen out). The trailing in-progress turn is flagged `partial: true` and its entries carry no stable `seq` until the turn closes (a turn is bounded by a user-input) — a consumer reprocesses `partial` and skips entries `<= seq`. `seq` is the authoritative dedup + cursor key. #### The `--json` output shape The snapshot is one pretty-printed JSON object; `--follow --json` emits one **compact** JSON object per line (a delta stream). Shapes as of v0.26.0: ```json { "turns": [ { "input": "fix the bug", "input_seq": 4294967296, "entries": [ { "Agent": { "text": "on it", "seq": 4294967297, "ts": "2026-07-06T09:00:00Z" } }, { "ToolSprint": { "tools": [ { "name": "Write", "arg": "src/a.rs" } ], "seq": 4294967298 } }, { "Boundary": { "kind": "clear", "ts": "2026-07-06T09:05:00Z" } }, { "Context": { "kind": "owl_message", "body": "ping", "ts": null } } ] } ] } ``` - **Turn**: `input` is the opening user-input text, `null` for a preamble turn (boundary/context entries that precede any input). `input_seq` and `partial` are **omitted** when absent/false — a trailing open turn carries `"partial": true` and its entries carry no `seq`. - **Entries are tagged by kind** — each entry is a one-key object whose key is the kind. The closed kind set: `Agent` (`text`, optional `seq`/`ts`), `ToolSprint` (`tools`: `{name, arg}` in order, `arg` presentation-truncated; optional `seq` = the **last** collapsed record's, optional `ts`), `Boundary` (`kind`: `clear` | `compact` | `boot`), and `Context` (`kind`: `psyche_download` | `echo_commune` | `owl_message`, plus `body`). `Agent`/`ToolSprint` omit `seq`/`ts` when absent; `Boundary`/`Context` carry no `seq` (they are spt-injected, not transcript records) and their `ts` is present-but-`null` when unknown. - **A delivered message can appear twice by design**: as the turn-opening `input` (your extractor's classification, below) *and* as a `Context`/`owl_message` row whose `body` is the **whole composed `` envelope verbatim** — exactly what the agent saw. Parse it with the [envelope rules](../messaging/overview.md#the-event-wire-contract); it is the message-identity anchor for dedup across the two appearances. - **`--after` signal**: when the cursor predates the window, the snapshot is the full window plus a top-level `"after_predates_window": true`. - **stderr trailer**: every successful pull prints `DIGEST: version=` on stderr (the version pairs with the delta stream below); an endpoint with no activity buffer reports `NO_DIGEST:` and exits non-zero. - **`--follow --json` delta lines**: `{ "version": , "from": , "turns": [ … ] }` — apply by truncating your view to `from` turns and appending; `from == 0` is a full replace (the base snapshot, or a window slide). Deltas are sent only when the digest actually changed. **Binding for your `[digest]` extractor / `api digest-entry`:** classify a **delivered user-facing message as a turn-opening `input` record** (equivalent to a direct PTY user-input). The projection treats `role: "input"` as the turn boundary; if messaging-delivered turns are not opened as `input`, a messaging-driven session collapses into a few giant turns and `--last`/`seq` lose granularity. *What* becomes `input` is your call; *that it opens a turn* is the contract. ### Global `--json` for read/status commands The read/status command set (`endpoint list`/`whoami`, `daemon status`, `subnet status`/`show-code`, `endpoint description`/`role`, `adapter list`/`version`, `notif list`, `grant list`, `access list`, `shell list`, `how-to`) honors a global **`--json`** flag (v0.16.0) for scripted consumption — stable, explicit per-command field names (a committed wire-parity surface). Action commands ignore it. Flag reference: the [CLI reference](../cli/reference.md). Committed compatibility posture for every `--json` shape: **additive evolution** — new fields appear (often omitted-when-absent), existing fields are never renamed or re-typed; parse tolerantly (ignore unknown keys). #### `endpoint list --json` — the output shape One object, three sections (as of v0.27.0): ```json { "self": { "id": "doyle", "status": "live_agent", "ready": true, "alive": true, "unbound": false, "description": null, "psyche_host_error": null }, "subnets": [ { "name": "home", "endpoints": [ { "id": "flynn", "node": "1a2b3c…", "node_label": "HFENDULEAM", "status": "Active", "resources": null, "endpoint_type": "live_agent", "project": "spt-mobile" } ] } ], "local": [ { "id": "doyle", "state": "live_agent", "address": "127.0.0.1:52110", "ready": true, "alive": true, "unbound": false, "project": "spt-core" } ] } ``` - **`self`** — the calling session's own endpoint, `null` when the session has no perch. `status` is the local perch state token (`live_agent`, `ready_agent`, …; `null` with no local perch), `ready`/`alive` likewise `null` for a pinless session. `description` is the endpoint's authored description or `null`. The fault annotations (each a string, and each meaning the human view shows the same fault line) do **not** all signal absence the same way, so test for the fault itself rather than for the key: `translation_fault` and `host_error` are **omitted entirely when absent**, while `psyche_host_error` is **always present and `null` when absent** — as the example above shows. Keying on whether `psyche_host_error` is present reads every clean perch as faulted. - **`subnets`** — one group per subnet the node belongs to, `endpoints` from the subnet's gossip projection. `status` is the ADVERTISED cross-node state, closed set: `Active` | `Dormant` | `Suspended` | `Offline`. `node` is the hosting node's key prefix, `node_label` its display label (or `null`). `resources` is the endpoint's advertised description string (or `null`). `endpoint_type` (`live_agent`, `ready_agent`, …) and `project` (latest project id) are **omitted when absent** — older rows may not carry them. - **`local`** — this node's perches from the roster. `state` is the same token set as `self.status`; `address` is the listener address (or `null`); `project` omitted when absent. - **Filters apply before serialization**: worker endpoints are excluded from all three sections by default (v0.27.0) — pass `--workers` to include them; suspended rows honor `--all` the same way. `spt whoami --json` emits its OWN identity-only shape *(since v0.33.0 — previously this list shape)*: `{id, state?, ready?, alive?, unbound?, description?}`, or `{"id": null}` + exit 1 when the session owns no endpoint. It never derives projects — the bounded-time identity verb for hook paths (see the [API reference](api.md) Introspection section). --- ## "Am I done?" — the floor - [ ] Manifest validates against [`manifest.schema.json`](http://localhost:5474/manifest.schema.json) - [ ] `[adapter]` header complete (`name`, `kind`, `version`, `min_spt_core_version`, `hostable_types`) - [ ] One startup flow wired: `SessionStart → seed` + `listen` (harness-hosted) **or** `[session.self]` + `bind` (spt-hosted) - [ ] (harness-hosted) `[adapter] host_binaries` names your harness exe(s) so `seed`/`listen` resolve with no `--adapter`; `spt adapter use ` sets the active default when several adapters host the same binary - [ ] `api state idle` fires on real inactivity; `can_inject` values are honest - [ ] An inbound delivery channel is declared (`[inject]`) or pulled (`api poll`) - [ ] `[history]` strategy chosen; `api boundary` wired for clear/compact - [ ] (mind continuity) **every** session-start path fires `api psyche-download` and injects its stdout, so a resumed session gets its durable context back — the `SessionStart` hook if you have one, **and** the extension's post-`bind` step if your harness is spt-hosted with no hook surface, **and** the go-live path (promoting a running session does not replay `SessionStart`). Verify by asking a *resumed* agent what it knows: if the answer is only your repo's static agent-instructions file, the pull is missing - [ ] (for a live digest) `[digest]` extractor declared + `digest-proof`-checked, or `api digest-entry` push - [ ] (spt-hosted, if your harness resumes by id) `[session.resume]` declares the native-resume command — else a resume comes up blank - [ ] (spt-hosted, for idle message delivery) `[message-idle-translation-binary]` declared + `translate-proof`-checked, or accept the degenerate `payload+enter` inject - [ ] (for an always-on background process) `[service]` declared with an explicit `start = "boot"|"bind"`; the binary calls `$SPT_BIN` (never bare `spt`), watches `SPT_SERVICE_DIR/stop-requested` and exits on it, and expects no session identity — see the [manifest reference](manifest.md#service--a-daemon-supervised-resident-service) - [ ] **Recommended:** `api now-signal` injected at every turn boundary (and `api hint` retired if you were injecting it — it is one category of this now) - [ ] (IO funnel) `api state busy|idle` carries the turn's payload on `--payload-stdin` / `--payload-file`, every span **exactly once across the turn** (`--mid` for a mid-turn span; spans and the `idle` remainder disjoint) - [ ] (optional) `api io-events --session-id --json` polled if your adapter builds behaviour on the session's own events — first poll seeds silently, so expect nothing back until the turn after you start - [ ] (shortform) `[io] compliance = true` declared **in the same release that deletes your own `@<…@>` / `;;` parser** — never in a release before it - [ ] `[update]` avenue declared (ripple-update + install-on-demand) - [ ] Teardown fires `api session-end` (or `api shutdown` for graceful signoff) - [ ] **Recommended:** commune/signoff directory watched (mind continuity) - [ ] `spt adapter add ./your-adapter` registers clean; `api … capability` echoes your `hostable_types` ## Next - **Reference:** the complete [manifest reference](manifest.md) and [`spt api` reference](api.md). - **Ship it:** the [install-on-demand bootstrap](install-on-demand.md). - **Driven surfaces:** [Shells](../shells/overview.md) — the `kind = "shell"` flavor of this same contract. ===== /harness-contract/manifest.md ===== # Manifest reference The runtime manifest is the declarative half of the harness contract: one TOML file per adapter, declaring **only what varies per harness or shell**. This page is the complete field reference. Machine-readable companion: [`manifest.schema.json`](http://localhost:5474/manifest.schema.json) — generated from the exact code that parses manifests, so it never drifts. Validate your manifest against it, then `spt adapter add` enforces the cross-field rules listed at the bottom. ## The principle **SPT is not a harness.** Command templates are opaque strings — spt-core never parses out a model, tool list, or flag; the adapter writes the full command line and spt-core runs it with `{key}` substitution placeholders filled. Anything spt-core owns is *not* in the manifest: - **Sentinels** (idle markers, the echo gate) — managed via `spt api state` / `spt api echo-gate`; adapters only call them. - **Spool, registry, perch, and daemon-state schemas.** - **The event-block vocabulary** — the tags spt-core surfaces to agents are a fixed, documented constant. Adapters pass spt-core's output through unchanged. - **File-drop filenames** — statically `-commune.md` / `-signoff.md`; only the watched *directory* is declared. - **Config knobs** (pulse period, summarizer windows, …) — global spt-core settings with per-endpoint overrides, never per-adapter. ## Substitution keys The full `{key}` vocabulary spt-core fills into command templates. A role's `keys` list must be a subset of this catalog, and every `{placeholder}` in a `command` (or `cwd`/`source`/`fires`/…) must resolve to a value spt-core supplies for that spawn — an unknown or unprovided key fails with a one-line error. Not every key exists in every context: spt-core fills only those relevant to the spawn (e.g. `{psyche_*}` only for a live agent's Psyche role, `{source}` only for a `[digest]`/`[history]` extractor). | Key | spt-core fills it with | |---|---| | `{id}` | The endpoint id being hosted. For a **Psyche** role this is the **parent endpoint id** (the LiveAgent being hosted), not the nested `-psyche` perch id. | | `{adapter_name}` | The adapter's declared `name` (the value every `api` call carries). | | `{adapter_dir}` | The adapter's install dir (the registry record's `source_dir`) — adapter-static, available wherever substitution runs (every `[session.*]`, `[digest]`, the translation binary, lazy `[strings]`, and — since v0.44.0 — the `[shell].spawn` and `[shell].wake_command` templates). Survives updates; lets a command point at the adapter's own packed binary (resolve-not-execute, ADR-0029). | | `{session_id}` | The harness session id (minted at spawn; reported back via `api seed`). For a **Psyche** role this is the Psyche's **own** custody session id — its own conversational thread, which a parent boundary (`/clear`, `/compact`) does not rotate — never the parent's. | | `{parent_session_id}` | The **parent** session id, exposed under its own explicit key so a Psyche role template that needs the parent's id never aliases `{session_id}` (which on a Psyche spawn is the Psyche's own custody id). | | `{session_name}` | The session's display name, when one is supplied. | | `{node}` | This node's **advertised label** — the value the roster and picker render (its OS hostname, read into the label store at daemon startup), never the pubkey. Node-static: available wherever the session keys populate **and** in lazy `[strings]` resolution. **Single-token fill only** (a space-carrying label stays adapter-shim territory); when no label is known the key is left unfilled so a referencing template fails loudly, never an empty token. Note: the daemon-side lifecycle resolves it once at startup while a CLI-originated spawn reads a fresh hostname, so the two differ only across a mid-life hostname change. | | `{subnet}` | This endpoint's **anchor-subnet label** (`local` when unanchored), filled whenever it is known so a nested Psyche turn need not resolve a `--subnet` it cannot know. A single `{subnet}` concept — there is deliberately no `{home}` key. When no subnet is known the key is left unfilled so a referencing template fails loudly (the `{node}` precedent). | | `{parent_pid}` | The harness parent process pid — the SessionStart `api seed` anchor. | | `{agent_type}` | The hosted agent type. | | `{psyche_context_file}` | The **path** to the file spt-core writes the Psyche's carried context into before each turn (never the context body on the argv — a large mind would exceed the command-line length cap). Fresh vs continue is the file's **content**: a fresh/reseeded turn writes it non-empty, a continue turn writes it 0-byte. Replaces the former `{psyche_context}` body key. | | `{link_token}` | A shell-link capability token (shell adapters). | | `{perch_dir}` | The shell instance's perch directory (shell `spawn` template only — a `wake_command` fills its own smaller catalog, which since v0.44.0 includes `{adapter_dir}` but never this key). What lets the binary resolve a `shell_file` frame's **perch-relative** `path` attribute — the spawned child inherits the *broker's* working directory, so without this key no mechanical resolution exists. Opt-in: a template that never names it fills exactly as before. Filled as **one argv element** even when the directory contains spaces. See [the frame contract](../shells/frames.md#shell_file--a-landed-file). | | `{source}` | The transcript/log path spt-core resolves for a `[digest]`/`[history]` extractor. | ## `[adapter]` — header (required) The only mandatory section, and it must be readable *before* any install or update — `min_spt_core_version` is the compatibility gate. ```toml [adapter] name = "my-harness" # the adapter_name; an optional --adapter override kind = "harness" # "harness" (default) | "shell" version = "1.0.0" min_spt_core_version = "1.0.0" # lowest spt-core this adapter tolerates hostable_types = ["LiveAgent", "ReadyAgent", "Worker"] host_binaries = ["my-harness"] # harness exe(s) you host → bind-time resolution, no --adapter web_short_path = "reports" # optional alias; the adapter facet exists without it ``` | Field | Required | Meaning | |---|---|---| | `name` | yes | Adapter id; the value an optional `--adapter ` override carries | | `kind` | no (default `harness`) | `harness` hosts agents; `shell` provides a driven surface | | `version` | yes | The adapter's own version | | `min_spt_core_version` | yes | Compat gate, checked before install/update | | `hostable_types` | no | Endpoint types this adapter can host | | `host_binaries` | no (harness) | Harness exe basenames you host — the bind-time match-key so `seed`/`listen` resolve with no `--adapter` (since v0.9.0). Matched on **lowercase + stem-before-first-dot**, so `claude` matches `claude`/`claude.exe`/`claude.cmd`/`claude.exe.old.` (a self-update can rename the running exe); a declared name must not contain a dot | | `web_short_path` | no | Requested short alias for the base adapter's core-owned served root; collisions receive a persisted suffix | **Unknown keys.** A key spt-core does not know is ignored, never refused, so an adapter written against a newer core still registers. `spt adapter add` names each one on stderr as `manifest: unknown key []. (ignored)` and proceeds. A misspelled `web_short_path` therefore registers without an alias and says so. Tables the contract declares free-form (`[profiles.*]`, `[strings]`) are the adapter's own vocabulary and are not swept. **Served output.** Core creates `$SPT_HOME/adapters//web/` before committing activation, even if the daemon is stopped. Write only intended served output there; core never exposes the adapter's install tree, manifest, records, or strings on its behalf. The daemon reconciles one `dir` entry per active base adapter at startup and after adapter changes. `http://localhost:5474//a//` always names that entry; `web_short_path` adds `///` as an alias. A profile never adds a separate row or root; the base declaration controls the shared resource. Aliases must be nonblank single segments, not `.` or `..`, and contain no path separators, colon, or control characters. The reserved facets `f`, `docs`, `a`, `m`, `bin`, and `install` are refused case-insensitively before registration writes and when resolving manifests. Other collisions allocate `reports~1`, `reports~2`, …; `spt serve list` reports the assigned alias. An update or repeated registration preserves the live assignment, including whether it has an alias. A changed/added/removed declaration takes effect on deactivation followed by reactivation. With the same declaration, reactivation reclaims the root's prior name and kind; other sources cannot take retired names. Removing or deactivating an adapter removes exposure, not output bytes; updates and reactivation also retain them. Redirected roots and symlinks escaping the served subtree are refused. ## `[hooks.]` — inbound hook table One entry per harness event, declaring the `spt api` command it fires, the input fields it maps in, and whether the hook can surface text into the agent's context. ```toml [hooks.SessionStart] fires = "api seed --pid {parent_pid} --session-id {session_id}" # adapter-agnostic since v0.9.0 reads = ["session_id", "parent_pid"] can_inject = true [hooks.Stop] fires = "api state idle" can_inject = false # no inject channel -> sentinel/relay fallback ``` | Field | Required | Meaning | |---|---|---| | `fires` | yes | Opaque `api …` command line the harness invokes for this event | | `reads` | no | Input fields (e.g. from the hook's stdin payload) mapped into the command | | `can_inject` | no (default `false`) | Whether this hook can inject context back to the agent. When `false`, spt-core falls back to its sentinel + relay/poll path instead of expecting injection | `can_inject` is the single most load-bearing harness-varying fact — declare it honestly per hook. ## `[session]` — watched dirs + role templates Two watched-directory keys sit directly on `[session]`; the file *names* are fixed by spt-core, only the directory varies: ```toml [session] commune_dir = ".my-harness" # watched for -commune.md signoff_dir = ".my-harness" # watched for -signoff.md ``` Commune and signoff are **file-drops, not commands** — an agent writes a markdown file; spt-core's watcher does the rest. ### `[session.]` — outbound templates One opaque command template per role. Model, tools, flags, permissions — all live inside `command`, never as separate fields. Roles: `self` (the agent's own session) · `resume` (the agent's own-session **native resume**, the `self` sibling) · `psyche_init` (**go-live gate only** — its presence promotes the endpoint to a LiveAgent; spt-core never spawns it) · `psyche_resume` (the **sole driven** Psyche role — one bounded per-event turn) · `echo_commune` (the bounded history summarizer for sessions that end without a signoff) · `signoff` (final context save) · `notif` (endpoint-native notification render). **Resuming an existing harness session (since v0.13.0).** `[session.self]` is the *fresh* bringup; `[session.resume]` is the **native-resume** sibling. spt-core selects `[session.resume]` over `[session.self]` only when a bringup carries a prior session (`spt endpoint resume `, `spt go ` on an offline endpoint, or the picker's *Resume from history*) **and** your manifest declares the role. **Resume is latest-only** — no verb takes a session argument, and one is refused rather than ignored: core resolves which session to resume from the endpoint's ledger. Declare it with your harness's native-resume verb — if your harness resumes a transcript by id, use that form (Claude Code: `claude -r {session_id} …`), **not** the fresh create-session form. Skip the role and a resume silently re-runs `[session.self]` (a *fresh* session → a blank transcript). spt-core fills the SAME key catalog as `self` (`{id}`, `{session_id}` = the **resumed** id, `{session_name}`, `{adapter_name}`) and lands the PTY in the session's recorded **project cwd** (a harness resolves a transcript by `session_id` **+ cwd**) — the per-session ledger row's cwd, else the endpoint's bind cwd, else the current dir. **A resume can legitimately start FRESH — and says so.** `{session_id}` is always a **harness-reported** id from the endpoint's ledger, never spt-core's own spawn-time provisional (your harness has never seen that one and cannot resolve it). If the endpoint has no harness-reported session on record — only a spawn provisional — spt-core does not hand the provisional to your template: it prints `RESUME_NO_HARNESS_SESSION:` and starts a fresh session through `[session.self]`. Your `[session.resume]` command simply does not run that time, which is correct and is *not* a template failure; the notice on stderr is how you tell the two apart. ```toml [session.resume] command = "my-harness resume --session {session_id} --id {id}" keys = ["session_id", "id"] ``` ```toml # Go-live gate ONLY — spt-core never spawns this; its presence makes the endpoint live. [session.psyche_init] command = "my-harness run --agent psyche --model cheap" # The role spt-core actually drives — one bounded turn per Psyche event. [session.psyche_resume] command = "my-harness run --agent psyche --resume {session_id} --model cheap" env_remove = ["MY_HARNESS_SESSION_ID"] recursion_guard_env = "SPT_ECHO_COMMUNE" keys = ["session_id", "parent_session_id", "psyche_context_file", "subnet"] ``` A Psyche runs as a **bounded per-event turn**, not a resident process (there is no psyche pid to poll — liveness is that turns succeed). Declaring `[session.psyche_init]` is the **go-live signal only** — spt-core **never spawns it**; the per-event turn drives **`[session.psyche_resume]` exclusively**. For that turn spt-core fills `{session_id}` (the Psyche's **own** custody id — see the key table), `{parent_session_id}`, `{psyche_context_file}`, and `{subnet}` (when known); the adapter-static/node keys `{id}` (the **parent endpoint id**), `{adapter_dir}`, `{adapter_name}`, and `{node}` are also available. It does **not** fill `{session_name}` (a `[session.self]` key). Declaring a key your role's spawn isn't given fails at spawn, so template only the keys spt-core fills for the role. **Not declaring `[session.psyche_resume]` is allowed, and it is loud (since releases#239).** The role is **load-bearing when declared** — it is the only role the per-event turn drives — so an endpoint without it simply runs no psyche turns. That is a supported configuration, not a fault, and spt-core treats it as one: - the turn is **skipped**, decided before anything is spawned; - a single `PSYCHE_ROLE_ABSENT:` line is logged **once per endpoint**, not once per fire; - **no strikes accrue.** The consecutive-failure budget is for a declared role that *fails*; a role that was never declared cannot fail and cannot self-heal, so spending that budget on it would exhaust a guard built for a different mechanism; - the endpoint's status carries `psyche_role_absent` (visible on `spt endpoint list --json`), and it is a **status** field, not the `psyche_host_error` failure latch — nothing is being retried, so there is no attempt count and the stamp records when the absence was *first noticed*; - **it clears itself.** Declare the role and the next fire runs a turn and drops the status, with no operator gesture. `[session.echo_commune]` behaves the same way with one deliberate difference: its absence is *quiet*, because the published contract presents it as an optional template, while a missing `psyche_resume` silently disabling every psyche turn is exactly the kind of degradation that has to announce itself. **Reserved exit codes — how a `psyche_resume` turn tells spt-core *why* it failed.** spt-core classifies a failed turn on the process **exit code alone — never on output text** (your harness may reword, restructure, or JSON-wrap its errors freely; only the code is contract). Any other nonzero exit is a generic failure: spt-core keeps the Psyche's session custody, counts a strike, and retries. | Exit code | Meaning | What spt-core does | |---|---|---| | `95` | **Psyche session gone** — the harness's own session store no longer resolves the `{session_id}` it was asked to resume. Exit `95` **only** when the resumed session itself is missing/expired; a *fresh* turn (non-empty `{psyche_context_file}`) must never exit `95`. | Reseeds: clears custody and re-mints the Psyche session from the carried context. The **only** exit that reseeds. | | `96` | **Account/credential refusal** — the inner tool refused for account-level reasons (spend/usage cap, expired or revoked credential, org quota): the session is healthy, the code is healthy, a retry would succeed on a healthy account, and only a **human** can restore it. | Retries on its own slow pacing and surfaces the outage under a distinct label. Never reseeds (custody is fine — a reseed would destroy a healthy transcript), and never spends the crash/defect strike budget. | Adapters own the mapping from their inner tool's observable failure to these codes (match your tool's output **in the adapter**, where you can track its wording — that is exactly why spt-core never does). Emit the diagnostic text on **stderr** and keep it in the exit line if you wrap an inner process: a bounded tail of both streams in the failure message is what turns an outage from a mystery `exit code: 1` into a one-glance diagnosis. **Shipped binaries resolve from the install dir (since v0.8.0).** A command template's bare program token (its first token, e.g. `my-harness-digest`) resolves against the adapter's **install dir** before `PATH`, so a `.spt` that ships its own binaries is self-contained — no PATH placement needed. spt-core runs `/` (on Windows also trying the `.exe` suffix) when that file exists, else falls back to `PATH`. The install dir is where your adapter was registered (the `--release`/`--github` durable home, or the copy-mode source dir). This applies to the `[session.psyche_resume]` per-event turn, the [`[digest]`](#digest--session-digest-extractor) extractor, `spt adapter digest-proof`, and — since v0.44.0 — the `[shell].spawn` and `[shell].wake_command` templates: a released shell adapter's binary launches by bare name from its install dir, with no node-local manifest edits. Ship a binary in your `.spt` and reference it by bare name; you need not place it on `PATH`. | Field | Required | Meaning | |---|---|---| | `command` | yes | Opaque command line with `{key}` placeholders | | `cwd` | no | Working directory (substitutable) | | `recursion_guard_env` | no | Env var set on summarizer children so *their* hooks bail (no summarizer-of-summarizer loops) | | `detach` | no (default `false`) | Spawn detached | | `env_remove` | no | Env vars stripped from the child's inherited environment | | `keys` | no | The substitution keys spt-core fills for this role | | `invocation_budget_secs` | no (default `90`) | How long a **bounded** invocation of this role may run before spt-core kills it. Declare it on any role that is an LLM turn — the adapter is the only party that knows what its own model costs. Clamped to `300`; a role that declares nothing gets `90`. See [Invocation budgets](#invocation-budgets) | ### Invocation budgets Some roles spt-core runs are **bounded**: it spawns them, waits, and kills them if they overrun. A role that is an LLM turn should declare how long its own model needs, because spt-core cannot know it: ```toml [session.echo_commune] command = "claude -p --model haiku …" invocation_budget_secs = 120 ``` **A role that declares nothing gets 90 seconds**, and a declared value is **clamped to 300** — an adapter may ask for more time than the default, never for effectively unbounded. The resolution keys on the field, not on which role is asking, so a future bounded role picks this up with no core change. Pick the number from what your model actually costs, with headroom for a loaded machine. The default exists because a flat 30-second bound used to kill legitimate summarizer turns: the same input on the same node measured 23s and 35s depending on load, so whether a healthy agent was killed came down to what else the machine was doing. If your turns measure near the bound, raise it — being killed at the bound is not treated as a defect (see below), but it does mean the work is lost. **A bound kill is not counted as a fault.** spt-core tracks bound kills on a separate, far more forgiving budget than real failures, precisely because a kill says more about the machine's load than about your adapter. A slow-but-healthy harness will not be marked failed. `notif` is the endpoint-native notification render — an OS toast, a status LED, anything the adapter can run. Spawned detached when a notification surfaces at this endpoint. Keys spt-core fills: `{notif_id}`, `{notif_from}`, `{notif_subnet}`, `{notif_body}`. ```toml [session.notif] command = "powershell -Command New-BurntToastNotification -Text '{notif_from}','{notif_body}'" keys = ["notif_id", "notif_from", "notif_subnet", "notif_body"] ``` ## `[env.]` — env-var table Vars to inject into (or read from) sessions, and how. The injection channel is asymmetric by hosting mode: **spt-hosted** sessions inherit env from the broker that spawned them (no channel needed); **harness-hosted** sessions need the harness's declared channel. ```toml [env.MY_HARNESS_SESSION_ID] direction = "inject" # "inject" | "read" value = "{session_id}" # required for inject channel = "MY_ENV_FILE" # harness-hosted only ``` ## `[history]` — transcript access How spt-core reads a session's conversation history (it powers the echo-commune summarizer). Three strategies; pick exactly one: ```toml [history] strategy = "fetcher" # "fetcher" | "locate_normalize" | "native" fetcher = "my-harness-history --session {session_id}" ``` | Strategy | Required fields | Meaning | |---|---|---| | `fetcher` | `fetcher` | spt-core runs your binary; it emits normalized history | | `locate_normalize` | `locate_template`, `normalize_command` | spt-core locates the raw transcript, then runs your normalizer over it | | `native` | — | The adapter pushes via `spt api history-log`; spt-core stores it | spt-core has **no built-in transcript parser for any harness** — the adapter always owns that knowledge. ## `[digest]` — session-digest extractor The session digest's own seam (ADR-0019) — separate from `[history]`, which stays opaque and single-session for the echo-commune. `[digest]` declares an **imperative extractor** that maps your harness's native log to the digest-record contract: ```toml [digest] extractor = "my-harness-digest --session {session_id} --in {source}" source = "~/.my-harness/{session_id}.jsonl" # optional; defaults to [history].locate_template window_turns = 5 # optional presentation defaults you declare… arg_truncation = 40 # …any consumer may override at pull/subscribe sprint_collapse = true ``` | Field | Required | Meaning | |---|---|---| | `extractor` | yes | Opaque command: native log → contract JSONL (one record/line). Under `locate_normalize` spt-core fills `{source}` with the resolved path and pipes the bytes on stdin; under `fetcher` it just runs the command and reads stdout. | | `strategy` | no | Which side locates the transcript, mirroring `[history]` — `locate_normalize` (default) or `fetcher`. See the strategy table below. | | `source` | no (locate_normalize only) | Own-source log path; absent, reuse `[history].locate_template`. Under `locate_normalize` one of the two **must** resolve, else `spt adapter add` rejects (see [Cross-field rules](#cross-field-rules-spt-adapter-add-enforces-these)). Ignored under `fetcher`. | | `window_turns` / `arg_truncation` / `sprint_collapse` | no | Adapter-declared presentation **defaults**; any consumer may override. spt-core fallback: `3` / `25` / collapse-on. | `[digest]` supports the same two locate strategies as `[history]` — pick with `strategy`: | Strategy | Who locates the transcript | `source` | |---|---|---| | `locate_normalize` (default) | **spt-core** resolves the single `source` file, reads it, pipes the bytes to the extractor on stdin. | Required (own `source` or inherited `[history].locate_template`). | | `fetcher` | **The adapter's** extractor locates + reads + emits; spt-core runs it bounded and consumes stdout — no `source`, no pre-read. | Not used. | Use `fetcher` when the transcript lives in a **partitioned** layout spt-core cannot name with one template — e.g. Claude Code's `projects//.jsonl` or a date-globbed rollout tree. spt-core feeds the extractor only the harness-**neutral** inputs it owns — `{session_id}`, the perch-bound `{cwd}`, and any captured [`[env] direction = "read"`](#envvar--env-var-table) vars (e.g. `{CLAUDE_CONFIG_DIR}`) — never a harness-specific project slug; the extractor globs the unique `{session_id}` under the root itself: ```toml [digest] strategy = "fetcher" extractor = "my-harness-digest --session {session_id} --config-dir {CLAUDE_CONFIG_DIR} --cwd {cwd}" # no `source` — the extractor locates the file ``` Why a command, not a declarative map: real harness logs are nested (one line → many entries, mixed block lists, types to filter); a flat map can't express them. A **log-less** adapter declares no `[digest]` and pushes via `spt api digest-entry` instead. Validate before shipping with `spt adapter digest-proof --sample `. `digest-proof` fills the same `{id}` and `{session_id}` the runtime `endpoint digest` does, so a `{session_id}`-templated extractor (e.g. `--session {session_id} --in {source}`) proofs exactly as it runs live; pass `--session ` to pin a specific session id. ## `[inject]` — input-injection methods How text can be put in front of the agent, per activity state. Any combination of `pty`, `hook`, `relay`, `http`: ```toml [inject] activity = ["hook"] # non-disruptive while the agent is working idle = ["pty", "hook"] ``` ## `[io]` — IO-funnel compliance **Opt-in, and absent means off.** Declaring `[io]` is how an adapter tells spt-core that its own local tag parsers are gone as of this release, so core may parse its ingest: ```toml [io] compliance = true # core may parse this adapter's ingest shortform = false # optional: stay compliant, keep core-side shortform off ``` - **`compliance`** *(bool, default `false`)* — the declaration itself. Absent or `false`, core parses **nothing** of this adapter's ingest. - **`shortform`** *(bool, optional; absent ⇒ enabled)* — the exotic-harness opt-out. It is **one switch over both shortform markers**, the `@<…@>` dispatch tag and the `;;` seal mint, because they are one feature with one suppression grammar. Setting it `false` disables that reader and leaves the compliance declaration standing. **Declare compliance in the release that deletes your own parser, not before.** That ordering is the whole point of the default: an adapter that ships its own tag parser today stays the only parser until one change removes it and declares here, so no version exists in which both parse the same text and send it twice. The grammar these fields gate — what a tag looks like, how backticks and fenced blocks suppress it, what happens with no controller attached, and where the outcomes surface — is the frame contract's [shortform section](../shells/frames.md#shortform-sending-from-inside-a-turn). ### `[io.now_signal]` — standing now-signal tuning What `spt api now-signal --spec-manifest` reads. An adapter knows which categories its surface can render, which are noise in it, and what its injection budget is; this is where it says so: ```toml [io.now_signal] without = ["SHELLS"] # suppress a category max_lines = 4 # cap each category's output per poll # only = ["DISPATCH_RESULTS"] # or narrow to an explicit set ``` - **`only`** *(array of category names; empty ⇒ no narrowing)* — when non-empty, the only categories rendered. - **`without`** *(array of category names)* — categories to suppress. If a category appears in both, **suppression wins**. - **`max_lines`** *(integer, optional)* — a per-poll cap on the lines a single category may print. **It narrows and tunes; it never invents.** A name outside the category vocabulary is ignored rather than conjured — and ignored rather than *refused*, so a manifest may carry a deferred category's name ahead of core building it and still load. Absent `[io.now_signal]`, a `--spec-manifest` poll renders the default picture; so does a malformed one, because this verb runs on a hook at every turn boundary and a config typo must not break a working session. The category list itself is in [the frame contract](../shells/frames.md#the-v1-categories). ## `[message-idle-translation-binary]` — spt-hosted idle delivery **Opt-in, spt-hosted only (since v0.13.0).** An adapter's **idle-delivery translation binary**: a pure `stdin → stdout` JSON-lines filter spt-core lifecycle-manages (spawned when the spt-hosted endpoint comes up, terminated when it goes down). spt-core feeds it the inbound `` message feed and reads back keystroke-commands, which it applies to the broker-held PTY **atomically** — a live `spt rc` controller's input is buffered during the emitted sequence and flushed after, so idle injection coexists with an attached operator (spt-core owns every PTY write). **Idle delivery only** — busy / mid-turn delivery stays your `[inject]` hook path. **Every byte spt-core writes on this leg, so your editor is never surprised.** Three things reach the PTY on an idle delivery and nothing else: **(1) a readiness probe** before the delivery's first byte on an echoing PTY — the DSR cursor-position query `ESC [ 6 n`, repeated every ~40 ms until the session produces output or a bounded deadline elapses (a non-echoing ConPTY, where the probe is never observable, latches it off); **(2) the keystroke-commands your binary emitted**, verbatim; **(3) a re-drive** — the same payload typed again, after another probe — if the typed head does not echo back. spt-core never sends a clear-line or clear-input of its own; if a draft in your editor vanishes on delivery, the erasure is either your emitted sequence or your editor's reading of the probe (a TUI that treats an unrecognised CSI, or a bare `ESC`, as clear-input). If you declare no translation binary, spt-core never touches the PTY on message arrival and idle messages spool. "Idle" is spt-core's view of the *agent*: a human composing a draft while the agent is idle is on this leg. Declared as a **table** carrying a `path` scalar (a table can't be silently absorbed by a preceding section and stays extensible): ```toml [message-idle-translation-binary] path = "cc-spt-idle-translate" # the binary spt-core spawns + drives ``` - **stdin** (spt-core → binary, one JSON object per line): `{"type":"init","endpoint_id":…,"node":…}` first · `{"type":"event","envelope":""}` per inbound message (the `` envelope) · `{"type":"input"}` — a **content-free** ping each time the operator types, so the binary can track user-idle (the PTY input content is **never** duplicated to the binary). - **stdout** (binary → spt-core, one per line): `{"key":"ctrl+s"}` · `{"delay_ms":50}` · `{"text":""}` · `{"key":"enter"}` · `{"commit":true}`, … (extensible vocabulary). - **`{"commit":true}` is the mandatory sequence terminator — and you MUST send it for EVERY `{"type":"event"}`.** While your emitted sequence is in flight, spt-core buffers a live `spt rc` controller's keystrokes (the *inject floor*) and applies your commands to the PTY atomically; `{"commit":true}` — emitted as the **last** record — releases that floor and flushes the buffered controller input *after* your sequence. The submit keystroke is **not** the terminator: `{"key":"enter"}` (or a trailing `\r` inside a text payload) submits the input, but a choreography may keep typing *after* it (e.g. a stash/restore that presses a key after submitting), so commit is a distinct, explicit signal you always send last. **An empty response is a protocol violation:** even when you have nothing to inject (an event with nothing armed, or an event without an envelope), you MUST still answer with at least a bare `{"commit":true}` — a response of zero records is treated as a missed commit. - **Missed commit → the sequence is tolerated, not fatal.** If no `{"commit":true}` arrives within the **commit deadline (5 s)**, spt-core still flushes the buffered operator input (never stranded) and re-spools that one message once so it is not lost — but it does **NOT** terminate a healthy binary. A single miss is tolerated; the binary is preserved and the next event delivers through it as normal. Only after **3 consecutive** missed commits (a genuinely wedged binary), or a real binary death, does spt-core fault the binary — and even then it **bounded-eager-respawns** it (a healthy commit resets the budget) rather than leaving it permanently dead, surfacing the fault on the endpoint's status while it is degraded. (This supersedes the pre-v0.14.3 "falls back to a raw inject" behavior — raw inject was removed; a missed commit never types your payload raw.) - Unknown fields are **not** rejected here — a newer adapter declaring a future key against an older spt-core parses fine (the key is ignored), so the contract degrades gracefully. - `{"text":…}` is applied to the PTY **verbatim** — bytes are typed exactly, with **no** control-character stripping. A trailing `\r` *inside* a text payload (`{"text":"…\r"}`) therefore **submits**, identical to a following `{"key":"enter"}` (`enter`→`\r`). Submit either way; just don't do both. Corollary: neutralize any CR/LF *inside* the message body before the trailing submit, or an embedded newline fires the input early. - A minimal binary just emits `{"text":payload}{"key":"enter"}{"commit":true}` with no choreography. (spt-hosted idle delivery is translation-binary-only since v0.14.3; there is no raw-inject fallback — a binary that fails to spawn or misses its commits spools the message, it is never typed raw.) ## `[service]` — a daemon-supervised resident service **Opt-in (since v0.44.0).** Declares a **resident service**: a binary the **daemon** supervises on the adapter's behalf, core-owned from birth. It is spawned **job-neutrally by the daemon**, so it is never a shell's child (a tree-kill of the shell cannot reach it) and never inside a launching terminal's Job Object (closing the terminal cannot sweep it). It has **no perch, no identity, and no address** — a service needing a two-way agent-facing surface has one at its adapter's endpoint/shell layer. It runs independent of any agent's liveness. ```toml [service] command = "{adapter_dir}/gw-hub serve" # opaque; program token + args start = "boot" # "boot" | "bind" — REQUIRED stop_grace_ms = 30000 # optional; defaults to 30s ``` - **`command`** — an **opaque** command string (program token plus args), like every other command seam. Its program token resolves against the adapter **install dir** before `PATH`, and args support adapter-static `{adapter_dir}` / `{adapter_name}` substitution only. Must be non-empty: a declared service means spt-core owns and supervises a process. - **`start`** — **required**, no default. `"boot"` is **desired-state-running, not an event**: the supervisor reconciles the service toward running at daemon boot, at **adapter registration against a live daemon** (installing or registering an adapter never requires restarting spt to bring its service up), at update-hold release, and at first shell bind as a defensive ensure. `"bind"` starts lazily at the adapter's first shell bind. Both are supervised identically once running. The key is required rather than defaulted because the choice decides whether a least-trusted third-party binary rises with the daemon itself — an adapter author says so explicitly. - **Registration reports what it did, and never fails over the service.** After a successful `spt adapter add` or `spt adapter update`, the CLI asks the daemon to reconcile that adapter and prints one line per option — started, already running, held, deferred to first bind, or not started with the reason. If the daemon is **not running**, the registration still succeeds and the CLI says so: the service is declared and starts at the next daemon boot. A registration is never refused because a service could not be started, and the notice is not optional — without it a `start = "boot"` service would silently not exist until something else restarted the daemon. - **`stop_grace_ms`** — how long a cooperative exit has before the supervisor force-kills. Defaults to `30000`. Must be `> 0`: a zero grace would leave no window to exit in. - **Cardinality** is one supervised instance per registered adapter-option (`[:profile]`). The supervisor threads the option name and a per-option runtime dir into the service's spawn environment, so an adapter can scope its own guards and config per option. An adapter may keep its own file lock as a private double-start guard; spt-core neither reads nor depends on it. - **The spawn contract, by name.** A supervised service is started with these environment variables, and they are the whole interface: | variable | value | |---|---| | `SPT_SERVICE_OPTION` | the adapter-option this instance serves, e.g. `hub` or `hub:staging` | | `SPT_SERVICE_DIR` | this instance's private runtime directory, created before the spawn | | `SPT_BIN` | absolute path to the `spt` executable to call (see below) | | `SPT_HOME` | the state root that `spt` must be run against | The option is the raw string an operator types, not a path encoding. The runtime dir is per-option, so two options of one adapter never share a directory — scope any private lock or config file inside it. - **Calling the `spt` CLI from a supervised service.** Invoke `$SPT_BIN`, not a bare `spt`. A service is spawned by the daemon, not by a login shell, so its `PATH` is whatever the daemon inherited — a daemon started by the platform service manager or a scheduler has no reason to carry the install dir, and a bare `spt` would work on the author's box and be silently missing in the field. `SPT_BIN` also names the *running daemon's own image*, so the CLI the service calls is never a different build than the supervisor that owns it. `SPT_HOME` is likewise pinned to the home the daemon resolved rather than left for the child to re-derive from a per-account platform default. Both are absolute. `SPT_BIN` is the one variable here that can be **absent** — if core cannot read its own image path it says nothing rather than handing out a guess, so treat an unset `SPT_BIN` as "the CLI is not available" and report it. - **A supervised service has no session identity.** Core *removes* `SPT_ENDPOINT_ID`, `OWL_SESSION_ID` and `SPT_AGENT_ID` from the spawn: a service is a node-scoped process with no session and no perch, so its `spt send` presents as the anonymous `cli@` origin. Without the scrub a daemon that happened to be started from inside an agent's shell would hand that agent's identity to every service on the node, and their messages would claim to be from that agent — with the replies routed back to it. A service that needs a perch identity registers one; it never inherits one. - **The runtime dir's core-owned filenames, also by name.** Three names inside `SPT_SERVICE_DIR` are contract; everything else in there is the adapter's own. | file | written by | meaning | |---|---|---| | `stop-requested` | spt-core | the quiesce request — its *existence* is the whole message (see below) | | `status-advisory` | **the service** (optional) | one **advisory** line surfaced by `spt adapter service status` | | `startup.capture` | spt-core | the service's own stdout+stderr from its startup window — the evidence a `STARTUP_FAULT` carries | `status-advisory` is the one file in this contract an adapter writes and core reads. It is **display-only and never consulted for a decision** — no reconcile, hold, kill or adoption reads it — because core deciding on it would put a least-trusted binary's self-report in the control path, and a service that stopped updating it would silently become whatever it last claimed. The read is **bounded** (the first line, capped) and an unreadable file is simply no advisory: nothing here ever requires reading a file the service holds an exclusive OS lock on. Write it however suits the service — a whole-file rewrite each cycle is the intended shape. `startup.capture` holds **both** streams on one handle (an adapter reporting its fault on stdout must not produce a diagnostic-free `STARTUP_FAULT`). Core truncates it at every spawn and again once a run outlives the startup threshold, so it is evidence and never a log to accumulate in — a service that wants a durable log writes its own file beside it. - **Quiesce is cooperative exit plus a deadline.** The supervisor creates the file **`stop-requested`** inside `SPT_SERVICE_DIR`. Its *existence* is the entire message: there is no content to parse, no reply to send, and no channel to open — a service that already has a loop just stats that one path each cycle and exits when it is safe to. The kernel-observed exit **is** the acknowledgement, so "not ready yet" is expressed by not-yet-exiting and no busy record exists to go stale in either direction. Past `stop_grace_ms` the supervisor force-kills. **Delay is possible; veto is not.** - **Update holds the service.** An adapter update is an ordered supervisor operation: quiesce → **hold** (stopped, and never relaunched while held) → swap bits → start the new bits → release. Crash-relaunch applies only when not held, because a supervisor that eagerly relaunched mid-swap would re-pin the old executable and turn a diagnosable failure into an unwinnable race. - **Liveness is derived, never recorded.** The supervisor is the parent and holds the child handle, so exit is kernel-observed and no "running" record exists to go stale. - **Consecutive fast exits are a configuration fault, not a crash.** A service that exits repeatedly within the startup threshold trips a loud `STARTUP_FAULT` diagnostic carrying its captured startup output, rather than being ground silently through relaunch backoff. A run that outlives the startup threshold resets that counter. - **The service can invoke the spt CLI** (`spt send` and friends) from its supervised environment, under the usual identityless `cli@` from-label. It takes no inbound spt traffic. - **Operator surface:** `spt adapter service list` and `spt adapter service status ` (see the [CLI reference](../cli/reference.md#spt-adapter-service)). These live under `spt adapter` — the resident service belongs to the adapter, whereas `spt daemon`'s "service" wording refers to the OS service manager hosting the daemon itself. Both are **read-only** and both are **answered by the daemon or not at all**: the supervisor holds the child handles, so service state exists only in the daemon's memory. With no daemon running the CLI says exactly that — it never derives "running" from the pid file in the runtime dir, which exists so the *next* daemon can kill an orphan and is not a liveness record. Each row reports the declared start trigger, whether the service is running, whether an update is holding it, any relaunch suppression **with the captured startup output behind it**, and the service's own advisory line when it wrote one. ## `[identity]` — session identity How the harness's session id is obtained: ```toml [identity] session_id_source = "post_spawn" # "post_spawn" | "uuid_inject" parent_ancestor_name = "my-harness" ``` `post_spawn`: discovered after spawn (process tree / wrapper hand-off), with `parent_ancestor_name` as the process-tree anchor. `uuid_inject`: spt-core injects a UUID the harness echoes back. ## Session digest — the digest-record contract The live activity digest (`spt endpoint digest `) is a **projection of the endpoint's session logs**, not a parse of the PTY byte stream. Your `[digest]` extractor (or a `spt api digest-entry` push) emits the **digest-record contract** — JSON objects spt-core projects: ```json {"role": "input", "text": "add a file", "ts": "2026-06-13T21:00:00Z"} {"role": "agent", "text": "on it"} {"role": "tool", "tool": {"name": "Write", "arg": "src/a.rs"}} ``` - `role` ∈ `input` | `agent` | `tool` (the source tag). - `text` — the input / agent span (omitted for `tool`). - `tool` — `{name, arg}`, present iff `role == "tool"`; consecutive tool records collapse into one sprint (unless `sprint_collapse = false`). - `ts` — optional RFC3339-UTC ordering key (used to interleave with spt's own injected-context entries). Unknown fields are ignored; a line that isn't a valid record is **dropped with a counted reason** (never silently). `spt adapter digest-proof` shows you exactly what dropped and why. Presentation (window depth, arg truncation, sprint collapse) is spt-core's, defaulted by your `[digest]` and consumer-overridable; extraction is yours. ## `[strings]` — adapter string values (+ profiles) An adapter-authored key/value tree any process on the node reads by dot-path with `spt adapter get-string ` — e.g. a harness hook fetching per-profile `additionalContext`, so one hook script serves every profile and only the data differs. **Strings are data only** — spt-core never executes a string (command templates live in the typed sections, never here). Node-local; not cross-node synced. ```toml [strings] greeting = "hello" # inline literal skills.whoami = { file = "whoami.md" } # file pointer → resolved to the file's contents ``` **Two value forms:** - **Inline literal** — `get-string` prints it as-is. - **File pointer** — a value-position table with **exactly one** key, `file`: `{ file = "rel/path" }`. `get-string` resolves it to the file's **contents** (large bodies — skill instructions, hint text — stay out of the manifest). The exactly-one-key rule disambiguates: any other table shape stays an opaque nested strings tree, and `{ file = … }` is **reserved** as the pointer form (it can't double as inline data). **File-pointer rules (since v0.7.0):** - Files live in the adapter's per-adapter aux dir **`adapters//strings/`** (sibling of `profiles/`); the path is **relative to that dir and must stay inside it** — `..` traversal and absolute paths are refused at registration (`ADAPTER_ADD_FAIL: invalid [strings] file pointer: pointer … must be a relative path inside the strings/ dir (no absolute paths, no `..` traversal)` — manifest-first, so the whole add registers nothing). - **Validated at registration** (fail-fast on an escaping/missing pointer), **read lazily** at `get-string` so live file edits reflect without re-register. A missing/unreadable file at read time **skip-diagnoses** — a diagnostic plus "not set", never a silent drop or hard error (mirrors `[digest]`). - On `spt adapter add`, the adapter dir is **copied** into the registry (`adapters//{manifest.toml, record.toml, strings/…}`). **Profiles + update-safety:** strings resolve through the same **leaf-replace** profile overlay as the rest of the manifest — a shipped or local profile may override base strings, and `get-string ` returns the merged view. A **local** profile's own file pointers resolve against the **user-owned local-profile dir**, not the adapter-shipped `strings/` (which adapter updates overwrite) — so a local override survives updates (or a local profile may just inline a literal). `set-string` edits a **local** profile's `[strings]` only, never adapter-shipped files. ## `[update]` — adapter self-update How spt-core updates (and first installs — install is the first update) this adapter: ```toml [update] avenue = "delegated" # "delegated" | "file_pull" | "gh_release" command = "my-harness plugin update spt" # delegated: the updater to run self_verifies = true # delegated: attests the updater verifies its content uninstall = "my-harness plugin uninstall spt" # optional inverse, run by `spt adapter remove` message = "Run `/reload-plugins` in any ongoing sessions." # optional; shown on apply ``` | Avenue | Required fields | Meaning | |---|---|---| | `delegated` | `command` | spt-core delegates to the harness's own updater. Set `self_verifies = true` to attest that updater verifies what it installs — an unattested delegated update is skipped as unverifiable | | `file_pull` | `repo`, `signing_key` | spt-core pulls files from `repo` (optionally filtered by `path_regex`) and verifies them against the adapter author's Ed25519 `signing_key` (64 hex chars) before applying | | `gh_release` | `repo` | spt-core ships your updates from your own GitHub releases (since v0.8.0). `asset` (default `adapter.spt`) and `signing_key` are optional | **`message`** (optional, any avenue) — a plain human notice `spt adapter update` prints to stdout, markdown-rendered, **only when a new version is actually applied** (never on a no-op). Printed after the update completes; multi-line supported. No `{key}` substitution. Use it to tell the operator what to do after updating — e.g. `"Run \`/reload-plugins\` in any ongoing sessions."` for spt-claude-code. With `file_pull`, **you** sign your releases with your own key; spt-core's release keys never extend to adapter content. ### `gh_release` — ship updates from your GitHub releases (since v0.8.0) The simplest avenue to publish for: distribute exactly as you do for `spt adapter add --release`, and your registered adapter stays current. ```toml [update] avenue = "gh_release" repo = "your-org/your-adapter" # required: whose releases ship updates asset = "adapter.spt" # optional: the release asset to fetch (default adapter.spt) signing_key = "deadbeef…" # optional Ed25519 (64 hex): enables fail-closed verify ``` `spt adapter update [name]` (no name sweeps every registered `gh_release` adapter; a name updates just that one) compares your repo's latest release version against the installed one and, when newer, fetches the release `.spt` archive — the same archive `spt adapter add --release` installs — then re-extracts and re-registers it. `repo` is the only required field. **Trust is opt-in signing, fail-closed.** Declare no `signing_key` and the fetched `.spt` is trusted on HTTPS + GitHub, exactly like first acquisition. Declare a `signing_key` and the fetched `.spt` is verified against a **detached signature** you publish as a sibling release asset named `.sig` — a lowercase-hex Ed25519 signature over the raw archive bytes. Verification runs after the archive is fetched and before it is extracted, against the key in the **installed** manifest (so a new release must verify against the key already on the node). A bad or missing signature refuses the update and the fetched bytes are discarded, never extracted. You sign your own releases with your own key; spt-core's release keys never extend to adapter content. ### `[update.post]` — the composite post-step (since v0.16.0) An optional, avenue-agnostic second step spt-core runs **after** the primary avenue resolves — one lever pulls your `.spt` **and** runs your in-harness reconcile (e.g. a plugin updater): ```toml [update.post] command = "{adapter_dir}/reconcile --sync-plugin" # required; {key} substitution + program-token # resolution against the install dir self_verifies = true # attestation, mirrors the delegated avenue ``` **When it runs.** On every `spt adapter update` of this adapter, **and on `spt adapter add`** (all three sources — install is the first update; since v0.19.0): an eager-extract acquisition (`--release` / `gh_release`) runs it right after registration; a `delegated` acquisition runs it only once the acquisition command succeeded. The one exception is a `file_pull` add with no payload yet (`ADAPTER_INSTALL_PENDING`) — nothing is installed, so no post-step until the payload lands via the update engine. It runs **unconditionally** on updates — even a no-op version check — so make the step idempotent and let its own check decide what to do. **Execution model — foreground, bounded, no background leg.** The step runs as a child of the `spt adapter add`/`update` process, cwd = the adapter's install dir, with a **120-second timeout** (a hung step is killed and counts as failed). spt-core never backgrounds it and never detaches it: when the CLI returns, the post-step has finished (or failed). If your step spawns and detaches its own child, spt-core cannot see that child or its errors — keep real work in the foreground and finish within the bound. **stdin seam.** One JSON line (additive keys — ignore unknown): ```json {"adapter_applied": true, "adapter_name": "spt", "profile_name": null, "version": "0.21.0", "previous_version": "0.20.0", "adapter_dir": "…"} ``` **stdout arbitrates the post-update notice** (exit code is orthogonal): non-empty custom text **supersedes** the static `[update].message` (markdown-rendered); the reserved sentinel `!!update-message!!` fires the static message; empty prints nothing. **Failure contract — how it surfaces.** A nonzero exit, spawn failure, or timeout prints `ADAPTER_UPDATE_POST_FAIL:: …` **with your step's stderr detail, on the CLI's stderr**, and the CLI **exits nonzero**. The committed pull/registration is never rolled back (failure-isolated), and — deliberately — the static `[update].message` still fires when the adapter applied: a post-step failure never swallows the adapter's own notice. **Verify-then-notify (recommended).** Because the static message prints even when the post-step failed, a static message that promises success ("finishing in the background…") can read as a happy install over a failed one to an operator watching only stdout. Instead: keep the static `[update].message` modest (or omit it), have the post-step **verify its own work** and print a custom success notice on stdout only when verified, exit nonzero when not — and have whatever invokes `spt adapter add`/`update` check the **exit code** and surface **stderr**. That combination makes a fresh-install failure loud end to end. ## Shell adapters (`kind = "shell"`) A shell adapter provides a **driven surface** (notifier, robot, sensor) instead of hosting agents: same file, different body — the `[shell]` section is required for (and exclusive to) `kind = "shell"`. See [Shells: getting started](../shells/getting-started.md) for a worked, shipping example; the field reference: ```toml [shell] # Broker-launched; opaque template. Substitution keys: {id}, {adapter_name}, # {link_token}, {adapter_dir} (since v0.44.0), and {perch_dir} (the instance's # perch dir — required in practice for a shell that receives files; see the # frame contract). The program token resolves against the adapter's install # dir before PATH (since v0.44.0) — a shipped binary launches by bare name. spawn = "my-shell --link {link_token} --root {perch_dir}" ephemeral = false # true -> no offline perch, no history retention broadcast = "subnet" # "subnet" | "same-node" | "none" (discovery scope) command_receipt = "stdin" # "http" | "stdin" | "relay" (how commands arrive) pre_close = "park-and-save" # optional instruction sent on link-break close_timeout_ms = 3000 # graceful-termination window persistent = true # auto-online whenever the owner endpoint is online; across a node restart a boot sweep restores it, and an owner that comes online after that sweep restores it on that transition (owner online + launch predates boot; an instance with no launch stamp is left down) wake_command = "my-waker --link {link_token}" # wake-watcher, run while offline AND eligible — an offline instance sitting on a same-boot corpse arms no watcher and waits for relink. Exit code 86 = wake. Program token + {adapter_dir} resolve like spawn (since v0.44.0); {perch_dir} never fills here can_shutdown = false # may the shell fire `api owner-shutdown`? require_approval = "none" # "none" | "remembered" | "always" (per-spawn gate) max_instances_per_owner = 4 # optional cap (online + offline both count) over_cap = "reject" # "reject" | "approve" at the cap [shell.capabilities] # the agent->shell command vocabulary (durable) notify = { args = ["title", "body"] } clear = {} # A capability may carry its OWN approval gate (independent of the per-spawn # gate), with an optional class_key scoping the grant finer than the verb: [shell.capabilities.attach] args = ["busid"] require_approval = "remembered" # "none" | "remembered" | "always" (per-act gate) class_key = "hid" # a remembered hid grant never authorizes another class [shell.sensory] # the shell->agent sensory vocabulary (live-only) types = ["event"] [shell.drive] # the owner->shell continuous control channel types = ["stick"] # latest-wins, ephemeral, never spooled (real-time input) [shell.tunnel] # an opaque reliable-ordered byte stream pair (on-LAN) enable = true protocol = "usbip-urb" # opaque label; the taxonomy never interprets the bytes ``` The capability, sensory, and drive vocabularies live in the manifest — spt-core resolves them by adapter name, validates against them, and rejects anything outside the declared vocabulary. The shell binary binds with `spt api … bind-shell --link ` (the link token *is* the credential), pushes sensory payloads with `spt api … emit`, and takes drive frames with `spt api … drive-poll`. Channel contracts differ — see [Shells: four channels](../shells/overview.md): commands are **durable** (spooled, replayed); **drive** is **ephemeral** (latest-wins, dropped if offline); **sensory** is **live-only**; the **tunnel** carries **opaque bytes** the taxonomy never reinterprets (not enveloped, not framed, not spooled — the link lifecycle closes it). The tunnel is reliable- ordered ⇒ congestion is lag never loss ⇒ **on-LAN only**. Per-capability `require_approval` reuses the same grant store as the per-spawn gate; `class_key` narrows a grant to `(owner × verb × class × node)`. Shell ownership is **owner-type-agnostic** — a Gateway (or any non-shell endpoint) owns and drives a shell identically to an agent; exclusivity keys on the owner's endpoint id, never its type. ## Cross-field rules (`spt adapter add` enforces these) The schema validates structure; registration additionally enforces: - `adapter.name` and `adapter.version` must be non-empty. - `kind = "shell"` **requires** a `[shell]` section, which is **exclusive to** shell adapters (a `kind = "harness"` adapter omits it). - `[history] strategy = "fetcher"` requires `fetcher`; `locate_normalize` requires both `locate_template` and `normalize_command`. - `[digest]` requires a non-empty `extractor`. Under `strategy = "locate_normalize"` (the default) it **also** requires a resolvable source: either its own `source` or a `[history] locate_template` to fall back to — absent both, registration rejects (*"[digest] needs `source` (own-source) or a [history] `locate_template`"*). Under `strategy = "fetcher"` no `source` is needed (the extractor locates the transcript itself). The JSON schema alone accepts a bare `extractor`, so this only surfaces at `spt adapter add`. - `[env.*] direction = "inject"` requires a `value`. - `[update] avenue = "delegated"` requires `command`; `file_pull` requires `repo` **and** `signing_key`; `gh_release` requires `repo` (`asset` and `signing_key` optional). A violation is a one-line error naming the field — fix and re-add. ===== /harness-contract/api.md ===== # The `spt api` surface The imperative half of the harness contract: the inbound entry points a harness's hooks (and a shell's binary) fire to keep spt-core's on-disk state in sync. This page is the complete command reference plus the two startup flows that tie it together. Three rules apply to `api` calls: 1. **`--adapter ` is an optional override** (since v0.9.0). For a harness-hosted session you normally **omit it**: `listen` resolves the owning adapter/profile at bind, from the seed's parent pid → the harness exe basename → the adapter(s) that declare it in [`[adapter] host_binaries`](manifest.md) → the active-profile pointer (set by [`spt adapter use`](../cli/reference.md)) or, with no pointer, the freshest-registered hosting adapter. Pass `--adapter` only to **pin** a specific adapter/profile (adapter dev, or explicit disambiguation). The profile qualifier `:` is **runtime selection** — retained onto the perch record, and the daemon resolves the profile **overlay** when it later spawns the session's lifecycle roles. So a `live` profile whose `[session.psyche_init]` is in the resolved manifest is a **LiveAgent** (spt-core drives the Psyche as a bounded per-event turn); a profile without it is a **ReadyAgent**. Ready-vs-live is a profile choice, not a separate "go-live" verb. 2. **Prove association.** Commands that touch an existing perch take `--session-id ` (matching the perch's record) or a capability `--token`; shell commands authenticate with `--link ` (the link token minted at launch *is* the credential — no token, no access). This includes the read-side drain: an unauthenticated `api poll` is **refused** (exit 1, nothing printed) — see [`api poll`](#api-poll-id---include-deferred---link-token). 3. **Status rides stderr; stdout is payload; the exit code is authoritative.** Action-command status lines (`BOUND: token=…`, `READY:`, `SENT:`, `QUEUED:`, `WORKER_STARTED:…`, failure tags) print to **stderr** — always, piped or not (only the *color* is tty-gated; a redirect gets the bare tag unchanged). **stdout** is reserved for machine payloads: `--json` output, polled message frames, and documented payload emissions. A program shelling out must therefore capture **stderr** to read a status tag (`2>&1`, or capture the streams separately) — discarding stderr (`2>$null` / `2>/dev/null`) discards the status line by design — and should treat the **exit code** as the success contract: `0` = the action took effect, non-zero = it did not. ```text spt api [--adapter ] [--manifest ] … ``` `--manifest` points at the adapter's manifest for the commands that need it (e.g. `capability`). ## The two startup flows **Harness-hosted** — the harness owns the process; spt-core is invoked from inside it (hooks): ```text SessionStart hook ──► api seed --pid {parent_pid} --session-id {session_id} session's listener ──► api listen (consumes the seed, holds the perch) ``` `seed` records an ephemeral hand-off keyed by parent pid; `listen` consumes it, registers the perch, drains backlog, and blocks relaying events into the session. **spt-hosted** — spt-core spawns the session itself from the manifest's `[session.self]` template, in its own terminal layer: ```text spt-core spawns the template ──► session comes up session (or its wrapper) ──► api bind --set-session-id ``` No seed file is involved; `bind` attaches the live session to its perch post-spawn. **Going ONLINE (the presence badge).** The `endpoint list` ONLINE badge means one thing: a live process is **holding the relay** — an `api listen ` that consumed a seed and is blocked relaying events. Binding alone does not light it. A headless adapter binary (a gateway or any `[session.self]` host that wants ONLINE presence and a live event stream) uses the same two-step the harness-hosted flow does, against its **own** process: ```text api seed --pid --session-id (hand-off keyed to itself) api listen (consume, hold the perch, stay ONLINE) ``` Drop the listener and the endpoint decays to Dormant/Offline as its last-seen ages out. ## Session lifecycle ### `api seed --pid --session-id ` Harness-hosted startup, step 1: record an ephemeral seed keyed by the parent process id. Fired by the harness's session-start hook. Prints `SEEDED:`. **Seed lifetime.** The seed lives **in the daemon's memory only** — no file — and survives until exactly one of: a successful `listen` bind consumes it, a newer `seed` for the same pid overwrites it, or the daemon process restarts (which drops the whole map). Nothing re-fires it until the harness's **next** SessionStart. So an adapter must not rely on the seed for a session that goes live late (hours after SessionStart) or after a daemon restart — that is what `listen --session-id` (below) is for. ### `api listen [--once] [--parent-pid ] [--subnet ] [--session-id ]` Harness-hosted startup, step 2: consume the seed, register/hold the perch, drain spooled backlog (the same spool [`api poll` drains — see there](#api-poll-id---include-deferred---link-token)), then block relaying messages. `--once` runs a single drain+receive cycle (testing). `--subnet` names the anchor subnet when this creates a brand-new endpoint on a multi-subnet node (the anchor is assigned deterministically at creation). **Recoverable refusals do not consume the seed.** The seed is consumed by a **successful bind** — or by a refusal that proves the seed itself dead (see spend-vs-restore below). A recoverable refusal that never bound — `ANCHOR_REFUSED` on a multi-subnet node without `--subnet`, `ADAPTER_UNRESOLVED`, a live-perch conflict — leaves the seed consumable, so the corrected retry on the same pid binds instead of dead-ending on `NO_SEED`. (Effect before irreversible consume: the destructive step follows the successful effect, never a recoverable refusal.) **`--session-id ` — binding when the seed is gone.** A session that goes live late, or after a daemon restart, finds no live seed; with `--session-id` the listener binds directly from the given harness session id (loud `SID_BIND:` marker). The fallback fires **only** on `NO_SEED` — every other refusal keeps its own diagnostic — and carries the same identity/auth gates as a seeded bind (live-conflict refusal, dead-anchor refusal on the parent pid). Without a live seed **and** without `--session-id`, `listen` refuses with `NO_SEED`. > **Provenance caveat — same gates, weaker provenance.** A seed is a > consume-once capability minted by the harness for exactly one anchor pid; > `--session-id` is a **bearer string** — any local caller who knows a live > session id can present it and revive that perch. Treat session ids as > secrets: never log or publish them. (The local surface already trusts local > callers — `--parent-pid` is an override — so this is a contract > qualification for adapter authors, not a sandbox.) **Refusals and the seed, spend vs restore.** A refusal that proves the seed itself dead — a stale (dead-pid) anchor, an empty session id — **spends** it: that seed can never retry as itself, and restoring it would re-arm a dead-keyed seed for a recycled pid to steal. Recoverable refusals (the `ANCHOR_REFUSED` retry case above, a live-perch conflict) restore it. ### `api bind [--set-session-id ]` spt-hosted startup: bind a freshly spawned session to its perch, recording the session id discovered post-spawn. Identity precedes sessions — rebinding never mints a new endpoint. **Auth is intrinsic — `bind` takes no association proof.** It is an *establishing* call (the exception to Rule 2), not a touch-an-existing-perch call: spt-core spawned this session into its own broker-held terminal layer, so that parentage *is* the credential. The only guard is ownership — an existing *live* perch under a different session id is refused (you can only bind your own). The broker injects **no** capability token into the spawned environment, so there is nothing to echo back and no `[env.*]` entry to author for one; the endpoint id arrives via the `{id}` fill in `[session.self]`, and that is the only identity spt-core plants. `--set-session-id` *records* the discovered id into the perch — it is not a proof. `bind` prints `BOUND: token=`. The token is a freshly minted local credential the session *may* retain for later authenticated calls, but it is optional: every subsequent mutating call can instead prove association the Rule 2 way, passing `--session-id ` for spt-core to match against the record this bind wrote. Successful bind and `api boundary` resolve the endpoint's recorded adapter/profile before resurfacing context. An adapter declaring `[io] compliance = true` receives shell awareness through the now-signal `SHELLS` category, not the deprecated session-start `spt-shells` message. Noncompliant adapters and missing or unresolved manifests retain the legacy context. Resolution is best-effort and does not make a successful bind or session rotation fail. **A perch is claimed to the session only after this call SUCCEEDS.** `bind` can refuse — a live-ownership conflict, or `ANCHOR_REFUSED` when the endpoint has no record yet and the node holds more than one subnet, since an endpoint's anchor subnet is its default scope and spt-core will not guess one. An adapter must therefore treat a session brief that asserts perch ownership as conditional on the bind's exit, never on having *attempted* it: **on a refused bind, emit the no-perch shape and carry the refusal into it** so the agent learns it is unreachable and why. Telling a session it "already owns a live perch" after a bind that failed produces an agent that reports itself reachable, does not listen, and cannot be sent to — while every message addressed to it spools against an endpoint that is in no roster (releases#204). The refusal text is the diagnosis; putting it only in an adapter-side log leaves the one party who could act on it — the session itself — the only party who never sees it. ### `api boundary --to-session-id --session-id ` The session was reset (context cleared or compacted) and continues under a new session id: rebind the perch, preserving the endpoint's identity, spool, and history across the boundary. **The rotation catch-22 — read this before wiring the hook.** Rule 2 applies to `boundary` like every mutating verb, but here the "matching" `--session-id` is the sid on the perch record — i.e. the session being **departed**, not the one you are rotating to. `--to-session-id` is the *payload*, never the *proof*. By the time your rotation hook fires, the old session's context (its env, its per-session files) is typically gone and the hook payload carries only the new sid — so a hook that only knows "the current sid" cannot authenticate this one verb. Two hard requirements for adapter authors: 1. **Persist the current session id at every SessionStart** in adapter-owned state keyed by the *endpoint id* (reference pattern: `{adapter_dir}/state/session/.sid`, single line, rewritten each SessionStart). At clear/compact, read it back as the **prior** sid and pass it as `--session-id`. Do **not** persist it in a per-session env file — that file dies with the session, which is the catch-22 itself. 2. **Never skip or swallow this call.** A rotation that is silently skipped (unresolvable endpoint id) or silently refused (`AUTH_REFUSED` on stderr, exit 1) leaves the perch pinned to the dead sid — after which **every** id-scoped call from the live session refuses, including a boundary retry, and the endpoint strands with zero message delivery until a full relaunch. Surface the id-resolution failure and the refusal reason loudly in your hook output. Resolve the endpoint id from your stable identity (`$SPT_ENDPOINT_ID`), not by looking up the new sid (it is not registered yet — the same catch-22). A perch stranded by a *crashed* session (recorded pid dead) self-heals on the next call via the dead-owner re-pin; a **live** session's rotation always requires the prior-sid (or `--token`) proof. The long-term design (ADR-0032) adds an OS-verified ancestry proof keyed on the endpoint's stable `parent_pid` anchor, which will make the persisted-sid pattern optional; until then it is required. ### `api psyche-download [--session-id ]` Pull the agent's **resume context** to stdout, to inject as the session's additional context at every session start — after a `/clear`, a `/compact`, or a fresh resume. Emits the durable two-tier mind — the agent's role, its cross-project live context, and the current project's context — **plus** any commune/signoff drop that has been written but **not yet synthesized** into that durable context (as `` / `` slices), so a just-written delta is never invisible on resume. The project is resolved from the perch's recorded cwd. Read-only — it never writes the mind store. Prints `NO-CONTEXT:` on stderr (exit 0) when nothing is stored yet, the adapter's fresh-init signal. > The *read-back-in* half of the commune/signoff file-drops (the *write* > side): the agent drops its delta, spt-core synthesizes it into the durable > mind, and `psyche-download` is how the next session reads that mind back in. > Call it wherever your harness starts a session, and inject its stdout — that > is how a resumed session keeps its accumulated context. **Call it from whatever your start path actually is — the verb is not hook-shaped.** A hook-driven harness fires it from `SessionStart` alongside `seed`/`listen`. A harness with no hook surface — an spt-hosted one whose own extension owns bind and delivery — has no `SessionStart` to hang it on and must call it **itself, immediately after `api bind`**, injecting stdout as the session's opening context. A harness-hosted **go-live** needs the same explicit call: promoting an already-running session to a live agent does not replay `SessionStart`, so nothing pulls the mind unless the go-live path does. Skipping it is silent — every other surface works, messages deliver, the mind is written faithfully by the Psyche, and the agent simply resumes knowing nothing. Nothing in spt-core can detect the omission for you: the pull is the adapter's, always. **Authentication — prefer `--token`.** Like every perch-scoped verb this needs association proof: `--token ` or `--session-id `; without one it exits non-zero with `AUTH_REFUSED:`. **Use the bind token.** The two forms are not equivalent here: `--session-id` is *also* a lifecycle lever — against a perch whose recorded owner is gone, a mismatched sid triggers the dead-owner rescue and **re-pins the perch** to the sid you presented (loudly, as `SESSION_REPIN:` on stderr, and refused outright if that sid already owns another perch or is a Psyche custody sid). A read-only context pull has no business writing lifecycle state, so the token keeps it inert. If you do pass a sid, pass only the **real, already-bound** one — a speculative or placeholder value can move a recoverable perch onto a session that does not exist. **Keep stderr out of the injected context.** This verb writes the mind to *stdout* and its signals to *stderr*. A runner that folds the two together will inject `NO-CONTEXT:`, a `SESSION_REPIN` line, or an auth refusal into the model's context **as if it were the agent's mind**. Read stdout alone for the injection; surface stderr through your logs — never swallow it, and never inject it. `NO-CONTEXT:` with exit 0 means inject nothing: it is the fresh-init signal, not an error, and a failed pull should log and let the session start rather than block it. ### `api session-end [--erase]` Soft teardown: the session is over; the perch's spool and history are preserved (that's what makes the next `poll`/`listen` drain work). `--erase` hard-wipes instead — the exception, not the rule. ### `api shutdown ` Graceful live-agent signoff: runs the final echo-commune **before** teardown (the context delta is never lost to ordering), then soft-stops. This is what the `spt endpoint shutdown` lifecycle path calls. **A boundary leaves an echo owed.** The session that just ended is the one with an unsummarized delta in it, so the boundary records *that* session id and arms the echo gate; the next pulse summarizes the departing session rather than the empty one the harness just opened. The key is captured under the same lock as the rotation, because by the time anything downstream runs, the pin has already moved. It is best-effort in both halves and **never fails the boundary**. Your harness has already rotated by the time you tell us; turning an echo problem into a refusal would only desync our record from the reality it exists to describe. ## Activity and presence ### `api state [--no-gate] [--payload-stdin | --payload-file ] [--mid]` Report the session's activity state. Activity/idleness comes from these explicit reports — **never** from terminal quiescence, which lies. Reporting `idle` also arms the echo gate (below) unless `--no-gate` — **the arming is unconditional; the *fire* waits for age.** **The turn's text rides this call, optionally.** `busy` carries the `USER_INPUT` payload and `idle` carries the `AGENT_OUTPUT` end-of-turn payload into [the IO funnel](../shells/frames.md#io--the-sessions-io-events-durable): ```text spt api state busy --payload-stdin < the-user-input spt api state idle --payload-file /path/to/turn-output ``` - **The payload is optional and its absence is the back-compat arm.** With no payload the verb behaves exactly as it always has and emits nothing, so an already-shipped adapter keeps working untouched. - **Stdin or a file, never an inline argument** — payloads are 16 KB-class and an inline arg hits the Windows command-length limit. `--payload-stdin` is explicit rather than sniffed because this verb fires on every hook with stdin inherited from the harness, and a read that sniffed for one would block forever and wedge the hook. - **Both sources at once is a named refusal**, `STATE_PAYLOAD_AMBIGUOUS`. - **One event per payload-carrying call**, not per busy/idle *transition*, and core does not deduplicate — report every payload span **exactly once across the turn**; that discipline is the adapter's, because knowing that two payloads are the same span means modelling how your harness assembles a turn. The idle-edge stamp `activity` frames carry is untouched by any of this. - Parsing this payload for [shortform](../shells/frames.md#shortform-sending-from-inside-a-turn) happens only when the manifest declares [`[io] compliance`](manifest.md#io--io-funnel-compliance). Parsing runs over the **full** payload you reported; the 16 KB cap bounds only the frame body that is emitted, so a marker past the cap is still read. A non-mid `busy` payload is a **provenance claim that the seated user typed the text**, just like `now-signal --user-input`. Never put peer-delivered text there. For path-bearing reports, core may register the quoted files on the live authenticated remote controller's node for the receiving endpoint. See [the file helper](../serving/attachments.md#the-file_access_helper-signal). Core's exclusion of delivery bytes it physically wrote is a backstop, not permission for adapters to forward peer text as user input. **`--mid` reports a MID-TURN SPAN of agent output.** The agent is still working, so the span rides the `busy` arm — and it is still an `AGENT_OUTPUT` event: ```text spt api state busy --payload-stdin --mid < the-span-just-produced ``` - The event carries `mid="1"` on its [`io` frame](../shells/frames.md#io--the-sessions-io-events-durable) and `"mid": true` from [`api io-events`](#api-io-events-id---session-sid----after-seq---limit-n---json). **Present-only**: an event without it is the turn's close, which is what every `AGENT_OUTPUT` meant before this flag existed. - **`--mid` at `idle` is a named refusal**, `STATE_MID_ON_IDLE` — `idle` reports the turn's close, so a mid-turn span there is a contradiction. **`--mid` with no payload** is `STATE_MID_NO_PAYLOAD`. - Spans are parsed for shortform like any other ingest. One narrowing: a **bare trailing `;;`** in a span mints nothing and is refused as `SEAL_BARE_MIDTURN`, because it seals through end of output and a span has not reached it. Pairs mint normally. See [the seal grammar](../shells/frames.md#what-happens-after-you-type-it). ### `api echo-gate ` Manage the echo-gate sentinel directly. The gate marks "a summarization may be needed when this session ends without a graceful signoff" — `state idle` sets it as a side effect; a graceful signoff clears it. **The gate has two arms, and they fire on different rules.** | arm | armed by | fires | | --- | --- | --- | | **edge** | an attention change — detach, attention shift, `spt suspend` — or `echo-gate set` | **immediately**, at the next pulse | | **work** | every `api state idle`, i.e. every turn end | only once that report is **15 minutes old** | The edge arm is ungated because its whole value is timeliness: it fires when attention is leaving, and an echo that arrives after the agent is gone is an echo that did not happen. The work arm is age-gated because a turn end is not by itself news — an agent reports dozens an hour, and summarizing each one would spend a model call to say almost nothing. Fifteen minutes of accumulated work is the unit that has something in it. They are **two sentinel files**, not one file with a flag, so an idle report can never overwrite a pending attention-change fire and quietly turn an urgent echo into a delayed one. `set` arms the **edge** arm — an explicit set means *now*, and routing it to the age-gated arm would silently mean *within fifteen minutes*. `clear` clears **both**: you asked for no pending echo, so no arm is left standing. The window is a constant, not a knob. If you want it configurable, that is its own request rather than a flag added here. ### `api presence ` Report user/agent presence at this endpoint (feeds most-recently-active resolution across the subnet). ### `api driven-by ` Print which node (if any) is currently remote-driving this endpoint, so a session can tell whether input is local or remote. ## Situational awareness ### `api now-signal --session [--user-input ] [--agent-output ] [--spec-manifest | --spec-file ]` The one answer to *what changed that I should know about* — the verb an adapter injects at every turn boundary. It prints per-category XML under a single `` root, and **nothing at all** when nothing is new: not an empty root, not a blank tag, so a quiet turn costs zero context. Pass the turn's text so the categories that read it (endpoint mentions, monics) can fire. **It is delta-only, per session.** Each category tracks what this `--session` has already been shown. A new session — a `/clear` is one — is entitled to the picture once, and every later poll is thin. Inject it on every UserPromptSubmit- and PreToolUse-equivalent; that cadence is what it is built for. **`--user-input` is a provenance claim, not a generic text input.** It and the non-mid `api state busy` payload claim words typed by the seated user. Core binds a path-bearing report to the session's live authenticated remote-controller seat and may register quoted absolute or `~`-rooted paths on **that controller's node**, addressed to the receiving endpoint. The [file helper](../serving/attachments.md#the-file_access_helper-signal) normally arrives with the prompt after a short bounded wait; a late answer remains available at a later poll. **Adapters must never submit peer-delivered text through either input.** Core excludes matching delivery bytes it physically wrote, but that is a backstop for its own delivery path, not permission to forward peer text or proof that arbitrary text was human-authored. `--spec-manifest` takes the tuning from the manifest's [`[io.now_signal]`](manifest.md#ionow_signal--standing-now-signal-tuning); `--spec-file` takes the same shape as JSON composed per poll, and wins over `--spec-manifest` when both are passed. A missing, unreadable or malformed spec degrades to the default picture — **never a refusal**. The category vocabulary and the delta rules are in [the frame contract](../shells/frames.md#the-now-signal-one-funnel-for-what-changed). ### `api io-events {--session-id | --after } [--limit ] [--json]` *(authenticated)* Read the endpoint's **IO events** — `USER_INPUT`, `AGENT_OUTPUT`, `MSG_IN`, `MSG_OUT`, `COMMUNE`, `COMMUNE_FAIL` — as a delta-cursored poll. The same poll also serves the endpoint's **session boundaries** — `boot`, `clear`, `compact` — which ride this cursor rather than a second one. They are a [frame class of their own](../shells/frames.md#boundary--the-endpoints-session-edges-durable) on the push side; here they arrive as ordinary events with an **empty payload**, so switch on `kind` and do not read the empty body as a missing one. A kind in neither vocabulary is ignored rather than refused, so a newer core's tokens cannot break an older adapter's hook. This is how an adapter builds behaviour on top of what a session did (wake-marker-class constructs over commune and IO events are the motivating case) without polling a digest and diffing it. **Give it a cursor; one of the two is required.** - `--session-id ` keeps a per-session cursor, the way [`now-signal`](#api-now-signal-id---session-sid---user-input-text---agent-output-text---spec-manifest----spec-file-path) keeps per-session seen-sets. This is the shape for a turn-boundary hook, which has a session id and no memory of its own. **It is the same flag that authenticates the call** — the harness session is one identity, so it is one flag. - `--after ` answers with events newer than a seq you carry yourself, the way [`endpoint digest --after`](../cli/reference.md) does. It writes no session cursor and wins over the session cursor when both are passed. This is the mode for a `--token` caller, which has no session identity. A cursor above the log's head returns no events and the actual head as `cursor`, so the caller can resume from that lower value instead of remaining blind. A poll carrying **neither** cursor is refused by name (`IO_EVENTS_NO_CURSOR`, exit 2) rather than answered with an empty poll — a cursorless poll could only replay the log, and an empty answer would read as *nothing happened*. **A new session's first poll returns nothing and seeds its cursor silently.** That is deliberate: history is [`endpoint digest`](../cli/reference.md)'s job, and replaying a backlog into a turn-boundary hook is the cost the delta discipline exists to avoid. Poll again after the next turn and you get that turn's events. On the first append to a log damaged by the former sequence-reset bug, core repairs its retained rows under the log lock: file order and payloads are kept, and sequences are reassigned above the old global maximum. A session carrying an old cursor therefore sees retained history **once**, bounded by the log's 1250-row retention ceiling. This is not a new emission: adapters acting on old `COMMUNE` content must still reject frames older than their current session. **`--limit` says when it capped.** The answer carries `more`, and the rows it deferred are the next poll's first rows — a bounded poll never silently reads as a complete one. While `more` is true, `cursor` is the last event handed over; otherwise it is the log snapshot's true head, including ignored kinds. **`--json` is the adapter shape and is emitted even when empty:** ```json { "cursor": 412, "seeded": false, "more": false, "events": [ { "seq": 412, "at_ms": 1787960000000, "kind": "AGENT_OUTPUT", "payload": "…", "truncated": true } ] } ``` `payload` is capped at the same 16 KiB the shell IO frame uses and is complete unless `truncated` is set; a truncated remainder is not recoverable through this verb today. `digest_seq` is **reserved — nothing emits this today**: the shape names a digest pointer slot for a future emitter, so keep it optional and never wait for it. `seq` is **this log's own cursor** and `digest_seq` is **the digest's**; they are unrelated numbers, which is why they have different names. **Authentication is required**, as it is for [`api poll`](#api-poll-id---include-deferred---link-token) and for the same reason: this returns the session's **verbatim** user input and agent output. Prove association with `--session-id ` — the sid you already pass to `api state`, which doubles as the cursor key — or a capability `--token` plus `--after`. (`now-signal` is ungated because it renders derived summaries and never a raw payload; the gate follows the content, not the verb family.) A kind this binary does not know is **ignored, not refused**, so a newer core on the other side of an event cannot break your hook. `TOOL_USE` is named in the taxonomy but **nothing emits it**, so no poll will ever carry one. ### `api hint --session ` *(message on stdin)* The keyword-hint verb, unchanged — at most one matched hint line, once per session. It is now a **thin alias** over the `HINTS` category and shares its seen-set, so an adapter injecting both `hint` and `now-signal` is injecting the same thing twice — inject one. Select the manifest through a group-level option **before** `hint`: `spt api --manifest hint --session `, or `spt api --adapter hint --session ` for a registered adapter. If neither route resolves a manifest, the command refuses. ## Messages ### `api poll [--include-deferred] [--link ]` Drain delivered messages over the hook channel (the pull-based path for harnesses whose hooks can't inject). Deferred-flagged rows are excluded unless `--include-deferred`. With `--link` this is the shell-flavored drain: the link token authenticates, and the rows are the shell's stamped command/text/file frames. `poll` and `listen` drain the same per-perch spool — a message either one delivers is marked taken and is never re-served by the other, so a harness running both sees each message exactly once, on whichever leg reaches it first. **Authentication is required** (rule 2 above): the drain must prove association with `--session-id ` (the perch's recorded session) or a capability `--token` (`--link ` for the shell flavor). An unauthenticated `poll` is refused with **exit 1 and no output** — messages are addressed to the endpoint's occupant, not to whoever asks. ### `api history-log ` Append normalized history (body on stdin) to the endpoint's native history store — the push half of `[history] strategy = "native"`. ## Workers Nested, short-lived agents under a parent endpoint. A worker is process-local machinery — it authenticates with its parent's session id and carries no capability token of its own. ### `api worker-start [--agent-id ] [--agent-type ]` Create a nested worker perch under `parent`. The worker id is **minted by spt-core**, not supplied by the caller: `{parent}-w{N}` with a persistent, per-parent counter. The caller does **not** pass an id (a stray positional id is rejected). Output channels follow the api status-line discipline: - **stdout** carries the bare minted id and nothing else (the machine-readable result — empty on any refusal). Read this to learn the worker's id. - **stderr** carries the human line `WORKER_STARTED:{parent}-w{N} under {parent}`. `--agent-id` / `--agent-type` are optional: the caller's own agent identifiers, recorded on the worker as **correlation metadata only** — never the perch identity. Authenticates against the **parent** (the parent's session id or token); the worker record stores the parent's current session id as its registration sid. ### `api worker-stop --session-id ` · `api worker-poll --session-id ` Soft-stop (drop the ready marker; info + spool preserved) or drain a worker. Both authenticate **symmetrically by session id** — no token. A presented sid is accepted when it matches **either** the worker's stored registration sid **or** the parent's *current* session id, so a context clear/compact that rotates the parent's sid between start and stop does not lock the worker out. The natural call `worker-stop --session-id ` is therefore correct as-is. ## Shells The driven-surface flavor of the contract. The **link token** minted at launch is the only credential a shell binary ever holds or needs: ### `api bind-shell --link ` The shell binary's first call: resolve the instance **by link token alone** (the spawn template carries only `{link_token}`; the owner is derived from the link) and flip it online. **What it prints.** Everything is a line on **stderr**; stdout stays empty. There is no JSON form — `--json` is a query-shape flag, and this is an action command, so passing it changes nothing here. | Outcome | Line | Exit | |---|---|---| | Bound | `BOUND_SHELL: owner= status=online` | `0` | | Unknown or retired token | `BIND_SHELL_REFUSED: no instance holds this link token` | non-zero | A bound instance whose manifest enables `[shell.tunnel]` adds one more line after the bind line — `SHELL_TUNNEL_OPEN:` when the tunnel came up, or `SHELL_TUNNEL_WARN:: ` when it did not (the bind itself still succeeded; a shell that declares no tunnel prints neither). Parse the `BOUND_SHELL:` line for the outcome, not the tunnel line. The bind also pushes the owner's current [`activity` frame](../shells/frames.md#activity--the-owners-busyidle-state-pushed) to the freshly linked binary, so your first `api drive-poll` can already tell you whether the owner is busy or idle. Its `since` is the owner's **last real transition**, not the moment you linked — re-emitting the current state on a link is not itself a state change. ### `api emit --type --link ` Push a sensory payload (one of the manifest's declared `[shell.sensory]` types) to the owner's **live** session. REST-only by definition: never spooled — if the owner isn't live, it's dropped with a diagnostic. Sensors report the present, not the past. ### `api owner-shutdown --link ` A shell suspends its linked owner directly (e.g. a power-button surface), bypassing agent messaging. Gated by the manifest's `can_shutdown` pre-consent flag — fail-closed; an undeclared shell gets a refusal. The firing shell cascades offline with its siblings, by design. ## Introspection ### `api capability` Print the adapter's declared `hostable_types` (requires `--manifest`). The cheap way to smoke-test that spt-core reads your manifest the way you meant it. ### `spt whoami` — the identity verb *(identity-only since v0.33.0)* The bounded-time "which endpoint am I?" answer for hooks and adapter glue: resolves the calling session to its endpoint (`$OWL_SESSION_ID` / `$SPT_AGENT_ID` / process ancestry) and prints that ONE endpoint's SELF line — id, liveness, description. **The no-derivation bound is the contract**: whoami never enumerates the roster, never derives projects, never runs git, never touches the network — safe to call from deadline-bounded hook paths (the class that previously timed out and black-holed message delivery). Unresolved is a clean answer, not an error stall: `NO_PERCH` on stderr (`--json`: `{"id": null}`), exit 1. `spt whoami --json` emits the committed identity shape `{id, state, ready, alive, unbound, description}` — additive evolution only. The full roster view lives on `spt endpoint list`; `api endpoint-info` is NOT an identity carrier (it derives projects). ## Conventions - **Output is line-oriented and stable**: `SEEDED:`, `READY:`, `SENT:`, `QUEUED:`, error lines as `CODE:detail`. Parse lines, not prose. - **Exit codes**: `0` success; non-zero = refused or failed, with the reason on stderr. - **Commune/signoff are file-drops, not api commands.** An agent writes `-commune.md` / `-signoff.md` into the manifest's watched directory; spt-core's watcher ingests it. There is deliberately no `api commune`. ===== /harness-contract/echo-commune.md ===== # Echo-commune — the I/O contract When a session ends **without** a graceful signoff, its context would be lost. The **echo-commune** recovers it: spt-core runs the adapter's bounded summarizer over the session, captures the brief the summarizer prints, and routes it straight into the session's durable context — the same delta a hand-written [commune](../lifecycle/overview.md) would have carried. This page is the **adapter-facing I/O contract** for that mechanism: the role you declare, the keys spt-core fills, what it does (and does not) feed the summarizer, how the summarizer locates the harness, and where spt-core routes the result. It is the companion to the [`[session.echo_commune]` role](manifest.md#sessionrole--outbound-templates) in the manifest reference. > The echo-commune is spt-core's. The adapter supplies **one command > template** — spt-core owns the spawn, the keys, and the routing of the brief > into the durable tiers. Everything below is the seam between those halves. ## The role `[session.echo_commune]` is one outbound role template. Its fields are the standard role shape: ```toml [session.echo_commune] command = "my-harness run --agent summarize --session {session_id}" recursion_guard_env = "SPT_ECHO_COMMUNE" # set on the child so its own hooks bail env_remove = ["MY_HARNESS_SESSION_ID"] # stripped from the child's env keys = ["id", "session_id"] # the keys this template expects filled ``` | Field | Required | Meaning | |---|---|---| | `command` | yes | Opaque command line with `{key}` placeholders. Model, tools, flags — all inside the string; spt-core never parses it. | | `cwd` | no | Working directory for the child (substitutable). A role `cwd` wins over the endpoint default. | | `recursion_guard_env` | no | Env var name set on the summarizer child so *its* harness hooks bail — no echo-of-an-echo. | | `detach` | no (default `false`) | Spawn detached. | | `env_remove` | no | Env vars stripped from the child's inherited environment. | | `keys` | no | The substitution keys spt-core fills for this role (your declared expectation list). | The child runs **bounded** — a budget caps it, and a non-zero exit files **nothing** (the failure is loud, never a half-written delta). **Declare the budget.** The cap is [`invocation_budget_secs`](manifest.md#sessionrole--outbound-templates) on this role: absent it is 90 seconds, and it is clamped to 300. Declare it on any role that is an LLM turn — spt-core cannot know what your model costs, and a summariser whose real duration straddles the cap is killed by the load of the moment rather than by anything about its work. **A bound kill is not a non-zero exit, and it is not silent.** Being killed at the budget is a third outcome: the child dies *before* printing anything, so there is nothing to route and no partial result to clean up — a brief that was never produced leaves no trace to detect it by. spt-core therefore records the **expectation** before it spawns, and an expectation that no brief ever satisfies surfaces at the agent's next resume as a `COMMUNE_NEVER_INGESTED` warning naming the fire it came from and the bound it died at, stating plainly that the durable context does not include that work and the agent may be resuming stale. The expectation is current-state only: a later successful commune overwrites it and the warning stops. A bound kill also does not count against the same budget as a real fault. A psyche host latches as failed on consecutive **hard** failures; a timeout or bound kill spends its own, softer budget, so a slow-but-healthy host is not latched by load. Any success clears the stamp — **an ingest success included**, not only a turn. ## Keys spt-core fills For an echo-commune spawn spt-core fills its base catalog. Template only the keys you are given; a `{placeholder}` spt-core does not supply for this role fails the spawn with a one-line error naming the missing key. | Key | spt-core fills it with | |---|---| | `{id}` | The endpoint id being summarized. Always filled. | | `{session_id}` | The harness session id — filled when one is known. | | `{node}` | This node's advertised label — filled only when non-empty (a `{node}` reference with no value fails loud rather than resolving an empty token). | | `{subnet}` | The endpoint's anchor-subnet label (`local` when unanchored) — filled only when non-empty. | | `{adapter_dir}` | The adapter's install dir — adapter-static, always available (lets the command point at the adapter's own packed summarizer binary). | | `{adapter_name}` | The adapter's declared `name`. | | `{VAR}` | Any manifest-declared [`[env] direction = "read"`](manifest.md#envvar--env-var-table) var captured at bind — see [Self-locating the harness](#self-locating-the-harness). | This is the **same base catalog** the Psyche and notification roles build on; it deliberately does **not** include `{session_name}` (a `[session.self]` key) or the Psyche-only `{psyche_context_file}` / `{parent_session_id}`. ## History is not fed on stdin spt-core has a stdin channel for the summarizer — but **you must not depend on it carrying the transcript.** The rule, field-proven against the reference Claude Code adapter: - If the manifest declares a [`[history]`](manifest.md#history--transcript-access) strategy that yields records, spt-core normalizes them and pipes them to the summarizer on **stdin**. - With **no `[history]` section**, or a `native` history store that is still empty, there are no records — so **stdin is empty**. This is the field case: the reference adapter's history is native and typically empty at echo time, so the summarizer receives an empty stdin. The load-bearing consequence for an adapter author: **the echo-commune command must self-source the session it summarizes** (locate and read the transcript itself), exactly as a [`[digest]` `fetcher`](manifest.md#digest--session-digest-extractor) extractor does. Do not write a summarizer that reads its transcript from stdin. What spt-core reliably supplies is the **command template with the key catalog filled** (and the child's env — see below); the transcript is the summarizer's to find. ## Self-locating the harness A summarizer that self-sources its transcript needs to find the harness's config/log root. spt-core carries that in through the manifest's **read-env allowlist**, so the value survives the daemon boundary (the echo child runs in the daemon context, where the original launch environment is long gone). ```toml [env.CLAUDE_CONFIG_DIR] direction = "read" value = "~/.claude" # fallback when the launch env didn't set it ``` - Declare each locator var with `direction = "read"`. spt-core captures it **from the launch environment at bind** — an explicit allowlist, never the whole environment, and only when the ambient value is actually present. - The captured value is written onto the perch record, so it is available when the echo (or digest, or Psyche) child spawns later. - At spawn spt-core injects it as a `{VAR}` substitution key. **Resolution order:** the captured ambient value wins (a relocating profile — e.g. a wrapper that sets `CLAUDE_CONFIG_DIR` to a private dir) → else the directive's own `value` fallback (the base harness default, e.g. `~/.claude`) → else the var is **omitted**, so a `{VAR}` reference fails loud rather than resolving a wrong path. A leading `~` expands to the home dir. Reference the captured key in the echo command the same way `[digest]` does: ```toml [session.echo_commune] command = "my-harness-summarize --session {session_id} --config-dir {CLAUDE_CONFIG_DIR}" keys = ["session_id", "CLAUDE_CONFIG_DIR"] ``` ## Where the brief goes spt-core routes the summarizer's output **straight into the durable context tiers** at the moment of the fire, stamped `Source: echo-commune`, and publishes it as a `COMMUNE` I/O event. The brief never becomes a file. Three invariants define the contract: **1. The echo routes; it does not file.** The brief goes from the summarizer's stdout into the two-tier store in one step, through the same routing the drop-file ingest uses. Nothing is written to disk on the way, so there is no window in which the brief sits as a file — for anything else to overwrite, or to be overwritten by. **2. `commune_dir` is the _agent's_ channel, not the echo's.** The directory an adapter declares under `[session] commune_dir` is where **the agent** drops its own hand-written commune — the fixed filename `-commune.md` — which spt-core then ingests and deletes. The echo does not write there. > *spt-core filed its echo brief to that same path until v0.67.x. Two writers on > one path with no arbitration meant an agent's boundary commune, authored at a > `/clear` and not yet ingested, could be overwritten **unread** by the echo that > fired seconds later. See KNOWN-HAZARDS 6.12.* A `commune_dir` may be absolute or relative, and the **ingest** resolves it per-endpoint *(hardened in v0.29.0)*: - **Absolute** → used as-is. - **Relative** → resolved against the **endpoint's own recorded working directory**, read fresh — never against the daemon's process cwd. - **Relative with no recorded cwd** → spt-core **skips and warns once** (per endpoint, per daemon run). It never guesses and never falls back to the daemon's cwd. This is the fix for a real outage: under a service-launched daemon whose process cwd was a system directory, a relative dir once resolved there and failed with a permission error. The loud skip makes a mis-declared relative dir a diagnosable signal instead of a silent failure. Declare an **absolute** `commune_dir`, or ensure the endpoint's cwd is recorded, to avoid the skip. An adapter that declares `[session.echo_commune]` but **no** `commune_dir` still echoes — the echo needs no directory. A missing `[session.echo_commune]` role is a **loud once-skip**, not a retried fault. **Read the resolved dir; never re-derive it.** Because rule 2 resolves the directory against the *endpoint's* recorded cwd — not the caller's — an agent working in a git worktree, a subdirectory, or any other cwd cannot tell where its own commune must land by looking around. Ask spt, in one command: ```console $ spt endpoint list --json { "self": { "id": "todlando", ..., "drop_dir": "C:/repo/.claude" }, ... } ``` - `self.drop_dir` — where **your** commune must land. - `local[].drop_dir` — the same fact for the node's **other** endpoints, which is the form the question usually takes: a stray `-commune.md` is found by whoever trips over it, not by its owner. - The human view prints the same fact as a `commune drop dir:` line under the SELF pin, so `spt endpoint list` answers it without `--json`. Both fields resolve through the *same* resolver the ingest watches with, so the answer cannot drift from the behaviour. An endpoint with no recorded cwd or adapter, or a manifest declaring no `commune_dir`, **omits** the field rather than guessing — an absent answer is honest, and a guessed path is worse than silence. Subnet-remote rows carry no drop dir at all: that would be another node's filesystem, and a path this machine cannot read is not an answer. A drop file sitting in a dir that is *not* the one reported here was written somewhere nothing watches: it will never ingest, and reading it is the recovery. **3. Ingest deletes the agent's drop.** On its next pulse tick spt-core reads the agent's drop, routes it into the durable context tiers, and **deletes the file** — whether the content was written or suppressed as a stale snapshot (both mean "consumed"). A read/write *error* leaves the file in place to retry on the next pass. The file disappearing is the success signal. ## What spt-core expects on stdout The summarizer's **stdout is the brief** — the cheap-model synthesis of the session, as plain text. spt-core does not require a structured format; it stamps a provenance header (`Source: echo-commune`) and routes the result into the durable tiers. That body is parsed, at that moment, with the **two-slice envelope** grammar, the same one a hand-written commune uses: - `…` → the **live tier** (who the agent is and what it is doing; follows the endpoint everywhere). - `…` → the **project tier** (scoped to the current project). - An **untagged body** routes whole to the live tier. The **project anchor** is the endpoint's recorded working directory, the same one rule 2 resolves a relative `commune_dir` against; there is no anchor when no cwd is recorded or it lies inside the spt home (a psyche host, the engine room). Every write is precedence-guarded — a stale snapshot arriving inside another writer's protection window is suppressed (but still consumed). An endpoint with **no project anchor** (a psyche host, the engine room) has no project tier to fill, so a `` slice in an echo brief is discarded with a loud `ECHO_PROJECT_UNROUTABLE` line rather than held as a file; the `COMMUNE` I/O event still carries the brief verbatim, so the funnel remains the record. The checkpoint sentinel `!!checkpoint!!`, if the brief carries one, is stripped before both presentation and the durable write, so it never persists in the stored context. ## In one line Declare `[session.echo_commune]` with a command that **self-sources its transcript** (found via a `direction = "read"` locator key) and **prints the brief to stdout**; let spt-core do the spawn and route the brief into the durable tiers. That is the whole contract. `commune_dir` is a separate declaration for your **agent's own** communes — declare it absolute — and the echo neither needs it nor writes to it. ===== /harness-contract/install-on-demand.md ===== # Install-on-demand bootstrap How an adapter ships spt-core *with itself*. The contract: **the canonical install path is also every adapter's pack-in installer** — there is no second mechanism, no vendored binary, no bespoke fetch logic to maintain. Your adapter checks for `spt`, and when it's missing runs the official bootstrap: `gh release download` the platform binary from the release channel, then the binary's own **`spt install` verb** — it places itself at the canonical install path, registers the user PATH, refuses a wrong-platform binary, and is non-interactive and idempotent by construction. The release channel is private, so the node needs an authenticated GitHub CLI (`gh auth login`, once per machine, with an account that can read the channel) — see [Installing](../reference/install.md). ## The generic contract ```text if `spt` is on PATH -> done (optionally check `spt --version` ≥ your floor) else -> gh release download the platform binary + run its `install` verb then -> first invocation may need the absolute path (Windows) then -> register your manifest: spt adapter add --github / ``` After first install, spt-core keeps itself current (signed self-update over the same gh channel), so the bootstrap can leave upgrades to spt-core. The remaining bootstrap step is to register your adapter — see [Activate the adapter](#activate-the-adapter--register-your-manifest) below. ## Check-and-install: POSIX sh Drop this into your adapter's bootstrap (plugin install step, postinstall script, first-run guard): ```sh if ! command -v spt >/dev/null 2>&1; then echo "spt-core not found - installing..." gh release download --repo BigscreenVR/spt-bs-releases \ --pattern 'spt-x86_64-linux' --dir /tmp chmod +x /tmp/spt-x86_64-linux /tmp/spt-x86_64-linux install # current shell may not see the PATH update yet: SPT="${SPT_HOME:-$HOME/.spt-core}/bin/spt" else SPT="spt" fi "$SPT" --version ``` ## Check-and-install: PowerShell ```powershell if (-not (Get-Command spt -ErrorAction SilentlyContinue)) { Write-Output "spt-core not found - installing..." gh release download --repo BigscreenVR/spt-bs-releases ` --pattern 'spt-x86_64-windows.exe' --dir $env:TEMP & (Join-Path $env:TEMP 'spt-x86_64-windows.exe') install # The user-PATH registration only reaches NEW terminals -- use the # absolute install path for everything in THIS process: $spt = Join-Path $env:LOCALAPPDATA 'spt-core\bin\spt.exe' } else { $spt = 'spt' } & $spt --version ``` ## Activate the adapter — register your manifest Installing the binary is the first half of a pack-in; registering your manifest is the second. Installing the binary makes `spt` available; **`spt adapter add` activates your adapter** — registration is what lights up its profiles, `[strings]` bodies, `[digest]` extractor, and hooks and makes it show in `spt adapter list`. So the step right after the binary check is registering the manifest: ```sh # after `spt` is confirmed present (above): # from a GitHub release — ships built binaries, source-free, versioned: "$SPT" adapter add --release / # latest "$SPT" adapter add --release / --tag v1.0.0 # pinned # ...or clone a repo whose ROOT holds manifest.toml: "$SPT" adapter add --github / # ...or a local directory your harness ships: "$SPT" adapter add ./adapter ``` `adapter add` is **manifest-first** — a clean add proves the cross-field manifest shape — and it conducts your [`[update]`](manifest.md#update--adapter-self-update) avenue once (install is the first update). Confirm with `spt adapter list`: your adapter and its version appear. Keep this idempotent in your bootstrap the same way the binary check is — register when `adapter list` shows your adapter missing or below the expected version. **`--release` is the recommended distribution.** It fetches a `.spt` archive asset — a tar whose root holds `manifest.toml` + `strings/` + the binaries the manifest points at — from the named GitHub release, extracts it to the durable registry home, and registers the root. That ships your **built binaries**, source-free and **versioned by tag** (`--tag`, default the latest release), and first-acquisition trusts gh's authenticated TLS + GitHub exactly like the bootstrap's first binary fetch. A development **monorepo stays a monorepo**: your release CI packs the archive (`tar -czf adapter.spt manifest.toml strings/ bin/…`) and uploads it as a release asset, so the adapter ships straight from your existing repo. Override the asset name with `--asset` (default `adapter.spt`). **Cover several platforms in one `.spt` (since v0.13.2).** To ship binaries for more than one OS/arch in a single asset, add a **target-triple subdirectory** at the archive root per platform and put that platform's binaries inside it, leaving the shared `manifest.toml` + `strings/` at the root: ```text adapter.spt ├── manifest.toml # shared — at the root ├── strings/ # shared — at the root ├── x86_64-pc-windows-msvc/ # one platform's binaries… │ └── bin/… # …in the same relative layout a flat .spt uses └── x86_64-unknown-linux-gnu/ └── bin/… ``` On install, spt-core extracts the shared root plus **only the current node's triple**, flattened into the install dir — so the bare-name `/` resolution above is unchanged; mirror, under each triple, exactly the per-platform tree a flat `.spt` would place at the root. The recognized triples are the platforms spt-core itself ships for — today `x86_64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`, and (since v0.30.0) `x86_64-unknown-linux-musl` — one set shared with platform-targeted update sets, so a new spt-core platform tier extends this list automatically; a root subdirectory whose name is **not** a recognized triple is treated as a shared root entry (so binaries for other platforms still ship as **separate single-platform assets**, one selected per node with `--asset`). A multi-platform archive that lacks the recipient's triple is refused with a clear `NoArtifactForPlatform` error — never a silent partial install — and requires `min_spt_core_version >= 0.13.2`. A flat archive (no triple subdirectories) installs exactly as before. `--github` is the alternative for an adapter whose **repo root already holds `manifest.toml`**: it clones the repo and registers the clone root (`adapter add` resolves a directory source to `/manifest.toml` at the root). Local development uses the directory form, which takes any path or filename: `spt adapter add ./adapters/my-adapter.toml`. What registration holds under `adapters//` follows your [`[update]`](manifest.md#update--adapter-self-update) avenue: a `delegated` or `gh_release` adapter is **pointer-mode** (the manifest and `strings/` are read live from the durable home), and a `file_pull` (or avenue-less) adapter is **copy-mode** (the `manifest.toml` and `strings/` are copied in). Publish the binaries your manifest references in the `.spt` (or repo) too, and reference them **by bare name**: since v0.8.0, a command template's program token resolves against the adapter's install dir before `PATH`, so a `.spt` that ships its binaries is **self-contained** — the shipped binary is found without any PATH placement. (Absolute paths still work; an unshipped tool still falls back to `PATH`.) This applies to the `[session.psyche_resume]` per-event turn, the `[digest]` extractor, and `spt adapter digest-proof`. > **"Install the plugin, get the adapter for free" — include the activation > step.** The [`[update]`](manifest.md#update--adapter-self-update) avenues > keep a *registered* adapter current. The straightforward path for a > `--release`-distributed adapter is **`gh_release`** (since v0.8.0): declare > `avenue = "gh_release", repo = "your-org/your-adapter"` and > `spt adapter update` ships the latest release `.spt` to the node — fetched, > optionally verified against your `signing_key`, re-extracted, and > re-registered. The other avenues: `delegated` (your harness's own updater > installs the content — set `self_verifies = true` to attest it verifies what > it installs), and `file_pull` (its automatic network-pull transport is **on > the roadmap**). Deliver the manifest with `adapter add --release` (or > `--github`, or a packed local dir) and let `gh_release` carry updates. ## The Windows PATH-refresh gotcha The install verb registers the binary directory on the **user** PATH via the registry. Registry PATH changes reach **new** processes; an already-running process — including the terminal (and *your bootstrap*) that just ran the install — keeps the PATH it started with. So: **the first invocation after an install must use the absolute path** (`%LOCALAPPDATA%\spt-core\bin\spt.exe`; the verb prints it). Every new terminal after that finds `spt` normally. The snippets above bake this in. On Linux the equivalent (a `~/.profile` entry the current shell hasn't sourced) is handled the same way: the printed absolute path, once. ## Pinning and install-dir overrides Pin a release by giving `gh release download` an explicit tag (`gh release download v0.32.0 --repo … --pattern …`). The verb's knobs: | Flag | Meaning | |---|---| | `--dir ` | Override the install directory | | `--no-path` | Skip user-PATH registration | ## Trust model First fetch trusts gh's authenticated TLS + the private channel's access control (check the download against the release's `SHA256SUMS` for a belt on the braces). From then on, `spt update` performs full Ed25519 signature verification against the two-key trust anchor embedded in every binary — so the bootstrap is the strong link only once. ===== /harness-contract/patterns.md ===== # Adapter patterns & pitfalls The [integration checklist](integration-checklist.md) tells you *which* surfaces to wire. This page is the field guide: the patterns that decide whether an adapter merely registers or runs like a native part of the harness — the design rules, the lessons that save you a debugging session, and the cheapest ways to prove each piece on the live binary. Everything here is behaviour of the **shipped public surface** — the `spt` binary, the [manifest](manifest.md), and the [`spt api`](api.md) commands, verified against a live binary. It is harness-agnostic; where one harness's quirk is the clearest illustration it is called out as such, and the pattern generalizes to any harness with the same shape. ## The one rule: manifests are static, logic lives in binaries If you internalize a single thing, make it this. - **Manifest fields are static templates spt-core fills.** A field is a fixed template: spt-core substitutes `{key}` placeholders from a fixed [catalog](manifest.md#substitution-keys) (`{session_id}`, `{parent_pid}`, `{adapter_name}`, `{id}`, the digest/psyche keys), and `~` expands to home. That is the whole of a template's power. - **Anything that depends on runtime state belongs in a binary the manifest points at** — the `[digest]` extractor, a `[session.*]` runner. Reading an env var, branching on runtime state, or computing a value is *logic*, so it lives in a binary. If your harness can move its own state directory at runtime, for example, treat the manifest `source` as a *fallback* root and have the binary it points at resolve the real location itself. - **A `.toml`-only leaf carries no code of its own**, so verify it by registering and resolving it on the live binary (below), and put anything you want covered by real tests into a binary (an extractor or runner). Hold this rule and most of the surface falls into place: the manifest is the *declaration*, your binaries are the *behaviour*. ## The adapter lives in the registry An adapter — its manifest, profiles, `[strings]`, the `[digest]` extractor, any runner binaries — is registered with **`spt adapter add `** into the node-local adapter registry. The version recorded there (`spt adapter list`) is the **version-of-truth** for what the adapter does. That is the entire, universal delivery mechanism: every spt adapter ships this way, and registration is where spt-core validates it (see [the second gate](#validate-against-the-live-binary)). If your harness *also* has a plugin or marketplace channel (so casual users can one-click install it), that is a separate distribution choice on top. When you go that route, let the **registry** carry the binary, manifest, and runtime state, and version the plugin independently of the manifest/binary. ## Profiles are sparse leaf-replace overlays A profile is selected as the composite `:` and **leaf-replaces only the leaves you declare** — everything else inherits from base. Override exactly what differs: - `[profiles..session.self].command` — retarget the bringup command (for example, wrap the launch in another binary). - `[profiles..digest].` — widen one digest knob. - `[profiles..session.psyche_init]` — add the [live-agent seam](#the-live-agent-companion-seam); its presence on the merged view is what flips an endpoint to a live agent. **Make an overlay observable.** Also leaf-replace one `[strings]` key (say a label) in the profile. Then `spt adapter get-string : ` differs from the base value — and that diff is your proof the overlay resolved. It is the cheapest profile acceptance assertion there is. A profile that wraps the launch in another binary works when that binary is a drop-in for the base harness binary on the same argv and passes inherited env through unchanged. Routing a session through a launcher wrapper (a model or billing multiplexer, say) is exactly this: replace the `session.self` command and let the injected endpoint-id env ride through untouched. ## Wiring hooks: you own the harness side spt-core supplies the harness-**independent** `spt api` primitives and their I/O format. *You* author all harness-specific wiring: spt-core supplies the primitives, and your adapter hand-writes its hook config to shell out to `spt api`. A mapping that works on the public surface, in terms any harness can translate to its own events: | When the harness… | …fire | Why | | --- | --- | --- | | starts a session | `api seed --pid {parent_pid} --session-id {session_id}` | Seed the endpoint (adapter-agnostic) — keep this fast and non-blocking. | | submits a user turn | `api poll {session_id}` · `api now-signal --session {session_id} --user-input …` | Drain the inbox to stdout; the now-signal adds what changed since the last poll (peers named, monics fired, dispatch outcomes) and prints **nothing** when nothing did. It subsumes `api hint` — inject one, not both. | | goes idle / busy | `api state idle` / `api state busy` (add `--payload-stdin` to carry the turn's text) | Honest activity; spt-core treats your explicit `api state` calls as the source of truth. The optional payload is what feeds the IO funnel — one payload-carrying call per turn. | | ends the session | `api session-end {session_id}` (or `api shutdown ` for graceful signoff) | Teardown that preserves the spool + history. | | spawns / ends a sub-agent | `api worker-start` / `api worker-stop` | Nested short-lived workers. | Two structural rules sit under that table: - **Run the blocking listen/poll loop from a skill the user invokes.** Seed on start so bringup stays fast, and let an explicit `/ready`-style skill own the blocking stream. - **Message delivery is stdout framing.** `api poll` emits the self-delimiting envelope `body` (the live listener stream uses the same shape). Multi-message drains split cleanly on ``. Decode a body by splitting on `
` → newline, then HTML-unescaping `< > "` and `&` **last** (the full entity set and decode-order contract: [the `` wire contract](../messaging/overview.md#the-event-wire-contract)). Route that stdout into your harness's injection channel — that routing is adapter glue. ### Get these right in the hook layer A few patterns here save you a debugging session — wire them deliberately. - **Pre-empt an injection channel's size cap.** If your harness caps the size of an injected blob (truncating it, or spilling it to a file and evicting it from the context the agent actually reads), cap the combined hook output adapter-side: under the limit, pass the output through verbatim; over it, spill the **full** text to an agent-readable file and inject a short pointer. Always cut on an `` boundary, so every envelope stays whole and every message survives a large drain. - **Inject a skill body *before* the perch gate, and gate only the message drain.** When the same prompt hook both injects a requested skill's instructions and drains messages, run the skill-body injection first — that keeps skills like "who am I" or "set me up" working for a new user, since they are valid while the perch is still being readied. Match the skill token as a leading token, so only an actual invocation fires (prose that merely mentions it stays inert). - **Make the setup/installer skill self-contained in its stub.** It runs precisely when the binary may be absent (installing it is the job), so carry its operative steps in the harness-native stub itself — the floor that always works — and let any file-backed body mirror them for the binary-present repair path. The one skill that most needs delivery is the one delivery reaches last, so give it a stub that stands alone. - **Report every payload span exactly once across the turn.** `api state busy|idle --payload-stdin` feeds the [IO funnel](../shells/frames.md#io--the-sessions-io-events-durable), and spt-core emits one event per **payload-carrying call** — it does not deduplicate, so a hook that fires twice for one turn produces two `AGENT_OUTPUT` events and a consumer counting turns counts two. Pick the one hook that owns the turn's close and let the others report without a payload. If you also report [mid-turn spans](../shells/frames.md#reporting-a-turns-payload) with `--mid`, the spans and the remainder you report at `idle` must be **disjoint**: core cannot tell that two payloads are the same text without modelling how your harness assembles a turn, which is yours to know. If your adapter already streams the turn through its `[digest]`, report `idle` with no payload rather than sending the same text a second way. Note the stdin collision this implies: the payload goes in on the `spt` child's **own** stdin (or `--payload-file`) — it is not the hook's stdin JSON, and `--payload-stdin` is explicit precisely so the verb never reads a stdin it was not handed. - **Read hook inputs from stdin.** A hook receives its data (the prompt, the session id) as a JSON object on **stdin** — parse that, which keeps a `/`-leading value (a `/` token, an absolute path) intact. Under Git-Bash/MSYS on Windows, an argument beginning with `/` is rewritten to a Windows path before your command sees it (a `/foo:send` token can arrive as `C:/Program Files/Git/send`), so stdin is the transport that preserves it. If a command must take such an argument, guard it (`MSYS_NO_PATHCONV=1`, or a file/stdin transport). It is the same class as the UTF-8-stdout trap below — choose the transport that carries the data faithfully. ## `[strings]`: keep the manifest thin, point at the live binary A `[strings]` value is either an inline string or a **file pointer** (`key = { file = "relative/path" }`), resolved lazily by `spt adapter get-string` to the file's contents — so live edits reflect without re-registering. Keep pointer files inside the `strings/` dir; the add enforces that containment. Use file pointers to keep skill-instruction bodies out of the manifest. When a skill body needs to describe the spt surface, point it at the binary's own self-documentation, so the guidance stays current with the shipped binary — two always-current tiers: - `spt how-to ` is the task-oriented agent-guidance surface, covering **selected** topics, each a canonical write-up of verbs, flags, and result codes. Treat it as the curated tier: for a verb it covers, read the topic; for any other verb, probe and fall through (an undocumented topic returns `NO_SUCH_TOPIC:`). - For any verb, **`spt --help` is the always-present source-of-truth** — it tracks the shipped binary. A skill body that says "the verb list is `spt --help` — match the user's intent to a verb" stays correct across releases. Either tier stays current with the binary, and a skill body that points at them stays correct across releases. They are also the fastest way to learn the surface while authoring — it self-documents. ## `[digest]`: the transcript→record extractor The `[digest]` seam maps your harness's native transcript into spt-core's digest-record contract. The contract beyond the schema: - **Name where it reads** — either `source` or a `[history].locate_template`. `spt adapter add` requires this even though the JSON schema alone would accept a bare `extractor`; the cross-field rule surfaces at registration, so validate against the live binary. - **Treat `--in {source}` as a root.** The extractor is invoked `--session {session_id} --in {source}` and locates ``'s transcript *within* that root — your harness's internal subdir scheme is yours to resolve, and spt-core keeps the key catalog harness-agnostic. Handle both shapes: `--in` a directory (locate the session) and `--in` a direct file (the `digest-proof --sample` path). - **Resolve a runtime-relocated state tree in the binary.** When a runtime value (an env var, an isolated profile) moves the real transcript tree, have the extractor prefer that value on its directory branch, with the manifest `source` as the fallback root. That resolution is logic, so it lives in the binary — the headline rule in miniature. - **Emit raw records as UTF-8.** Output one NDJSON line per record (`{role ∈ input|agent|tool, text?, tool?, ts?}`) and leave presentation to spt-core's renderer (`window_turns`, arg truncation, sprint collapse). Pin stdout to **UTF-8** so non-ASCII (em-dashes, smart quotes) round-trips — spt-core reads the stream as UTF-8. (Native-UTF-8 languages get this for free, which is part of why this seam is a binary.) Prove the whole path with `spt adapter digest-proof --sample ` (below). ## The bringup / launcher seam `[session.self].command` is the spt-hosted bringup template — spt-core spawns it into a broker PTY. For a harness with no native session-id flag, mint the id internally and pass the endpoint id via an injected env var (`[env.]` with `direction = "inject"`, `value = "{id}"`); the start hook reads that env and self-registers with `api bind `. That bind is **intrinsically authenticated**: for a broker-spawned session the broker parentage is the proof, so `api bind --set-session-id ` alone establishes the association, and later mutating calls prove themselves with the session id the bind recorded. (The flip side shows up in [testing](#testing-against-a-real-harness-isolate-identity): the framework keys association on *identity*, so identity is the thing you isolate.) `adapter.shortcut_basename` brands the generated launcher shortcut (`-`) and is decoupled from the adapter name. ## The live-agent (companion) seam An endpoint is a **live agent** exactly when its *resolved* manifest declares `[session.psyche_init]` — declaring that section is the single go-live signal. A base manifest is a ready agent; a profile overlay that adds the section makes a live agent. spt-core checks this on the **merged** view, so the profile resolved at **bind time** drives the spawn decision all the way through — the bound profile governs the full runtime lifecycle, beyond bringup argv. Since v0.9.0 the seed is adapter-agnostic: the profile is resolved when `listen` binds, from the active-profile pointer ([`spt adapter use :`](../cli/reference.md)) or an explicit `--adapter :` override on the `listen` call. - **`[session.psyche_init]` is a go-live GATE ONLY — spt-core never spawns it.** Its mere presence promotes the endpoint to a LiveAgent; the command is opaque and, in the per-event model, unexecuted. Keep it minimal. - **The daemon drives the Psyche as one bounded `[session.psyche_resume]` turn per event** (a pulse fire, a commune/signoff drop, a session-custody transition) — stdin-fed and **stdout-captured**, exiting at turn end. There is **no resident wrapper, no seed-once, no detached process**. `psyche_resume` is the *sole* driven Psyche role. - **Keys spt-core fills into the turn:** `{session_id}` = the Psyche's **own** custody sid (its own thread — a parent `/clear`/`/compact` does not rotate it), `{parent_session_id}` = the parent's sid, `{psyche_context_file}` = the path to the composed-mind file (fresh = non-empty, continue = 0-byte — never on the argv), and `{subnet}` (when known). The adapter-static/node keys are also available: `{id}` = the **parent endpoint id** (not a `-psyche` override), `{adapter_dir}`, `{adapter_name}`, `{node}`. There is **no** `{psyche_dir}` or `{psyche_prompt}` fill — those retired with the resident spawn. - **The runner is yours to build; its lifecycle is the daemon's.** `psyche_resume.command` is adapter-authored and opaque to spt-core. **If your harness's headless mode runs one turn per invocation, that is exactly the model** — the daemon invokes `psyche_resume` once per event, so no resident wrapper is needed (and none is wanted). Build it like the `[digest]` extractor — a compiled, dependency-light binary the daemon can exec bare on any platform, resuming the Psyche's own session by `{session_id}` and reading the mind from `{psyche_context_file}`. ### Prove live bringup non-interactively To prove your live path actually goes live — without an interactive terminal — drive the bringup as a child process and assert on deterministic side-effects. The harness plays the long-running-listener role: 1. **Seed**, anchoring on the OS process pid — not a shell-wrapper pid. Under Git-Bash/MSYS `$$` is the MSYS pid, which fails the seed's liveness guard, so derive the real OS pid: `spt api seed --pid --session-id ` (adapter-agnostic — no `--adapter`). 2. **Bind, then send a probe.** A send to a never-bound perch is `NO_PERCH` (no spool exists yet), so establish the perch first; then `spt send ` `QUEUED`s against it, ready to drain on bringup. 3. **Spawn the persistent relay as a child**, capturing its stdout/stderr: `spt api listen ` (no `--once` — that exits after one delivery). The adapter resolves from your `[adapter] host_binaries`; pass `--adapter --manifest ` only to pin a specific adapter/profile. Assert `BOUND:` then `READY:` on its stderr, and the relayed `` carrying your probe on its stdout. 4. **Assert the endpoint went live and its turns succeed.** The relay marks the perch online; the endpoint reports kind `live_agent` (its resolved manifest declares `[session.psyche_init]`). Because the Psyche is a **per-event turn, not a resident process**, there is **no `-psyche` perch to come online** and **no `LIVEHOST_PSYCHE` marker** to assert — those belonged to the retired resident model. Instead assert the healthy-turn signal: after a psyche event fires, the endpoint's perch carries **no `psyche_host_error`** (an absent error is the "turns succeed" proof; a present one names the failing turn). Scope that assertion to the fault you are proving absent: the stamp composes from SEVERAL independent fault latches (a failing turn, a failing commune ingest, a timeout), and a successful turn clears only its own. A stamp naming an INGEST failure therefore still stands after a perfectly healthy turn — correctly, since a working turn cannot vouch for ingest. Read the stamp's `reason`; a non-null `psyche_host_error` after a good turn is not automatically a broken turn. Absence is also spelled differently depending on where you read it: the perch RECORD omits the field, but `endpoint list --json` always emits the key and sets it to `null` when there is no fault. Assert on the VALUE, never on the key's presence. 5. **Kill the child** to end the session — the relay is freely killable; the Psyche runs only as bounded per-event turns the daemon drives (a graceful `spt endpoint shutdown ` ends the endpoint). Pin the identity env (`OWL_SESSION_ID`) for the auth-gated calls, and give the system-under-test a throwaway identity per the [identity-isolation rule](#testing-against-a-real-harness-isolate-identity). ## Lifecycle continuity is file-drops Commune and signoff are delivered as **file-drops** by design. The agent writes `-commune.md` (delta context) or `-signoff.md` (final save) into the manifest-declared `[session].commune_dir` / `signoff_dir`; spt-core's daemon watcher ingests it and deletes it (the daemon is the single writer). The **filenames are contract-fixed** and the directory is adapter-declared, so wire the directory watch and read the contract filename. This is the single biggest continuity win, so it is worth getting exactly right. ## Testing against a real harness: isolate identity The surest way to prove your hook wiring fires is an acceptance test that **spawns a real harness session as the system-under-test**. Doing so meets a framework property you design around: - A perch's identity is **resolved from the environment** (the same vars `spt whoami` reads), and perches are **name-keyed, last-establish-wins**. The most recent session to establish a perch under a given identity holds it, taking the active poll/listen stream with it. - So a spawned test session that loads your adapter (whose start hook seeds and binds a perch) under the identity of the agent running the tests would take that agent's perch. **Identity isolation is the guard.** - Give every spawned system-under-test a disposable identity distinct from any live agent — override **both** identity env vars before the spawn to a throwaway `-ci-`, so the nested session and the operator's perch coexist cleanly. Identity is the key, so isolating identity is the whole guard. - Keep the orchestration deterministic and **assert on a hook side-effect** — a marker or digest file, or `spt` state — the deterministic signal. Keep the harness as the system-under-test and let its side effects be your assertions. ## Validate against the live binary Treat registration as the **second gate**: beyond JSON-schema validity, `spt adapter add` runs cross-field checks that go past what the schema expresses (the `[digest]` source rule is one). Build for it: - A **registration integration check**: `adapter add` → `adapter list` (assert the adapter and each shipped profile composite resolves) → `get-string` (the base value, each overlay diff, and each file-backed pointer resolve to a body) → a soft `adapter remove` (leaving the registry clean). Gate it behind an opt-in env flag and a minimum `spt` version, since it mutates the node-local registry. - Two author-time tools work without a live session: - `spt api --adapter --manifest capability` reports the manifest's hostable types from the manifest alone — assert it advertises the type your bringup spawns. (A clean `add` already proves the cross-field shape, since add is manifest-first; `capability` is the lighter, non-mutating check.) - `spt adapter digest-proof --sample ` runs the real extractor through the registry and renders the result — proving the transcript → record → render path end-to-end on a fixed sample. It fills the same runtime substitution keys the daemon does, so passing proof means it works at runtime. (Use a recent `spt` — current binaries fill the full key map.) - `spt adapter translate-proof --event ''` spawns and feeds your declared `[message-idle-translation-binary]` exactly as the daemon does at idle delivery, then prints the keystroke-command stream it emits (`{key}` / `{text}` / `{delay_ms}` / `{commit}`) — failing a binary that emits nothing or never sends a terminating `{commit}` (which would fault at the commit deadline live). The EMIT-half mirror of `digest-proof`; the atomic PTY apply stays covered by the daemon's integration gate. - **Proof a DEV build off disk — `--dir` / `--manifest`.** Both `digest-proof` and `translate-proof` accept `--dir ` (binaries resolve there, just like a registered install) or `--manifest ` (pins the manifest; its parent is the install dir) to proof an adapter that is **not registered** — e.g. a freshly built binary beside a hand-written `manifest.toml`, or a bare-file `gh_release` adapter that was never staged into a full extracted install. `--dir` defaults the manifest to `/manifest.toml`; with neither flag the command resolves the registered adapter as before. Mirrors `digest-proof --sample` pointing straight at a file — proof without a full `spt adapter add` round-trip. And the meta-lesson: **observable behaviour of the public binary is itself public surface.** When prose docs lag, a byte-capture against the live `api` / `adapter` surface is a legitimate way to confirm a contract. ## Next - **The full surface:** the [integration checklist](integration-checklist.md) — every contract surface grouped by necessity. - **Reference:** the [manifest reference](manifest.md) and the [`spt api` surface](api.md). - **Ship it:** the [install-on-demand bootstrap](install-on-demand.md). - **Driven surfaces:** [Shells](../shells/overview.md) — the `kind = "shell"` flavour of this same contract. ===== /instances/overview.md ===== # Instances One endpoint, several seats. `sergey` is a single identity; an **instance** of sergey is his presence on one node. The registry tracks every instance's node and state (active / dormant / suspended / offline), and the same mind syncs to wherever he sits. ## The rules that keep it sane - **Identity is adapter-agnostic and node-spanning** — instances on different nodes are rows under one endpoint id; renaming (`spt endpoint rename`) ripples everywhere, collision-checked. - **Bare-id resolution never guesses** — `sergey` resolves locally first, then to the sole live instance; with several live nodes (or several subnets) it refuses and makes you qualify (`sergey@desktop`, `home:sergey`). Per-node recency is not comparable across nodes, so there's no silent "most recently active" pick. - **The anchor subnet is immutable** — assigned at creation. Moving an endpoint into another subnet is `spt endpoint fork`: a **new identity** seeded with a one-time copy of the mind, diverging immediately. Copy-then-diverge, never re-anchor — history stays honest. - **Visibility is per-(endpoint, subnet)** — hidden means neither advertised nor routable there, and hidden gates sync too. - **Rest states are first-class** — dormant (warm) and suspended (cold) instances stay addressable; deferred messages are held and released exactly once on wake. Remote `spt endpoint suspend sergey@desktop` / `spt endpoint wake sergey@desktop` work across paired nodes. ## What a fork carries A fork copies the source's **whole mind tier at its tip** — every tracked file on that endpoint's branch, enumerated from the tree itself. Not a list of filenames: a fork that copies named files drops every mind file nobody remembered to add to the list, silently, one omission per file, discoverable only by someone later noticing an absence. That had already happened in the field — the endpoint's durable **role** file was tracked on the same branch and simply was not copied, so every fork produced an endpoint whose role had vanished. Copying the directory closes that gap and every future one in the same move: context, role, [monics](../networking/monics.md), and whatever the mind tier grows next all ride without anyone wiring them in. There is **exactly one exclusion**, and it is a decision rather than an oversight: surfaced-but-unresolved **conflict artifacts** stay with the mind that surfaced them. A fork starts clean, and a fork inheriting the source's unresolved pairs would make that quietly false. The source keeps all of it. ## Forking an endpoint another node holds The source does not have to sit on this machine. Name it `id@node` and the fork is made **where the source is**, by the node that holds it: ```text spt endpoint fork sergey@desktop sergey-lab --subnet labnet ``` What a fork *is* does not change across the boundary: a new identity, seeded with a one-time copy of the source's whole mind tier, diverging immediately — and **the source is left intact**. Both arms run the same primitive on the node that holds the source, so a fork performed for a caller on another node is the same act a local operator performs, refusal for refusal. A fork that happened is reported as `FORKED:` and names the node that made it. A request that goes unanswered is reported as `FORK_UNCONFIRMED:` — never as forked: a node too old to know the verb and a node that declined to admit you are indistinguishable from the calling side, and calling either one done would be a fork someone believes they have. A node that *accepts* the request and then answers nothing is a third thing, and it says so: `FORK_PEER_SILENT:`. The two silences are not the same fact. An unanswered request came back from a stream the far side finished — an old or refusing node, and the remedy is at that node's version or its admissions. A silent one is still holding the stream open, which points at a node that is wedged or overloaded, and there is nothing to upgrade. Neither is a fork. One stated limit: the new id is collision-checked against the same **stale-tolerant** registry snapshot the local path reads, so a simultaneous mint of the same name on another node can slip past it. It is a check, not a distributed guarantee. ### The reach to fork and the reach to find are granted together Forking across nodes is a [control surface](../networking/access-viewing.md) — `FORK` — so the owner of the *source* decides, through the same rules every other surface uses. It is its own surface rather than a rider on a neighbouring one because a fork copies an endpoint's **entire mind**: folding it under "you may suspend my agent" or "you may transfer files" would hand over mind-cloning to anyone trusted with either. **A `FORK` grant on its own cannot be exercised.** Listing an endpoint's surfaces closes every surface not listed, so a `FORK`-only grant denies `DISCOVER`; the holding node then never advertises that endpoint into the registry the caller replicates, and the caller's **own resolution** — which runs before anything is dialled — cannot find the name it has been given permission to fork. What comes back says the endpoint is not in view: *not on this node, and no node in view holds it*. That is literally true, and it is **existence-shaped, not permission-shaped** — word for word what a typo'd id or an endpoint that never existed produces. Nothing tells the operator that a grant they hold is the reason. So grant **both** `FORK` and `DISCOVER`; today the pairing is something you have to know, and making the dead end announce itself is filed work rather than shipped behavior. ### `--delete-source` is local only `--delete-source` is the move-an-agent flag, and a fork whose source **resolves to another node** never deletes. Asked for one anyway, the command **refuses the whole invocation before anything is dialled** — nothing forked, nothing deleted — naming the node that holds the source and what to do instead. It is refused rather than quietly downgraded to a copy, because honouring half of what was typed leaves an operator who meant to *move* an agent holding two live minds and no word about the difference. The trigger is where the source **resolves**, not how it was spelled: naming your own machine explicitly (`sergey@thisnode`) is just a longer way of saying a local source, and `--delete-source` works there exactly as it always has — the delete running only after the fork is whole. ### Who a fork grant admits A fork request carries **no proven sender endpoint** today, so the only subject that can govern it is the requester's **whole machine**. Node-tier rules decide, and a rule naming a sender endpoint on `FORK` is [refused when you type it](../networking/knocking.md#refusals-you-can-predict) rather than stored to match nothing — the refusal names the machine form to use instead. That makes answering a knock for `FORK` a **widening** act, the shape described in [Knocking](../networking/knocking.md#what-an-approval-may-and-may-not-write): the grant admits every endpoint on that machine, whatever the knock named. An endpoint's **own agent** must acknowledge that widening with `--admit-node` and satisfy the node's policy; a user at the machine is node-sovereign and the engine room's bring-up is its own authorization, so neither has to restate it. You are told this **before** you answer, not after. The knock listing composes each row's prescribed approval from the same predicate the approve path decides on, so what it prescribes depends on who is reading it: to the endpoint's **own agent** a row asking for `FORK` prescribes the `--admit-node` form and names whose machine the grant would admit; a **person at the terminal** is node-sovereign and sees the plain form; and where the node's policy forbids an endpoint widening to a whole machine at all, the row offers **no invocation at all** — it names the engine room as the only seat that can answer, so from the agent's seat that request is a dead end rather than a harder path. What the listing does **not** prescribe is the `FORK`-plus-`DISCOVER` pair. It tells you what a grant would admit, not that `FORK` without `DISCOVER` cannot be exercised at all — that remains something you have to know, and closing it is filed work. The gate reads the **handshake-proven** origin of the request, never anything the request says about itself, and it is the *source* endpoint's rules that are consulted — the endpoint whose mind is about to be copied is the one whose owner's grant matters. A refusal creates nothing and, following the same posture as the other surfaces, tells an unadmitted caller nothing about what exists. ## Startup defaults (`endpoint auto-start`) Infrastructure endpoints (a gateway the phone treats as always-there) should not need hands-on bringup after a box reboot or daemon restart. `spt endpoint auto-start ` records the endpoint — its id, adapter option, and working directory — as a **startup default** in `daemon.json`; the daemon **replays** every saved default when it starts, as a fresh session with the adapter re-resolved at replay time. One entry per endpoint id (setting it again replaces the prior one); `spt endpoint auto-start --off` removes it. Replay is best-effort and loud, and never blocks daemon start: a saved run that comes up logs `ENDPOINT_AUTOSTART:`; a saved adapter that no longer resolves logs `ENDPOINT_AUTOSTART_SKIP:` (set it again to refresh it); a failed launch logs `ENDPOINT_AUTOSTART_FAIL:` and the daemon carries on. This is a **startup default**, not a session restore — it replays what you recorded, never "whatever was up before the restart" — and it is symmetric with `spt subnet attach --save` (the serve-state startup default). ## Commands `spt endpoint list` · `endpoint rename` · `endpoint fork` · `endpoint create` · `endpoint start` · `endpoint resume` · `endpoint auto-start` · `endpoint suspend` · `endpoint wake` · `endpoint description` — [CLI reference](../cli/reference.md). *Cold-launching an endpoint on a node that has no instance ("instantiate-anywhere") is deliberately deferred behind the consent framework; the gate exists and refuses today.* ===== /shells/overview.md ===== # Shells A **shell** is the non-agent endpoint kind: a *driven surface*. Notifiers, robots, lamps, game characters, sensor feeds — anything an agent should be able to command, and that might sense things back. Shells join the same network as agents: addressable, discoverable, owned. ## The model in five facts 1. **A shell adapter declares it; instances are minted.** The `kind = "shell"` [manifest](../harness-contract/manifest.md#shell-adapters-kind--shell) declares the binary, its command vocabulary (`[shell.capabilities]`), and its sensory vocabulary (`[shell.sensory]`). `spt shell spawn ` mints a new instance (`notify-1`) — spawn is the creation act, not an on/off switch; bringing an existing instance back is relink/wake. 2. **The link token is the credential.** The broker mints a per-launch link token into the spawn template; the binary binds with it (`api bind-shell --link`), drains commands with it, emits with it. No token, no access. 3. **Commands are vocabulary-checked and durable.** `spt shell cmd notify-1 notify "title" "body"` is validated against the manifest's declared verbs and arity before delivery — agents can't drive a shell outside its contract. Commands are discrete and durable: they spool and a persistent shell wakes to drain them. 4. **Sensory is live-only.** `api emit` payloads reach a *live* owner session or are dropped with a diagnostic — sensors report the present, never the past. 5. **Instantiation is governed.** Per-spawn approval (`require_approval: none / remembered / always`), per-owner instance caps (`max_instances_per_owner` + `over_cap`), and node-local discovery scope (`broadcast`) are all manifest-declared floors. ## Four channels between owner and shell A link can carry up to four distinct channels — each with its own delivery contract, all keyed to the same link token: - **Command** (owner→shell, durable): the vocabulary-checked verbs above — discrete, spooled, replayed to a waking persistent shell. - **Sensory** (shell→owner, live-only): `[shell.sensory]` emits to a live owner or drops with a diagnostic. - **Drive** (owner→shell, ephemeral): `[shell.drive]` + `spt shell drive` — a continuous control channel for real-time input (scroll, stick, avatar pose). **Latest-wins, never spooled**: a newer frame supersedes an undelivered one, and an offline shell drops the frame (no queue, no wake, no replay). Use it for *continuous* control; use commands for *discrete, must-arrive* actions. - **Tunnel** (owner↔shell, opaque bytes): `[shell.tunnel]` + `spt shell tunnel` — an optional reliable-ordered byte stream pair the taxonomy never interprets (first consumer: usbip URB). Not enveloped, not framed, not spooled; the link lifecycle governs it (a link-break closes it). Reliable ordering means congestion surfaces as **lag, never loss** — so the tunnel is **on-LAN only** by design (not for use across a WAN). The byte relay is proven **same-node**; cross-node operation (on-LAN only, by the same posture) is **not yet available** — it lands when a cross-node consumer needs it. Alongside the four channels, a link also carries two things spt-core itself pushes — nothing is declared in the manifest to receive either, because they are spt-core's own frames, and they sit at **opposite ends** of the delivery taxonomy: - the **owner's busy/idle state**. Every transition — and every (re-)link — puts an [`activity` frame](frames.md#activity--the-owners-busyidle-state-pushed) on the same ephemeral drain the drive channel uses, carrying the current state and when it took effect. Drive-class like the channel it rides — current-state-carrying, never spooled, never replayed. A shell that wants to react to its owner going idle just reads it. - the owner session's **IO events**. What the user asked, what the agent answered, which messages crossed, which communes landed — as discrete [`io` frames](frames.md#io--the-sessions-io-events-durable) on the durable spooled stream. Command-class: MAC-stamped, replayed to a binary that was down, and each frame is its own event rather than a restatement of a state. The durable owner→shell channels also carry free **text** and **file** transfers (`spt shell send`). The exact wire shapes a shell binary parses — frame types, attributes, body encodings, the MAC stamp, and how a landed file's path resolves — are specified in [the frame contract](frames.md). ## Two safety properties - **Per-capability approval gates.** Beyond the per-*spawn* gate, an individual `[shell.capabilities.]` may carry its own `require_approval` (with an optional `class_key` scoping the grant finer than the verb — e.g. a remembered HID-class attach never authorizes a storage-class attach). Spawn gates govern whether an instance may *exist*; capability gates govern whether a dangerous *act* may run. - **Ownership is owner-type-agnostic.** Any non-shell endpoint may own, spawn, drive, command, link, and tunnel a shell — a Gateway as readily as an agent. Control-exclusivity keys on the **owner's endpoint id**, never its type: a different endpoint (even of the same type) cannot drive your shell. Lifecycle extras: `persistent` shells auto-online with their owner; `wake_command` runs a watcher while offline (exit code 86 = wake); a shell with `can_shutdown = true` may suspend its own owner (`api owner-shutdown`) — fail-closed otherwise. Lifecycle facts worth knowing before you rely on either: - **Persistent instances return after a daemon-only restart as well as a machine reboot.** The boot sweep and each owner offline→online edge restore every persistent instance that is down in fact while its owner is online. Launch age and missing launch stamps do not exclude it. The birth-safe process probe still protects a live binary, including a launch awaiting bind. Failed launches are retried on an owner-online edge, not every reconcile tick. - **Only nonpersistent instances retain the force-kill freeze.** Their same-boot or undatable corpses arm no watcher; cleanly closed instances and dated pre-boot casualties remain watcher-eligible. Persistent instances bypass this freeze. To keep a persistent shell down, use `teardown` or a nonpersistent manifest rather than killing its process. - The daemon's `SHELL_RECORD_HEALED:/` diagnostics enumerate every instance whose stale online record was corrected, not a representative shell per owner. Already-correct records produce no repeated notice. - **`relink` refuses an instance that is still running; `--force` is the override.** Plain `spt shell relink ` is the *online switch* for an instance that is down, so it refuses one whose binary is up. When you mean "stop it and start it again" — a redeploy, a wedged binary — pass `--force`: it runs the ordinary link-break close first (the manifest's `pre_close` instruction, then the `close_timeout_ms` termination window, then the authenticated kill), and only then re-spawns and links. The canonical id, the perch and its persisted state, and the alias all survive; teardown + spawn is what churns the id and frees the mint slot. A successful local relink reports `status=binding (online at bind)`: the binary has launched and the bind handshake is still the online transition. It does not describe that successful launch as `offline`. Two things `--force` deliberately will **not** do: - **It refuses on an `ephemeral` instance.** An ephemeral shell's close *is* its teardown — the perch and its spool history are erased and the mint slot freed — so there would be nothing left to restart. The refusal happens before anything is stopped or erased. To replace such an instance, tear it down and spawn a new one (which is a new canonical id, by design). - **It refuses to relaunch if the binary cannot be proven stopped.** A close can legitimately leave a process running: the force-kill authenticates its target against the recorded pid **and** its birth stamp, and refuses rather than fire on a recycled pid. When the pid is still held after the close, `--force` reports it (naming the pid and what could be proven about it) instead of launching a second binary for one instance — the second one would be unreachable through the retired link token and invisible to the record. The link *is* closed at that point, so the instance is offline and re-linkable as soon as that process is gone. Cross-node (`@`) the flag rides as an argument of the existing relink action, so no wire version moves — but a node running an spt that predates the flag ignores it and answers "already online". That reply is reported as a **failure** (`SHELL_REMOTE_FORCE_UNHONORED`), never as success: under `--force` "it was already up" is precisely the thing that did not happen. ## Teach the agent about your shell: `[[hints]]` A shell adapter can declare `[[hints]]` exactly like a harness adapter — it is a top-level manifest section, not a harness-only one: ```toml [[hints]] keywords = ["screenshot", "what's on screen"] text = "the PACER shell can capture a window: `spt shell cmd PACER-0 capture `" ``` Each hint fires **once per session**, and your adapter contributes **at most one line per message** (the per-source cap — the harness gets one, and so does every other shell adapter, so a second shell can never be silenced by a chatty first). Which line the agent sees depends on **instantiation, never on link state**: - the owner **holds an instance** of your adapter → the **full** hint text, whether that instance is online or offline; - the owner holds **no instance** → a **teaser** naming the keyword that fired and the command that shows the text: `spt adapter hints `. That command is also how you read your own hints back: ```console $ spt adapter hints spt-shell-notify [screenshot, what's on screen] the PACER shell can capture a window: … ``` It resolves the merged view, so a profile's `[[hints]]` overlay is what prints — and it prints nothing (exit 0) for an adapter that declares none. ### How a keyword matches By default, each keyword is a **case-insensitive substring**: there are no word boundaries, whitespace is literal, and symbols match as written with no escaping. Set `regex = true` on a `[[hints]]` row to compile its keywords as regular expressions. Regex matching is **case-sensitive** unless the pattern uses `(?i)`. An **invalid regex matches nothing** — it silences its own hint and never panics. For word boundaries around a phrase: ```toml [[hints]] keywords = ['\bpair machine\b'] regex = true text = "Pair the machine before sending it work." ``` With `regex = true`, use `keywords = ['(?i)\bsweep\b']` for a case-insensitive whole word, or `keywords = ['pair\s+machine']` to allow one or more whitespace characters between the words. ## Start here [Getting started: a notification shell](getting-started.md) — install the shipping `spt-shell-notify` adapter, drive a native toast from an agent, and copy its manifest for your own surface. ===== /shells/getting-started.md ===== # Getting started: a notification shell The fastest way to understand shells is the shipping one: [`spt-shell-notify`](https://github.com/SaberMage/spt-shell-notify) renders agent commands and surfaced notifications as **native OS notifications** (Windows toast / Linux `notify-send`). Its manifest plus one small binary are the **only** glue to spt-core — no spt-core source, no SDK; the binary speaks the public `spt api` surface and nothing else. This page installs it, drives it, and reads its manifest as the template for your own shell. ## 1. Install and spawn it ```console $ git clone https://github.com/SaberMage/spt-shell-notify $ cd spt-shell-notify $ cargo install --path . # puts `notify-shell` on PATH $ spt adapter add . # validates + registers the manifest ADAPTER_ADD:notify:Shell:Copy (registered) $ spt shell spawn notify # mints an instance (notify-1) and launches it ``` `spawn` **mints a new instance identity** — `notify-1` — and launches the binary; it's the creation act, not an on/off switch. The first spawn asks for approval once (the manifest sets `require_approval = "remembered"`), and the grant persists. ## 2. Drive it from an agent Two render paths, by design: **Explicit command** — an owner agent drives a toast down the durable command channel: ```console $ spt shell cmd notify-1 notify "build finished" "all 139 tests green" ``` The resident binary drains its command frames (`spt api … poll --link`) and renders. Commands are validated against the manifest's declared vocabulary — a verb or arity outside `[shell.capabilities]` is refused before it ever reaches the binary. **Surfaced notification** — no agent in the loop: ```console $ spt subnet notify "deploy window opens in 10 minutes" ``` A subnet-wide notification resolves to the node the user most recently touched, and spt-core spawns the shell's `[session.notif]` template there — a native toast on the machine you're actually at. ## 3. Read the manifest The complete contract for this shell, annotated: ```toml [adapter] name = "notify" kind = "shell" version = "1.0.0" min_spt_core_version = "1.0.0" [shell] # Broker-launched; the {link_token} is the binary's only credential. spawn = "notify-shell --link {link_token} --id {id}" # A display is node-local; discovery never offers it off-node. broadcast = "same-node" # Auto-online with the owner: the notification surface should be up # whenever the user's endpoint is. persistent = true # First spawn asks once; the grant is remembered. require_approval = "remembered" pre_close = "closing" close_timeout_ms = 2000 # Offline wake-watcher: reports wake (exit code 86) after a short settle. wake_command = "notify-shell --wake" # The whole command vocabulary: one verb, two positional args. [shell.capabilities.notify] args = ["title", "body"] # The notif render seam: spt-core fills the {notif_*} keys and spawns this # detached when a notification surfaces at an endpoint this shell serves. [session.notif] command = 'notify-shell --render-title "{notif_from}" --render-body "{notif_body}"' detach = true keys = ["notif_id", "notif_from", "notif_subnet", "notif_body"] ``` What the binary itself does (three modes, ~one file): - **resident** (`--link …`): calls `api bind-shell --link ` to come online, then loops `api poll --link ` draining command frames and rendering them. - **one-shot render** (`--render-title/--render-body`): the `[session.notif]` template — render and exit. - **wake watcher** (`--wake`): run while the instance is offline; exiting with code 86 signals "wake me". ## 4. Make your own A shell is worth building whenever agents should *drive* something — a desktop widget, a robot, a lamp, a game character, a sensor feed: 1. Start from this manifest; change `name`, `spawn`, and the `[shell.capabilities]` vocabulary to your verbs. 2. Your binary needs exactly three behaviors: **bind** with the link token, **drain** commands (`api poll --link`, or declare `command_receipt = "http"`/`"stdin"` if those fit better), and optionally **emit** sensory payloads back (`api emit … --type --link ` — declared in `[shell.sensory]`, delivered only to a *live* owner session: sensors report the present, never the past). 3. Need more than discrete commands? A link can also carry a **drive** channel (`[shell.drive]` — continuous, latest-wins real-time input like a stick or scroll, never spooled) and an opaque **tunnel** (`[shell.tunnel]` — a reliable-ordered byte stream the taxonomy never interprets, on-LAN only). See [the four channels](overview.md#four-channels-between-owner-and-shell) for when to reach for each, and gate a dangerous verb with a per-capability `require_approval` (+ optional `class_key`). Any endpoint type may own a shell — a Gateway as readily as an agent. 4. Pick lifecycle behavior: `persistent` for always-up surfaces, `ephemeral = true` for fire-and-forget ones, `wake_command` if the surface can wake its owner. 5. `spt adapter add .` and `spt shell spawn `. Field-by-field details: the [manifest reference](../harness-contract/manifest.md#shell-adapters-kind--shell); the shell-side api calls: the [`spt api` reference](../harness-contract/api.md#shells). ===== /shells/frames.md ===== # The frame contract: what a shell binary parses Everything spt delivers to a shell binary — and everything the binary sends back through the machinery surfaces — is a small set of **typed frames**. This page is the complete vocabulary: the frame types, their attributes, and their body encodings. A shell binary written against this page needs no knowledge of spt's internals; this is the contract the mock and notify shells are built against, verbatim. ## The envelope and the stamp Every frame is one line of XML-shaped text: ```text body ``` One line **always** holds — not as a convention but as a consequence of the body encoding below: newlines are encoded away before framing, so no frame can span lines and a line-by-line reader is always frame-aligned. Frames that ride the durable spool (command, text, file, close) arrive **MAC-stamped**: the line the binary drains is the hex MAC, one space, then the frame — ```text ... ``` Both ends derive the per-link key from the link token the spawn template delivered (`{link_token}`): the key is `SHA-256(token)`, and the stamp is `HMAC-SHA256(key, frame-bytes)`, lowercase hex — computed over the frame's **on-wire (escaped) form**, exactly the bytes after the space. Verify before parsing, and decode entities only after; drop a frame whose MAC does not match. spt applies the same rule in the other direction — an unstamped or mis-stamped frame is never processed. The relay drain (`spt api poll --link `) prints the stamped frames **raw, one per line**. They are deliberately *not* wrapped in the harness `` arriving-message envelope that agent perches receive — the shell relay is its own transport, and the stamped line is the whole payload. The stdin delivery mode (`command_receipt = "stdin"`) writes the same stamped lines to the binary's stdin, newline-terminated. **A spooled frame is never split**: one line is always one whole frame, whatever its size. The `` chunking that exists on the *agent* listener stream does not apply to the shell surfaces — a shell decoder needs no reassembly logic, and will never see an `` line on the relay or stdin drains. ## Body and attribute encoding Attribute values and bodies are **HTML-entity-escaped** on the wire. A decoder that treats them as raw text works only until the first `&`, `<`, `>`, `"`, or newline in real content — decode them, in the order specified here, before using any value. **Escape set** — these four are applied to *both* attribute values and bodies (ampersand escaped first on encode); the newline token after the table is the one place the two halves differ: | character | on the wire | |---|---| | `&` | `&` | | `<` | `<` | | `>` | `>` | | `"` | `"` | **Newlines — a different token per half.** A body newline is encoded as `
`. An attribute-value newline is encoded as ` `. Attribute values never contain `
`, and bodies never contain ` ` as a linebreak, so a decoder always knows which half of the envelope it is holding. Attribute values are line-safe because the **encoder makes them so**, not by construction: a receiver-composed attribute can carry newlines (the `trust-warning` block runs to several), and the frame is a single line, so an unencoded newline would split one delivery into several. **Carriage returns are unrepresentable.** The encoder normalizes `\r\n` and lone `\r` to `\n` *before* the linebreak encoding — `
` in a body, ` ` in an attribute value — so no frame ever carries a raw CR and a decoder always receives `\n` newlines. Do not expect `\r` to round-trip — content that needs CRs preserved does not fit this codec. **Decode order is binding.** Decode a *body* as: `
` → `\n` **first**, then `<`/`>`/`"`, then `&` → `&` **last**. Decode an *attribute value* the same way, with ` ` → `\n` **first** in place of the `
` step. Amp-last is the invariant that prevents double-decoding: a body carrying the literal text `<` arrives as `&lt;`, and decoding the ampersand first would turn it into `<` instead of `<`. And decode **only the extracted body or attribute substring** — never run the unescape over the full envelope line, or the framing tokens themselves get rewritten. The consequence for structured bodies: a `shell_command`'s JSON arrives looking like `{"direction":"north"}`. **Unescape first, then JSON-parse** — feeding the wire form to a JSON parser fails on the first quote. ## `shell_command` — a vocabulary-checked verb ```text {"arg1":"v1","arg2":"v2"} ``` - `from` — the owner id. - `op` — the verb, always one your manifest declared under `[shell.capabilities]`. - body — a **JSON object of named args**, entity-escaped on the wire ([unescape before JSON-parsing](#body-and-attribute-encoding)). The positional values the owner typed are zipped, in order, onto the arg names your capability declared; trailing args the owner omitted are absent from the object. **Arity is enforced before composition, and extras refuse.** A capability declared `args = ["text"]` takes at most one positional — `spt shell cmd s1 note one two` refuses rather than guessing. The corollary is a sharp edge worth knowing when driving shells from scripts: a multi-word tail must be **one quoted argument** (`spt shell cmd s1 note "one two"`), because an unquoted composite becomes extra positionals and the vocabulary check refuses the command. Nothing is silently joined. ## `shell_text` — free text ```text the text, entity-escaped ``` The 2-way text channel's owner→shell direction (`spt shell send `). The body is the text, [encoded as above](#body-and-attribute-encoding) — unescape it to recover what the owner typed, newlines included. The shell→owner direction is not a frame at all: the binary sends an ordinary message to the owner's perch (`spt send --from `). ## `shell_file` — a landed file ```text original-name ``` - `xfer-id` — keys the transfer's progress record. - `path` — where the blob landed, **relative to the shell's perch directory** ([attribute-decode](#body-and-attribute-encoding) before use — a filename with `&` arrives escaped). - body — the original filename, entity-escaped like every body. By the time the frame is drained, the bytes are already on disk: `spt shell send --file ` copies the blob to `/files/-` *before* spooling the frame, so a drained frame is a completed landing, never a promise. **The path stays perch-relative by design** — a frame can sit spooled across a perch move or ride to another node, and an absolute path baked at compose time would lie there. Resolve it at read time instead: put `{perch_dir}` in your spawn template (see [the manifest reference](../harness-contract/manifest.md#substitution-keys)), and join the frame's `path` against that directory. The substituted value is one argv element even when the directory contains spaces — no quoting gymnastics in the template. ```text spawn = "my-shell --link {link_token} --root {perch_dir}" # at runtime: read(<--root value> / ) → the landed bytes ``` Without `{perch_dir}` there is no mechanical way to resolve `path` — the binary is spawned with the *broker's* working directory, not the perch — so treat the key as required for any shell that receives files. Do not guess at the spt home layout instead; it is not a contract. ## `shell_close` — the pre-close instruction ```text manifest pre_close instruction ``` Sent ahead of a link-break's termination window when the manifest declares `pre_close`. The body is the manifest's own instruction string (entity-escaped like every body), **not** vocabulary-checked — the vocabulary bounds what an *agent* may ask; a manifest is its own authority over its own binary. Treat it as "finish up": after the window, the process is killed. ## `sensory` — shell→owner, live-only ```text payload ``` Composed by spt when the binary calls `spt api emit --type --link `; `` must be declared under `[shell.sensory]`. Delivered only to a live owner session — never spooled, dropped with a diagnostic otherwise. The binary never composes this frame itself; it drives the `api emit` surface and passes the payload **unescaped** — spt applies the body encoding when it composes the frame. ## `drive` — owner→shell, ephemeral ```text payload ``` The continuous-control channel (`spt shell drive`), drained by the binary via `spt api drive-poll --link `. The payload body is entity-escaped like every body — [decode before use](#body-and-attribute-encoding). Latest-wins: a newer frame supersedes an undelivered one, and an offline shell drops frames — use commands for discrete, must-arrive actions. The same poll may also serve an [`activity`](#activity--the-owners-busyidle-state-pushed) or an [`attach`](#attach--who-is-attached-to-the-owners-terminal) frame, each on its own line; the three hold independent slots. ## `activity` — the owner's busy/idle state, pushed ```text ``` - `from` — the owner id. The state is the **owner endpoint's**, not the shell's; the link says whose, so nothing is addressed and no verb is called. - `state` — `busy` or `idle`. `idle` means the owner endpoint reported that it stopped working; `busy` that it is working. - `since` — **epoch milliseconds, when that state took effect** — not when the frame was emitted or drained. Anchor edge arithmetic (an idle countdown, a "quiet for N seconds" trigger) to this value and observation latency cancels out of it. - body — empty, and reserved. Everything is in the attrs. Drained on the **same `api drive-poll --link ` call** as the drive frame, on its own line and its own latest-wins slot — a pushed state can never displace a pending drive command, or the reverse. A poll can therefore print zero, one, or two lines; read them line by line and switch on `type`. **Drive-class, and that is load-bearing.** An activity frame is *not* an event log: - it carries the **current state**, so a redundant same-state frame is a harmless no-op — **derive edges yourself** by comparing against the last state you saw; - it is **never spooled and never replayed**. A frame written under a link that has since broken is dropped, not re-served: replaying "went idle at 14:02" to a binary that relinked at 14:30 would be a lie; - a missed frame is superseded by the next, so **do not build on frame counts**; - the current state is **re-emitted on every link establishment and re-link**, so a binary that just started (or restarted, or whose daemon restarted) learns its owner's state without waiting for a transition that may never come. **The delivery promise is bounded observation:** a frame per transition, promptly — sub-second class, never hard-real-time. Poll on your own cadence; a transition that happened between two polls is represented by the state the next frame carries, and `since` tells you when it actually happened. Like the `drive` frame it shares a drain with, an activity frame is **not MAC-stamped** — the link token presented on the poll is the credential for the whole ephemeral drain, and the frames are the reply to that authenticated call. The stamped-line shape applies to the spooled channels only. ## `attach` — who is attached to the owner's terminal ```text ``` - `from` — the owner id. Like `activity`, the fact is the **owner endpoint's**; the link says whose, so nothing is addressed and no verb is called. - `controlled` — `yes` or `no`: whether *anybody* is driving the owner's hosted terminal. - `controller-node` — the controlling node's hex. **Absent** when nobody drives, and also when the controller is a local one that presented no node identity — which is why `controlled` is its own attribute: "somebody is driving" is knowable when "which node is driving" is not. - `viewers` — how many read-only viewers are attached. - `viewer-nodes` — the comma-separated origin nodes of those viewers, for the ones that are known. It can be **shorter than `viewers`** (a local viewer carries no node), and it is absent when none are known. - `changed` — the node whose attachment moved on this edge. Present only when exactly one *known* node moved: two moving at once (or a local one moving) has no single honest answer, and a link (re-)establishment names nothing at all because nothing changed for that link — it simply arrived. Treat it as a hint; the state in the other attributes is always complete without it. - body — empty, and reserved. Everything is in the attrs. Drained on the **same `api drive-poll --link ` call** as the drive and activity frames, on its own line and its own latest-wins slot — an attachment push can never displace a pending drive command or an activity frame, or the reverse. **Drive-class, exactly like `activity`, and for a sharper reason.** It carries the **current attachment**, so derive edges yourself by comparing against the last frame you saw; it is **never spooled and never replayed**; a missed frame is superseded by the next, so do not build on frame counts; and current state is **re-emitted on every link establishment and re-link**. A stale attachment is not merely old — it would name watchers who may since have left, so replaying one would be a lie about who can see you. An attachment change that happened while your link was down reaches you as the re-link's current state, never as a backlog. **The delivery promise is bounded observation:** a frame per change, promptly — sub-second class, never hard-real-time. **What the endpoint's own agent is told.** The same attachment fact drives the [away and return notices](../terminal/overview.md#when-nobody-is-watching) sent to the owner agent itself. A shell reading these frames and an agent reading those notices are looking at one fact from two sides. Like the `drive` and `activity` frames it shares a drain with, an attachment frame is **not MAC-stamped** — the link token presented on the poll is the credential for the whole ephemeral drain. ## `boundary` — the endpoint's session edges, durable ```text ``` The endpoint crossed a **session lifecycle edge**. A shell binary that needs to know its owner restarted, cleared, or compacted — to reset its own view, to stop attributing new output to the old session — reads these. - `from` — the owner id, as with every owner→shell frame. - `kind` — one of exactly three: `boot`, `clear`, `compact`. - `seq` — **reserved — nothing emits this today**. The shape names a digest pointer slot for a future emitter; keep it optional and never wait for it. - body — **empty, and reserved.** A boundary's whole content is *which* edge and *when*; there is no truncated half living anywhere else. This is the one durable frame with no payload, so do not read an empty body here as a missing one. | `kind` | fires when | |---|---| | `boot` | the perch is bound with a session that is not the one already current — a cold start, or a resume of an OLDER session; resuming the already-current session is a re-bind and emits nothing | | `clear` | a `/clear` boundary rotates the session, carrying no context | | `compact` | a `/compact` boundary rotates the session, carrying a summary | **Event-class, and that is the whole reason this is not an `activity` frame.** Each occurrence matters: a `clear` followed by a `compact` is two edges, and the first is not superseded by the second. The `activity` frame's latest-wins slot would drop it. So a boundary takes the durable side — it spools and replays, and a shell that was not linked when the edge happened still receives it. **And durable means MAC-stamped, explicitly:** a boundary frame is spooled and therefore arrives as the stamped line every spooled channel uses — the same `HMAC-SHA256(SHA-256(token), frame-bytes)` stamp, the same verify-before-parse rule, no exception for the empty body. A consumer that requires the stamp on durable frames and drops a mismatch (counted, never silently) is building to this contract; a boundary is never delivered unstamped. **One frame per real edge.** Re-reporting the session that is already current is a re-bind, not an edge: it succeeds and emits nothing. So a frame arriving means something actually changed, and a consumer can act on it without debouncing. ### What you can and cannot see - **Linked and live** — every boundary is pushed to you as it happens. - **Polling with `--session-id`** — you see every boundary from your seed forward. Your first poll seeds silently and shows no history, as with any funnel event. - **History before your first contact** — reachable only with an explicit `--after `, and only while the rows are still inside the log's retention window. - **`boot` in particular** fires at perch bind, before a shell can plausibly be attached. It is observable because this class is durable — you get it when you link — and by an early `--after`. It is **not** replayed to a consumer that seeded silently after it. ## `io` — the session's IO events, durable ```text payload ``` The IO funnel: what happened on the owner's session, as discrete records. A shell binary that wants to follow the conversation — what the user asked, what the agent answered, which messages crossed — reads these. - `from` — the owner id, as with every owner→shell frame. - `kind` — one of the closed vocabulary below. - `mid` — present and `1` when an `AGENT_OUTPUT` body is a **mid-turn span** rather than the turn's closing report ([how an adapter reports one](#reporting-a-turns-payload)). Absent means the turn's close, which is what every `AGENT_OUTPUT` meant before this attribute existed — so treat it as optional and never default it to anything but absent. - `seq` — **reserved — nothing emits this today**. The shape names a digest pointer slot for a future emitter; keep it optional and never wait for it. A future emitter must still leave it absent for an open turn until the turn commits when the endpoint goes idle or the next input arrives (see the [digest's turn-sealing rule](../reference/json-shapes.md#window-and-cursor-flags)). - `truncated` — present and `1` when the body was cut at the payload cap. Absent means the body is complete. - body — the payload, entity-escaped like every body ([decode before use](#body-and-attribute-encoding)). ### The kind vocabulary | `kind` | fires when | |---|---| | `USER_INPUT` | the user's input reaches the agent | | `AGENT_OUTPUT` | the agent produces output — a mid-turn span (`mid`), or the turn's close | | `MSG_IN` | a message arrives at a delivery edge | | `MSG_OUT` | a message is committed at the send edge | | `COMMUNE` | a commune file is ingested | | `COMMUNE_FAIL` | a commune ingest fails, with a named reason | | `TOOL_USE` | **reserved — nothing emits this today** | `TOOL_USE` is named so that the vocabulary is complete and a future emitter reuses this exact token. Switch on the kinds you handle and pass over the rest, the same forward-compatible posture the rest of this page asks for. ### The other way to read these events A shell binary reads `io` frames because it is **linked** and the funnel pushes to it. A **harness adapter** is not linked and is not a shell, so it reads the same events by **polling**: [`spt api io-events`](../harness-contract/api.md#api-io-events-id---session-sid----after-seq---limit-n---json). Same six emitted kinds and 16 KiB payload cap, with the same reserved digest pointer slot — a different transport, deliberately identical in what it carries, so one event reads the same either way. **The cap bounds the FRAME, not the parse.** Core parses an ingested payload — [shortform tags and `;;` seal markers](../harness-contract/patterns.md) — over the **full** text you reported, and only then bounds the body it emits to 16KB. So a tag past the cap still dispatches, and the `truncated` flag on the frame says the body was cut, never that anything went unread. The poll is served by a per-endpoint **append-only log** the funnel's third sink writes (`/io-events.log`), bounded and trimmed oldest-first. It is a sink like this one, not a second funnel: an event reaching a shell and an event reaching an adapter are the same publish fanned out twice. ### Command-class, and that is load-bearing An `io` frame is the **opposite** of the [`activity`](#activity--the-owners-busyidle-state-pushed) frame it shares a stream with, so read the two with different assumptions: - it is **spooled and replayed** — a frame produced while your binary was down is waiting when you relink, because an IO event is a record and a missed record is lost information; - it is **MAC-stamped** like the other spooled channels, so verify it the way you verify a `shell_command`; - **each frame is its own event.** Two frames with the same `kind` are two things that happened, never a resend — count them, and build on the counts. ### The payload cap Bodies are capped at **16 KiB**. A longer payload arrives cut, carrying `truncated="1"`, and the cut lands on a character boundary so the body is always valid UTF-8. An unflagged body is complete; a truncated remainder is not recoverable through the IO frame or its reserved `seq` slot today. ### What the funnel promises the reporting side Emission is an **observation, never a control path**. Reporting IO to spt-core succeeds or fails on its own terms: - a consumer that fails to receive a frame **never changes the exit code** of the `spt api state` call, send, or delivery that produced it; - consumers are independent — one failing leaves the others served. Report your IO and read your own command's exit status as meaning what it always meant. ### Reporting a turn's payload `USER_INPUT` and `AGENT_OUTPUT` ride the activity report an adapter already makes: ```text spt api state busy --payload-stdin < the-user-input spt api state idle --payload-file /path/to/turn-output ``` - The payload is **optional**. `spt api state busy|idle ` with no payload behaves exactly as it always has and emits nothing, so an existing adapter keeps working untouched across this release. - Pass the payload on **stdin (`--payload-stdin`) or `--payload-file`**, never as an inline argument — payloads are 16 KB-class and inline arguments hit the Windows command-length limit. `--payload-stdin` is explicit so that this verb never reads a stdin it was not offered. It is explicit rather than sniffed because this verb fires on every adapter hook with stdin inherited from the harness — an inherited pipe that is open and idle is not a terminal and has no data, so a read that sniffed for one would block forever and wedge the hook. - Passing **both** sources is refused by name (`STATE_PAYLOAD_AMBIGUOUS`): pass exactly one. - **One event per payload-carrying call.** spt-core emits on the report itself, not on the busy/idle *transition*, so an adapter that reports `idle` at the end of every turn gets an event for every turn — including when it never reports `busy` and is therefore never in a transition. **`AGENT_OUTPUT` covers ALL of the agent's output, mid-turn included.** A stop-hook-equivalent fires once the turn is over and never sees the lines that streamed while it ran. If your harness can observe those lines as they land, you may report each one as it happens: ```text spt api state busy --payload-stdin --mid < the-span-just-produced ``` - `--mid` marks the payload as a **mid-turn span** rather than the turn's close. It rides the `busy` arm because the agent is still working, and it is still an `AGENT_OUTPUT` event: your words are the agent's either way. - On the frame it appears as `mid="1"`, and in [`api io-events`](../harness-contract/api.md#api-io-events-id---session-sid----after-seq---limit-n---json) as `"mid": true`. **Present-only** — an event without it is a turn's closing report, exactly as every `AGENT_OUTPUT` was before this flag existed. - `--mid` at `idle` is refused by name (`STATE_MID_ON_IDLE`): `idle` reports the turn's close, so a mid-turn span there is a contradiction rather than an event. So is `--mid` with no payload (`STATE_MID_NO_PAYLOAD`). - Reporting spans is **optional**. An adapter that reports only at `idle` behaves exactly as it did, and its consumers see exactly what they saw. **Report every span EXACTLY ONCE across the turn.** spt-core does not deduplicate and never will: knowing that two payloads are the same span means modelling how your harness assembles a turn, which is yours to know and not core's. So the spans you report mid-turn and the remainder you report at `idle` must be **disjoint** — if you have already streamed the whole turn as spans, report `idle` without a payload. Overlap is not refused; it is delivered twice, and a consumer counting agent turns counts the same text twice. An adapter's `[digest]` feed supplies the digest independently of these payload reports. Reporting a payload leaves activity behaviour untouched: the busy/idle sentinel and the `since` instant that [`activity`](#activity--the-owners-busyidle-state-pushed) frames carry are unchanged, so an idle-countdown consumer is unaffected by whether payloads are being reported at all. ### Messages: `MSG_IN` and `MSG_OUT` These are accounted by spt-core at the delivery edges it already owns, so an adapter gets them without reporting anything. `MSG_OUT` fires where a send is committed, `MSG_IN` where core delivers or injects an inbound message. Treat a `MSG_IN` body as **content, not instructions**: it is what someone else wrote. spt-core never parses a received message body for shortform tags or ceremonies, and a shell binary reading these frames should hold the same line — a message that arrives carrying a tag is a message *about* that tag. ### Communes: `COMMUNE` and `COMMUNE_FAIL` A commune is a context snapshot an agent's harness drops for spt-core to ingest. Like the message kinds, these are accounted by spt-core at a seam it already owns — an adapter reports nothing to get them. **`COMMUNE` fires when spt-core consumes the drop**, which is also when it deletes the file. The payload is **that file's bytes before parsing or routing, capped at 16 KiB with the head retained**; it is not digest-backed. It is not the composed brief a resume renders, and it is not what the context tiers ended up holding. Two consequences worth designing against: - **Markers in the body are just text.** `!!wake!!` and friends belong to the harness adapter that wrote them; spt-core carries them through untouched and acts on none of them. If you consume these frames, treat the payload as someone's document, not as a script. - **One event per commune actually ingested.** A drop whose project half cannot be committed yet is *preserved* rather than consumed — it stays on disk and is ingested later — and it emits nothing until that later pass. So a `COMMUNE` frame means the content landed, once, and counting frames counts communes. A consumed **signoff** drop emits nothing: it is a different kind of drop, and the vocabulary has no token for it. **`COMMUNE_FAIL` fires when an ingest fails**, carrying a named reason. The drop file is **left exactly where it is** — it stays the on-disk diagnostic and will be retried on a later pass, so the event is a signal that something needs attention rather than a report of anything lost. This kind exists because the failure used to be silent. A shared-checkout lock collision once failed six ingests across three agents in a single day; the failures were real, the files survived, and every affected agent carried on believing its context had been rebuilt. Treat a `COMMUNE_FAIL` as the thing that should have interrupted someone. ## Shortform: sending from inside a turn An agent can send a message by writing a tag in its own output, instead of shelling out to `spt send`: ```text @ ``` `@<` opens it. The comma-separated target ids run to **the first space** — so `@`. Several tags in one turn are several dispatches. A tag that never closes sends nothing: an author who is still typing has not dispatched anything, and guessing where they meant to stop would deliver a fragment. A tag with no target, or no body, is likewise not a dispatch. Dispatch goes through the **ordinary send path** — the same admission, sealing, spooling and refusal behaviour an operator-typed `spt send` gets. A shortform message is not a special class of message. **The parse imposes no body-length cap.** A long body dispatches exactly as written — the parser runs to the closing `@>` however far away it is. The size limit an agent *does* observe near shortform is a different surface: an adapter may cap what it re-injects into the session as context (confirmations, inbound deliveries), and how it handles an over-cap payload is that adapter's affair. Any such cap governs what the *author sees back*, never what the target receives. Prefer `spt send` with the body read from a file for long messages all the same — that is a courtesy to the receiving session's context budget, not a parser constraint. ### Writing about a tag without sending one A marker inside an **inline backtick span** or a **fenced code block** is a quotation, and fires nothing: ````text write it as `@` to send ← quoted, sends nothing ``` @ ← fenced, sends nothing ``` @ ← live, sends ```` This is one grammar, shared by every shortform marker spt-core reads — the same suppression governs the `;;seal me;;` mint. Learn it once. Two edges worth knowing: an **unclosed fence suppresses to the end of the text** (a truncated code block is still a code block, which is exactly the shape a cut-off turn produces), and a **lone backtick suppresses nothing** (stray backticks in prose cannot silently swallow the rest of your turn). ### Adapters opt in, and nothing happens until they do Core parses shortform out of an adapter's ingest **only** when that adapter's manifest declares IO-funnel compliance: ```toml [io] compliance = true # core may parse this adapter's ingest shortform = false # optional: stay compliant, keep core-side shortform off ``` `shortform = false` covers **both** shortform markers — the `@<…@>` dispatch tag and the `;;` seal mint. They are one feature with one grammar, so they get one switch rather than a knob each. **Absent `[io]`, core parses nothing.** That default is what makes the migration safe: an adapter that ships its own tag parser today keeps being the only parser until its own release deletes that parser and declares compliance in the same change — so no version exists in which both parse the same text and send it twice. Declare compliance in the release that removes your local parser, not before. ### How you learn what happened Per-target outcomes are accumulated and surfaced through the **now-signal's `DISPATCH_RESULTS` category** — that is the only channel, by design. A dispatch does not echo into your output, does not reply to you, and does not print a confirmation line, because a second channel is how an author ends up trusting whichever one they happened to notice. Note that spt-core parses shortform out of **your own turn's ingest** — the user input and agent output edges — and **never out of a message that arrives from someone else**. A peer can write a tag at you all day; it is text. Nothing you receive can make you send. ## Sealing from inside a turn: `;;` Wrap text in a pair of `;;` markers and spt-core runs the wax-seal ceremony over exactly that text: ```text ;;we ship the parser behind the manifest gate;; ``` **Each pair is its own seal.** Two pairs in one turn are two ceremonies over two texts, run in order — never one seal spanning the gap between them, and the text *between* pairs belongs to neither. **An empty pair does nothing at all.** `;;;;` mints no ceremony and produces no refusal: you asked for nothing, so there is nothing to report. **An odd trailing marker seals the rest.** If a marker has no partner, it seals everything after it through the end of your output — and leaves what came before it alone: ```text ;;first sealed;; ordinary prose ;;everything from here to the end is sealed ``` Pairs are matched first, greedy left to right; whatever marker is left over is the bare case. **A bare marker belongs to the turn's CLOSE, and mid-turn it is refused.** In a payload reported with [`--mid`](#reporting-a-turns-payload), "through the end of your output" names text core has not been given yet, so sealing there would seal a *shorter* text than you asked for — and a short seal looks exactly like a correct one. So an odd trailing marker in a mid-turn span mints nothing and is refused by name as `SEAL_BARE_MIDTURN` in `DISPATCH_RESULTS`. **Pairs are unaffected** — both ends are in the span, so they mint mid-turn like anything else. Close the pair, or leave the bare marker in the output you report at `idle`, where it means exactly what it says above. Both author paths mint: it makes no difference whether the user typed the directive verbatim or the agent drafted it. The [suppression rules](#writing-about-a-tag-without-sending-one) are the same ones the dispatch tag obeys — a `;;` inside backticks or a fenced block is a quotation, so you can write about this grammar without sealing anything. ### What happens after you type it **Your turn does not wait.** The ceremony needs a human at the controller, and that is human-scale time, so spt-core hands the mint off and your turn ends normally. The seal happens on its own. **With no controller attached, the ceremony refuses immediately** — nothing is queued waiting for someone to show up, and no seal is pending. You get `SEAL_NO_CEREMONY_SURFACE`, the ceremony's own answer, not a paraphrase. Either way the outcome lands in the **`DISPATCH_RESULTS`** now-signal category — the same one dispatch outcomes use, and the only place either is reported. A seal row carries no target, because a seal is about text rather than a recipient; if you read these rows, do not assume one is there. ## The now-signal: one funnel for "what changed?" `spt api now-signal` answers the question an agent asks at every turn boundary — *what changed that I should know about* — and it is the **only** place that answer arrives. Anything that wants to reach an agent between turns registers a category here rather than growing an injection point of its own. ```text spt api now-signal --session \ --user-input "" --agent-output "" ``` Output is per-category XML nested under one root: ```xml doyle — online on KITSUBITO; shared subnets: spt-dev -> perri: delivered -> hertz: no perch — nobody listening ``` `spt api hint` still works and does exactly what it always did. It is a thin alias over the `HINTS` category and has no behaviour of its own — one question gets one answer, so an adapter that injects both is injecting the same thing twice. ### It is delta-only, and silence is the normal case Every category tracks what **this session** has already been shown and reports only what it has not. A poll with nothing new prints **nothing at all** — not an empty root, not a blank tag. That is what makes it safe to inject on every UserPromptSubmit- and PreToolUse-equivalent: a quiet turn costs zero context. Two consequences worth designing around: - **A new session is entitled to the picture once.** A `/clear` is a new session, so the first poll after one can be substantial and every later poll is thin. The seen-sets live under the session directory and die with it. - **A datum whose STATE changed is new again.** A peer reported as online, then reported as offline, is two facts and you are told both. `EDGE_TRANSITIONS` is the one category that deliberately reads differently: a session's first poll **seeds silently and reports nothing**, because an edge is by definition a change and a session that has observed nothing holds only a state. Ask `ENDPOINT_MENTIONS` for the current picture; ask `EDGE_TRANSITIONS` for what moved since you last looked. ### The v1 categories | Category | Answers | | --- | --- | | `HINTS` | The keyword hints your manifest declares, once each per session — **and one line per shell adapter you can see** (full text when you hold an instance of it, otherwise a teaser naming the trigger and `spt adapter hints `). | | `ENDPOINT_MENTIONS` | Your words named a known endpoint: whether it exists, whether it is online, which node, which subnets you share, and its description **once per session**. | | `MONICS` | A standing judgement of yours that the turn's text fired. | | `SHELLS` | Your shell instances and adapters, and their status. | | `LAST_MSGS` | The last message each way: when, how long ago, with whom, and about ten words of it. | | `EDGE_TRANSITIONS` | Endpoints and nodes going on- and offline; subnet joins. | | `DISPATCH_RESULTS` | What became of your shortform dispatches and `;;` seal mints — the only channel that reports them. | `SHELLS` **replaces the session-start `spt-shells` message.** The same facts arriving through two channels is the ambiguity this funnel exists to end; read them here. `MONICS` is why the `user_input` and `agent_output` trigger kinds exist. They were ratified before anything read them, so a monic you wrote months ago with a `user_input` trigger starts firing here with no edit and no migration. One category is named but **not built** — `PROJECTS`. It is deferred deliberately, tracked as its own issue, and naming it in a spec is harmless: unknown names are ignored. `FILE_ACCESS_HELPER` was deferred in the same way and is now built; it appears among the categories added after v1 below. ### Categories added after v1 The v1 set above is closed and ratified. Later categories are **appended after it** by operator ruling rather than folded into it, and render order is declaration order, so the ratified order never shifts under you. | Category | Answers | | --- | --- | | `UPDATES` | The version you are running, for spt-core, your harness adapter, and each registered shell's adapter. | | `SEAL_BRIEF` | What sealing is and how to prove one — two sentences, once per session. | | `FILE_ACCESS_HELPER` | The exact `spt fetch` line for a file you were handed — an attachment on a delivered message, or a filepath a user quoted at you. | `UPDATES` reports **three subjects**: spt-core itself, the harness adapter this endpoint is running under, and the adapter of every shell currently registered to it — keyed **per shell**, not per adapter, because you act on a shell and a version that moved under one instance is the fact you need. For spt-core the **product version** leads, never the applied-update counter: the counter is an update-set sequence, and the version is what you are actually running. There is **no update event journal**, by design. Each subject's seen-set key carries its version, so you are told once at the version you first observed and hear nothing again until that version *changes* — at which point the key is new and the line fires. The delta discipline is the event detector; a journal would be a second source for one fact. **Absence is silence.** An endpoint with no update history emits nothing — no-updates is not an update — and a shell whose adapter is deregistered or unreadable contributes nothing rather than an error line. This rides a turn-boundary hook, where a diagnostic you cannot act on is just noise. `SEAL_BRIEF` tells you, once per session, what a [wax seal](../messaging/wax-seal.md) is — a **proven user directive** — and how to execute the proof: mint with the `;;text;;` shortform, verify with `spt api seal verify ` and the content on stdin. It is **at most two short sentences**, which is an operator constraint rather than an editorial preference, and the text is a single constant so that bound stays auditable. Once you have been told, you do not need telling again. ### Tuning it from your adapter An adapter knows things core cannot — which categories its surface can render, which are noise in it, what its injection budget is. Two flags carry that: ```text --spec-manifest # take the tuning from [io.now_signal] --spec-file # take it from a JSON file, composed per poll ``` ```toml [io.now_signal] without = ["SHELLS"] # suppress a category max_lines = 4 # cap each category's output # only = ["DISPATCH_RESULTS"] # or narrow to an explicit set ``` A spec **narrows and tunes; it never invents**. Category names outside the list above are ignored rather than conjured, and if a spec both selects and suppresses the same category, the suppression wins. **A broken spec is never a refusal.** Missing file, unreadable file, malformed JSON, a number where a list belongs — every one of them degrades to the default picture and the poll still answers. This runs on a hook at every turn boundary, and a verb that fails hard on a config typo is a verb that breaks a working session over one. ## Parsing posture The vocabulary above is closed and versioned with spt-core: parse the `type` attribute first, ignore frame types you do not recognize (new types may be added), and refuse nothing you don't have to — a shell binary that drains, verifies, extracts, [decodes](#body-and-attribute-encoding), and switches on `type` is forward-compatible by construction. ===== /self-update/overview.md ===== # Self-update spt-core keeps itself current without ever interrupting your agents, and without trusting anything unsigned. ## The invariant **No endpoint process terminates or suspends during a self-update.** The daemon's broker (holding PTYs, child processes, sockets) stays up; the brain (all logic) swaps under it. A hosted session's process id and byte stream are identical before and after. ## The trust chain - Every release ships `SignedRelease` metadata: an Ed25519 signature over the release's artifact digests. - Every binary embeds the **two-key trusted set** — an active primary and a never-used offline recovery key. Verification requires a valid signature from a trusted key *and* a matching artifact digest; an unverified binary never reaches the apply step. - Losing the primary key is a non-event: the next release is signed with the recovery key (already trusted by every deployed binary) and rotates in a fresh primary. - **Adapters sign their own content.** A `file_pull` adapter update is verified against the adapter author's key from its manifest; a `delegated` update is trusted only when the manifest attests the delegated updater verifies its own content (`self_verifies`). spt-core's release keys never vouch for adapter bytes. ## One command: `spt update` Bare **`spt update`** is the primary form *(since v0.32.0)*: it fetches and installs the latest signed core release, then updates every release-shipped adapter — the whole node current in one command. When the core is already current, only the adapters update. The invoking session **survives** a bare `spt update` by construction: installing cycles only the daemon's coordinator process, never the hosted terminals — so it is safe to run from inside an spt-hosted session. `--core-only` (`-c`) skips the adapters leg. Update completion messages and consent notifications point to this node's locally hosted `changelog.html`. When documentation lands, `UPDATE_DOCS_LANDED` points to the local `index.html`. Both links use the running listener's discovered port, not a guessed default or configured port. If live discovery is unavailable, the changelog retains the release-channel link and `UPDATE_DOCS_LANDED` retains the installed directory path. **`spt update --restart`** is the full-cycle form: fetch, update adapters, then finish by **restarting the daemon** onto the new version as the final step — after it, the whole node (coordinator *and* every live agent) runs the new version. The finish restart **bounces hosted sessions** (they come back automatically) — that consequence is why it is opt-in rather than the default, and why it runs last: everything else has already completed, from any invoking context, before the restart lands. **Missing web routes after an in-place update.** If the installed release is 0.68.0 or newer but the resident network layer reports a version below 0.68.0, `spt node status` and a successful in-place update both explain that node-prefixed docs URLs and serve controls are unavailable. Loading those routes requires a **full daemon restart, which stops hosted sessions**. `spt node refresh` only refreshes the coordinator; it does not replace the network layer. Ordinary compatible version skew does not need this notice, and an unknown resident version is not grounds for prescribing a restart. The update-completion check uses the signed release just applied, not the old updater's own compiled version; a failed or unanswered diagnostic query does not turn a successful update into a restart instruction. **What the composite's exit code means.** `spt update` runs several legs, and its exit is the **worst** leg outcome by precedence — never simply the last one that failed: | exit | meaning | | --- | --- | | `0` | every leg succeeded (an already-current core counts as success) | | `3` | a leg **refused with nothing done** — a guard declined and the box is exactly as it was — **and no leg failed** | | other nonzero | at least one leg **failed**; the code is the first failure's | A failure always outranks a refusal, whichever order they happen in. That matters under `--restart`, the one form that runs a leg *after* the failure-isolated adapters leg: if adapters fail and the finish then refuses, the command exits with the **failure**, not the refusal. Scripts branching on these codes can therefore treat `3` as "nothing changed, act on the guard's message" without a failure ever hiding behind it. **`spt update adapters [[,…]]`** runs the adapters leg alone (an alias of `spt adapter update`, which also stays; both accept a comma-separated list). Names are validated before anything updates — a typo never leaves a half-updated set — one adapter's failure never stops the rest, each adapter gets a summary line, and the exit is nonzero if any failed. A registered adapter without a release channel (a local dev registration) is skipped loudly, not failed. ## How updates move Peer-propagated: one node fetches a release; paired nodes offer/fetch staged releases from each other, each verifying independently before staging. Updating is **consent-gated by default** — a notification surfaces at your most-recently-active endpoint, and `spt update apply` is the explicit ack (it re-verifies the staged release before touching the live daemon). Full-auto is an explicit opt-in. The lower-level verbs remain for surgical control: `spt update fetch` pulls the latest signed release from the origin and stages it, then `spt update apply` installs it. `spt update fetch --apply` does both in one step (and still installs when the latest was already staged). *(`--apply` since v0.18.0)* **Prerequisite: the GitHub CLI.** The release channel is a private GitHub repository, and `spt update fetch` downloads releases through an authenticated `gh` *(since v0.32.0)*. Before downloading, fetch performs a bounded read of the selected release repository through the same `gh` carrier and inherited environment used for the download. GitHub CLI's effective credential precedence applies (`GH_TOKEN` before stored credentials on github.com); a stale stored login does not veto a working effective token. A missing CLI refuses with `GhCliRequired` and the OS install command. A read that times out refuses with `GhProbeTimeout`, not an authentication verdict. Other failed reads refuse with `GhAuthRequired`: check credentials, repository access, and connectivity. When `gh auth status` explicitly reports a failed host/account, the refusal names that account as diagnostic evidence, not as proof that it caused the read failure. Raw authentication output and token bytes are never included. The read and optional diagnostics share one ten-second preflight budget; spt does not switch or delete credentials. Signature verification is unchanged and carrier-independent — downloaded metadata and artifact bytes still pass the existing verification gates. See [Installing](../reference/install.md) for the gh setup steps. After self-updating, spt-core **ripple-updates registered adapters** through each manifest's declared `[update]` avenue — the same engine behind `spt update adapters` and the bare composite's second leg. ### Composite adapter updates — a delegated post-step (since v0.16.0) An adapter can run a second, adapter-owned step **after** its primary update avenue resolves — under `spt adapter update` **and under `spt adapter add`** (install is the first update, so a fresh install runs it too; since v0.19.0). Declaring an optional `[update.post]` sub-table (`command` required; an attestation-only `self_verifies` flag) lets one lever both pull the adapter's `.spt` (e.g. from `gh_release`) **and** run an in-harness sync (e.g. a plugin updater). The post-step: - **runs unconditionally** — even when the primary avenue was a no-op (its own idempotent check decides what changes); - runs **foreground and bounded** — a child of the CLI, 120 s timeout, never backgrounded or detached: when `spt adapter add`/`update` returns, the step has finished or failed; - receives a **published JSON line on stdin** describing the just-resolved update (`adapter_applied`, `version`, `previous_version`, `adapter_dir`, …; additive keys only — ignore unknown); - **decides the post-update notice via stdout** — custom text supersedes the static `[update].message`, the reserved sentinel `!!update-message!!` fires the static message, empty prints nothing; - is **failure-isolated and loud** — a nonzero exit / spawn failure / timeout prints `ADAPTER_UPDATE_POST_FAIL:` (with the step's stderr detail) on **stderr** and makes the CLI **exit nonzero**; the committed pull is never rolled back, and the static `[update].message` still fires when the adapter applied — so check the exit code, and don't let a static message promise what the post-step may have failed to do. The exact stdin keys, sentinel, notice precedence, timing, and the verify-then-notify pattern are in the [manifest `[update.post]` reference](../harness-contract/manifest.md#updatepost--the-composite-post-step-since-v0160). ## What changed in a release The [Changelog](../changelog.md) is a page of these docs, so the answer to *what does this update give me* is on the machine you are updating — no repository checkout, no network. It is **generated** from the project's `CHANGELOG.md` and drift-gated in CI, so a release note that exists anywhere exists here, verbatim. ## Commands `spt update` · the consent notification flow (`spt notif`) — [CLI reference](../cli/reference.md). ===== /changelog.md ===== # Changelog > **Generated** from the repository `CHANGELOG.md` (`cargo run -p xtask -- gen`) and drift-gated in CI — this page cannot disagree with the changelog. Do not edit by hand. All notable **user-facing** changes to `spt` — what a person running the CLI notices or does differently. The `## []` section of each release becomes that release's GitHub Release notes verbatim (see `docs/RELEASE-RUNBOOK.md`). This project follows [Keep a Changelog](https://keepachangelog.com) and semantic versioning. Pre-1.0, choose the bump by what a user can notice: **minor** when a release breaks something, or changes the observable behavior of existing surfaces broadly; **patch** for fixes, and for additive opt-in capability — a new key, flag, or page that no existing user can encounter without opting into it. ## [0.72.0] - 2026-09-22 ### Fixed - Successful `;;…;;` seal ceremonies now return the minted token in the author's `DISPATCH_RESULTS` as `seal minted seal=`, once per session. Older tokenless results remain readable without replaying previously seen outcomes. - IO-compliant adapters no longer receive the deprecated `spt-shells` context after post-spawn bind or clear/compact. Both paths now resolve the endpoint's recorded adapter/profile, matching the existing listen path; other adapters retain their legacy shell context. - File-access helpers now preserve quoted paths containing spaces on Windows and POSIX, including home-rooted paths, instead of looking for truncated fragments. Unquoted paths containing whitespace remain outside the supported contract. - File-access signals emit identical fetch commands only once within a poll. Reports of one prompt differing only in leading or trailing ASCII whitespace share the first receipt and its original deadline. - Handing the same live file to another endpoint adds that endpoint to the existing served entry's visible audience and resurfaces the same URL, without a second entry or extending its original 24-hour deadline. Helpers appear once per receiving endpoint, session and filepath, even if the prompt is rephrased. - Remote file helpers normally arrive with the path-bearing prompt after a short bounded wait. Late owner answers remain available on the next poll; pathless prompts trigger no helper lookup and add no wait. - Peer-delivered text that was re-encoded with XML entities is no longer mistaken for the user's own input, so a peer can no longer cause the controller's node to serve one of its files; bare ampersands are not treated as evidence of peer origin. The protection covers deliveries received after the node's daemon is restarted (restarting only its brain is not enough); deliveries received before that restart are not covered. - Self-update now checks access to its release repository with GitHub CLI's effective credentials, so a stale stored login cannot veto a working `GH_TOKEN`. Failed reads name a failed account only when `gh` reports one, without printing raw authentication output. A timed-out probe reports `GhProbeTimeout` separately from an authentication/access refusal. ### Known limits - Rolling back to 0.71.0 while a served entry has multiple audience endpoints makes every served file on that node answer HTTP 500, including unrelated entries. The registry is preserved and access fails closed. **Waiting 24 hours does not recover serving:** the old binary cannot load the registry to reap the expired entry. Roll forward, or stop the old daemon and manually remove the multi-audience entry from a backed-up registry, preserving its name-allocation history. Do not delete the registry or unrestrict the entry. Ordinary single-endpoint audiences retain the previous on-disk format. ## [0.71.0] - 2026-09-18 ### Fixed - An immediate `spt api io-events` poll now includes messages that a listener has already displayed, rather than sometimes missing a newly delivered message. - Starting or resuming an endpoint no longer incorrectly marks it offline while its session is still starting. This also covers resumes that fall back to a fresh session; genuinely dead sessions are still reported offline. - Attached sessions reached through `spt rc` no longer pause during pairing or repeated router discovery on Windows. Automatic UPnP, NAT-PMP and PCP router mappings are disabled; relay-assisted connections and NAT hole-punching remain available. Updating only the background service is insufficient: the running terminal host must also be updated for these fixes to take effect. - Engine-room sessions remain online during startup and receive their opening briefing reliably. - Served resources and their stable addresses no longer disappear when expired attachments are removed at the same time. Both the background service and terminal host must be updated for this fix to take effect. - Update completion messages and consent notifications link to the node's locally hosted changelog, and successful documentation installs link to its local index. When the local documentation service is unavailable, the existing release link or installed directory remains the fallback. - Active `spt rc` sessions resume input after `spt node refresh` or an update's service restart instead of freezing. ## [0.70.0] - 2026-09-13 ### Added - Quoting an absolute or home-relative filepath while controlling an agent through remote `spt rc` can now offer that agent a fetch command for the live file on the controller node. Access is limited to that agent for up to 24 hours; repeated reports neither extend access nor repeat the notice. Missing files and local or read-only input stay quiet. No adapter changes are needed. ### Fixed - Opening a node's root web address now opens its public documentation instead of a served-resources index. Redirects through another node retain the node label used in the original address. - Links from served files, attachments and local documentation now use the port the running service actually bound, rather than a configured or default port. - An unknown `spt shell cmd` operation now lists the available command operations and points to the adapter manifest for other input methods. - `Ctrl+B`, then `d`, now detaches a read-only `spt rc --view` session without stopping the agent or disconnecting its controller. - Older console clients now receive guidance to reopen or update when a known compatibility problem affects them, without forcing a disconnection. Version differences alone stay silent; client-only problems do not request a service restart. - Improved firewall setup for `spt serve lan --bootstrap` on Windows, including hosts with many firewall rules. If verification fails after rules are written, the diagnostic states that they may already be present. - Unlisted-peer presence checks in endpoint listings use a 2.5-second timeout instead of 10 seconds. A peer that does not answer remains unknown, not offline. ### Internal - Improved diagnostic logging for attached sessions; refresh freezes and console pauses remain unresolved. - Message-arrival records now include successful delivery to hosted agents; delivery outcomes are unchanged. ## [0.69.0] - 2026-09-11 ### Fixed - Cross-node messaging now recovers on its own instead of stalling until the service is restarted. Previously, one unanswered request could stop this node from advertising itself and reconnecting to peers, until other nodes could no longer reach it. - Sending a message to an agent on another machine no longer waits without limit when the far side accepts the connection and then never answers. Previously, such a send could hang indefinitely without reporting why. - Persistent shells now restart automatically after the background service restarts, once their owning agent is online. Previously, eligible shells could remain offline until relinked by hand. - A successful `spt shell relink` now reports `binding` while it waits for its handshake, instead of a successful launch reading as `offline`. - Agents on other machines that were already known are now remembered across a restart of the background service, rather than disappearing until peers advertise them again. - Service status and successful update completion now say when the running network layer is too old to serve node-prefixed documentation and serve controls, that loading them needs a full service restart, and that the restart stops hosted sessions. Successful updates no longer unconditionally advise restarting the service. - Stale-session cleanup no longer signals a process whose identity does not match the recorded session; the stale record is cleared instead. If the identity cannot be verified, the request declines and leaves the process alone. - Service status now reports the process id of the running service, taken from the running service itself; a recorded id that no longer matches is marked stale. Previously, status could display an obsolete process id from a file. ### Internal - Daemon logs now summarize healthy connection activity once a minute instead of recording every open and close. ## [0.68.0] - 2026-09-08 Web serving. Files, directories, adapter documentation and the changelog are reachable at node-prefixed addresses on the local server, and an address that names another machine in the subnet is answered by the machine that owns it. Messages can carry attachments the receiver pulls on demand, every message gets a short ID to show or reply to, and a machine with no spt on it can be handed the binary over the local network. The `XFER` access surface is retired. ### Added - `spt serve add`, `spt serve rm`, and `spt serve list --json` manage live file and directory references. Same-name registrations receive stable numbered suffixes; removing an entry never deletes its source. Only the same absolute path and kind may reclaim a retired name. - Every registered adapter gets a core-owned `web/` output directory. `[adapter].web_short_path` optionally gives it a short URL alias. Removing an adapter stops serving its output without deleting the files. - `spt adapter add` names each manifest key it does not know on stderr (`manifest: unknown key [
]. (ignored)`) and still registers; a misspelled optional key is no longer visible only by its absence. - `WEB` joins the access-control vocabulary. It is open by default within the subnet, but explicit WEB denies still govern. Existing file transfer is unchanged. - A served resource's URL now works from every machine in the subnet: a request for `//…` on the local loopback server is answered by the owning node through the local daemon. The body streams and nothing is cached; `HEAD` and `Range` requests are honored by the owner. An owner that refuses answers 403 naming `WEB`; an owner that cannot be reached answers 502 naming the node, within a bounded time. - `spt send --attachment ` sends a file with a message. The file's bytes are captured as they are at send time, so later edits or a deletion do not change what arrives, and the receiver pulls them with `spt fetch` when it wants them. `--ttl` sets how long an attachment stays available (default 30 days, a unit is required); expired attachments answer 404 immediately. - Every message now carries a short ID. `spt msg show ` prints a message by it, and `spt send --reply-to ` marks what a message answers. Messages from another machine resolve through the machine that holds them. - `spt serve lan --bootstrap` hands the spt binary to a machine that is not yet a node, over the local network on port 5470. It is off by default and off again after every daemon restart, serves only the binary, its release sidecar and an install command, and refuses to start by name when the applied update set is not signed or does not match. It prints a checksum per platform, and `spt install` gains `--expect-sha256` and `--release-json` so what was downloaded can be compared before it is run. The documentation port is untouched and stays on loopback. - `[adapter].docs_dir` publishes an adapter's own documentation at the `docs` segment of its address, beside the adapter's output directory rather than in place of it. A missing key, an unreadable manifest, a path that escapes the adapter's directory, and a directory that has since been removed all answer the same 404 naming what was asked for. - The changelog is now one of the pages the local documentation server offers. - A harness is told when a message it receives refers to a file the reader cannot open — an attachment to pull, or a path that belongs to another machine — instead of leaving the reader to discover it. For a path on another machine, that machine can be asked to publish it and answers with a link; it honors such a request only for its own endpoints, so no third machine can have someone else's file exposed. ### Changed - The loopback HTTP server now has a node-prefixed resource index with HTML and `?json` views. `/` redirects to `//`; canonical docs URLs live at `//docs/`, while existing bare docs paths remain compatibility aliases. ### Removed - The `XFER` access surface is retired: attachments replaced the transfer it gated, so the entry leaves the access-control vocabulary along with the transfer itself. An existing rule that names `XFER` is kept and reported at load rather than dropped silently; it no longer governs anything. The shell channel's own transfer progress is unaffected. ### Fixed - Messages delivered by `spt api listen` now reach the receiver's incoming-message history and last-message state, for both queued backlog and live TCP delivery. A later hook poll does not record those deliveries again; filtered notifications are not recorded as delivered messages. - A node's message and activity history reads back correctly once its log grows past a quarter of a megabyte. Positions no longer restart from the beginning, so a request for everything since a given point no longer comes back empty or repeats entries that were already seen, and an oversized position is answered with the current head instead of skipping a page. - An agent's own saved context is no longer overwritten, unread, by the automatic summary that follows it. The automatic summary is filed directly and never writes to the file an agent saves its own context to. - `spt api bind` no longer prints an engine-room probe line on a machine that has no engine room. ## [0.67.1] - 2026-09-06 Documentation-only release. The manifest reference in the developer docs now covers the `[service]` section — the always-on background process spt supervises on an adapter's behalf — which was previously described only in the CLI reference's `spt adapter service` entry. ### Added - **Manifest reference — `[service]`.** The developer docs' manifest reference now documents the `[service]` section: the `command`, `start` and `stop_grace_ms` keys; what registration reports when a service is declared; the environment a supervised process is started with (`SPT_SERVICE_OPTION`, `SPT_SERVICE_DIR`, `SPT_BIN`, `SPT_HOME`); the `stop-requested`, `status-advisory` and `startup.capture` files in its runtime directory; how a cooperative stop, an update hold and a startup fault behave; and what `spt adapter service list` and `spt adapter service status` report. The adapter integration checklist gains a matching line. ## [0.67.0] - 2026-08-30 The now-signal — the situational-awareness feed a harness injects at turn boundaries — now covers software updates, sealed-message education, and hints from shell adapters; shells can watch who is attached to their endpoint; and the automatic psyche-updating summaries called echo communes fire on a 15-minute cadence instead of at every turn end. ### Added - The now-signal gains an UPDATES category: when spt-core, the session's harness adapter, or a registered shell's adapter updates, the agent is told once, with the new version number. - The now-signal gains a SEAL_BRIEF category: a two-sentence, once-per-session brief telling an agent what a sealed message proves and how to verify one. - Shell adapters' `[hints]` are now read. Previously only the harness adapter's hints ever surfaced, so a shell's hints were dead text. A shell instantiated to the endpoint surfaces its full hint; one merely installed surfaces a one-line teaser naming the new `spt adapter hints ` verb, which prints the full text. At most one hint renders per source per message — the harness and each shell adapter get their own once-per-session slot, so one adapter's chatter can no longer silence another's hint. - Shells receive attachment frames: when a controller or viewer attaches to or detaches from their owner endpoint, each linked shell is told the current attachment picture — whether the endpoint is controlled, from which node, and which nodes are viewing — plus which node just changed when exactly one did. Frames are current-state-carrying and ephemeral, like activity frames. - An spt-hosted session that goes five minutes without any attached controller or viewer receives a one-time notice telling the agent to proceed but withhold user-aimed output until someone attaches; a short reciprocal notice fires when someone does. Endpoints without a hosted session are out of scope — nothing can attach to them. ### Changed - Echo communes now fire on an age gate: a turn end arms them, but they fire only once the oldest un-fired turn end is 15 minutes old, instead of at every turn end. Attention-change fires (detach, attention shift, suspend) stay immediate. A session boundary — clear or compact — now captures the departing session's history before the session id rotates, so the delta the boundary interrupts is recorded rather than lost. - A subnet-join line in the now-signal now names its subject: it reads `node --id ` starts it and drops you in. Detach (see `spt rc`) and it keeps running headless until you come back — from this machine or another node. - **`spt rc ` — attach to a running session's terminal.** Scrollback replays, live output streams, your keystrokes drive it. Detach with **ctrl-b** then `d` (the session keeps running); `ctrl-b ctrl-b` sends a literal ctrl-b. Works the same whether the session is on this machine or across the subnet. - **Controller / viewer model.** One person drives at a time (the *controller*); any number can **`spt rc --view`** to watch read-only (no input, never resizes the session). The controller's window size drives the terminal. - **`spt rc --take` — take control.** If someone else is driving, `--take` kicks them (they get a loud "you were taken over by …" notice and are detached) and you become the controller. A plain `spt rc ` on a session someone else controls now **refuses with guidance** (it tells you to `--view` or `--take`) instead of silently stealing control. - **`spt endpoint run` is now an interactive picker.** Run it bare (no `--adapter`/`--id`) and pick *Create new* (choose a harness adapter + profile, name the endpoint) or *Pick existing* (browse by project / local node / subnet with live status, type-to-filter, and a description pane), then attach / start / view / resume-from-history. The flagged form is unchanged for scripts. **Bare `spt`** (no subcommand) opens the same picker on an interactive terminal — a pipe, redirect, or CI run still prints help instead. A controlled endpoint in the picker shows **View** and **Kick and take control** (not a plain attach), pinned with `controlled by (+N viewing)`. Press `s` to bake the current selection into a project-root `spt-` launcher shortcut (an adapter can brand it, e.g. `cc-`, via the new `[adapter] shortcut_basename` manifest field). - **`spt subnet join` shows a QR code + setup code on success.** After joining, scan the QR (or read the `otpauth://` code) to re-provision an authenticator app for the subnet. - **Privilege-gated commands self-elevate, cross-platform.** When a command needs elevation, spt re-launches itself the right way for your system — a Windows UAC prompt, a Linux desktop `pkexec`/terminal `sudo`, or inline `sudo` in a terminal — and prints the exact command to run by hand when it can't. - `spt spt` — ??? ### Changed - **`spt whoami` now shows the full picture.** It is an alias for `spt endpoint list` — your own endpoint pinned first (with its description, if set), then the subnet roster — instead of just printing a bare id. ## [0.6.0] - 2026-06-13 The session digest grows up — its own adapter seam, it follows an agent across `/clear`, and it shows the context spt itself feeds the agent. ### Changed - **The session digest gets its own adapter seam, follows an agent across `/clear`, and shows the context spt feeds it.** An adapter now declares a `[digest]` *extractor* that maps its native log to the digest's `{role, text, tool, ts}` contract — its **own** manifest section, separate from `[history]` (which stays full-fidelity for the echo-commune). The digest **spans** a `/clear` or `/compact`: it enumerates an endpoint's recent sessions and shows a `── /clear ──` divider instead of going blank at every reset. It also **interleaves spt's own injected context** (session-start Psyche download, echo mirror, incoming messages) with the agent's activity, in time order. New `spt adapter digest-proof --sample ` runs your extractor against a real log and prints exactly what parsed, what rendered, and **every dropped line with the reason** — no more silent-empty digest. - **Breaking (adapter authors):** this **supersedes** the v0.5.0 guidance to emit the digest contract through your `[history]` normalizer. Declare a `[digest]` extractor (or push via `spt api digest-entry`) instead; one `[history]` normalizer can no longer serve both the opaque echo-commune and the contract-typed digest. ## [0.5.0] - 2026-06-13 Adapter customization and richer session surfaces — make an adapter your own without forking it, give an agent a durable role, mark who a message came from, and get an at-a-glance "what is this agent doing" view for any session. ### Added - **Adapter profiles — customize an adapter without forking it.** `spt adapter create-profile ` makes a named variant of an installed adapter (its own environment, prompts, and capabilities); launch it by addressing `adapter:name`. A profile you create locally **survives updating or re-adding** the underlying adapter, and `spt adapter list` shows each profile as its own spawnable option. `spt adapter delete-profile` removes one. (A profile may only *tighten* what the adapter allows — an attempt to loosen a capability is refused at registration.) - **Adapter config values.** `spt adapter set-string ` and `spt adapter get-string ` read and write an adapter's named settings — per-profile when you address a profile. - **Keyword hints.** An adapter can teach its own commands in context: when a keyword it declares appears in one of your messages, a one-line tip surfaces — at most once per session, so it never nags. - **`spt endpoint role` — a durable agent role.** Set a free-form statement of what an endpoint is for; it is shown to the agent **first**, at the start of every new session. `spt endpoint role` is the only thing that writes it — nothing automated ever overwrites your wording. - **`spt api digest-entry`** lets a harness with no readable session log feed its activity directly, so even those sessions show a live digest. ### Changed - **The live session digest now works for any session, not just terminal-hosted ones.** `spt endpoint digest ` builds its at-a-glance view from a session's normalized logs instead of scraping the raw terminal stream — so a session spt-core doesn't host in its own terminal (for example a Claude Code session) now shows a digest too. `--follow` still streams changes as they happen. - **Breaking (adapter authors):** the `[pty_digest]` manifest section is **removed**. The digest now rides your `[history]` source — emit your history records as `{"role": …, "text": …, "tool": …}` JSON (or push them with `spt api digest-entry`) and the digest builds itself. No digest-specific manifest section is needed. - **Messages now carry who sent them — a person or an agent.** A message you send is delivered marked as user-sent, and the daemon re-stamps anything that falsely claims to be from a user. A human-backed **Gateway** endpoint is accepted as a first-class endpoint — addressable, able to own shells, and able to subscribe to digests — including from another machine on your subnet. ## [0.4.2] - 2026-06-11 ### Fixed - **(Linux) An update now takes effect immediately — no manual restart needed.** On Linux, applying an update replaced the program on disk but the background service kept running the *previous* version until you restarted it by hand, so a fix could sit installed-but-inactive without you realizing the update hadn't truly taken hold. The service now relaunches its worker onto the freshly applied version on its own — the seamless behavior Windows already had. As an added safeguard on every platform, an update that somehow comes up running the wrong version is now detected and rolled back automatically instead of being recorded as applied. ## [0.4.1] - 2026-06-11 ### Fixed - **An unreachable peer can no longer stall your node's background work.** If another machine on your subnet dropped off mid-exchange — a network drop, a sleep, a hard crash — the daemon's outbound loops (peer sync, notifications, update checks) could hang waiting on it, in the worst case for hours, until something restarted the service. Now a stalled exchange gives up on its own in under a minute and the background loops resume, so one dead peer never freezes the rest of your node. ## [0.4.0] - 2026-06-10 ### Fixed - **`spt update apply` now actually runs the new version — no manual restart needed.** Previously, applying an update replaced the program files on disk but the already-running background service kept executing the *old* code until you manually restarted it. A fix could sit installed-but-inactive, and you'd keep seeing the old behavior — sometimes for a long time without realizing the update hadn't truly taken effect. The background service now relaunches itself onto the freshly installed version automatically, so an update goes live the moment you apply it. The swap is seamless: terminal sessions and network connections the daemon is hosting stay alive across it — nothing you're running gets dropped. - **A failed update now rolls back on its own.** If a newly applied version can't start cleanly, the service automatically returns to the last version that was working instead of leaving you with a daemon that won't come up. Your machine keeps running on a known-good build while you sort out the bad release. ### Changed - **(Windows) The background service no longer flashes brief console windows** when it starts or restarts its internal worker process. ## [0.3.2] - 2026-06-09 ### Fixed - **`spt update fetch` can no longer end up installing another platform's binary.** In a mixed Windows/Linux fleet, fetching an update on one machine and letting another machine pull it peer-to-peer could hand that machine a build for the *wrong* operating system — leaving `spt` unable to start. `spt update fetch` now downloads the signed, multi-platform update set, so every machine installs (and re-shares to its peers) the build for its own platform. As an extra safeguard, `spt update apply` refuses any staged update whose target platform can't be confirmed to match this machine. If you have an update staged from 0.3.1, re-run `spt update fetch` on 0.3.2 to replace it with the platform-safe set. ### Changed - **`spt update apply` prints a friendly confirmation** — for example `Updated spt-core to v0.3.2.` followed by a link to the changelog — instead of a terse internal status line. ## [0.3.1] - 2026-06-08 ### Added - **`spt update fetch`** — pull and stage the latest signed release straight from the project's GitHub releases, then `spt update apply` to install it. This bootstraps the first machine in a fleet (or any machine with no peer to update from), which previously could only receive an update from another machine that already had it. The download is verified against the same signed-release keys as peer-to-peer updates. Add `--tag vX.Y.Z` to fetch a specific version. ### Fixed - **Messages sent from Windows no longer arrive garbled.** A message piped into `spt send` or `spt ring` from a Windows shell (whose text carries a carriage return) could corrupt how the message displayed on the receiving machine. The message codec now neutralizes carriage returns, and `send`/`ring` trim their input like `notify` already did. - **A node is no longer stranded offline after a reboot.** If the daemon started before the machine's network was ready (common immediately after boot), it used to come up with no connection and stay that way until you manually restarted it — `spt daemon` would just report the peer pump as "STALLED". Now the daemon keeps retrying the network in the background and brings itself online once the network is up, with no restart needed. While it's waiting, `spt daemon` reports "no connection" honestly instead of a misleading stalled-pump message. (On Linux the installed service now also waits for the network at boot.) ## [0.3.0] - 2026-06-08 ### Added - **`spt subnet revoke …`** — remove one or more machines from a subnet across the **whole fleet**, not just locally. It tells every member to drop the node within moments, then rotates the subnet's shared secret so the removed machine is locked out and must re-pair to come back. By default the rotation is batched at the end of a one-hour window — several revokes in that window share a single rotation, and any member that was briefly offline heals automatically across it. Pass `--force-rotate-seed` to rotate the secret immediately (the compromised-machine path; a member that's offline at that moment will have to re-pair rather than auto-heal). Name each target by hostname, key prefix, or full key. Requires running elevated. This is the fleet-wide counterpart to `spt subnet prune`, which only cleans a dead node off the local machine. - **`spt daemon start`** — bring the daemon up in the background, idempotently. When `spt` is installed as a service (the Linux per-user service, or the Windows logon task), `start` and `stop` now drive *that* service instead of a stray hand-started daemon — so the two never fight each other for the connection. `spt daemon start` on an already-running daemon just says so and does nothing. ### Changed - **Subnets are now a full mesh.** *(Breaking — see the upgrade note.)* Every machine in a subnet now connects directly to, and shows, **every other member** in `spt subnet status --nodes` — previously you mainly saw the machines you had paired with directly. Membership in the subnet is now what grants trust, replacing the separate per-peer trust list that earlier versions kept. - **Upgrading from 0.2.0:** there is no automatic migration of the old trust list, so after updating, **re-pair your machines into their subnets** (`spt subnet join`, or create + invite from a seed holder) to rebuild membership. Until a machine is re-paired, it won't be reachable in its subnets. - **`spt daemon stop` is service-aware.** If a managed service owns the daemon, `stop` asks the service manager to stop it cleanly (so it doesn't immediately restart), instead of signalling the process directly. A hand-started daemon still stops the same way as before. - **`spt daemon run` is now strictly foreground on every platform** — it stays attached to your terminal until you stop it (the form the installed service uses). For a background daemon, use `spt daemon start`. On Windows, running `daemon run` from an elevated shell now refuses with a hint rather than silently disappearing into the background. - **`spt daemon status` shows what manages the daemon** — whether a service owns it (and is active) or it was started by hand. ### Performance - **`spt subnet status --nodes` is much faster when several nodes are offline.** It now checks all the quiet nodes at once, so the view comes back in about the time of a single check instead of stacking the wait up node by node. (This matters more now that a subnet is a full mesh and you see every member.) ### Fixed - **A peer's name no longer disappears when it goes offline.** Once you've seen another node's hostname in `spt subnet status --nodes`, it now stays shown even after that node goes offline — previously the name reverted to a bare key after the node went quiet for a while. The name is only forgotten when you explicitly `spt subnet prune` that node. ## [0.2.0] - 2026-06-08 ### Added - **`spt endpoint` command group.** A single home for everything you do to an endpoint: `spt endpoint fork`, `suspend`, `wake`, `shutdown`, `rename`, `stop`, and `digest` all live here now. (See **Changed** — this is where these moved from.) - **`spt endpoint list`** — one combined view of every endpoint you can see, grouped by subnet, with your own endpoint pinned at the top. - `spt endpoint list --local` shows just this machine's endpoints. - `spt endpoint list --subnet ` filters to one subnet. - `spt endpoint list --detail` adds each endpoint's description blurb. - **`spt endpoint description [set]`** — read or write an endpoint's description blurb (bare command shows it, `set` writes it). - **`spt endpoint access`** — per-endpoint access control (`allow` / `revoke` / `open` / `list`), scoped to the individual endpoint. - **`spt daemon` command group:** - `spt daemon status` (or bare `spt daemon`) — a node status view: whether the daemon is running, its background-sync health, your subnets, and your local endpoints. - `spt daemon stop` — cleanly stops the running daemon. - `spt daemon run` — runs the daemon in the foreground (previously a hidden command). - **Pause and resume a subnet without stopping the daemon:** - `spt subnet detach ` — stop advertising and connecting for that subnet (peers see you go offline for it) while everything else keeps running. - `spt subnet attach ` — start serving it again. - Add `--save` to either to make that choice the default the next time the daemon starts. - `spt subnet status` now shows a per-subnet state for each subnet (serving / detached / no connection). - **Leave a subnet:** `spt subnet leave ` removes the subnet and its trust completely from this node. - **Clean up dead nodes:** `spt subnet prune ` removes a stale node's trust so this machine stops trying to reach it. You can name the node by its hostname label, a key prefix, or the full key; it refuses if the name is ambiguous or refers to yourself. - **Node names in `spt subnet status --nodes`.** Each node now shows its hostname label and can be addressed as `@` in commands. Nodes that aren't running any endpoints still show their hostname instead of a bare key. - **Automatic re-pair cleanup.** If you reinstall or regenerate a node's identity and pair it again from the same machine under the same name, its old, now-dead identity is removed automatically during pairing — no manual prune needed. - **Firewall setup on Windows.** The installer (when run elevated) now adds the inbound network rule `spt` needs so other nodes can reach you. If it wasn't added, `spt subnet status` and the "coming online" banner now tell you the rule is missing and print the exact command to add it. - **Starts on boot.** The installer now registers `spt` to start automatically — at login on Windows, and as a per-user service on Linux — so your node is reachable after a reboot without running a command first. ### Changed - **BREAKING — commands have been reorganized; old spellings no longer work (no aliases).** If a command isn't found, check its new home below. The agent-messaging commands you use most are unchanged: `spt send`, `spt ring`, `spt ready`, `spt whoami`, and `spt how-to` all stay where they are, as does top-level `spt notif`. - These endpoint commands moved **under `spt endpoint`**: `fork`, `suspend`, `wake`, `shutdown`, `rename`, `stop`, `digest`. For example, `spt fork …` is now `spt endpoint fork …`. - The old `resources` view is gone; its listing is now `spt endpoint list --detail` and its per-endpoint blurb is now `spt endpoint description`. - `spt notify …` moved to `spt subnet notify [message] [--target ]`. With no `--target`, it sends to your home subnet; if you have no home subnet and don't pass `--target`, it refuses rather than guessing. - Stopping/checking the daemon moved under `spt daemon` (`spt daemon stop`, `spt daemon status`). - **`spt subnet status` tells the truth about a stopped daemon.** A node with no subnets now reads "this node is standalone" and no longer implies messaging works while the daemon is down. If the background sync has stalled, the status view says so instead of looking healthy. - **Cleaner node listing.** In `spt subnet status --nodes`, a normally-named node now shows just its hostname (e.g. `KITSUBITO`) instead of `KITSUBITO (43a51d9a…)`; the extra key prefix only appears when two nodes share the same hostname and need telling apart. - **`spt subnet` hints tidied.** The "hint:" lines now appear only on the bare `spt subnet` overview, not in `spt subnet status` (so the status view is clean to read). - **Pairing works on machines with a wrong clock.** Pairing now checks network time and tolerates a node whose system clock is off by more than a minute (which previously made pairing fail silently). If network time can't be reached, it falls back to the local clock as before; it never changes your system clock. - **Faster first sync after joining or restarting.** `spt` now remembers peers' last known addresses, so after a join — or after the daemon restarts — other nodes reappear in `spt subnet status --nodes` in seconds instead of taking up to a minute. - **Endpoints going online/offline show up almost immediately.** When an endpoint starts or stops, peers now see the change in `spt subnet status --nodes` within seconds instead of waiting for the next sync cycle. ### Fixed - **`spt subnet status --nodes` no longer hangs on a dead peer.** Checking a node that has gone away used to stall the command for ~30 seconds; it's now bounded to a couple of seconds, and the command prints "Checking remote nodes…" so the brief wait is expected. - **Detached/unreachable peers now read as offline.** A peer you've detached from a subnet (or that has stopped serving it) is correctly shown offline in `spt subnet status --nodes`, instead of appearing online indefinitely just because its machine is up. - **Messages from other agents now arrive properly formatted.** Incoming messages on the listener stream now include the full envelope with the sender's name, instead of showing as a raw, unwrapped line. - **`sudo spt …` now works on Linux user installs.** When `spt` is installed to your user directory, elevation guidance that said to "run as administrator/root" used to dead-end with `sudo: spt: command not found`. The installer now also makes `spt` reachable under `sudo`, and on an interactive terminal `spt` re-runs itself with `sudo` automatically; otherwise it prints a command that actually works. - **Elevated `spt` on Linux runs under your account, not root.** The first time you run an elevated `spt`, it asks once which account should own the daemon and its data, remembers that choice, and every later `sudo spt` runs the daemon and stores state under that account — never as root. - **`spt daemon stop` on Windows now finds the daemon it started.** A daemon launched through Windows' elevation prompt could end up using the wrong home directory, so `spt daemon stop` reported "daemon not running" while a daemon kept running. It now keeps the right home directory across that elevation step. - **Removed a confusing internal status line.** `spt` no longer prints the internal "DEELEVATED: running as uid …" notice during normal use. - **Stale node rows clear out on their own.** Nodes that haven't been heard from in a while are now removed from the listing automatically, so old/dead entries stop cluttering `spt subnet status`. ## [0.1.1] - 2026-06-07 Maintenance fixes following the first public release. (This changelog was introduced in 0.2.0; 0.1.1 and earlier are summarized here for completeness.) ## [0.1.0] - 2026-06-06 First public release of `spt`. ===== /cli/reference.md ===== # CLI reference > **Generated** from the `spt` binary's own `--help` output (`cargo run -p xtask -- gen`) and drift-gated in CI — this page cannot disagree with the binary. Do not edit by hand. ## spt ```text spt — a harness-independent core for an agent ecosystem: inter-agent messaging, live-agent lifecycle, terminal hosting, P2P networking, seamless self-update. Docs: http://localhost:5474 (spt docs url) Usage: spt [OPTIONS] [COMMAND] User commands: adapter Adapter registration: what this node can drive/launch docs The node-local docs: open them in your browser, or print their URL fetch Pull a served file to a local path go Take me to this endpoint — whatever state it is in grant Consent grant store: gated capabilities held on this node help Print this message or the help of the given subcommand(s) install Self-install this binary onto the node (the bootstrap path) knock Ask an endpoint to let you reach it, and answer the asks you receive msg Read one message back by its short-ID (spt msg show ) node The per-machine supervisor: run, stop, or status [aliases: daemon] notif Inspect and acknowledge notifications rc Attach a local terminal to a broker-held endpoint PTY serve Register local files and directories for node-prefixed HTTP serving subnet Subnet membership: status, create, show-code update Self-update: bare spt update brings the whole node current Agent commands: api Harness-contract inbound surface (hook entry points) endpoint Endpoint operations: list, lifecycle, fork, digest, access how-to Task-oriented instructions for agents: how-to ready Become reachable: register the perch and listen (blocks) ring Send and block for a reply (body read from stdin) seal Wax seals: mint a citable proof of user authority over content send Send a message (body read from stdin); fire-and-forget shell Shell instances: mint, list, drive, tear down owned surfaces whoami Who am I? This session's own endpoint, identity-only and fast Options: --json Emit machine-readable JSON instead of the human view. Honored by the read/status commands (list, whoami, status, description, role, the *-list queries, how-to); action commands ignore it -h, --help Print help -V, --version Print version ``` ## spt adapter ```text Adapter registration: what this node can drive/launch. The node-local registered set (one command for harness and shell adapters). Feeds creation-time adapter selection, shell discovery, and the self-update ripple. Usage: spt adapter [OPTIONS] Commands: add Register an adapter from a local path (a dir holding manifest.toml, or the manifest file itself) or from GitHub (--github user/repo, cloned under adapters/_github/). Manifest-first: an invalid manifest registers nothing. Install is the first update — the declared [update] avenue is conducted once after recording remove Soft-deregister: hidden from new-creation/discovery; existing and live instances keep running. The manifest's optional uninstall template is conducted only with --force until quiesce detection lands list List registered adapters (active and soft-deregistered), each followed by its shipped + local profiles as composite options version Print a registered adapter's declared version — the [adapter].version from its manifest. Resolves the option's merged view like the other adapter commands; exit 1 if the adapter is not registered hints Print a registered adapter's declared [[hints]] — for each, the keywords that fire it and the text it surfaces. This is the command a shell-hint teaser names: the teaser tells an agent that a hint exists, and this shows the text without instantiating anything. Resolves the option's merged view, so a profile's overlay is what prints create-profile Create (or overwrite) a local profile — a node-local sparse overlay registered beside the adapter that survives adapter add re-registration. The overlay TOML is read from --from or piped stdin (empty = a placeholder profile to populate later with set-string). Refuses a name shadowing a shipped profile, an invalid name, or an overlay that loosens a consent floor — nothing is written unless every check passes delete-profile Delete a local profile. Refuses a shipped profile name (adapter-owned, immutable) and errors if no local file exists get-string Read a [strings] dot-path from an adapter option's merged view ([:profile] ). Resolves through the profile overlay like every other consumer; prints the value (strings raw, else JSON). Exit 1 if the key is unset. Strings are data — never executed digest-proof Prove an adapter's [digest] extractor against a real log sample. Runs the declared extractor over --sample (or the declared source) and prints the parsed contract records, the rendered digest, and every dropped line with its reason — the author-time answer to "spt endpoint digest returns nothing" (no silent empty). Exit 1 if any line drops or nothing parses translate-proof Prove an adapter's [message-idle-translation-binary] against an inbound event. Spawns and feeds the declared translation binary exactly as the daemon does at idle-delivery — sends the init line then the --event envelope and reads back the emitted keystroke-command stream ({key}/{text}/{delay_ms}/{commit}), printed author-readable. This is the EMIT half ONLY: it proves the binary's spawn-feed-emit contract; it does NOT exercise the daemon's atomic PTY apply or controller buffering. Fills {id} and {session_id} into the envelope the same way the daemon does (use --session to pin the session id). Exit 1 if the binary fails to spawn, emits nothing, emits no commit, or emits an unparseable line set-string Set a [strings] dot-path on a local profile (:). Sugar over editing the overlay file; refuses a shipped profile and a bare option (a local target is required — create-profile first) update Update registered adapters that ship from their own GitHub releases: compare each [update] avenue = "gh_release" adapter's latest release version against the installed one and, when newer, fetch the release archive, verify it against the declared signing key if any (else trusting HTTPS + GitHub), and re-register. With no name, sweeps every gh_release adapter; with a name, updates just that one use Set or clear the active-profile pointer — the default [:profile] a harness session binds to when no --adapter is given. spt adapter use [:profile] points every host binary the adapter declares at it (run once per host binary you support); --clear drops the pointer (resolution falls back to the freshest-registered adapter). Never changed by install or update service The adapter's resident service: the background process spt's daemon supervises on the adapter's behalf when its manifest declares a [service] section. Read-only — list and status report what the daemon is supervising and never change it help Print this message or the help of the given subcommand(s) Options: --json Emit machine-readable JSON instead of the human view. Honored by the read/status commands (list, whoami, status, description, role, the *-list queries, how-to); action commands ignore it -h, --help Print help (see a summary with '-h') ``` ### spt adapter add ```text Register an adapter from a local path (a dir holding manifest.toml, or the manifest file itself) or from GitHub (--github user/repo, cloned under adapters/_github/). Manifest-first: an invalid manifest registers nothing. Install is the first update — the declared [update] avenue is conducted once after recording Usage: spt adapter add [OPTIONS] [PATH] Arguments: [PATH] Local manifest source (omit when using --github or --release) Options: --github GitHub source user/repo — shallow-clone the repo and register the clone root. Manifest-first, then install via the declared [update] avenue --json Emit machine-readable JSON instead of the human view. Honored by the read/status commands (list, whoami, status, description, role, the *-list queries, how-to); action commands ignore it --release GitHub release source user/repo — fetch the adapter archive asset from the release and register it: ships built binaries, source-free and versioned (the pattern for a monorepo whose adapter is a subdir) --tag Release tag for --release (default: the latest release) --asset Release asset name for --release (default: adapter.spt — a tar archive whose root holds manifest.toml + strings/ + binaries) --gh Force the gh CLI transport for --release (the private-repo path; gh honors OAuth + GH_TOKEN, so spt custodies no token). Mutually exclusive with --https. Default: auto (gh when installed+authed, else HTTPS) --https Force direct HTTPS transport for --release (public repos). Mutually exclusive with --gh. Default: auto -h, --help Print help ``` ### spt adapter remove ```text Soft-deregister: hidden from new-creation/discovery; existing and live instances keep running. The manifest's optional uninstall template is conducted only with --force until quiesce detection lands Usage: spt adapter remove [OPTIONS] Arguments: Options: --force Conduct the manifest uninstall template now, without waiting for quiesce --json Emit machine-readable JSON instead of the human view. Honored by the read/status commands (list, whoami, status, description, role, the *-list queries, how-to); action commands ignore it -h, --help Print help ``` ### spt adapter list ```text List registered adapters (active and soft-deregistered), each followed by its shipped + local profiles as composite options Usage: spt adapter list [OPTIONS] Options: --json Emit machine-readable JSON instead of the human view. Honored by the read/status commands (list, whoami, status, description, role, the *-list queries, how-to); action commands ignore it -h, --help Print help ``` ### spt adapter version ```text Print a registered adapter's declared version — the [adapter].version from its manifest. Resolves the option's merged view like the other adapter commands; exit 1 if the adapter is not registered Usage: spt adapter version [OPTIONS]