@astrosheep/square 0.3.93 → 0.3.95

package/guides/mcp-connection-lifetime.md

@@ -1,6 +1,6 @@
 # MCP connection lifetime
 
-An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call opens an actual `Square` handle with that request's captured environment, default participant and harness session; `square.participant()` performs nonmutating name selection. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
+An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call opens an identity-free `Square` handle with that request's resource environment; harness identity is passed to `join(name, {body, wakeAddress?})` or `selectOwnSeat(square, body, as?)`, never captured by the resource. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
 
 `createSquareResourceOwner()` is the explicit lifetime boundary. `Square.at({resources, ...})` borrows its connection; closing a request handle leaves the owner open. Ordinary callers open and close their own Square. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
 

package/guides/mcp.md

@@ -2,12 +2,12 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact Body (`channel`, `session`, optional `agent`); zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present; otherwise a reliable startup coordinate is required for participant writes. Read-only calls do not need a Body.
+Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact opaque owner; zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
 
-The server exposes `join`, `express`, `catch`, `history`, `attention`, `hold`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `hold` lowers the hand with `release: true`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
+The server exposes `join`, `express`, `catch`, `history`, `attention`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All seven tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
 
 Claude's bundled plugin configures this server automatically. Its mod supplies live session/cwd/subagent attribution through an out-of-band tool-use-ID association, not AI-visible arguments; see [Claude call identity](claude-native.md#mcp-tools-and-call-identity). The bundled endpoint requires that association rather than falling back to its startup environment.
 
-Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Join serializes the handle's name and receipt fields, never resource internals. All callers use the [same concrete resource API](square-api.md), with no alternate factory or generic outcome envelope. `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
+Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Domain receipts stay internal to these adapters; tools return only their rendered text. All callers use the [same concrete resource API](square-api.md), with no alternate factory or generic outcome envelope. `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
 
 Configure a client with command `npx` and arguments `--yes --package @astrosheep/square square mcp-server`, or use the installed `square` executable with argument `mcp-server`. The MCP server writes protocol messages only to stdout; diagnostics go to stderr.

package/guides/migration.md

@@ -1,159 +1,156 @@
 # Migrating an existing square
 
-Square stores its authority in one versioned SQLite artifact. Format 1 kept the
-history as one JSON snapshot; format 2 introduced typed rows; format 3 added the
-`unlisten` activity; format 4 added artifact-owned participant seats and delivery
-evidence; format 5 adds independent expiring delivery deferrals. Existing artifacts are never
-converted implicitly.
+Square stores its authority in one versioned SQLite artifact. Format 1 kept a snapshot;
+format 2 introduced typed facts; format 3 added `unlisten`; format 4 moved participant custody
+and delivery evidence into the artifact; format 5 added independent delivery deferrals.
+**Format 6 separates participant membership from host attachment; format 7 replaces harness Body
+coordinates with opaque owners; format 8 removes Square hold/resume activities and held state.**
+Existing artifacts are never converted implicitly.
 
-Use the explicit command while all processes using the artifact are stopped:
+Stop all processes using the artifact, make an offline backup, then run:
 
 ```sh
 square --location /path/to/SQUARE.square migrate
