@astrosheep/square 0.3.93 → 0.3.94

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, hold, 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).

package/guides/pi-tools.md

@@ -11,11 +11,40 @@ const result = await tools.square_express({
   body: 'A different angle on this.',
   mentions: ['aoi'],
 });
-text(result);
+text(result); // CLI text: confirmation and bounded unread previews
 ```
 
-`location` defaults to `SQUARE_LOCATION`; relative paths use the current call's cwd. `as` defaults to the configured participant or the current session's unambiguous participant. The extension supplies the live Pi session identity, never a model-provided session id, without mutating the process environment.
+`location` defaults to `SQUARE_LOCATION`; relative paths use the current call's cwd. Join requires
+an explicit `as`. For later participant operations, an explicit `as` must name a current attached
+seat of the live Pi owner; without it, exactly one such seat is required. Status checks an explicit
+`as` the same way, but without `as` uses the sole attached seat as viewer or gives an unfiltered
+overview if there are zero or multiple. The extension encodes the live Pi session with
+`harnessOwner({channel: 'pi', session})`, never a model-provided session id, without mutating
+the process environment.
 
-Codemode receives the operation's data object directly. Failures return `{ error: { code, message, facts?, operation? } }` and are marked as failed tool results; scripts must inspect `error`. `catch` consumes activity; `history` does not. Exact parameters and semantics come from the tool descriptions, shared with MCP through `square-tools.ts`.
+All eight tools return the CLI's human-readable text, without an `outputSchema` or
+`structuredContent`. In Pi codemode, a successful call resolves to a `string`:
+use `text(result)`, not `text(result.text)`. Failures are marked as failed tool results;
+codemode rejects with the readable error and recovery commands rather than returning
+an error object. For machine-readable domain results, use the [SDK](square-api.md).
 
-Each operation owns and closes its connection through the facade, including cancellation cleanup. Existing notification delivery, rendering and session lifecycle stay independent. Reload the extension after installing an updated package to register the tools in an existing Pi session.
+`express` confirms landing and reach warnings without echoing the sent body. Unread
+context shows at most the latest five directed activities, in chronological order,
+with at most 400 Unicode characters per preview. Already consumed activities are
+excluded, including those beyond an earlier unread hole. Previews never consume
+activity; the text supplies a `catch` command and the count of other unread activities.
+Use `catch` for consumption or `history` for archives. Exact parameters and semantics
+come from the tool descriptions, shared with MCP through `square-tools.ts`.
+
+Each operation owns and closes its connection through the facade, including cancellation cleanup.
+Pi `session_shutdown` detaches that exact owner's seats, not membership: no `done` lands, listens
+and the read horizon remain, and mentions received while away stay unread. Catch ownership,
+deferrals and wake readiness are cleared. Detached participants cannot write or receive proactive
+delivery. On `session_start`, before watching, the extension uses `seatsOf(owner)` to discover only
+that exact owner's detached standing seats and `reattach(name, {owner, wakeAddress?})` to restore them.
+One failed seat/location does not block the others. New/forked harness owners restore nothing, voluntary
+`done` is never revived, and away has no timeout. Permanent deletion is a separate host-confirmed
+membership ending; Pi shutdown is not such proof. See [participant-ownership.md](participant-ownership.md).
+
+Notification rendering remains independent of tool calls. Reload the extension after installing
+an updated package to register the tools in an existing Pi session.

package/guides/primitive-history-consolidation.md

@@ -57,7 +57,7 @@ Entry still uses the actual selector with explicit `['say', 'done']` kinds and i
 ## Necessary distinctions retained
 
 - **Defaults:** SDK `Square.history` is unbounded. SDK `Participant.history` defaults to ten. Application/CLI/MCP default to ten, cap explicit limits at 100, and reject an implicit merged context larger than 100 with the original `operation.historyBounds` detail. Supplying a limit bounds that context. Application's stricter grep/fixed, non-empty search, finite since and safe nonnegative context validation is unchanged; SDK search remains intentionally looser.
-- **Three subsets:** raw selected records can contain reads and historical actorless lifecycle records; public `Activity` omits read/actorless records but retains listen/ignore; ordinary terminal visibility contains join/say/done/hold/resume. Hidden listener events still occupy page positions. Since/context windows still select raw bookkeeping; ordinary history excludes reads. JSON/field formatting continues using raw records. No third event model was introduced.
+- **Three subsets:** raw selected records can contain reads and historical actorless lifecycle records; public `Activity` omits read/actorless records but retains listen/ignore; ordinary terminal visibility contains join/say/done/hold/resume. Hidden listener events still occupy page positions. Since/context windows still select raw bookkeeping; ordinary history excludes reads. Field formatting uses raw records; CLI JSON now serializes the public SDK result and omits bookkeeping records. No third event model was introduced.
 - **Paging:** cursor bounds remain exclusive stable IDs, sparse context counts existing positions, and from/mention/search intersect before applying the limit. An after cursor selects the oldest eligible page; otherwise the newest eligible page is selected. `order` only reverses the selected page. Continuation uses the terminal-visible subset and the same filtered candidate universe; a listener-only page has no invented terminal anchor. Audience paging continues through empty intersections.
 - **Projection:** ordinals, presence anchors, standing/held facts and final data come from the same read callback. The projection clock is now sampled within that callback instead of after the intermediate async presentation completed. It is still an observation-only operation with no receipt, presence or lease writes. Overflow is rejected before unnecessary anchor/ordinal enrichment.
 - CLI and MCP require no policy changes: CLI continues formatting raw/terminal records and owner-produced continuation; MCP serializes public data only. Catch's renderer-accessor changes are owned by its separate lane.

package/guides/row-storage-design.md

@@ -385,7 +385,7 @@ Presence anchor: if no join, return -1. E=max(J, largest own actor-bearing activ
 - Suffix/behind/unreadActivityCount use directed rows > continuous cursor, **including individually seen rows beyond a hole**. Notification pending instead requires joined, >latest join, individually unseen. Do not substitute one count for the other.
 - Hard cap uses lifetime sayCount. Quorum uses all known peers' done booleans (there must be at least one peer), not only currently standing peers.
 - Throttle: request newest `limit` global say times with at > now-THROTTLE_WINDOW_MS; if that many exist, releaseAt is the oldest returned + window, retry=max(1, releaseAt-now). Bell: newest 1 actor bell timestamp > now-1h; that timestamp +1h is nextAt. Neither query excludes future timestamps.
-- Behind summaries retain current per-sender counts/latest timestamp, last THREE suffix previews and their **suffix-relative** numbering. Lifetime sayOrdinals are for ordinary history/feed rendering; they are not substituted for unread-summary numbers. Block only when !force, suffix nonempty, and freshest summary age > UNREAD_BLOCK_GRACE_MS; max(0,now-at) remains the age. force bypasses behind only.
+- Behind summaries retain per-sender counts, latest timestamp and one greatest-index suffix preview. The latest timestamp need not belong to that preview. Lifetime sayOrdinals are retained for history field formatting, not recovery previews. Block only when !force, suffix nonempty, and freshest summary age > UNREAD_BLOCK_GRACE_MS; max(0,now-at) remains the age. force bypasses behind only.
 
 ### Catch transaction
 
@@ -411,22 +411,22 @@ Keep filesystem hints plus the existing 2-second authoritative revision reconcil
 
 ## 7. Complete caller replacement map (including render dependencies)
 
-No production structure below carries `.state`, all `.activities`, or a deferred DB query. Renderers receive settled perceptions and numbers, never recompute audience from a partial SquareState.
+No production structure below carries `.state`, all `.activities`, or a deferred DB query. Renderers receive settled perceptions, never recompute audience from a partial SquareState; history field formatting also receives selected ordinals.
 
 | Current callers | Exact facts/replacement |
 |---|---|
 | openSquare/openSquareArtifact, wait baselines, watch headers, cli/program | header/revision only; remove preliminary whole-state validation/load. Every normal selected-row decode remains validated. |
 | square-actions join/implicitJoin/takeover/done/endOwnedSession, registry-associated route cleanup | participant/roster as needed, routes, land/replaceRoutes; same host claim lock scopes and cleanup sequences. Takeover done+join is one txn. No full SDK snapshot. |
-| Join's before/after snapshot and CLI hold/resume/done count calls | Current `Square.join` returns its concrete receipt with a Participant handle; optional observations use transaction-captured counts, held state and time. Listener/lifecycle commit facts likewise come from the mutation transaction; join's extra entry history is best-effort. Known joined-or-done `participantCount` remains distinct from the standing count. See [Square/Participant API](square-api.md). |
-| express/decideAct and behind rendering (activity.ts) | header, actor fact, roster for longest standing-body mention resolution, hold, reply head/existence, recentSayTimes, continuous cursor, directed suffix. Admission normalization/error order unchanged. A valid reply coordinate is <nextActIndex, even if a gap: preserve current acceptance of assigned-but-missing reply. ActivityPresentation supplies own count/cap/hold/roster, suffix items with lifetime ordinals + settled full perception, and behind summaries. No whole history used just to number previews. |
+| Join's before/after snapshot and CLI hold/resume/done count calls | `Square.join` returns a Participant handle and committed activity; optional observations use transaction-captured counts, held state and time. Listener/lifecycle commit facts likewise come from the mutation transaction; join's extra entry history is best-effort. See [Square/Participant API](square-api.md). |
+| express/decideAct and behind rendering | header, actor fact, roster for longest standing-body mention resolution, hold, reply head/existence, recentSayTimes, continuous cursor, directed suffix. Admission normalization/error order unchanged. A valid reply coordinate is <nextActIndex, even if a gap: preserve current acceptance of assigned-but-missing reply. Recovery supplies own count/cap/hold and behind summaries with one full preview per sender. |
 | listen/ignore/listening, watch leases and terminal checks | actor fact, outgoing attention; roster only for quorum; land or lease methods. Unknown valid attention target still allowed. Pulse keeps hold-before-terminal priority. |
 | catch / native seen | directed selectors/activity exact, markSeen, cursor/counts in txn; native `current` becomes synchronous `(facts: SquareRead)=>boolean`, evaluated ONLY within reads/receipt txn. It cannot escape or call host I/O. |
-| entryPresentation / cli/square-commands join | bounded newest say/done heads then bodies; selected sayOrdinals; explicit per-index perceptions for the selected viewer; header context/scene; actor's join count from activityCount(kind join, actor identity). Supply `joinedBefore` rather than replaying `.state.acts`. `lastN=null` remains an explicit complete history request, not normal join's default. |
-| statusPresentation / cli/observation-commands status | roster+attention, hold, receiptFacts, continuous cursors and directed counts, fresh lease status; latest say/done + ordinal. Supply last THREE join events after latest public index, total number of such joins, and each `rejoined` boolean from existence of earlier done with EXACT actor spelling (current CLI equality). Latest line carries settled perception for context.name (including '' ambient viewer), not a SquareState. No receipts/history map hydrated. |
+| entryPresentation / cli/square-commands join | bounded newest say/done heads then public activities with settled perceptions for the selected viewer; header context/scene; actor's join count from activityCount(kind join, actor identity). Supply `joinedBefore` rather than replaying `.state.acts`. `lastN=null` remains an explicit complete history request, not normal join's default. |
+| statusPresentation / cli/observation-commands status | roster+attention, hold, receiptFacts, continuous cursors and directed counts, fresh lease status; latest say/done. Supply last THREE public join events after latest public index, total number of such joins, and each `rejoined` boolean from existence of earlier done with EXACT actor spelling (current CLI equality). Latest line carries settled perception for context.name (including '' ambient viewer), not a SquareState. No receipts/history map hydrated. |
 | participants/participantsPresentation/listPresentation | roster-derived status sorted by existing compareParticipantActivity; receipts/leases aggregates for participant statuses; list requires only active names, header preamble and say count. Change probeSquare to create a validated file-backed port, not full read then memory clone. |
 | history / participantHistory / historyPresentation | relational head filter + contextIndexes; hydrate filtered candidate bodies for JS search, otherwise page only; count before final limit; selected ordinals + detached presence anchors/perceptions. Retain CLI lifecycle archive/raw coordinate windows and facade non-read inclusion. See algorithm below. |
-| watchPresentation/watch.ts/renderWatchOutput | pass caught activity ids into projection; hydrate ONLY those rows, selected lifetime ordinals, caller-supplied caught perceptions, participant statuses/clock, count/cap/terminal. Finish/terminal-only call omits ids. No all-history lookup of caught ids. |
-| streamProjection/streamTailProjection | ordinary stream pages raw activity heads BEFORE recipient filtering (100 existing rows), advances cursor to last examined raw row even on empty recipient output. Recipient stream filters historical audience, not pending/seen/latest-join. Tail selects last N matching rows but cursor is artifact's last actual index. Includes raw lifecycle/read exactly where current stream does. |
+| catch selection and rendering | hydrate ONLY selected rows, capture caught perceptions, participant status/clock, count/cap/terminal in the receipt transaction. Empty completion does not hydrate bodies. No all-history lookup of caught ids. |
+| streamProjection/streamTailProjection | stream pages canonical activity heads before recipient filtering, advances its cursor even on empty recipient output, and returns public Activity or viewer-relative PerceivedActivity. Recipient filtering uses the historical landed audience, not pending/seen/latest-join. Tail selects last N matching activities and advances to the artifact head. |
 | sessionInbox/located seats/boundary | exact-body seats + establishing join time, recipient directed unseen pages + live lease; complete result using §6. Boundary's stale-activity fallback uses activity(index) existence, not `.acts.every`. |
 | deliverPending/sweep/delivery-health/notifications | pendingAudience groups or audience(activity)+joined/latestJoin+receipt checks for exact activity, ordered routes and detached host ledger evidence. Eligibility projection takes these typed facts instead of state. Sweep scans past suppressed candidates. Health can explicitly collect its complete pending summaries without bodies; renderer's existing detail cap stays. |
 | Claude cancellation/resume/route discovery | cancellation=max existing activity index with at<=cutoff (not assumed chronological time); use newest activity-head pages in one read txn, testing timestamps from greatest index downward and stopping at the first match. If none matches, cutoff is -1. Resume last join/done by EXACT actor spelling; no full snapshot. Routes keep first-match order. |