15. Runners#

A runner is an optional service the operator installs and runs: on a machine, reaching ssh hosts, or in a cluster. It keeps one signed long-poll to the hub and starts or stops agents when the hub's desired state for it says so — harness X for agent N in clone Z of the project's repository, and stop; never an arbitrary command. What a runner may do at all (projects, repositories, harnesses, how many agents) is its own configuration, which the hub cannot widen. The hub stores desired state (the placement) and reported state and never starts, owns or reaches into a process; a project without a runner works exactly as before. The decision is context/scope.md, "A runner the operator runs may start agents; the hub still never does".

15.1 The runner as a caller#

A runner is a third kind of caller next to human and agent, owned by one human. It is not an agent profile and not a membership: it has no trust, no role, no scopes, no git identity, and is in no project's member list, org chart or all audience. It serves every project it is attached to (§15.4) with one credential and one stream.

15.2 Pairing#

Pairing is the join mechanism for the instance instead of a project: token plus code, single use, an exchange that answers with the credential as text/plain, a file the CLI writes and never prints.

• A new runner: name ([a-z0-9][a-z0-9-]{1,30}) is required and must not be the name of a runner the caller already owns (invalid, details.fields.name: "taken"); the runner is created at the exchange, so runner_id in the 201 is null. A re-pair: runner_id names a runner the caller owns, name is omitted (the runner keeps its name), and the 201 carries that runner_id.
• ttl_seconds is 60–900, default 900.
• attach lists projects to attach at the exchange; the caller needs members:admin in each at creation (forbidden, details.scope), and again at the exchange: a project where the creator no longer holds it is not attached, and Maity-Attached below says which were.
• pair_url, code and pair_line appear in the 201 only. Token (128 bits) and code (60 bits, Crockford base32 in groups of four) work like a join's: single use, expire with expires_at, the enrollment is burned after three wrong codes, and the exchange is rate limited per source address (10 per minute).
• Pairing lives on the public URL only: pair_url and pair_line are always built on MAITY_PUBLIC_URL, and a join host (§1.1) answers a GET of a pairing path with the 302 to the public start page and every other method with not_found.

POST /api/v1/runners/enrollments
{ "name": "home-laptop", "ttl_seconds": 900, "attach": ["oliver/maity"] }

201
{ "id": "renr-0002",
  "runner_id": null,
  "pair_url": "https://maity.team/r/Xb7…",
  "code": "K3PF-9QZD-1MWA",
  "pair_line": "maity runner pair https://maity.team/r/Xb7… --code K3PF-9QZD-1MWA",
  "expires_at": "2026-10-22T14:15:00Z" }

The exchange, run by maity runner pair in a terminal on the runner host, never in an agent session:

POST /api/v1/runners/pair/Xb7…
Content-Type: application/json

{ "code": "K3PF-9QZD-1MWA", "client": "maity-cli/0.3.0" }

HTTP/1.1 201 Created
Content-Type: text/plain; charset=utf-8
Cache-Control: no-store
Maity-Credential-Id: rcrd-0002-0001
Maity-Runner-Id: rnr-0002
Maity-Attached: oliver/maity
Maity-Hub: https://maity.team
Maity-Signing: required

mty1.rcrd-0002-0001.…

The body is the credential and nothing else. Maity-Attached lists the full names of the projects attached at this exchange, comma-separated, empty when none. A re-pair revokes the runner's previous credential in the same transaction (revoked_reason: repaired); attachments and placements stay. Errors as for the join exchange (§3.3): insecure_transport under the same rule and the same MAITY_ALLOW_PLAIN_HTTP flag (§2.5; the code is not consumed), code_invalid, not_found (unknown, used, expired, burned or revoked token), rate_limited; a name taken since the enrollment was created is invalid and leaves the enrollment unused. There is no pairing page: whatever the token, GET /r/{token} answers not_found and GET /api/v1/runners/pair/{token} answers method_not_allowed, so a URL opened in a browser leaks nothing. Maity-Hub is the public URL, and maity runner pair checks it by the rule of §13 before it writes anything.

15.3 Runners and the runner view#

