# Server protocol reference ## Pending attachment reconciliation This source uses protocol **15** exclusively, through `borgmcp-shared@3.0.0`. Clients must use the matching contract; older protocol tags fail closed. The authenticated attach request and response shapes are unchanged. Retrying the original bearer reuses the same drone, session and initial log cursor; it never replaces an existing session with a new bearer. `POST /api/client/attach/reconcile` accepts `receipt`, `cube_id`, `role_id`, `action` (`inspect`, `finalize` or `retire`), and optional `prior_drone_id` in the standard protocol envelope. Omitted prior means the original request had no prior, not a wildcard. The shared receipt helper derives an internal locator from the original bearer. The locator is not authentication or a recovery credential, and is not returned in responses or diagnostics. Only the enrolled parent with current cube access may reconcile its own exact operation. An accepted operation can be finalized after durable local binding, or explicitly retired while still pending. Retirement revokes only the original current session and evicts its drone; it never touches a replacement. Retiring an operation that has not arrived records a durable cancellation fence against a delayed attach. Repeated retirement or finalization is idempotent, subject to current authorization and terminal-state checks. Revoked, evicted, superseded and foreign sessions remain refused. Cancellation fences are parent-scoped. Another parent's cancellation of an absent operation cannot block the original parent's inspection, cancellation or delayed attach. An actual foreign attachment remains inaccessible. An existing bearer-bound session without an operation record is conservatively registered as `finalized` on successful ordinary reuse. It is not assumed to have a failed pending bind, so pending recovery cannot retire it. This protects established sessions retained across a database upgrade without changing their bearer, drone, session or initial cursor. Newly created operations alone start as `accepted` in the same transaction as their session. Finalized operations cannot be retired through pending recovery (`409 ATTACHMENT_FINALIZED`); retired operations cannot attach or finalize (`409 ATTACHMENT_RETIRED`). General eviction still requires cube management access. No response restores a bearer. Lost local credentials after a completed bind/reset require explicit operator cleanup, not automatic replacement or re-enrollment. Whole-store loss still requires operator-consented re-enrollment. ## Advisory runtime metadata Protocol v8 attach requests may include the complete shared `runtime_metadata` report: Agent CLI kind, reported model, canonical public repository name, and canonical HTTPS origin. An omitted first report is stored as not reported; an explicit all-null report is stored as reported unknown. Reattaching the same authenticated seat may refresh the complete report without creating a new seat. An active drone session may repair only its own seat with `PATCH /api/cubes/:cubeId/drones/self/metadata`. Sparse patches preserve omitted fields, explicit null clears a field, and repository name/origin are always validated and changed as one pair. Drone-list responses expose the four fields plus `runtime_metadata_reported`. This metadata is display-only. It never grants cube access, changes role or posture, selects routing, marks liveness or `last_seen`, creates activity-log entries, wakes a seat, or starts a model turn. Validation and canonicalization come from the exact pinned `borgmcp-shared` contract; rejected values are not echoed in responses or debug diagnostics. ## Cube documents Protocol v10 adds immutable, cube-scoped text documents. The server accepts `text/markdown` and `text/plain` through these authenticated routes: | Operation | Route | | --- | --- | | Create | `PUT /api/cubes/:cubeId/documents` | | List metadata | `GET /api/cubes/:cubeId/documents` | | Read exact content | `GET /api/cubes/:cubeId/documents/:documentId` | | Remove from the working set | `DELETE /api/cubes/:cubeId/documents/:documentId` | All cube seats may list and read. Write or manage access may create documents. Only the original author or a cube manager may remove one. Unknown and cross-cube identifiers return the same secret-free not-found response. Document ids are opaque full identifiers. Titles are required discovery labels, not addresses. A creation may name one same-cube predecessor with `supersedes`. Each predecessor accepts at most one successor, producing a linear revision chain. Supersession never changes prior content. Removal delists a document and stops counting its bytes against the active budget, but exact-id reads continue to return its immutable content and removal audit metadata. Log append requests may carry `documents`, an ordered array of full document ids. Every citation is validated before the log mutation. Reads and streams return only each citation's id, title, UTF-8 size, and current state; content is fetched explicitly. Changing the citation set while reusing a `post_id` is a `POST_ID_CONFLICT`. Messages above the configured advisory threshold are accepted with `STORE_AS_DOCUMENT`. Messages above the configured hard limit are rejected with `CONTENT_TOO_LARGE`; the caller stores the detail as a document and cites it from a shorter log entry. ## Acknowledgement status Protocol v11 adds `GET /api/cubes/:cubeId/logs/:entryId/ack-status`. The strict request envelope repeats the full activity `entry_id`. The response reports the entry visibility, each intended direct recipient's current nullable label and role plus nullable acknowledgement timestamp, and advisory claims as a separate collection. Broadcast entries have no explicit recipient list. The query requires cube read access and applies the same directed-entry scope as log reads. Unknown, pruned, unauthorized, and cross-cube entries return the same `NOT_FOUND` response. Reading status does not acknowledge or claim the entry, append activity, or advance an unread cursor. ## Explicit addressing and entry lookup Protocol v12 makes delivery intent mandatory on every activity append. The `to` field must be exactly `"broadcast"` or a non-empty array of recipient selectors. Public `visibility` and resolved recipient-id inputs are rejected. Message classes, prefixes, and lifecycle values classify entries only; they do not select recipients or supply a default audience. Responses continue to expose stored visibility and resolved recipient ids as authoritative delivery evidence. Reusing a `post_id` is idempotent when content and explicit delivery resolve identically, even if advisory classification differs. `GET /api/cubes/:cubeId/logs/:entryId` reads one visible entry without a request body and without changing acknowledgements, claims, cursors, or activity history. `entryId` is either a canonical UUID or exactly eight hexadecimal prefix characters. Unknown, inaccessible, and cross-cube entries return the same `NOT_FOUND` response; an ambiguous prefix returns `409 LOG_ENTRY_PREFIX_AMBIGUOUS`.