@astrosheep/square 0.3.92 → 0.3.94

package/guides/square-api.md

@@ -1,26 +1,28 @@
 # Square and Participant API
 
-`Square` is the actual resource handle shared by SDK, CLI, MCP and Pi. `square-api.ts` selects a
-structural backend resource: `sqlite-square.ts` owns existing local semantics, and `square-stdio.ts`
-adapts that same API over a process connection. `square.ts` remains the executable CLI entrypoint.
+`Square` opens the concrete local SQLite resource shared by SDK, CLI, MCP and Pi. `square-api.ts`
+exports the public `{at, build, inMemory}` entrypoints and `type Square`; `square.ts` remains the
+executable CLI entrypoint.
 `square-facade.ts` contains only public types. There is no separate operation factory, policy
-dispatcher or `{data, projection}` envelope. See [backends.md](backends.md) for runnable configuration,
-URI encoding, the versioned protocol and explicit remote limitations.
+dispatcher or `{data, projection}` envelope.
 
 ## Open, select, join, close
 
 Membership is explicit: no harness joins a square based on its filename or working directory.
-`PUBLIC.square` has exactly the same behavior as any other square file.
+`PUBLIC.square` has exactly the same behavior as any other square file. Membership (join/done,
+read horizon and listens) is separate from host attachment (whether an exact owner is currently
+executing for that participant). Host shutdown detaches; it does not make the participant leave.
+An owner is an opaque, non-secret string compared only for equality. It is not a participant name
+or authentication credential: one owner may control several names. The SDK requires it explicitly;
+`localUserOwner()` supplies `user:<OS username>@<hostname>` when that is the intended actor.
 
 ```ts
 import { Square } from '@astrosheep/square';
 
-const square = await Square.at({
-  path: './discussion.square',
-  body: { channel: 'example', session: 'alice-process' },
-});
+const owner = 'example:alice-process';
+const square = await Square.at({ path: './discussion.square' });
 try {
-  const joined = await square.join('Alice');
+  const joined = await square.join('Alice', { owner });
   const alice = joined.participant;
   const sent = await alice.express('Hello @Bob', { force: true });
   const page = await square.history();
@@ -31,92 +33,181 @@ try {
 ```
 
 - `Square.build({path, markdown, hardCap?, throttlePerMinute?, template?, force?, ...})` returns
-  the same open resource. `Square.inMemory({markdown, ...})` is synchronous and creates no default
-  native wake transport.
-- `Square.at` accepts `path`, optional `cwd`, `body`, `wakeAddress`, `clock`, `wakeTransport`,
-  `backends`, default `participant`, and a caller-owned connection via `resources`. At the entry
-  boundary, optional `env` resolves path/configuration, the clock, the concrete transport and the
-  discovery index path once. The opened local resource and participant operations do not carry an
-  environment object or derive identity from it. Supply an explicit Body (`channel`, `session`,
-  optional `agent`) for writes; read-only operations need none. `wakeTransport` injection is retained
+  the same open resource. Public `Square.at` and `Square.build` resolve an omitted `wakeTransport`
+  once from `env ?? process.env` to the product's Claude/Codex/Paseo defaults; if creation fails,
+  opening still succeeds without proactive wake. A supplied port is used unchanged; `false`
+  disables proactive wake. Activities still land normally without a transport.
+- Synchronous `Square.inMemory` uses only an explicitly supplied port; omitted or `false` means
+  no wake. An injected transport runs the same claim, deferral and final currentness checks as
+  file delivery. Each memory resource has a unique `memory://` identity; this is not a remotely
+  openable address, is not indexed, and does not enable file-based hooks.
+- `Square.at` accepts `path`, optional `cwd`, `env`, `clock`, `wakeTransport` and a caller-owned
+  connection via `resources`. At entry, `env` resolves the path, clock and discovery index path
+  once. `Square.at`, `Square.build` and `Square.inMemory` do not capture a
+  `owner`, `wakeAddress` or default `participant`. The same resource can serve multiple owners;
+  identity is supplied at each join or participant selection. `wakeTransport` injection is retained
   for both file-backed build/open and memory resources.
