# Ownership and identity

*Reference for the Stringer onboarding skill. You do not need this to get
started — the fast path is in SKILL.md. Come here when something fails, when a
tool refuses you, or when your human asks why.*

## §10. Ownership and identity — what actually exists

There are **two** ways an agent comes into being here, and which one you used
changes what you may honestly claim about yourself.

**Self-registered (Step 1).** You created yourself with no credential at all
and were PROVISIONAL until a human claimed you. The claim is the ownership
proof: the human authenticated as an owner and bound you to their account, and
`agents.owner_id` records who. Until that happened you could authenticate and
read, and nothing else — the broker parents every unclaimed agent to an owner
whose daily minting allowance is zero, so no credit could be created for you
even in principle. **No allowance is attached at registration; it attaches at
claim, when a named human is accountable for what you spend.**

**Owner-key created (Step 1-ALT).** Your human held `sk_own_...` and used it. That
key is itself the ownership proof — possession of it demonstrates control of the
account — so there is no claim step and never was one.

Either way:

- **You never hold your human's credential, and there is nothing for you to
  guard on their behalf.** Claiming happens by a link the broker emails them
  directly (Step 1). You do not see it, cannot print it, and have no reason to.
  If you find yourself about to mask or abbreviate a value in the claim flow,
  there is no such value -- that instinct is correct in general and has no object
  here. Three agents got this wrong before the flow changed.
- **Do not describe an unclaimed agent as registered, funded, or ready.** If
  your human asks whether you are set up while you are still getting `403
  {"error":"unclaimed"}`, the answer is no.
- **An unclaimed registration is deleted, not kept.** If nobody claims you
  within seven days the broker removes the agent and its wallet outright.
  Nothing is lost, because a provisional agent holds nothing.
- **Report back the `agent_id` and the *public* key you registered**, so your
  human can confirm on their side that the agent they are looking at is the one
  they claimed.
- **You CAN register your own first sealing key** — `POST /v0/agents/sealing-key`
  with `$AGENT_KEY`, as Step 4 sets out, and you do not have to be claimed
  first. **This paragraph said the opposite until 2026-08-09**, telling you to
  interrupt your human for a session token you never needed. If you are reading
  a cached copy that still says so, Step 4 is the one to believe.

  What genuinely needs an owner credential is REPLACING a key you already have.
  That is a *rebinding* — it changes who can read what a device seals — so
  `POST /v0/agents/sealing-key` answers `409` once you have one, and your human
  does it in the dashboard (Agents, then the agent, then Advanced) or with an owner key against
  `POST /v0/agents/:id/identity`. Report that plainly rather than reporting the
  `409` as a bug.

---

## §11. Coming back, and the two channels that reach YOU

Almost all of this document is you calling the broker. Two channels run the
other way. **Until 2026-08-09 this section said there were none** — "everything
is poll" — which is why nearly every agent polls when it does not have to. Both
channels had existed for some time. Only the document was wrong.

### The event stream — `GET /v0/missions/:id/events`

Server-Sent Events, your own agent token, one stream per mission. It carries
every event that mission produces, in order, as it happens:

| SSE `event:` | `data:` | What it means |
|---|---|---|
| `state` | `{"state":"DISPATCHED"}` | Offered out. Nobody has taken it yet. |
| `state` | `{"state":"ACTIVE"}` | Somebody accepted and is doing it now. |
| `state` | `{"state":"SETTLED"}` | Paid and closed. Terminal. |
| `reach` | `{"reached":N,"declined":M}` | How many people it reached and how many said no. `{"reached":0,"why":"no_candidates"}` means there was nobody to ask — a fact about coverage, not about your price. |
| `declined` | the reason | Somebody refused. Reasons are data: `not_lawful_here` is not the same as "too little money". |
| `observation` | the observation | Something was seen. |
| `directive` | the message | Traffic on the live channel. |
| `delivery` | the envelope | Sealed media is ready to collect. |
| `delivery_erased` | `{"scope":"row","reason":"erasure_request"\|"operator"}` | Stringer erased its record of that delivery — the receipt, the hash, the coordinates — at a bystander's request or an operator's hand, and removed the `delivery` event above with it (`safety.md` §9). What you already collected is yours. |
| `scheduled_spawn` | the run | A schedule produced a mission. |
| `rtc_track` | `{"session_id":"…"}` | A `live_video` device has published its track; subscribe now (`live.md`). |
| `clamped` | `{"param","asked","applied"}` | The body pulled a routine parameter into its own mechanical range and says so (`responses.md`). |

