Multi-Agent Sessions

A multi-agent session lets a second agent join a session that another agent already started, with the join recorded as a signed, verifiable fact. Phase 1 of this model ships three CLI subcommands that wire one lifecycle: the host mints an invitation, a second agent joins against it, and the host countersigns the join.

The result is a participant envelope that carries two signatures: the joining agent's assertion of "I am joining" and the host's countersign of "I observed this join." Either signature alone is invalid, so a join cannot be forged by the joiner and cannot be fabricated by the host after the fact.

The lifecycle

host:    treeship session invite <session_id>   ->  prints an invitation blob
joiner:  treeship session join --invite <blob> --actor agent://...
host:    treeship session countersign <participant_artifact_id>

1. Invite

The host runs treeship session invite against the active session. It mints and signs an invitation with the keystore's default key, persists it under the artifact store, and prints an armored bootstrap blob beginning with -----BEGIN TREESHIP INVITATION-----.

Every invitation is restricted. You pick exactly one restriction:

An invitation also carries the granted capability action types, an expiry, a max_uses of 1, and a random nonce. The default lifetime is 1 hour and the protocol ceiling is 7 days.

2. Join

The second agent runs treeship session join with the blob and its own actor URI. The command:

• Decodes the blob and pins the issuer against the local SessionHost trust roots.
• Verifies the invitation signature, then checks expiry and restriction.
• Writes the invitation's nonce into the Approval Use Journal with max_uses=1, so a second join attempt fails through the journal's existing single-use path.
• Emits a single-signature, pending-countersign participant envelope and prints its artifact id.

3. Countersign

The host runs treeship session countersign with that participant artifact id. The command confirms the running default key matches the invitation's issuer, attaches the host countersign over the same canonical bytes, self-verifies, and overwrites the storage record with the finalized two-signature envelope.

A participant envelope is only valid once both signatures are present. Verification rejects an envelope that is missing the host countersign, carries too many signatures, has any signature that does not verify, or whose countersign key does not match the invitation's issuer.

Joining from another machine

Everything above assumes the joiner and the host run on the same machine, so the host can countersign straight from the local artifact store. Two agents on different machines -- a joiner's laptop and a host's server, say -- need one more step to get the pending envelope across, plus a liveness check that replaces "the host read it from local storage" with real proof.

host:    treeship session invite <session_id>                         ->  invitation blob
joiner:  treeship session join --invite <blob> --actor agent://... --out pending.json
                                                                        ->  send pending.json to the host
host:    treeship session mint-challenge                              ->  nonce + issued_at
                                                                        ->  send the nonce to the joiner
joiner:  treeship session answer-challenge <participant_id> --challenge <nonce> --actor agent://...
                                                                        ->  send the response file back to the host
host:    treeship session countersign --pending pending.json \
           --challenge <nonce> --challenge-issued-at <issued_at> \
           --challenge-response response.json

session join --out <file> writes the same pending participant envelope both to the local artifact store and to a file, so it can be copied (scp, a shared drive, pasted through chat, whatever channel you already trust for moving files) to the host's machine. The host then countersigns with --pending <file> instead of a participant id.

A minted challenge is valid for 10 minutes from --challenge-issued-at by default (TREESHIP_JOIN_CHALLENGE_WINDOW_SECS to change it). Past that window, or if the joiner's answer falls outside it, countersign refuses and tells you to mint a fresh one. Countersign is also single-use per invitation -- reserved in the host's Approval Use Journal before it signs, never released -- so a second countersign attempt against the same invitation is refused (has already been countersigned), and it refuses to finalize a join into a session that isn't open on this host right now, whether that's because the session was closed after the invitation was minted or because the invitation was never for a session started here at all. See treeship session countersign for the exact commands and error text.

The SessionHost trust root

The invitation issuer's public key is embedded in every invitation. Before treeship session join honors an invitation, that key must be pinned locally as a session_host trust root. Without the pin, a self-signed forgery would verify cryptographically but be quarantined by trust-root enforcement.

Confirm the key with the host out of band first -- a channel the invitation itself didn't travel on -- then pin it:

treeship trust add <key_id> ed25519:<pubkey> --kind session_host

Inspecting sessions locally

treeship dashboard is the read-only, localhost-only way to inspect sessions and their participants. It reads sealed .treeship packages from disk and surfaces trust status, agent membership, receipts, reports, and capabilities without requiring a hub. It also exposes JSON endpoints so the same data is scriptable.