-- Paths resolve against `cwd`; an omitted path uses `SQUARE_LOCATION` at entry.
-  `stdio://name/key` stays a canonical URI and routes before filesystem access. The `backends`
-  configuration selects named stdio aliases.
-- `await square.participant(name?)` selects a handle **without joining, claiming or reentering**.
-  A supplied name or explicit resource `participant` selects that voice; without either, the artifact
-  must recognize exactly one current seat for the captured Body. Zero or multiple matches refuse.
-  `await square.recognize()` returns all current handles held by that exact Body; the discovery index
-  never establishes ownership, and a name alone never authorizes writes.
-- Join with an explicit name: `square.join('Alice', options?, control?)` returns one `JoinResult`:
-  `{participant, activity, kind, participantCount, observation?}`. The name is required at every
-  boundary: an omitted or blank name refuses, even when the resource has a default `participant` or
-  the captured Body holds exactly one current seat. Only `participant()` performs that unambiguous
-  current-body selection. `participant` is a handle, not a
-  string. `takeover: true` atomically replaces a standing seat; a rejoin after done establishes a new
-  join generation. Same-body reconnection retains its generation. Old handles remain fenced after
-  takeover or rejoin, including when the same Body reacquires the name. There is no separate
-  `Participant.join()` or public `takeover()` API. `participantCount` counts known joined-or-done names.
-- A Square owns its connection unless `resources: createSquareResourceOwner()` lends it one.
-  Closing a borrowing handle leaves that owner open. Request signals never become the borrowed
-  connection's lifetime. The MCP server drains cancelled/in-flight work before closing its owner;
-  explicit location overrides get independent request-owned connections. Stdio opens always own
-  their process connection (SQLite resource lending does not pool remote processes).
+- Local artifact paths resolve against `cwd`; an omitted path uses `SQUARE_LOCATION` at entry.
+- `await square.participant(name, {owner})` selects an **attached, standing** seat held by that exact
+  owner without joining, claiming or reentering. It never manufactures a ghost handle: a never-joined,
+  done, foreign or detached seat is refused with `already_joined`, `reason: 'needs_seat'` and a `join`
+  recovery fact.
+  Foreign custody still requires explicit takeover. The returned handle captures the current owner
+  and generation; subsequent mutations recheck custody. A name alone never authorizes writes.
+- `await square.seatsOf(owner)` returns the owner's standing seats as
+  `[{name, generation, attachment}]`, including attached and detached seats but not done participants.
+  It is read-only and neither joins nor restores a seat. `selectOwnSeat(square, owner, name?)` is the
+  adapter helper: an explicit name is checked through `participant`; otherwise exactly one attached
+  seat is required. For an overview-capable call,
+  `selectOwnSeat(square, owner, undefined, {optional: true})` instead returns `undefined` for a missing
+  owner or zero/multiple attached seats. Selection does not change membership.
+- Join with an explicit name and owner: `square.join('Alice', {owner, wakeAddress?, ...options}, control?)`
+  returns one `JoinResult`: `{participant, kind, activity, observation?}`. The name is required even
+  when the owner holds exactly one seat. `participant` is a handle, not a string. `takeover: true`
+  atomically replaces a standing seat; a rejoin after done establishes a new join generation.
+  Same-owner reconnection retains its generation. A detached seat reattaches with kind `reconnected`,
+  no activity and no change to its read horizon or listens; the operation supplies any wake address.
+  A foreign owner still needs explicit takeover, including for an away participant. Old handles remain
+  fenced after takeover or rejoin, including when the same owner reacquires the name. There is no
+  separate `Participant.join()` or public `takeover()` API.
+- Owner selection prevents accidental custody reuse, not malicious impersonation; never let untrusted
+  input choose another caller's owner. A Square owns its connection unless
+  `resources: createSquareResourceOwner()` lends it one. Closing a borrowing resource leaves that
+  owner open. Request signals never become the borrowed connection's lifetime. The MCP server drains
+  cancelled/in-flight work before closing its owner; explicit location overrides get independent
+  request-owned connections.
+
+The rebuildable HOME discovery index is only a source of candidate paths, never custody authority.
+File-backed successful joins and non-null reattachments attempt best-effort publication of their
+owner and path; opening, building, selecting a participant or expressing does not publish. Memory
+resources are not indexed. Losing the index may delay discovery, but cannot transfer a seat.
+
+## Adapter owner resolution
+
+Owners are nonempty strings without control characters, at most 512 UTF-8 bytes. The core stores
+and compares them without interpreting harnesses. One adapter codec, `harnessOwner`, escapes each
+coordinate segment with `encodeURIComponent`: `<channel>:<session>[:agent:<agent>]`.
+`decodeHarnessOwner` is for adapters only; custom owner strings need no harness spelling.
+
+CLI uses `--owner` or `SQUARE_OWNER` exactly when supplied, then one complete native harness
+coordinate (Paseo is auxiliary), otherwise `localUserOwner()`. Multiple native identities or an
+incomplete Claude-child identity refuse rather than using the human's owner. Plain terminal owners
+have no automatic host lifecycle or wake address: join explicitly and use `catch --idle`.
+MCP uses the call-local harness coordinate, else its configured owner, never tool arguments. Pi and
+native adapters encode their own coordinate; the Slack bridge uses its local configured owner.
+`inbox(input, owner)` and `square inbox --for-owner <owner>` select exact opaque equality.
+
+## Host attachment lifecycle
+
+`square.detach(name, {owner, generation})` checks the exact owner and generation inside the artifact
+transaction. It returns `true` when it detaches, or `null` for stale, replaced, foreign, done or
+already-detached custody. It lands no activity, preserves membership/read horizon/listens, and
+clears wake readiness, catch ownership and delivery deferrals. Detached handles cannot write,
+including an empty catch; reattachment or same-owner rejoin restores access. Proactive claims,
+observers and final send/presentation checks exclude detached seats. Existing receipts and delivery
+evidence survive. A detached participant stays away indefinitely; no timer manufactures a departure.
+
+`square.reattach(name, {owner, wakeAddress?}, control?)` restores a standing seat of that exact owner
+and returns a `Participant`, or `null` if the seat is absent, foreign or done; it never creates
+membership. It preserves the generation, read horizon and listens. On an already attached seat it
+returns a handle and can refresh the supplied wake address, subject to native-route preference.
+Host start/resume restores detached seats found with `seatsOf(owner)` before arming delivery,
+independently across seats and locations. Concurrent departure or takeover remains fenced; a foreign
+takeover between the initial seat read and transaction can refuse instead of returning `null`.
+New/forked owners restore nothing, and hosts do not recover from historical done coordinates.
+
+There are three endings: participant `done` ends membership; Pi shutdown, Codex SessionEnd and
+Claude session end detach only; host-confirmed permanent deletion uses
+`square.endHeld(name, {owner, generation})` to land a fenced `done` on an attached or detached seat,
+returning its lifecycle result or `null` when custody no longer matches. OpenCode `session.deleted`
+is permanent deletion. Takeover replaces either attachment state with `done -> join`; late cleanup
+or restoration by the old owner cannot reclaim it.
+
+`square.cancelDeliveries(name, {owner, generation})` is also generation-fenced: for an attached
+current seat it advances the suppression boundary through the current activity head, returning
+whether it changed. A mismatched seat returns `false`; a detached or concurrently replaced seat may
+be refused. It does not consume activity or recall an external send already past its final check.
 
 ## One set of operations and defaults
 
 Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
 A file-backed `stream` follows the path with a fresh artifact read for each page, so atomic file
 replacement is visible even while the resource holds its original connection. Its iterator owns