+square --location /path/to/SQUARE.square doctor
 ```
 
-The command handles supported formats 2, 3 and 4 in place and publishes only final format 5.
-It does not create a
-backup, stop processes, install a runtime, or update another artifact. A legacy
-HostLedger that needs its own format conversion must be prepared separately with
-the old runtime's offline tooling.
-
-## Format 4 additive conversion
-
-An exact format-4 artifact needs no legacy owner or route import: that authority already lives
-inside the artifact. Read-only preflight checks framing and stored facts. One SQLite transaction
-adds the empty `delivery_deferrals` table and its owner/generation/expiry lookup index, then
-publishes format 5. The dedicated table stores participant key, captured generation, opaque ID,
-validated match and expiry, separately from catch leases and delivery evidence. All existing
-activities (including metadata), audience, receipts, seats, catch leases, delivery evidence,
-cancellation boundaries and both revision values remain unchanged. No lease is manufactured.
-The conversion does not consult or mutate HostLedger. Failure rolls back the table, index and
-format marker together.
-
-## Format 3 preflight and conversion
-
-Before writing, migration validates the exact format-3 schema, header, and legacy
-rows read-only. The configured legacy HostLedger must be frozen along with the
-artifact. Its latest owner row for each participant at this artifact is selected
-by source `(effectiveAt, seq)` only: no wall clock, retention, expiry, or ownership
-history reconstruction is involved.
-
-- A legacy owner Body (`channel`, `session`, optional `agent`) establishes a
-  standing seat only when it agrees with all of that name's local route Bodies
-  and the establishing last join is verified. An owner without routes needs no
-  wake address. Without a legacy owner, one unambiguous Body recorded by that
-  participant's own routes establishes its seat instead. An absent agent means
-  the top-level body; a known agent is preserved and compared exactly. Repeated
-  matching registrations are acceptable; a wake address is carried forward only
-  when the routes agree on it. Routes are location-bound: moving an artifact copy
-  to another path does not establish that its original routes apply there. An
-  off-location copy is not ownership-recovery evidence for the original location.
-- Without an owner or any route Body, the participant stays standing without a
-  seat. Its source participant state, activities, attention, receipts, landed
-  audience and catch lease are preserved. No Body, route or departure is invented;
-  the name has no write authority or delivery eligibility. Doctor retains its
-  strict history-derived consistency checks.
-- A Body may own several participant seats. Each name retains its own seat,
-  establishing join generation and wake address; sharing does not merge names or
-  choose one name over another. All evidence for each name must agree: if its
-  routes disagree with each other or with its legacy owner Body, that name stays
-  standing without a seat. Disagreement does not abort migration and neither side
-  is chosen as authoritative. Unverifiable joins still refuse before publication.
-  Migration does not guess or synthesize authority.
-- Evidence structure is validated before placement, including rows that cannot be
-  imported. Malformed fields, invalid activity IDs or malformed native correlation
-  still refuse without changing either source.
-- Wake/presentation evidence for a recovered seat is imported only when its Body
-  agrees and it names an existing directed say after the verified current join.
-  A missing seat, conflicting session/agent/channel or native harness, unknown
-  participant, or activity outside the generation causes the row to be skipped,
-  not a failed conversion. Nothing is reassigned to another owner.
-- Done participants get **no seat or completed coordinate**. Only native wake
-  correlation directly attributable to their verified latest join and a directed
-  activity between that join and done is retained for retired-token recognition.
-  It does not authorize admission, completion, or presentation. Conflicting
-  completed Body mappings, duplicate claim tokens and ambiguous attempt numbering
-  cause all affected rows to be skipped, rather than selecting a winner. A single
-  record without an attempt number receives attempt 0. Migrated Claude native
-  addresses include `sessionId` on both seats and evidence routes.
-
-This is deliberately a narrow, lossy conversion, not a general history importer.
-Conversation facts (activity IDs, bodies and audience), receipts and source revision
-meaning survive. Replay-critical delivery coordinates, outcomes and native
-correlation survive direct mappings. Completed non-native evidence and noncritical
-metadata—including old presence history, epochs, diagnostic messages, native
-observation histories and arbitrary legacy fields—are not imported. The legacy
-ledger is read-only and remains untouched, so it is still available for offline
-diagnostics. An absent ledger still permits route-derived seats; an unreadable
-or unsupported ledger refuses before changing the square. Evidence without a
-current or verified completed owner is skipped and counted. The source ledger is
-retained for offline diagnosis; skipped evidence never grants delivery authority.
-
-After successful preflight, one SQLite transaction imports seats and evidence
-and adds delivery deferral support, then publishes the current format. All
-existing activities, their indices and audience, participant state, attention,
-receipts, lease contents, and the source revision are preserved. Legacy routes
-are consumed only during migration. Lease generations are resolved only for exact
-owner spellings that match a standing participant; other lease rows retain their
-legacy, unbound generation. The command reports recovered seats and unowned
-standing names, and recovered seats whose Body is shared with another recovered
-seat, and skipped evidence rows, alongside the activity, receipt, lease and source
-route counts. The shared count measures seats, not distinct Bodies or shared groups.
-The skipped count includes every wake/presentation row read from the selected
-legacy ledger but not imported, including completed non-native diagnostics.
-The new delivery revision starts at zero. There is no intermediate published
-format, and any failure before commit rolls back the conversion.
-
-Format 2 first rebuilds only the activity table and its indexes to accept
-`unlisten`, then follows the same row-format preflight and conversion. Snapshot
-format 1 is not accepted by this migration. Formats 2/3 never publish an intermediate format 4.
-
-## What migration refuses
-
-Migration validates each source's exact row schema. Formats 2/3 include the legacy routes table,
-read using migration-local codecs; format 4 already has seats and delivery evidence. Current
-format 5 has no routes table or runtime route
-reader; migration consumes the old rows only to resolve seats, then drops the legacy
-table as part of the format change.
-
-Unrelated databases, unsupported formats, non-`DELETE` journal modes, unknown
-schemas, malformed headers, rows or native correlation are refused. The source artifact is preserved on every
-refusal. Migration is not a repair command and never rewrites journal mode to make
-conversion possible. A HostLedger that itself requires migration must be migrated
-separately before Square migration can import its delivery evidence.
-
-## Conservative retired-token restriction
-
-For an old artifact conversion, **any nonempty legacy `host_native_tokens` table
-makes preflight refuse**, including tokens for other sessions. Those token-only
-Claude tombstones are replay protection, not diagnostics: they contain only a
-session and token, with no artifact, participant or activity coordinate. The
-converter cannot safely assign them a join generation. This is deliberately a
-ledger-wide ambiguity refusal, not a claim that each token belongs to the square
-being converted. Even a tombstone duplicated by retained evidence is refused by
-this conservative implementation; no deduplication or history inference is done.
-
-Keep the original ledger and artifact intact. Resolve the ambiguity offline with
-replay protection preserved; **do not delete tombstones just to bypass preflight**.
-An already-current artifact returns without consulting the legacy ledger and
-remains a byte-preserving no-op.
-
-## Before and after migration
-
-Stop every session or service using the square, and for formats 2/3 freeze any process writing its
-legacy HostLedger. Make an offline backup, or use SQLite's backup facilities rather than
-copying a live database. Migration does not revoke an in-flight remote delivery or
-modify HostLedger evidence. Square writes use ordinary SQLite `DELETE` journals:
-the artifact must be writable and its containing directory must permit journal
-creation and removal. The legacy ledger needs read access only. After conversion,
-participation and delivery authority live in the artifact, not writable HOME;
-loss of the rebuildable HOME discovery index may limit automatic discovery but
-does not transfer custody or erase durable delivery evidence.
-
-Upgrade all attached runtimes before reopening the format-5 artifact; older runtimes
-must not be mixed with it. Updating a package does not migrate an artifact, and migrating an
-artifact does not install upgraded runtimes. For rollback after a committed conversion, stop all
-clients and restore the offline backup with its compatible older runtime; do not downgrade the
-format marker or drop tables in place. Run the read-only `doctor` command after migration and
-before restarting clients. Repeating migration on a current artifact is a
-byte-preserving no-op.
+The command handles supported formats 2–7 in place and publishes only final format 8, in one
+transaction. It does not make a backup, stop processes, install a runtime or update another
+artifact. For formats 2/3, also freeze and back up the legacy HostLedger used for owner/evidence
+import. A legacy ledger needing its own conversion must be prepared separately with its old
+runtime's offline tooling. Snapshot format 1 is not accepted by this conversion.
+
+Format 7 to 8 deletes hold/resume activities and rows keyed to them, clears replies that point to
+deleted activities, and preserves every surviving activity index. Gaps remain legal; `lastActIndex`
+is the greatest surviving index and `nextActIndex` never reuses a deleted index.
+
+## Membership and attachment after conversion
+
+Membership owns a participant's join/done history, read horizon and outgoing listens. Attachment
+says whether its exact owner is currently executing for it. There are three distinct endings:
+
+- A participant's voluntary `done` ends membership. A later explicit participant join is required
+  to return; no host start/resume revives it.
+- Pi shutdown, Codex SessionEnd and Claude session end detach only. No activity lands; membership,
+  listens, read horizon, receipts and delivery evidence stay intact. Wake readiness, catch ownership
+  and delivery deferrals are cleared. Away participants still receive landed audience and accumulate
+  unread activity, but cannot write or receive proactive delivery. Away has no timeout.
+- Host-confirmed permanent deletion ends membership through fenced
+  `endHeld(name, {owner, generation})`, including for a detached seat. OpenCode `session.deleted`
+  uses this path.
+
+On start/resume, hosts discover only their exact owner's standing seats with `seatsOf(owner)` and
+restore the detached ones with `reattach(name, {owner, wakeAddress?})` before arming delivery.
+Same-owner `join` or `reattach` preserves the generation, read horizon and listens, so mentions
+received while away remain unread. Reattachment returns `null` for absent, foreign or done seats;
+it never creates membership. Explicit takeover still performs `done -> join` with a fresh
+generation, even when taking over an away participant; old cleanup/recovery cannot reclaim it.
+The owner API requires this explicit format migration; see the
+[SDK breaking migration](square-api.md#sdk-breaking-migration-opaque-owners).
+
+## Conversion from formats 6, 5 and 4
+
+Format 6 -> 7 maps each seat's `channel`, `session` and optional `agent` through the adapter codec
+into one owner string, preserving its generation, attachment and wake. Evidence, deferrals, catch
+leases, cancellations, conversation facts and both revisions stay unchanged. Unmappable legacy
+coordinates (for example an encoded owner exceeding 512 UTF-8 bytes) refuse without changing the
+source; they are never truncated or reassigned. Keep the source backup for offline resolution.
+
+Formats 4/5 first acquire format 6 semantics in that same transaction: every existing seat becomes
+attached. Format 4 also gains empty deferral support. No detached seat is invented. Formats 4–6
+never consult HostLedger; any failure rolls back schema changes and final publication together.
+
+Existing done participants stay done. Before format 6, a host-cleanup `done` was indistinguishable
+from a voluntary leave; migration conservatively treats both as voluntary. It does not infer
+attachment history, reconstruct departures or provide a host recovery path for completed seats.
+
+## Verified import from formats 3 and 2
+
+Formats 2/3 need owner and delivery evidence import. Before writing, migration validates exact
+source framing, header and legacy facts read-only. The frozen legacy HostLedger's latest owner
+for each participant at this artifact is selected by source `(effectiveAt, seq)` only: no wall
+clock, retention, expiry or ownership-history reconstruction is involved.
+
+- A legacy owner Body (`channel`, `session`, optional `agent`) establishes a standing, attached
+  seat only when it agrees with all of that name's local route Bodies and the establishing join
+  is verified. An owner without routes needs no wake address. Without an owner, one unambiguous
+  route Body can establish the seat. An absent agent means the top-level Body; a known agent is
+  preserved and compared exactly. Matching repeated registrations are acceptable; wake readiness
+  carries forward only when the routes agree. Routes are location-bound: moving an artifact copy
+  does not establish that its original routes apply there.
+- Without a verifiable owner or route Body, the participant stays standing without custody.
+  Membership, history, attention, receipts, landed audience and catch ownership are preserved.
+  No Body, route, attachment or departure is guessed. Its name grants no write/delivery authority.
+- A Body may own several names; each retains its own generation and wake readiness. Sharing
+  does not merge names or choose a winner. Conflicting owner/route Bodies leave that name
+  standing without custody; disagreement does not abort conversion. An unverifiable establishing
+  join still refuses before publication.
+- Evidence structure is validated before placement, including evidence that cannot be imported.
+  Malformed facts, activity IDs or native correlation refuse without changing either source.
+- Wake/presentation evidence imports only when its Body agrees and it names an existing directed
+  say after the verified current join. Missing custody, conflicting session/agent/channel or native
+  harness, unknown participants and activity outside the generation cause evidence to be skipped,
+  never reassigned to another owner.
+- Done participants gain no seat or recovery authority. Only native correlation directly
+  attributable to their verified latest join and directed activity before departure is retained
+  for retired-token recognition. It authorizes neither admission nor presentation. Ambiguous
+  completed-Body mappings, duplicate claim tokens and ambiguous attempt numbering cause all
+  affected evidence to be skipped, rather than selecting a winner. A record without an attempt
+  number receives attempt 0. Migrated Claude wake addresses retain their native session identity.
+
+This is a narrow, deliberately lossy conversion, not a general history importer. Conversation,
+activity IDs, bodies, audience, receipts, source revision meaning and directly verified replay
+protection survive. Completed non-native evidence and noncritical metadata—including old presence
+history, epochs, diagnostic messages, native observation histories and arbitrary legacy extras—do
+not import. Evidence without current or verified completed ownership is skipped and counted. The
+read-only legacy ledger remains available for offline diagnosis; an absent ledger permits route-
+derived custody, but an unreadable or unsupported ledger refuses before changing the square.
+
+One transaction imports verified authority/evidence, adds deferral and attachment support, applies
+the format-7-to-8 deletion, and publishes format 8. Existing conversation and membership facts are
+preserved apart from the deleted hold/resume rows and cleared replies; no intermediate format is
+published. Legacy catch ownership is generation-bound only for exact standing owner
+spellings; otherwise it stays unbound. Legacy routes are consumed only during migration and are
+not a live authority source. The new delivery revision starts at zero. Format 2 first adds support
+for `unlisten`, then follows the same conversion.
+
+The receipt reports recovered seats, unowned standing names, seats sharing a recovered Body,
+skipped evidence, and source activity/receipt/catch/route counts. The shared count measures seats,
+not distinct Bodies or groups. Skipped includes every legacy wake/presentation record read but
+not imported, including completed non-native diagnostics.
+
+## Conservative refusal and retired-token protection
+
+Unrelated databases, unsupported formats, non-`DELETE` journal mode, unknown framing, malformed
+headers/facts or native correlation refuse without source changes. Migration is not repair and
+never rewrites journal mode to make conversion possible.
+
+For formats 2/3, **any nonempty legacy token-only tombstone collection makes preflight refuse**,
+including tokens for other sessions. Those Claude tombstones are replay protection, not diagnostics:
+they identify only a session and token, without artifact, participant, activity or join generation.
+The converter cannot safely assign them. This is a ledger-wide conservative ambiguity refusal,
+not a claim that each token belongs to the artifact being converted. Even a token duplicated by
+retained evidence refuses; conversion does not deduplicate or infer history to bypass protection.
+
+Keep the original ledger and artifact intact. Resolve ambiguity offline with replay protection
+preserved; **do not delete tombstones just to bypass preflight**. An already-current artifact
+returns without consulting the legacy ledger and remains a byte-preserving no-op.
+
+## Before reopening and rollback
+
+Freeze every artifact user and, for formats 2/3, every legacy-ledger writer. Make an offline backup
+or use SQLite backup facilities rather than copying a live database. Migration cannot revoke an
+in-flight remote delivery. Writes use ordinary SQLite `DELETE` journals: the artifact and its
+containing directory must permit writing and journal creation/removal. A legacy ledger needs read
+access only. Losing the rebuildable HOME discovery index may delay restoration/delivery but cannot
+transfer custody or erase evidence. The disposable index changes to `{location, owner}`; old index
+rows are ignored. Rejoin with the exact migrated owner to republish discovery (or let that same
+harness reconnect). This preserves generation, listens and unread activity; do not use takeover
+merely to rebuild the index.
+
+Upgrade all attached runtimes before reopening format 8; older runtimes must not be mixed with it.
+Updating a package does not migrate an artifact, and migration does not install upgraded runtimes.
+After conversion, run read-only `doctor` before restarting clients. To roll back a committed
+conversion, stop all clients and restore the offline backup with its compatible older runtime;
+do not downgrade the format marker or remove facts in place. Repeating current-format migration
+is a byte-preserving no-op.

package/guides/operation-cancellation.md

@@ -21,7 +21,7 @@ Ownership and delivery have the same limitation: cancellation can stop work that
 Presentation checks cancellation and eligibility before invoking its sink. A rejected sink is not
 success, including a native notification whose landing acknowledgement was cancelled. Once the sink
 succeeds, recording its evidence and seen receipts is mandatory settlement, not a new cancellable
-presentation attempt. It uses the same artifact connection and captured Body/join generation, without
+presentation attempt. It uses the same artifact connection and captured owner/join generation, without
 inheriting the pre-effect operation signal or a signal captured when opening that artifact. Claim
 release after a cancelled/failed attempt uses the same independent cleanup lifetime and writes no
 success receipt. Both settle through the normal authority gate, with a five-second storage budget;

package/guides/participant-ownership.md

@@ -1,60 +1,91 @@
 # Participant ownership
 
-A participant has one current artifact-owned seat: its normalized participant name, exact Body
-(`channel`, `session`, optional `agent`), establishing join generation, and optional wake address.
-Display spelling and discovery-index entries never grant write authority. The artifact transaction
-is the sole custody authority; there is no writable HostLedger ownership layer.
-
-## Captured handles and lifecycle
-
-`Square.at` captures an explicit Body for writes. `participant(name?)` selects a handle without
-joining; `recognize()` returns current handles held by that exact Body. A name alone is not
-permission to mutate. Read-only archive operations need no Body. See [square-api.md](square-api.md)
-for the public resource lifetime and selection contract.
-
-- `join(name)` atomically lands the join and stores its seat. Same-body reconnect preserves its
-  generation and may refresh the wake address. A foreign Body receives `already_joined` rather
-  than taking ownership implicitly.
-- `join(name, {takeover:true})` explicitly completes the captured old seat and establishes a new
-  one with `done -> join` in one transaction. Its compare-and-set generation prevents a concurrent
-  takeover from being silently replaced.
-- Participant mutations carry the captured seat into the transaction. The gate checks both Body
-  and generation, including when the same Body later reacquires the name. An old handle never
-  becomes fresh because a name matches again.
-- `done` retires only the current captured seat, catch lease and delivery deferrals. A later join
-  establishes a fresh generation. Completed coordinates retained for exact-body diagnostics are
-  not current write authority. Owner-session cleanup uses the same fence and cannot complete a
-  replacement seat.
-- Stdio retains the selected Participant in a connection-local reference. Each operation uses that
-  captured handle instead of reselecting authority by name. Rejoin/takeover therefore fences old
-  remote handles just as it does local SDK handles.
-
-The HOME discovery index is rebuildable candidate-path data. Losing it can delay discovery but
-cannot transfer a seat or erase delivery evidence. A wake address is only transport readiness for
-an existing seat, not an alternative ownership fact.
+Membership and host attachment are different facts. Membership says a participant is in the
+square; it owns their join history, read horizon and outgoing listens. Attachment says whether
+an exact opaque owner is executing for that participant now.
+A standing seat may be attached or detached. The artifact transaction is the sole custody
+authority; display spelling, wake addresses and the rebuildable HOME discovery index never
+grant ownership. There is no writable HostLedger ownership layer.
+
+Owners are opaque non-secret strings, not harness coordinates or authentication. Harness adapters
+encode their own identity; terminal owners use `user:<OS user>@<host>` and are never automatically
+detached or ended by a harness. A seat's optional wake route is self-contained transport readiness,
+not an owner or an alternative custody fact.
+
+## Three endings
+
+- **The participant leaves:** `Participant.done()` ends membership, removes its seat, catch
+  lease and delivery deferrals, and removes outgoing listens. A later explicit `join` establishes
+  a fresh generation and read horizon. No host start or resume brings a voluntary leave back.
+- **The host session ends:** `detach(name, {owner, generation})` detaches only that exact owner and
+  join generation. It clears wake readiness, catch ownership and delivery deferrals, without landing
+  an activity or changing membership, listens or the read horizon. A detached participant is
+  **away**, still receives normal landed audience and accumulates unread activity, but cannot write
+  or receive proactive delivery. Away has no timeout; a session that never returns simply stays away.
+- **The host confirms permanent deletion:** `endHeld(name, {owner, generation})` ends membership
+  with a fenced `done`, including for a detached seat. OpenCode's `session.deleted` uses this path.
+  Pi shutdown, Codex SessionEnd and Claude session end do not prove permanent deletion and therefore
+  detach.
+
+An explicit takeover remains `done -> join` in one transaction, whether the old seat is attached
+or detached. It transfers the name to the new owner with a fresh generation; old cleanup and
+recovery cannot reclaim it.
+
+## Captured handles and restoration
+
+A `Square` captures no participant identity. `participant(name, {owner})` selects an attached,
+standing seat held by that exact owner without joining; never-joined, done, foreign and detached
+seats refuse with join recovery facts, not ghost handles. `seatsOf(owner)` is a read-only discovery
+surface for the owner's standing seats as `{name, generation, attachment}`. It includes attached and
+detached seats, but does not join or return done participants. See [square-api.md](square-api.md)
+for resource lifetimes and adapter selection.
+
+- `join(name, {owner, wakeAddress?})` atomically establishes membership and its seat when absent.
+  A same-owner reconnect preserves the establishing generation. On a detached seat it also
+  reattaches, using the operation's supplied wake address, and returns `reconnected`, with no
+  activity, new read horizon or listening changes. A foreign owner gets `already_joined`; takeover
+  must be explicit.
+- `reattach(name, {owner, wakeAddress?})` returns a handle for an exact-owner standing seat, or
+  `null` for absent, foreign or done custody; it never creates membership. A foreign takeover racing
+  the transaction can instead refuse. It can also refresh an attached seat's wake address subject to
+  native-route preference. Host start/resume restores only detached seats found through
+  `seatsOf(owner)` before arming delivery. One unavailable location or
+  failed reattachment does not block the others. A new or forked session has a different owner and
+  restores nothing. Hosts never infer restoration from a historical departure.
+- Participant mutations require both the captured generation and an attached current seat.
+  Detach suspends existing handles; they cannot express, catch, listen, leave or change
+  deferrals until reattachment. Rejoin/takeover fences old handles permanently, even if the same
+  owner later reacquires the name. Host cleanup checks owner and generation inside its transaction;
+  stale, foreign, done or already-detached detach changes nothing. Host `cancelDeliveries` also
+  requires the captured owner/generation and an attached current seat; it does not consume activity.
+
+The HOME index supplies candidate paths only. Successful file-backed joins and non-null
+reattachments attempt best-effort publication; opening or expressing does not publish. Losing the
+index may delay restoration or delivery but cannot transfer a seat, erase delivery evidence or
+consume unread activity. A wake address is transport readiness for an attached seat, not an
+alternative ownership fact.
 
 ## Independent delivery deferrals
 
-`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral` require that same captured
-current seat. Deferrals live in the artifact, keyed by normalized participant, generation and fresh
-UUID, independently of the single catch lease and of delivery claims/receipts. A lease contains
-only its validated metadata match and expiry; it is not an acknowledgement intent or an activity.
+`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral` require the same captured,
+attached current seat. Independent artifact-owned leases belong to one participant and generation,
+separately from catch ownership, delivery claims and receipts. Each has a fresh opaque ID, validated
+metadata match and expiry. It is not an acknowledgement intent or an activity.
 
 Each lease's nested own-property scalar equalities combine with AND; matching active leases combine
-with OR. Renewal cannot revive an expired lease. Release touches only its named live lease, and
+with OR. Renewal cannot revive an expired lease. Release touches only its named live lease and
 returns false for an absent/expired ID. A current owner cannot use another participant's ID.
-Expired rows may be pruned during owner writes; read/claim eligibility always checks expiry and
-the current generation. Done/takeover/rejoin remove deferrals in the same transaction, and stale
-rows can never become active for a new generation.
+Expiry is checked live. Detach, done, takeover and rejoin clear deferrals in the same transaction;
+reattachment never revives an old lease.
 
 Deferrals change only proactive eligibility. They preserve audience, history, unread counts and
-explicit catch. An explicit catch consumes normally and prevents later replay after release.
-All proactive paths recheck the same typed policy at claim and final send/presentation boundaries.
-An already-dispatched external message cannot be recalled by acquiring a lease.
+explicit catch. A caught record is not replayed after release. Producers, observers, claims and
+final send/presentation gates all require attached current custody and apply the same deferral
+policy. Neither detach nor a deferral can recall an already-dispatched external message.
 
 ## Acceptance boundaries
 
-Tests exercise foreign and stale handles, same-body reconnection/rejoin, explicit takeover,
-transaction-scoped generation fences, independent leases, precise expiry, explicit catch and
-stdio parity. Assertions belong to the authoritative facts, not helper call ordering or display
-copy. Migration of old owner/route facts is offline and explicit; see [migration.md](migration.md).
+Tests exercise foreign/stale/detached handles, same-owner restoration with unread activity intact,
+voluntary leave, explicit takeover, permanent deletion, exact-owner adapter lifecycle, generation
+fences and delivery eligibility. Assertions belong to authoritative facts, not helper ordering or
+display copy. Migration is offline and explicit; see [migration.md](migration.md).