Read a workspace text file under coherence tracking. Returns {content, version, owner_generation}. The version is the comparand you pass to swg_write_cas; KEEP BOTH version and owner_generation and pass them to swg_gate before any irreversible external action you decide from this read (owner_generation=null means this coordinator does not report generations, so swg_gate will hold). When the path has a handoff record the result also carries handoff: the record as it concerns this session (role giver, successor or bystander, the two session_agent_ids, version_at_transfer, hold_shape, status, live); handoff_unknown=true instead means the read was denied and the record could not be fetched. The coordinator attaches the record best-effort, so a result with neither does not prove there is no record; swg_status lists every record. A sticky-INVALID view returns fresh bytes but stays INVALID — use swg_reacquire to recover before writing. If the bytes on disk are not the content at the current version, the read is DENIED with reason=stale_view and no version. A peer's commit still reaching disk clears on its own: swg_reacquire, then swg_read again, retrying for a few seconds. Only if it stays denied past that was the file changed outside the coordinator (an out-of-band edit, or a commit whose disk write failed): swg_write the content swg_reacquire returned (or your merge of it), then swg_read. A write made sooner can be overwritten by a peer commit still reaching disk. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Write a workspace text file (acquire -> write -> commit). DENIED with reason=stale_view if the file changed since you read it — a peer commit OR an out-of-band edit (another tool/editor): recover with swg_reacquire, then write FROM its bytes. A mid-write preempt returns reason=commit_preempted (disk may hold un-versioned bytes; reacquire_and_reconcile). SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Recover from a stale_view deny: re-mint identity and return the CURRENT bytes. You MUST write FROM these exact bytes — the server enforces version lineage, NOT that your content was derived from what you read. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Report coherence state: coordinator on|off|unknown (unknown is NOT off), per-path enforced|not_registered (with handoff: the path's handoff record -- giver, successor, version_at_transfer, hold_shape, status, live -- when it has one; per_path is null, not {}, when the coordinator's /status answer carries no list of tracked paths, as a degraded answer does when its registry was busy: retry shortly and do not treat it as nothing tracked; the text result then says per_path=unavailable. With coordinator=unknown, per_path is {} and says nothing about what is tracked), is_attached/is_degraded/session_id, session_agent_id (this session's id as a handoff successor: the value another session passes to swg_transfer to hand this session a path; it does not change when this session reacquires, and it names this session as a successor only while principal_claim is bound), principal_claim (this session's caller-principal state: bound; unsupported = the coordinator issues none; unconfirmed = the last claim's answer was lost and the next call claims again by itself; refused = the session is bound under another nonce, so every later swg_read/swg_write/swg_gate answers the typed caller_principal_* deny with recover=restart_session while the coordinator stays on; not_attempted = nothing claimed yet), caller_principal_absent_total and caller_principal_refused_total (the coordinator's counters; null, never 0, when it is unreachable or does not report them), registry_schema_version (the schema version of the coordinator's store, an integer; an older release refuses a store at a newer version; null when the coordinator is unreachable (coordinator=unknown) or its answer carries no such field, as a coordinator built before the field does; report it to the user rather than act on it), and heterogeneous_scope_detectable=false (a multi-host or differently-scoped setup is NOT distinguishable in v1). SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Verify a file is STILL unchanged and still under the same grant. Pass BOTH comparands from your earlier swg_read — expected_version AND expected_generation (its owner_generation). Call this immediately BEFORE any irreversible external action you decided from that read (sending a webhook, opening a PR, running a deploy, posting a message). Returns decision=proceed, or DENIES with reason=stale_view if the file moved OR the grant you read it under was reclaimed (the version alone cannot see a reclaim) OR a peer write-claim preempted your grant (which moves neither comparand — the gate re-checks that the grant still stands) OR either comparand is unconfirmed. On a deny: do NOT take the action — swg_reacquire, re-read, re-decide. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Concurrent same-key write via compare-and-set. You read (swg_read returns the version comparand; swg_reacquire does NOT — it is for swg_write recovery), MERGE, then call swg_write_cas(path, expected_version, new_content). Stale-write-rejected: if a peer committed since your read, the CAS is a TYPED CONFLICT (reason=version_mismatch, current_version returned) — NOT an auto-merge; re-read at current_version, re-merge, and retry. A win on a path with a live handoff carries handoff: outcome=completed when this session is its successor, overtaken (with counterparty) otherwise. The per-session conflict counter bounds only a COOPERATING agent (one session, stops on retryable=false); it is NOT livelock-proof against a fresh session or one that ignores retryable=false. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

Hand this session's claim on one or more paths -- the write grant from swg_write, or the standing read from swg_read -- to another session, the successor. Name the successor by the session_agent_id that the successor's OWN swg_status reports. Answers one grant per path, in order: transferred=true with the record (giver, successor, version_at_transfer, hold_shape, status=pending), or transferred=false with a typed reason and nothing changed (handoff_not_held: this session holds no claim on the path; handoff_successor_unknown: the coordinator does not know that id; handoff_in_flight: another session's handoff of the path is live). The result is an error unless every grant transferred, and each refused grant carries recover and retryable=false and a fixed next_step: fix_successor for a successor id that names no other session, check_handoff for handoff_not_held (a transfer that already landed answers it too), stop_and_report otherwise; the top level speaks for the most restrictive refused grant. While a handoff is live this session's swg_write and swg_write_cas on its path are denied with reason=handed_off. The fence covers this MCP session only: a write you make through any other route (your own file tools, a shell) is another session's and is not refused, so write a path you handed off by no route. If the answer is commit_unconfirmed (recover=check_handoff) the transfer may have landed: look at the path's handoff (swg_read or swg_status) first. A handoff from you to that successor made at the version you held (its version_at_transfer), live or ended, means your transfer landed: do not transfer again, and do not withdraw to start over. Transfer again only if no such handoff shows; if the path was written since or shows another session's handoff, ask your user. Once the successor has written the path, a second transfer is a new handoff. A transfer fences the giver and does not reserve the path: other sessions keep reading and writing it by the ordinary rules, and the handoff only labels what they do. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

As the successor, accept the live handoff of a path without writing it: a pending handoff becomes completed (a write of the path completes it too). The giver stays fenced until a write moves the version. If another session has acquired the path and nothing has written it since, the handoff is overtaken but live: the accept is taken but changes nothing, answers status=overtaken and names that session as counterparty. Once a write has moved the version the handoff has ended, and the accept is refused handoff_not_live with the status saying how. Refused with handoff_not_successor or handoff_not_live, as an error that changes nothing (recover=stop_and_report, retryable=false, and a fixed next_step). A transfer fences the giver and does not reserve the path: other sessions keep reading and writing it by the ordinary rules, and the handoff only labels what they do. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

As the successor, decline the live handoff of a path: the handoff ends and its giver's fence lifts. Refused with handoff_not_successor or handoff_not_live, as an error that changes nothing (recover=stop_and_report, retryable=false, and a fixed next_step). A transfer fences the giver and does not reserve the path: other sessions keep reading and writing it by the ordinary rules, and the handoff only labels what they do. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

As the giver, withdraw this session's live handoff of a path: the handoff ends and this session's fence on the path lifts. Take it only on the user's or host's explicit instruction. It is never the recovery for the handed_off refusal: when a write of a path you handed off is refused, stop and report to your user or host. Refused with handoff_not_giver or handoff_not_live, as an error that changes nothing, whose next_step says to stop and report. A transfer fences the giver and does not reserve the path: other sessions keep reading and writing it by the ordinary rules, and the handoff only labels what they do. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.