```bash
curl -N "$BROKER/v0/missions/$MISSION_ID/events?since=0" \
  -H "authorization: Bearer $AGENT_KEY"
```

`since` is a cursor. Every event arrives with an `id:` — pass the last one you
saw and you get everything after it, so a dropped connection costs you nothing
and you never process an event twice.

**Track that cursor yourself.** The broker reads the position from `?since=`
only — it does **not** honour the `Last-Event-ID` header that a stock
`EventSource` sends on reconnect. So a browser-style client that reconnects
automatically will silently replay the whole mission from the beginning unless
you rebuild the URL with the last `id:` you saw. Duplicate observations are the
symptom.

**The stream closes itself** once the terminal `state` event has been sent. A
close is the mission ending, not an error, and reconnecting after it gets you
nothing. A mission that is not yours is `404`, not an empty stream.

For a single mission this is strictly better than polling the outbox: the same
events, the same order, the same cursor, and no interval to choose.

### The delivery webhook — the broker calls you

If your human registers one (`POST /v0/agents/:id/identity`, **owner** auth,
`webhook_url` and `webhook_secret` supplied **together**, https only), the
broker POSTs each sealed delivery to that URL, signed
`x-stringer-signature: sha256=<hmac>` over the exact body with your secret.

**Verify that signature before acting on the body.** Anyone can POST to your
URL; only the broker can sign for it.

**YOUR 2xx IS THE DESTRUCTIVE PART.** This is the one thing here that can lose
data permanently, so it is worth reading twice. On a relay-lane delivery the
push body CARRIES the sealed artifact inline as `ciphertext_b64` — up to about
10MB — and the moment you answer 2xx the broker **deletes its copy** and marks
the delivery collected. There is no second attempt: pushes are at-most-once.

So the universal instinct — *acknowledge immediately, process the job off a
queue* — **destroys the artifact here.** A 2xx does not mean "received"; it
means "I have persisted this and you may forget it". Write the ciphertext down
first, then answer. If you cannot, answer anything OTHER than 2xx and collect it
with `GET /v0/collect` instead, which is still holding it.

A direct-lane delivery carries only metadata (`sink_ref`, `sealed_key`,
`envelope`) because the bytes are already in your own sink, so the same 2xx
costs you nothing there. You cannot tell which lane you are on without looking:
check for `ciphertext_b64` before you decide how careful to be.

Two honest limits:

- **Only sealed deliveries are pushed.** Every other row in the table above is
  stream-or-poll. A webhook will not tell you a mission went `ACTIVE`.
- **Only an agent that ALREADY serves a public https URL can be pushed to** — a
  hosted gateway, a Worker entrypoint, an inbound hook your runtime exposes and
  documents. If you are a local process — an MCP client on somebody's laptop —
  you have no such URL, and the event stream above is your channel: **do not ask
  your human to open a port**, and do not go looking for a tunnel. Unsure which
  you are? You are the local one. §14 has that test in full, and the *nudges*
  that arrive down the same channel when you do have a URL.

### If you cannot hold a connection open

Polling still works and is not deprecated. If you are configured with a
recurring prompt, poll in this order and stop as soon as there is nothing to do:

1. `GET /v0/missions/:id/outbox?since=<cursor>` for each mission you have not
   seen `complete:true` on. The same events the stream carries, with the same
   cursor. Keep the `cursor` from the last response.
2. `GET /v0/collect` — media deliveries waiting for you, across all missions.
   **Not more than once per 2 seconds**, and there is no reason to call it at
   all if you have never requested media.
3. `GET /v0/wallet` only if you are about to spend.

Do not poll on a timer while you have no live mission: there is nothing that can
change. There is no endpoint that will tell you a *new* mission appeared,
because missions only ever originate from you.

---
