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. If it stays denied past that, the bytes on disk were never recorded (an out-of-band edit, a commit whose disk write failed, or a write whose commit did not reach the coordinator); reading again does not clear it: 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). In either mode the write takes a write grant on the path and keeps it after the write. When you finish writing a path, swg_release it: until you do, other opted-in agents that write it wait, for up to 30 minutes. On a refuse-mode server (SWG_ON_HELD=refuse) a success also carries opted_in: true when the write asked first, false when the path is not among the managed files, so the write took the file from any agent that held it. A refusal carries reason, recover and retryable; follow its next_step when it has one. 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, never the content you just sent. The other reasons: other_holder (refuse mode only), another agent holds the path and nothing was written (recover=wait_then_reacquire); commit_preempted, a mid-write preempt (disk may hold un-versioned bytes; reacquire_and_reconcile); commit_unconfirmed, the bytes are on disk but may be unrecorded (recover=write_again); link_out_of_managed (refuse mode only), the path goes through a link to a file outside the managed files; handed_off, this session handed the path off; coordinator_failed, the coordinator failed while answering (recover=reacquire when an earlier attempt of this session still holds the path); coordinator_unavailable, it gave no usable answer or is not attached; caller_principal_absent, caller_principal_foreign or caller_principal_claimed, this session's caller principal was refused (swg_status shows principal_claim); internal_error, a failure with no recovery; invalid_path or io_error, a bad path or a disk failure. 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. It is also the step a swg_write refusal names with recover=reacquire or wait_then_reacquire. The re-mint drops every hold this session has: the write grant on every path, not only this one, so other agents can then write those paths. To give back one path and keep the others, use swg_release. 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.

Give back this session's write grant on one path and keep every other hold. swg_write takes a write grant on the path it writes and keeps it after the write. When you finish writing a path, swg_release it: until you do, other opted-in agents that write it wait, for up to 30 minutes. Answers {ok, path, released}. released=true means this session gave a grant back; it does not mean the path is free (another agent may hold it), and this session keeps a read at the version it held, so its next swg_write of the path needs no swg_reacquire unless the file changed since. released=false means this session had no write grant recorded on the path and nothing was sent, as on a repeat. A release the coordinator did not confirm answers reason=release_unconfirmed, recover=release_again, retryable=true: calling swg_release again is safe, at most twice more; if it still is not confirmed, report that this session's write grant on the path may still stand (swg_reacquire drops every hold, this one included). 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), the write holder on each per_path entry someone holds for writing: holder_agent_id (the holder's attempt id, in the 32-hex spelling an other_holder refusal names; ids are per attempt, so it never equals session_agent_id) and held_by (this_attempt; earlier_attempt, an earlier attempt of this session whose grant still stands, which you release; or another_agent), neither key on an entry nobody holds, and this_attempt covering another caller sharing this server, since every caller of one server process is one agent to the coordinator; on_held (this server's mode: refuse when the operator set SWG_ON_HELD=refuse, else displace), held (the sorted paths this session holds for writing, either attempt; null when the coordinator cannot say who holds each path: null means cannot tell, never that nothing is held; the text result gives on_held, held, and a line per path held_by another_agent or earlier_attempt), 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. A call that reaches the coordinator drops every hold this session has: it starts a new attempt, which gives back the write grant swg_write took on every path, as swg_reacquire does. 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.