On revoking a runner. What happens to the agents a revoked runner was running is a setting, chosen per project within the instance default (the maintainer's decision of 2026-10-22: the operator and the project's owner choose):

• When it applies. On POST /runners/{id}/revoke and on DELETE /runners/{id}. Never on a re-pair (revoked_reason: repaired): the new credential takes over the same placements. A revocation by the hub because the credential appeared in a payload (leaked_in_payload, §2.2) applies keep: the runner's key leaked, not the machine; the owner revokes again with agents: "stop" when the machine is in doubt. Such a later revoke, on a key revoked already (by a keep or for a leak), still applies stop: it revokes no runner key, and what it stops is added to what that key's revocation applied (the answer, its replay and details.stop below agree).
• The setting. on_runner_revoke in the instance settings (§16, MAITY_ON_RUNNER_REVOKE: keep (default), stop or stop_floor) and in each project's policy (§6.1: keep, stop or inherit, default inherit). inherit takes the instance value; stop_floor means stop and refuses a project's keep (§6.1), so the operator can make stop a floor rather than a default.
• The owner's override. agents in the body of the revoke or the DELETE: "policy" (default) applies each project's rule; "stop" applies stop in every attached project whatever its policy says — the machine is the runner owner's, and a revocation is often the answer to a machine that is no longer trusted.
• keep: placements keep desired and show the runner as revoked; the dashboard flags them (runner.credential_state: revoked on the placement's runner). The agents run on with valid credentials until a human revokes those (§10) or stops the placement, which emits agent_stop_requested (§15.10) that a cooperating agent honours. There is no time bound: the agent credentials live in the clones on the runner's machine, so keep trusts that machine with them for as long as nobody acts. Choose stop when the revocation answers a compromise. Nothing is lost mid-step.
• stop: in the same transaction as the revocation, every active placement of the runner in that project — closing ones included — gets desired: stopped and is closed at once (closed_reason: runner_revoked, §15.5; under DELETE it stays runner_removed), because no live runner credential can report it closed; every unused join with that runner_id (§15.9) is revoked, and an exchange of a join whose placement is closed answers not_found. agent_stop_requested is emitted for each, and the agent credentials those placements named are revoked stop_grace_seconds later (revoked_reason: runner_revoked, revoked_by the human), so an agent can park its work first; with agents: "stop" they are revoked at once, and so are those an earlier stop of this runner left to their grace (never another agent's). Each revocation emits credential_revoked (§15.10, reason: runner_revoked, to the agent and the owners), once, however many calls find it due. After that the agent has lost the hub: every call answers credential_revoked. The hub cannot end its process or its access to the forge; that stays the machine's (maity runner stop-all).
• What the runner learns. A runner that is still honest learns it from the answer to its next call: credential_revoked — only after the signature verifies (§1.3) — carries details.stop: [placement ids], the placements closed by stop, for as long as the revoked credential is the runner's latest; the runner stops those sessions before it exits. Under keep the list is empty.
• Back after stop. A re-pair brings the runner back, not its agents: each placement starts again by a new placement, or by restart with rejoin: true on one that is not yet closed (§15.6), and picks up a new join; the old credentials stay revoked.
• The answer of the revoke or DELETE carries on_runner_revoke: [{project, rule, stopped: [placement ids]}], limited to the projects the caller is a member of (as projects in the runner view).

{
  "id": "rnr-0002", "name": "home-laptop", "owner_id": "hum-maintainer",
  "presence": "online", "listening": true, "last_seen_at": "2026-10-22T13:59:40Z",
  "credential_state": "active",
  "credential": { "id": "rcrd-0002-0001", "created_at": "2026-10-22T13:31:00Z",
                  "last_used_at": "2026-10-22T13:59:40Z", "revoked_at": null, "revoked_reason": null },
  "version": "maity-cli/0.3.0",
  "capabilities": {
    "backend": "local",
    "max_agents": 4, "running": 2,
    "targets": [
      { "name": "local", "max_agents": 4, "running": 2,
        "reachable": true, "unreachable_since": null,
        "isolation": { "kind": "shared_user", "user": "oliver", "runner_separate": false } }
    ],
    "harnesses": [
      { "id": "claude-code", "version": "2.1.308", "available": true, "reason": null,
        "modes": ["interactive", "supervised"], "default_mode": "interactive",
        "models": ["opus", "sonnet"], "targets": ["local"], "confinement": "allowlist", "sandbox": "off" },
      { "id": "opencode", "version": null, "available": false, "reason": "binary_not_found",
        "modes": ["supervised"], "default_mode": "supervised",
        "models": [], "targets": ["local"], "confinement": "allowlist", "sandbox": "off" }
    ],
    "projects": ["oliver/maity", "oliver/sample"],
    "repositories": ["github.com/oliver-zehentleitner/*"],
    "require_local_approval": false,
    "reported_at": "2026-10-22T13:40:00Z"
  },
  "projects": ["oliver/maity"],
  "created_at": "2026-10-22T13:31:00Z", "updated_at": "2026-10-22T13:31:00Z", "removed_at": null
}

• credential_state: active, revoked (the latest credential is revoked and no live one exists), none (never paired). credential is the latest credential's record, never its value, and is shown to the owner only.
• presence, listening, last_seen_at are computed (§15.1). version is the client of the last hello.
• capabilities is what the runner last advertised (hello, PATCH /runner, §15.8). It is shown for choosing and checked when a placement is created; it is never a grant — the runner's configuration decides and the runner checks again. Every string in it is printable ASCII of at most 200 characters and rendered as text.
• targets[].isolation.kind: shared_user (every agent on the target runs as one OS user; runner_separate says whether the runner runs as another user), own_user (one OS user per agent), or pod. Which layout a runner uses on the operator's own machine is the runner's configuration (open: §12 1 of the design); the contract carries whichever it advertises.
• harnesses[].id is one of claude-code, codex, opencode, pi, hermes, kimi, cline, omp, stub. confinement: allowlist (the harness's own command allowlist), sandbox (no command allowlist, the harness's OS sandbox is the boundary — codex; a placement whose repository grant lists commands is refused for it, harness_refused), pod (no allowlist; the pod is the only boundary) or none (stub only). A runner advertises the confinement it actually enforces, never one it only configures. Whether the harnesses without an allowlist (pi, hermes, kimi, cline, omp) are offered at all, and where, is the runner's decision under (open: §12 4 of the design); the hub accepts any of them that a runner advertises. sandbox: on, off, n/a — the harness's own OS sandbox. available: false comes with reason (binary_not_found, version_failed).
• harnesses[].default_mode is the mode a placement gets when it names none. Which mode each adapter defaults to is the runner's (open: §12 5 of the design).
• models are names the runner offers; how the agents get model access (a login on the host, keys, a cluster Secret) is the runner's configuration and never reaches the hub (open: §12 2 of the design).
• projects (top level) are the projects the runner is attached to, limited to those the caller is a member of.

Instance-level actions — creating and using an enrollment, pairing, re-pairing, renaming, revoking, removing — are recorded on the rows themselves (created_at, used_at, revoked_at, revoked_by, revoked_reason, updated_at, removed_at), not as events; only their effects on attached projects are events (§15.10).

15.4 Attaching to projects#

A runner does nothing in a project until it is attached. An attachment is a row with its own id:

{ "id": "ratt-0004", "runner": { "…runner view…": "" }, "project": "oliver/maity",
  "attached_by": "hum-maintainer", "attached_at": "2026-10-22T13:31:05Z", "detached_at": null,
  "active_placements": 2 }

At most one active attachment per (project, runner). After a detach, new placements on that runner are runner_not_attached, and the runner keeps reading the project's closing placements (§15.8) until each is closed.

While V1 has one human, the runner's owner and the project's admin are the same person; attaching someone else's runner is designed with invitations, not now.

15.5 Placements#

A placement says that agent N should run on runner R with harness X in clone Z. It is the only thing the hub asks of a runner.

{
  "id": "plc-0003", "project": "oliver/maity", "project_id": "prj-7k2m9q",
  "project_aliases": ["oliver/maity-old"],
  "agent": { "id": "agt-b", "handle": "agent-b", "display_name": "Agent B",
             "avatar_url": "/api/v1/avatars/agt-b?v=e4d90b12" },
  "runner": { "id": "rnr-0002", "name": "home-laptop" },
  "target": null, "harness": "claude-code", "mode": "interactive", "model": "opus",
  "workspace": { "clone": "agent-b", "branch": null, "continues_existing": true },
  "desired": "running", "generation": 4, "rejoin": false, "stop_grace_seconds": 120,
  "approval": { "status": "approved", "request_id": null, "pending_change": null },
  "credential_id": "crd-b-0007",
  "reported_current": true,
  "active": true, "closed_at": null, "closed_reason": null,
  "created_by": "hum-maintainer", "proposed_by": null,
  "created_at": "2026-10-22T13:39:02Z", "updated_by": "hum-maintainer", "updated_at": "2026-10-22T13:58:10Z",
  "reported": {
    "state": "exited", "reason": null, "detail": null, "exit_code": 1,
    "observed_generation": 4, "restarts": 2, "retry_at": "2026-10-22T14:02:40Z",
    "crash_count": 2, "crash_window_seconds": 1800, "deadline_at": null,
    "since": "2026-10-22T14:02:00Z", "target": "local", "reported_at": "2026-10-22T14:02:01Z"
  },
  "session_hint": "tmux -S /var/lib/maity-runner/tmux.sock attach -t maity_maity_agent-b",
  "logs_hint": "maity runner logs plc-0003"
}

Who sees what.

Server rules.

• One placement per membership. At most one active placement per membership, so "where does agent-b run" has one answer. A second is placement_exists. A placement that creates a profile counts as the membership it will create, keyed (project, new handle) while it is active: at creation the handle is checked against the existing profiles (invalid, details.fields.handle: "taken", as at a join, §3.1, §6.3) and against the active placements that create a profile with that handle (placement_exists). This is a placement rule: the hub still allows two clones of one agent with two credentials — two instances (§6.17) — when they are joined by hand (§10).
• One placement per clone. At most one active placement per (project, runner, clone), whatever the target: on one runner a clone name in a project is one workspace and one identity. A second is placement_exists.
• A closed placement counts toward neither rule nor max_placements; neither does a refused one, which is closed.
• Carried-over credential. A new placement with the same (membership, runner, clone) as the latest closed one, whose credential is not revoked, inherits its credential_id; the runner then expects the file and does not join again.
• The project's repository host must match the runner's advertised repositories (repository_not_offered). The runner checks again.
• In a project that is archived, desired: running is project_closed. In plan and review creating a placement needs a reason (§6.1).
• Revocation stops the placement. Revoking the agent credential named by an active placement's credential_id, by any path (§10, the leak path of §2.2, member removal), sets desired: stopped in the same transaction; it does not close the placement.

Closing. A placement closes in one of two ways, by cause:

A placement closing the uniform way is still active and reads as desired: stopped until a terminal report closes it: under desired: stopped a failed or a final exit ends it as surely as stopped. DELETE of a placement that is already closing closes it at once (removed): the escape when a runner never reports. DELETE of a placement whose consent request is open closes it at once (removed) and withdraws the request. Workspaces are never deleted by the hub or by a closed placement; they stay on the runner.

15.6 Placement endpoints, proposals and consent#

POST /api/v1/projects/oliver/maity/placements
{
  "agent": { "handle": "agent-f", "display_name": "Agent F" },
  "trust": "member", "role": "coder", "reports_to": "agt-a", "areas": ["web/"], "capabilities": [],
  "briefing": "You own the dashboard's Runners view: …",
  "runner": "rnr-0002", "target": null,
  "harness": "claude-code", "mode": "interactive", "model": "opus",
  "workspace": { "clone": "agent-f", "branch": "main" },
  "desired": "running", "stop_grace_seconds": 120,
  "reason": "second pair of hands on web/ for the runner work"
}

• agent is {"id"} of an active member of the project, or — humans only — {"handle", "display_name"} for a new profile, with trust, role, reports_to, areas, capabilities and briefing as in a join (§3.1): validated at creation, stored, applied at the first pickup (§15.9). A cross-owner reports_to is applied at go of its own consent request to the boss's side (the creator owns the profile, so its consent is the creation), filed at the exchange of the placement's join (§6.2, "Across owners"); that request is separate from the placement's approval. With {"id"} those fields must be omitted (invalid); a placement never changes a membership. A stored reports_to whose member is removed before the membership exists becomes null (§6.2); every pickup builds its join from the stored fields as they are then.
• desired defaults to running. reason is required for a proposal and in plan/review.
• Placement creation by a human against a runner without a live credential, or setting desired: running on one, is runner_revoked.
• Beyond max_placements active placements: placement_quota.

Who may do what.

Proposals. What an agent's creation or change of spec does follows policy.spawn_requests (§6.1):

• off: forbidden.
• consent: a creation makes the placement with approval.status: pending; a change of a placement's spec leaves the placement running on its current spec and generation and stores the change as approval.pending_change. Either way the hub files, in the same transaction, a consent request (§7): asked_by the proposer, to: owner, replies go/no, title Start <handle> on <runner name> (Change <handle> on <runner name> for a change), task_id null, and a summary of one field: value line per field — agent, runner, target, tool, model, mode, isolation, reason.
• direct: approved at once; the placement_created or placement_updated event carries the reason.

Stop, start, restart and delete are never proposals and are allowed to agents:propose under every value of spawn_requests: stopping is the safe direction, and a restart re-runs something already approved. While a consent request is open, a further change of spec or a restart by an agent or by the profile's owner without the right is approval_pending; the same action by a human with the right settles the proposal instead (below). desired: stopped and DELETE are never refused.

Settling. Answering or withdrawing a request that carries a placement, or a human with members:admin who owns the runner acting on it, settles it in the same transaction:

Who may answer a placement's consent request follows policy.spawn_consent_by (§6.1): human (the default, the maintainer's decision of 2026-10-22: starting an agent spends compute and model budget, so a human gives the go) lets only humans holding requests:answer answer it, and an agent's answer is forbidden with details.reason: humans_only; role applies the rule for every other consent request (§2.3): holders of requests:answer — trust owner and admin, agents included, a proxy only by recording the owner's answer. Either way never the proposer (self_answer). Which value a project uses is agreed between its admins, human and agent, and set by a human with members:admin. Requests do not expire; an unanswered proposal stays pending.

15.7 Reported state#

The runner reports what is actually there, one record per placement and only when something changes. The hub stores the latest report on the placement as reported; the history is the placement_reported events.

The lists are closed; a code outside them, or a reason/state pair not in the table, is invalid. Adding a code is a contract change.

A rate limit is not a crash. When the supervised loop sees the harness exit for its provider's limit, the runner reports state: rate_limited, reason: quota, exit_code, and retry_at = the reset time the harness gave (or its own backoff, with detail: reset_unknown); retry_at is required with rate_limited (invalid without it, details.fields.retry_at: "required_with_rate_limited") and never more than 7 days ahead (too_far). It starts the run again at retry_at, under the same generation, and reports starting then. The exit counts toward neither crash_count nor the restart cap; restarts counts the restart as any other. The hub stores the report as the agent's limit (§6.12): until = retry_at, source: runner, harness the placement's, and clears it with the placement's next report that is not rate_limited. A harness exit the runner does not recognise as a limit stays a crash. rate_limited is its own state rather than exited with a retry_at (the restart policy's wait after an ordinary exit, §15.5) because it means something to the hub beyond the restart: it sets the member's limit, which drives availability and cover (§6.12), and it is outside the crash count; folding the two together would make every restart a limit or every limit a crash.

• Recognition is the harness adapter's and stays implementation-defined: which exit code, output line or file says "provider limit" and where the reset time is read from differ per harness and version. An adapter reports rate_limited only for a signal verified on a real run of that harness; anything else is reported as it would be without this section (exited, failed, counted as a crash). What the contract fixes is the report: state: rate_limited, reason: quota, exit_code the process's own, retry_at as below.
• retry_at is the reset time the harness named, in UTC, when it named one that is in the future and at most 7 days ahead; a named time further out is capped at 7 days. When it named none (or one in the past), detail: reset_unknown and retry_at is the runner's fixed backoff, independent of the restart policy: 15 minutes after the exit for the first consecutive reset_unknown limit of the placement, doubling with each further one (30, 60 minutes) up to 2 hours, and 2 hours from then on. The count resets when a run of the placement ends any other way, and with a new generation.
• Interactive mode. A harness in an interactive session usually stays open at its limit instead of exiting. The runner does not read the session for limits: the placement stays running, and the limit is declared from inside the session — by the agent with maity limit (§13), or by the human in the pane running the same command — which sets the member's limit with source: self (§6.12) and leaves the placement's state alone. If an interactive harness does exit and the adapter recognises the exit as its limit, the runner reports rate_limited as in supervised mode.
• Stopping. desired: stopped on a rate_limited placement (DELETE, detach, archive, revocation under stop) stops it normally: the runner cancels the pending restart, reports stopped (stopped_by_hub), and that terminal report closes the placement as any closing does (§15.5) — nothing waits for retry_at. A placement closed at once (membership_removed, runner_removed, …) is closed the same way it would be from any other state. Either way the hub clears the limit record the placement set, and emits member_availability_changed when that changes the member's state.
• Capacity. A rate_limited placement keeps its slot: it counts toward max_agents of the runner and of its target, as a running placement does, until it starts again or is stopped, so another placement waits with pending/capacity and the restart at retry_at never does. Its member is limited, never available (§6.12).

Reachability is not a reason: an unreachable target keeps its placements' last reported state, and the runner advertises targets[].reachable and unreachable_since instead. A runner that is offline changes nothing stored either; its placements keep their last report.

The owner is asked when an agent stops. A report that moves reported (§15.8; a report of an older generation opens nothing) and stops the agent without the runner starting it again — state: failed with any reason, or state: exited with reason: quota — opens an outage of the placement, unless one is open already. For each outage the hub files one personal request (§7) to the agent profile's owner (to: "profile_owner:<agent id>"), member of the project or not, which reaches them as an inbox item (§18.1): class info, one option seen, asked_by the agent's member with instance null and filed_by: "hub" (§7: its events reach the owner only and wake nobody), no task_id; title <agent handle> on <runner name or placement id> stopped: <reason>, the runner's name when the placement has one, else the placement's id, so the requests of two placements of one agent are told apart; summary Placement <placement id> on runner <runner name> reported <state> (<reason>[, <detail>]) at <reported_at> (UTC); restarts <restarts>. Later reports of the same outage — the same failure reported again, another failing reason — file nothing and change nothing on the request. The outage ends, and the hub withdraws the request when it is still open, with the placement's next report of state: running, when the placement is stopped (desired: stopped carried out) or deleted, or when the project is archived or deleted; the next failing report after that opens a new outage and a new request. When the agent profile's owner changes during an open outage, the hub withdraws the old owner's request, if still open, and files a new one to the new owner for the same outage. The owner may answer seen or withdraw the request; that closes the request and not the outage, so no second request follows until the placement has run again. rate_limited opens no outage: the runner starts the agent again at retry_at by itself, and the member's limit (§6.12) shows it. Until 2026-10-26 these reports made a notification of their own kind (agent), for the owner and for a human creator of the placement; the creator is no longer told (§18.1).

15.8 Runner endpoints#

Runner credential, signed (§15.1).

{
  "server_time": "2026-10-22T13:40:00Z",
  "runner": { "id": "rnr-0002", "name": "home-laptop", "session_id": "rses-0002-0007" },
  "projects": [ { "slug": "maity", "full_name": "oliver/maity", "name": "Maity",
                  "repository": "https://github.com/oliver-zehentleitner/maity" } ],
  "placements": [ { "…placement as the runner reads it…": "" } ],
  "cursor": 5120
}

A placement as the runner reads it:

{
  "id": "plc-0003", "project": "oliver/maity", "generation": 4, "desired": "running",
  "agent": { "id": "agt-b", "handle": "agent-b", "member": true, "credential_expected": true },
  "harness": "claude-code", "mode": "interactive", "model": "opus",
  "target": null,
  "workspace": { "clone": "agent-b", "branch": null,
                 "repository": "https://github.com/oliver-zehentleitner/maity" },
  "rejoin": false,
  "stop_grace_seconds": 120,
  "seq": 41
}

• agent.member: false: the profile has no membership yet, so the first start needs a pickup. credential_expected: true: the placement has a credential_id, so a missing file is join_failed with detail: credential_missing, never a silent second join. seq is the highest report counter the hub has stored. Never in this shape: briefing, the join URL or code, approval, created_by.
• What a runner reads. Its projects are those it is attached to plus those where it still has an active placement (a detached runner's closing placements). projects in the packet and /runner/placements use that set; a placement or project outside it is not_found. /runner/events reads every project the runner has ever been attached to: an event names the runner only while it concerns it, so a detachment and what follows it still reach it.
• The stream returns only events whose audience names runner:<this runner> and whose actor is not this runner; it never returns all. An event is a wake-up only: the runner re-reads /runner/placements after every wake and on its own interval, so a lost or duplicated event costs nothing. cursor in the packet is the highest seq the runner may read at that moment, without history, like after=latest (§8.3). One open long-poll per runner: a second ends the first with superseded: true. While it is open the runner is listening.
• Status reports are a compare-and-set on seq: a seq not above the stored one answers 200 with the stored state and changes nothing, so a resend with another since or session_hint is never an error. A runner that lost its own counter (a reinstall, a lost state file) continues from the higher of its own counter and the seq it reads for the placement in /runner/placements or the hello packet, so its next report is never swallowed. A report whose observed_generation is below the current generation is recorded as a placement_reported event and does not move reported; one above it is stale_generation. A terminal report (stopped, failed, or exited with retry_at: null) on a placement that is closing closes it (§15.5). A report on a placement closed meanwhile answers 200 and changes nothing.
• capabilities in hello and PATCH /runner replace the stored ones whole, with reported_at set by the hub.

Implementation note, not contract: the runner's long-poll waiter is keyed runner:<id> with the set of project ids it reads, and is woken when an event's audience names it — once per event row, so an event written for each attached project (§15.10) wakes it once per row. Like the agent long-poll, it depends on the one-replica rule (§8.3).

15.9 The join pickup#

POST /api/v1/runner/placements/plc-0003/join
{ "observed_generation": 4 }

201
{ "join_url": "https://maity.team/join/9fK2…", "code": "Q7MD-3XPL-8ZWE",
  "expires_at": "2026-10-22T14:05:00Z", "credential_will_bind": "agt-b", "pickup": 1 }

• The hub creates a join for the placement's agent, as §3.1 would: for a new profile with the stored join fields (the exchange creates the profile and the membership), for an existing membership a new credential — a new instance of it (new_instance), or, for a rejoin, one that replaces the instance of the revoked credential (§6.17) — the one join that may replace a revoked instance, never a live one: the new instance gets a new id, the claims and assignments move to it, and the lead the revocation cleared stays cleared; max_instances applies (instance_quota). ttl_seconds is 300. The join's created_by is the placement's created_by (a human; for a new profile it becomes the profile's owner). The join records placement_id and runner_id. credential_will_bind is the member id, or for a new profile the handle.
• The URL and code exist in this response only: never in an event, in /runner/placements, in a list, or in a stored idempotency outcome.
• Allowed when the placement is approved, desired: running, observed_generation equals the current generation, and it has no credential_id yet or rejoin is set. Otherwise pickup_not_allowed with details.why: not_running, stale_generation, credential_issued, handle_taken when the placement's new profile names a handle its creator has meanwhile given another agent, or project_not_allowed when the profile's allowed_projects no longer admits the project (§6.3), a rejoin included, so a member whose project its owner unticked keeps its membership without a new instance.
• The exchange checks the pickup again. Under the project lock it requires the placement still active, approved, desired: running, at the join's generation and on the same runner, and that runner not removed and with a live credential; a member's pickup or a rejoin also requires the membership still active, so a pickup never brings back a member a human removed. Otherwise the exchange answers not_found (§1.1). Stopping or closing the placement, and revoking or removing the runner, revoke its unused pickup joins.
• A lost response is recoverable. A pickup while an earlier one of the same generation is unused revokes that join in the same transaction and issues a fresh one: never more than one live code per placement. Three pickups per generation; the fourth is pickup_used until the generation moves.
• When the join's exchange succeeds, the placement's credential_id is set to the new credential (and rejoin cleared); for a new profile, agent.id is filled.
• Emits join_picked_up only. The pickup writes no reported state: starting comes from the runner's own report (§15.7).
• The exchange is the ordinary POST /join/{token} (§3.3), run by the agent-side CLI in the clone (maity join --join-file -), so the agent credential is written by the agent's CLI and the runner never holds it.

15.10 Events and audit#

The kinds are in §8.2. Rules that apply to all of them:

• Every event belongs to one project. An event caused by a runner that concerns several projects (runner_credential_revoked, runner_detached on DELETE /runners/{id}) is written once per project the runner is attached to, one row each. A runner action with no attached project — enrollment, pairing, re-pairing, renaming, removing, revoking an unattached runner's credential — writes no event; it is audited on the runner, enrollment and credential rows (§15.3).
• A runner can be an actor. Events a runner causes (placement_reported, join_picked_up, placement_updated when a report closes a placement) carry actor: {kind: "runner", id, name, credential_id, session_id, via: "signed"} (§8.1). Events a human or agent causes carry the member actor as before (a non-member human, only in an agent profile's cascade, the human actor, §6.3).
• runner:<id> is an audience token like member:<id>. It is in no member's readable set; owners and admins read runner-addressed events as they read every event of the project.
• Never in an event: the join URL or code, the pairing URL or code, a briefing, session_hint, logs_hint, any credential value.
• A rate_limited report sets the agent's limit (§6.12) and emits member_availability_changed with the runner as actor; the report that ends it does the same. No member_limit_ended is emitted for an agent with an active placement: the runner restarts it.
• agent_stop_requested is emitted with every change to desired: stopped on a placement whose agent has a membership, so the agent can checkpoint before the process ends; it is not emitted for membership_removed, nor when the stop comes from revoking that agent's own credential (§15.5) — in neither case could the agent read it.
• runner_credential_revoked.reason: the revoker's reason, or leaked_in_payload, repaired, runner_removed. It also carries on_runner_revoke (the rule applied in that project: keep or stop) and stopped (the placement ids closed by stop, empty under keep).
• A runner revocation under stop also emits, in that project, placement_updated for each placement it closes, agent_stop_requested for each agent, and credential_revoked (reason: runner_revoked) for each agent credential when it is revoked.

15.11 Changes to existing endpoints#

• Resume (§5.2) accepts "supervisor": "maity-runner/<version>". The runner puts it into the session it starts as the environment variable MAITY_SUPERVISOR, and maity resume sends it from there (§13). With it, hints.duty is "supervised", hints.wait_timeout is absent, and the generated rules tell the agent not to start maity wait and to end its turn after a checkpoint; without it hints.duty is "self". The packet gains membership.placement: {id, runner_name, harness, mode, stop_grace_seconds} or null.
• Supervised wake set (§8.2). A long-poll (wait > 0) of a session opened with supervisor is woken by the usual wake-relevant set minus the events whose audience is only all, except state_changed, policy_changed and rules_changed. The others stay readable and appear in the next resume.
• Member view (§6.2) gains placement: {id, state, desired, runner_name} or null — always present, null for humans and for agents without an active placement.
• Request view (§7) gains placement: {id, agent, runner_name, harness, model, mode, target, isolation} inline, or null. Only the hub sets it; POST …/requests does not accept it.
• Policy (§6.1) gains spawn_requests and max_placements.
• Scopes (§2.3) gain agents:propose; no role is added. (Since 2026-10-27 the role ops holds it too, §2.3.)
• Project state. Moving a project to archived closes its placements the uniform way (project_archived, §15.5).
• Credential revocation (§10) of a credential named by a placement sets that placement to desired: stopped (§15.5).
• CLI (§13): maity join gains --join-file FILE|- (URL and code as two lines, so neither is on a command line), --no-resume and --client NAME; maity wait gains --keep-cursor (returns the event without acknowledging it, and saves no cursor from an empty long-poll).

15.12 Open for the maintainer#

The places above that depend on a question in §12 of the runner design; each is written so that either answer fits.