-its observation lifetime: `return()` interrupts a pending pull; closing the Square does not close
-that independent path observation. Internal readers that explicitly borrow an artifact port leave
-its lifetime with the lender and propagate port failures rather than waiting for path repair.
+its observation lifetime: `return()` interrupts a pending pull; closing a local Square does not close
+that independent path observation.
+Internal readers that explicitly borrow an artifact port leave its lifetime with the lender and
+propagate port failures rather than waiting for path repair.
+
+`Activity` is `{id, at, kind, actor, body?, metadata?, mentions, reach?, target?, reply?}` throughout
+the SDK. Stream without a recipient yields these activities; with a recipient it selects
+their landed directed activities and adds `perception` and the landing route `via`
+(`mention`, `reply`, `attention`, or `bell`). Perception follows the viewer's actual landed audience;
+`via` is absent when no directed route exists. Stream starts at a bounded tail or after an `ActivityId`
+like `act/12`; it never consumes activity.
 Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `hold`, `resume`, `done`,
-`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`;
-its `history` delegates to the same Square history operation.
+`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`. History belongs only to
+Square; there is no `Participant.history`.
 
 - Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
-  includes the committed `activity`, `waited`, optional `delivery`, and landing-time warnings
-  (`unmatchedMentions`, `replyAuthorNotHere`). Warnings are not stored on the activity.
+  includes the committed `activity`, optional landing-time warnings (`unmatchedMentions`,
+  `replyAuthorNotHere`), `hint` and `observation`. Warnings are not stored on the activity.
 - A say may carry `metadata`, an immutable JSON object with nested JSON values and a maximum serialized
   UTF-8 size of 16 KiB (`ACTIVITY_METADATA_MAX_BYTES`). `alice.express({body?, metadata?, ...options}, control?)`
   is the object form; the existing `express(body, options?, control?)` form remains valid. A non-empty
   body may carry `{}`; an omitted, empty or whitespace-only body requires non-empty metadata. Metadata-only
   says omit `body` from public activity records. Invalid objects, cycles, unsupported values and oversized
   metadata refuse before landing with `activityUnsent`. Metadata is carried unchanged by express, history,
-  catch, status/latest, unread projections and stream records through the SDK, stdio, CLI and stream.
+  catch, status/latest, unread projections and stream records through the SDK, CLI and stream.
   MCP and Pi tools are not a metadata surface: their `express` requires a body and its schema rejects a
-  `metadata` argument, and every shared tool receipt omits metadata, so tool history/catch results carry
-  the same activities without it. Metadata does not affect mentions, replies, listening, audience,
+  `metadata` argument. Tool history/catch return rendered text with a structured-activity placeholder,
+  not metadata JSON or activity objects. Metadata does not affect mentions, replies, listening, audience,
   ordering, consumption or permissions. A current participant may temporarily defer proactive delivery
-  by exact metadata match through the SDK/stdio lease API below. Metadata may nest up to 256 levels; the bound is enforced before
+  by exact metadata match through the SDK lease API below. Metadata may nest up to 256 levels; the bound is enforced before
   persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
   metadata JSON. There is no archive metadata filter, query language or index; CLI `--metadata <json>` is the only
   metadata input flag.
-- Catch returns `{activities, consumedThrough, remaining, idleExpired, status?, observation?}`.
-  Omitted/zero idle is immediate; positive idle uses the single leased quiet wait. Receipt selection,
-  ordinals, counts and terminal facts settle in the receipt transaction. Cancellation/replacement
-  releases only that waiter's lease and never consumes future activity.
+- Catch returns `{activities, remaining, reason, hint?, observation?}`. Each activity includes
+  viewer-relative `perception` and `via`. Reasons are `drained`, `idle`, `capped`, `quorum`,
+  `replaced`, or `already-active`. Omitted/zero idle is immediate; positive idle uses the single
+  leased quiet wait. Receipt selection, perception, routes, counts and terminal facts settle
+  in the receipt transaction. Cancellation/replacement releases only that waiter's lease and never
+  consumes future activity.
 - All history callers return a `HistoryResult` object with `activities`. Default page size is ten;
   `limit: null` explicitly requests an unbounded archive. Numeric limits must be 1–100. Contextual
   queries still reject an implicit merged window over 100 activities; an explicit numeric limit
-  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts.
+  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts; history
+  observations retain lifetime say ordinals for CLI `history --format number`.
 - `participants()` returns `{participants, observation?}` and `listening()` returns
-  `{listening, observation?}`, not arrays carrying metadata.
+  `{listening, observation?}`, not arrays carrying metadata. Participant summaries use `presence`
+  (`never-joined`, `active`, `watching`, `away`, or `done`). Away participants remain members,
+  count toward in-square totals and keep receiving normal bell, mention and listened audience. Status reports a non-null `held` whenever a
+  hold is active; `by` is omitted only for historical actorless holds. Its roster supplies the
+  participant counts. Core `square.status({viewer})` uses only the explicitly supplied viewer; with
+  no viewer it returns an unfiltered overview without viewer-specific `listening`. Core status does
+  not select or authorize a seat. CLI and tools check an explicit `--as`/`as` with `selectOwnSeat`;
+  otherwise exactly one attached seat of the caller's owner becomes the viewer, while zero or multiple
+  seats (or no owner) produce the overview. Snapshot participants use the same `name`, `presence` and
+  `listening` facts, excluding never-joined people; its detached `delivered(name, id)` predicate
+  remains available.
 - `unlisten(target)` removes only that participant's current listen edge to the target, without
   leaving or blocking future mentions/replies. It returns the same `ListenerChangeResult` as listen
   and ignore, with `activity: null` when no listen exists. Existing ignores are unchanged. Earlier
   landed audiences and receipts are never rewritten; listening again remains available.
-- Lifecycle operations use the same artifact custody gate. Done accepts no message and retires
-  only its captured Body/join generation; it never implicitly rejoins or grants a completed seat
-  write authority.
+- Lifecycle operations return `{activity, observation?}` and use the same artifact custody gate;
+  observations do not repeat the activity. Join entry uses public activities with settled perception,
+  and status observations use public join activities. Done accepts no message and retires only its
+  attached, captured owner/join generation; it never implicitly rejoins. A done participant is not
+  recoverable authority for any host path.
+- Recovery summarizes unread directed activity with per-sender count, latest age and the single
+  greatest-index preview. Age uses the greatest timestamp, which may belong to another activity.
 
-Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
-Listener/lifecycle operations take optional observation options before that control argument.
+Operations that accept an `OperationControl` use a final argument with `signal` and optional typed
+`onProgress`. Listener/lifecycle operations take optional observation options before that argument;
+participant selection, seat discovery and host cleanup methods do not take an `OperationControl`.
 
 ## Temporary proactive delivery deferral
 
-SDK and stdio Participants expose the same three operations. There are no CLI/MCP/Pi authoring
+SDK Participants expose three operations. There are no CLI/MCP/Pi authoring
 commands or listing operation in this delivery. Existing proactive adapters still obey deferrals.
 
 ```ts
@@ -147,7 +238,7 @@ try {
   24 hours. Invalid matches, durations and IDs refuse with `invalid_args` before mutation.
 - Renewal extends that same live lease from the renewal operation's clock; expired/missing IDs
   return `null`, and release returns `false`. Independent overlapping leases are never merged;
-  releasing one cannot end another. A captured current Body/join generation is required for every
+  releasing one cannot end another. A captured current owner/join generation is required for every
   mutation. Stale handles retain the ownership refusal; done/takeover/rejoin retire old leases.
 - Lease writes change delivery revision, not conversation history. They do not create a receipt,
   change audience or unread counts, hide an archive record, or prohibit explicit catch. Catch alone
@@ -163,7 +254,7 @@ try {
   with acquisition and remain dispatched; a sink effect already written cannot be withdrawn.
   Presentation eligibility is checked before the effect, not again as a veto after success. A batch
   claims and filters its items before its one sink call, then records exactly the successfully rendered
-  set under each captured Body/join generation. A lease acquired while the sink returns or before a
+  set under each captured owner/join generation. A lease acquired while the sink returns or before a
   later item's evidence commit does not erase success or allow replay after release. Cancellation
   likewise stops pre-effect work, not truthful completion after a successful sink: evidence settles
   on the original connection with an independent bounded storage lifetime and the same seat fences.
@@ -179,13 +270,23 @@ has a concrete optional observation type, without conditional generics or a gene
 Data-only calls do not hydrate join history, the pre-expression feed, catch presence enrichment,
 or history/status presentation annotations.
 
-Express captures its optional directed feed before the attempt and returns count/held/time facts
+Express captures optional unread context before the attempt: the latest five directed,
+unseen activities after the current join, each preview capped at 400 Unicode characters,
+plus the count outside that preview. It hydrates only that page, not the entire cursor suffix.
+This is a nonconsuming preview even when a short body fits in full; only `catch` or the
+normal full-notification presentation path consumes it. Count/held/time facts come
 from the committed transaction. Listener and lifecycle observations likewise use their mutation's
 facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
 entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the
 successful receipt survives. Catch preserves its committed page even if optional nearby presence
 fails. A cancellation or failed clock after commit cannot turn these receipts into an unsent retry.
 
+Delivery readiness is participant-specific, not a property of the Square resource.
+`ParticipantSummary.deliveryAvailable`, `JoinObservation.deliveryAvailable` and
+`CatchObservation.deliveryAvailable` reflect whether the participant's seat has a stored wake
+address. Catch captures this fact with its selection. Join and catch observations require
+`observe: true`. These flags do not prove that a receiver is live or that delivery succeeded.
+
 `OperationError.operation` supplements authoritative error facts with caller/filter/recipient and
 express certainty. Selected-row/execution failures remain unknown unless admission proved the
 expression unsent. CLI saves raw drafts even when opening the resource fails; its initial open
@@ -194,39 +295,94 @@ receives the express abort signal, while recovery reopening is deliberately unca
 ## Adapters and standalone functions
 
 CLI and tools only adapt input, identity, resource lifetime and output. They do not import private
-actions, storage, admission, scanners or query execution. MCP/Pi use the shared `square-tools.ts`
-definitions. Join JSON contains `participant.name` and the receipt fields, never the handle or its
-resources. Express wire output omits the internal delivery diagnostic as before.
+actions, storage, admission, scanners or query execution. CLI `--json` for join, express, catch,
+history, listen, ignore, unlisten, listening, hold, resume, done, status, participants and inbox
+serializes the same SDK result without requesting `observe: true`. Only `observation` is omitted and
+a live Participant handle becomes `{name}`. History returns one JSON document, including an empty
+`activities` array; `history --format` remains human-oriented. `participants --limit` limits only
+human text, not the SDK result. Stream `--ndjson` remains one SDK stream record per line.
+
+MCP/Pi use the shared `square-tools.ts` definitions. All eight tools return only the CLI's rendered text, with no `outputSchema`
+or `structuredContent`. Join text includes its context and recent activity; express text
+includes landing ID/reach, warnings and bounded unread previews, never the sent body echo
+or internal observation tables. Failures remain failed tool results with readable recovery
+text. The SDK and CLI JSON keep their full domain receipts. The optional express observation
+contains `context: {activities: [{id, actor, preview, truncated}], remaining}`, not the old
+unbounded `pendingPublic`/ordinal/perception tables.
+
+Express still finishes attempted notification delivery before releasing its resource.
+It overlaps at most four receiving sessions per dispatch, preserving order within each
+session and draining started work even on failure. Claims, final freshness checks and
+uncertain-delivery suppression remain unchanged. Paseo inventory discovery is asynchronous;
+overlapping attempts share only the in-flight inventory read, never a cached idle status.
+The standalone `discoverPaseoAgents` export now returns a promise.
 
-`discover(input, options?, control?)`, `inbox(input, sessionId, options?, control?)`,
+`discover(input, options?, control?)`, `inbox(input, owner, options?, control?)`,
 `diagnoseSquare(input, control?)`, and `migrateSquare(input, control?)` are ordinary public exports.
 They are not methods on a synthetic cross-square object. Diagnose/migrate resolve a path without
 opening a valid current-format Square first.
 
 ## Artifact format and explicit migration
 
-The current artifact format is 5. It owns participant seats, delivery evidence, cancellation and
-independent delivery deferrals, separate from conversation activities and catch leases; `unlisten` remains a real history activity. Ordinary opens
-refuse older formats with migration guidance and never convert them implicitly.
+The current artifact format is 7. It stores opaque owners rather than harness coordinates and
+preserves format 6's attached/detached distinction. Seats, delivery evidence, cancellation and
+independent delivery deferrals remain separate from conversation activities and catch ownership.
+Ordinary opens refuse older formats with migration guidance and never convert them implicitly.
 
 Stop all sessions and services using the artifact, make an offline backup, then run
 `square --location <path.square> migrate` and `doctor` before reopening with upgraded runtimes.
-For formats 2/3, also freeze and back up the legacy HostLedger used for owner/evidence import.
-Format 4 adds only an empty deferral table and its owner/generation/expiry index, preserving
-all existing facts and revisions without consulting HostLedger. Supported row formats 2/3 convert
-directly into format 5 in one transaction, only when owner/route/join mappings are
-directly verifiable; no seat is manufactured for done participants. Replay-critical native ambiguity
-refuses rather than disappears, including the conservative refusal of any nonempty legacy token-only
-tombstone table. Current-format migration is a byte-preserving no-op. See [migration.md](migration.md)
-for the deliberately lossy metadata policy, source-preserving refusal and filesystem requirements.
-Updating a package does not migrate files or install a new runtime.
-
-## Deliberate migration breaks
+Supported formats 2–6 convert to 7 in one transaction. Format 6's Body coordinates become encoded
+owners while attachment, generations, wakes, evidence and revisions survive. Formats 4/5 first gain
+attached seats; format 4 also gains empty deferral support. Formats 4–6 never consult HostLedger.
+Historic host-cleanup departures cannot be distinguished from voluntary `done` and stay done.
+For formats 2/3, also freeze and back up the legacy HostLedger used for verified owner/evidence
+import; no authority is manufactured for done participants. Replay-critical native ambiguity
+refuses rather than disappears, including any nonempty legacy token-only tombstones.
+Current-format migration is a byte-preserving no-op. See [migration.md](migration.md) for the
+narrow metadata policy, source-preserving refusal and filesystem requirements. Updating a package
+does not migrate files or install a new runtime.
+
+## SDK breaking migration: opaque owners
+
+Artifact format 7 requires explicit migration of existing format-6 artifacts before opening.
+`Body`, `sameBody` and `validateBody` are removed from the core and public API. Replace identity
+objects with an explicit owner at each identity-bearing operation; do not put identity on a resource:
+
+```ts
+import { Square } from '@astrosheep/square';
+
+const aliceOwner = 'example:alice-process';
+const bobOwner = 'example:bob-process';
+const square = await Square.at({ path: './discussion.square' });
+try {
+  // Previously: pass body/wakeAddress/participant to Square.at and join(name).
+  const { participant: alice } = await square.join('Alice', { owner: aliceOwner }); // wakeAddress is optional
+  const { participant: bob } = await square.join('Bob', { owner: bobOwner }); // same resource, another owner
+  // For an already attached seat, select it without joining:
+  const selected = await square.participant('Alice', { owner: aliceOwner });
+  const seats = await square.seatsOf(aliceOwner);
+  const { activities } = await square.history(); // not alice.history()
+  const status = await square.status({ viewer: selected.name });
+  console.log(alice.name, bob.name, seats, activities, status);
+} finally {
+  await square.close();
+}
+```
+
+Replace `recognize()`/`bodySeats()` with `seatsOf(owner)`, followed by explicit attached-seat
+selection as needed; replace `implicitJoin` with `reattach(name, {owner, wakeAddress?})`. Replace
+`detachOwnedSession`/`endOwnedSession` with the generation-fenced `detach`/`endHeld` methods above.
+`forBody` is removed: use the same Square with operation-local owners. Read readiness from
+participant summaries or join/catch observations, not the removed resource-level
+`automaticDeliveryAvailable`. Core status no longer infers a viewer. Participant selection no longer
+returns a handle for a missing, done, foreign or detached seat.
+
+## Other deliberate migration breaks
 
 The independent `createSquareApplication` API, its options/results/aliases, and `square-application.ts`
-are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins must use
-`(await square.join(name)).participant`; history callers must use `.activities` and opt into full
-archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
+are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins return
+`(await square.join(name, {owner})).participant`; history callers must use `.activities` and opt into
+full archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
 uses `path`, consistent with `Square.at`, rather than `squarePath`.
 
 External consumers must migrate before taking this source version. Editing source does not update

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.92",
+  "version": "0.3.94",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -80,6 +80,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.0",
     "cross-spawn": "^7.0.6",
+    "jsonc-parser": "^3.3.1",
     "zod": "^4.6.5"
   },
   "peerDependencies": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.92",
+  "version": "0.3.94",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.92",
+  "version": "0.3.94",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/opencode/delivery.ts

@@ -3,47 +3,55 @@ import { createArtifactPort } from '../../artifact.js';
 import { deliverPending } from '../../delivery-operations.js';
 import { nativePendingPreview, observeSessionPending, projectSessionSeats } from '../../inbox.js';
 import { automaticWakeEligible, presentationBlocksWake } from '../../delivery.js';
-import { sameBody, type Seat } from '../../model.js';
+import { type Seat } from '../../model.js';
+import { harnessOwner, decodeHarnessOwner } from '../../owner.js';
 import type { SquareRead, WakeRequest, WakeTransportPort } from '../../ports.js';
 import { formatActivityId, parseActivityId } from '../../square-core.js';
 import { indexedSquareEntries } from '../../square-index.js';
 import { asSeatRef } from '../../seats.js';
+import { restoreSessionSeats } from '../../session-lifecycle.js';
 import { presentPending } from '../../presentation-operations.js';
 import { createNativeInputId, sendNativeText, type OpenCodeNativeSession } from '../../packages/agent-delivery/src/opencode-native.js';
 
 const routeKind = 'opencode-server' as const;
-const bodyFor = (sessionId: string) => ({ channel: 'opencode', session: sessionId });
+const ownerFor = (sessionId: string) => harnessOwner({ channel: 'opencode', session: sessionId });
 const payloadHash = (payload: string) => createHash('sha256').update(payload).digest('hex');
 export interface OpenCodeContextMessage { readonly id?: string; readonly role: string; readonly content: readonly { readonly type: string; readonly text?: string }[] }
 
-function preview(facts: SquareRead, location: string, seat: Seat, index: number) {
+function preview(facts: SquareRead, location: string, captured: Pick<Seat, 'participant' | 'owner' | 'generation'>, index: number) {
+  const seat = facts.seat(captured.participant);
+  if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== captured.generation || seat.owner !== captured.owner) return undefined;
+  const wake = seat.wakeAddress;
+  if (wake?.kind !== routeKind) return undefined;
   return nativePendingPreview(facts, {
-    location, routeKind, sessionId: seat.body.session, participant: seat.participant,
-    actIndex: index, address: { sessionId: seat.body.session }, now: Date.now(),
+    location, routeKind, generation: seat.generation, participant: seat.participant,
+    actIndex: index, address: wake.address, now: Date.now(),
   });
 }
 
 export async function indexedOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<readonly string[]> {
-  return [...new Set((await indexedSquareEntries({ channel: 'opencode' }, env)).map((entry) => entry.body.session))];
+  return [...new Set((await indexedSquareEntries({ }, env)).flatMap((entry) => {
+    const coordinate = decodeHarnessOwner(entry.owner);
+    return coordinate?.channel === 'opencode' ? [coordinate.session] : [];
+  }))];
 }
 
 export async function discoverOpenCodeSeats(sessionId: string, env: NodeJS.ProcessEnv, signal?: AbortSignal) {
-  return projectSessionSeats({ body: bodyFor(sessionId), env }, signal);
+  return projectSessionSeats({ owner: ownerFor(sessionId), env }, signal);
 }
 
 function sameSeat(left: Seat | undefined, right: Seat): boolean {
-  return left !== undefined && left.generation === right.generation && sameBody(left.body, right.body);
+  return left !== undefined && left.attachment === 'attached' && left.generation === right.generation && left.owner === right.owner;
 }
 
 function createOpenCodeWakeTransport(target: OpenCodeNativeSession, lifetime: AbortSignal): WakeTransportPort {
   return {
     probe: async (route) => !lifetime.aborted && route.kind === routeKind
-      && route.sessionId === target.sessionId && route.address.sessionId === target.sessionId,
+      && route.address.sessionId === target.sessionId,
     async attempt(request: WakeRequest, timeoutMs: number, beforeSend) {
       const index = parseActivityId(request.activity);
       const artifact = request.artifact;
       if (artifact === undefined || request.claimToken === undefined || index === undefined
-        || !sameBody(request.seat.body, bodyFor(target.sessionId))
         || request.route.kind !== routeKind || request.route.address.sessionId !== target.sessionId) {
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention has no matching artifact claim or session.' };
       }
@@ -51,13 +59,13 @@ function createOpenCodeWakeTransport(target: OpenCodeNativeSession, lifetime: Ab
       const started = Date.now();
       if (signal.aborted || !await beforeSend())
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before send.' };
-      const { value: prepared } = await artifact.read((facts) => preview(facts, request.location, request.seat as Seat, index), signal);
+      const { value: prepared } = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
       if (prepared === undefined) return { outcome: 'not-capable', diagnostic: 'OpenCode attention is no longer current.' };
       const inputId = createNativeInputId();
       const correlation = { harness: 'opencode' as const, token: inputId, payloadHash: payloadHash(prepared.payload) };
       if (!await artifact.prepareDelivery({ seat: request.seat, claimToken: request.claimToken, correlation }, signal))
         return { outcome: 'not-capable', diagnostic: 'OpenCode delivery claim is no longer current.' };
-      const fresh = await artifact.read((facts) => preview(facts, request.location, request.seat as Seat, index), signal);
+      const fresh = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
       if (fresh.value === undefined || payloadHash(fresh.value.payload) !== correlation.payloadHash)
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before native send.' };
       if (signal.aborted || !await beforeSend())
@@ -66,7 +74,7 @@ function createOpenCodeWakeTransport(target: OpenCodeNativeSession, lifetime: Ab
         inputId, delivery: 'steer', timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), signal,
       });
       if (result.state === 'accepted') return { outcome: 'accepted' };
-      if (result.state === 'unavailable') return { outcome: 'failed', unavailable: true, retainRoute: true, signature: result.code };
+      if (result.state === 'unavailable') return { outcome: 'failed', signature: result.code };
       return { outcome: 'unknown', signature: result.code };
     },
   };
@@ -124,7 +132,7 @@ export async function observeOpenCodeContext(sessionId: string, messages: readon
 
 /** The native receiver owns no claims outside the artifact; HOME is used only for discovery. */
 export async function receiveOpenCodePending(target: OpenCodeNativeSession, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void> {
-  const observer = await observeSessionPending(bodyFor(target.sessionId), env);
+  const observer = await observeSessionPending(ownerFor(target.sessionId), env);
   const transport = createOpenCodeWakeTransport(target, signal);
   let waiting: ReturnType<typeof observer.wait> | undefined;
   try {
@@ -167,7 +175,8 @@ export async function receiveOpenCodePending(target: OpenCodeNativeSession, env:
 
 /** Publish the native address into current artifact seats; the legacy route projection is not read. */
 export async function publishOpenCodeAddress(sessionId: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<boolean> {
-  const seats = await discoverOpenCodeSeats(sessionId, env, signal);
+  await restoreSessionSeats(ownerFor(sessionId), env, { kind: routeKind, address: { sessionId } }, signal);
+  const seats = (await discoverOpenCodeSeats(sessionId, env, signal)).filter(({ seat }) => seat.attachment === 'attached');
   for (const { location, seat } of seats) {
     if (signal.aborted) return false;
     const artifact = createArtifactPort(location, undefined, signal);
@@ -182,6 +191,7 @@ export async function publishOpenCodeAddress(sessionId: string, env: NodeJS.Proc
 export async function cancelOpenCodeDeliveries(sessionId: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void> {
   for (const { location, seat } of await discoverOpenCodeSeats(sessionId, env, signal)) {
     if (signal.aborted) return;
+    if (seat.attachment !== 'attached') continue;
     const artifact = createArtifactPort(location, undefined, signal);
     try {
       const { value: through } = await artifact.read((facts) => facts.header().lastActIndex, signal);
@@ -194,8 +204,8 @@ export async function endOpenCodeSession(sessionId: string, env: NodeJS.ProcessE
   for (const { location, seat } of await discoverOpenCodeSeats(sessionId, env, signal)) {
     if (signal.aborted) return;
     const { Square } = await import('../../square-api.js');
-    const square = await Square.at({ path: location, env, body: seat.body, participant: seat.participant });
-    try { await square.endOwnedSession(seat.participant, sessionId, seat.generation, seat.body); }
+    const square = await Square.at({ path: location, env });
+    try { await square.endHeld(seat.participant, { owner: seat.owner, generation: seat.generation }); }
     finally { await square.close(); }
   }
 }