@astrosheep/square 0.4.0 → 0.4.2

package/guides/mcp.md

@@ -6,7 +6,7 @@ Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override
 
 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.
+Claude's bundled plugin configures this server automatically. Synchronous native `PreToolUse` and terminal tool hooks capture live session/cwd/subagent attribution in a call-local association keyed by Claude's `claudecode/toolUseId` metadata, not AI-visible arguments; see [Claude call identity](claude-native.md). Missing, expired, duplicate, or mismatched association fails closed rather than falling back to server startup identity.
 
 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.
 

package/guides/operation-cancellation.md

@@ -14,11 +14,8 @@ but the committed activity remains recoverable through `history` or a later `cat
 require a second acknowledgement. The separate `pending` query never consumes; its optional
 follow-up `ack(ids)` commits exact receipts with the same cancellation boundary.
 
-The single catch lease and independent delivery-deferral leases have distinct lifetimes. Cancelling
-an active catch releases only that catch's lease. Cancelling a deferral operation before commit
-prevents its mutation; once creation or renewal commits, the lease survives caller cancellation
-until explicit release, expiry or retirement of its captured seat. A committed release is likewise
-not undone. There is no automatic rollback lease or per-message cancellation timer.
+Cancelling an active catch releases its catch lease, permitting still-unconsumed activity to proceed
+at the next ordinary posting opportunity. It cannot recall export ownership already committed.
 
 Ownership and delivery have the same limitation: cancellation can stop work that has not entered the boundary, but it cannot withdraw an ownership effect or a transport send that already happened. The returned committed result and existing degradation classification remain authoritative.
 

package/guides/participant-ownership.md

@@ -1,91 +1,27 @@
 # Participant ownership
 
-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 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
-returns false for an absent/expired ID. A current owner cannot use another participant's ID.
-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. 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/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.
+Membership and host attachment are distinct. Square owns the standing participant, opaque owner,
+join generation, listens and read horizon. The host delivery ledger owns session attachment and
+routes; it does not own membership. An owner is not an authentication credential.
+
+`done` ends membership and outgoing listens. After the leave commits, Square best-effort withdraws
+matching posted cards for that captured participant and join generation when they are not already in
+ledger custody. It does not consume producer history or recall an in-custody effect. Cleanup failure
+does not undo the leave or make it retry. A later join establishes a fresh generation; explicit takeover fences the
+previous owner and generation. Host end only detaches the ledger session:
+the participant remains away without a timeout, retains audience and unread activity, and cannot
+write or receive proactive delivery. Start/resume attaches the ledger session, not individual seats;
+there are no seat restore or detach hooks. A voluntary departure or takeover is never resurrected.
+Host-confirmed deletion marks the ledger session deleted; the next privileged mutating Square
+operation reconciles it and lands a generation-fenced `done`. Read-only history, status and
+participants do not perform that mutation.
+
+Participant handles capture owner and join generation; stale, departed or replaced custody refuses.
+Sandbox selection and exact ACK authorize against locally known World custody alone,
+without requiring access to the user ledger. This is not proof of current host attachment: a ledger-only
+detach or deletion is learned at the next privileged producer reconciliation. A local control never
+grants host delivery authority or revives a deleted session; export checks the actual ledger state.
+
+Exact future ACK is producer-owned and recipient-scoped; see [square-api.md](square-api.md).
+Proactive delivery suppression belongs in the host delivery ledger; see
+[delivery-primitives.md](delivery-primitives.md).

package/guides/pi-native-delivery.md

@@ -1,58 +1,21 @@
 # Pi shared native delivery
 
-The shipped `plugins/pi/square-pi.js` remains the **only Square Pi extension**.
-Both its activity steer and advisory `nextTurn` send call the SDK-free shared
-`sendPiMessage` leaf compiled from `packages/agent-delivery/src`. Square keeps
-framing, custom type, display, preview/UI, observation/presentation evidence,
-uncertain-landing and canceled-batch suppression; the leaf neither schedules nor tracks.
-
-Pi injection and external wake injection acquire mutually exclusive artifact-owned content custody.
-An accepted or uncertain Paseo wake suppresses native Pi reinjection without asserting presentation
-or consumption. Only proven failed/released attempts can return to the automatic queue. Missing
-landing events, thrown sinks and expired claims do not authorize replay. Renderer details describe
-only the batch that won custody, not the earlier observed inbox. Budget-omitted activities belong to
-that same delivered batch: the omission line settles their presentation as `clipped`, without a
-full-consumption receipt. They stay available to explicit catch, but never get paged into later
-model completions or replayed on extension reload. See `delivery-primitives.md`.
-
-For independent existing-session delivery, opt into its local receiver:
-
-```sh
-mkdir -m 700 /private/path/delivery
-pi --agent-delivery-socket /private/path/delivery/p.sock
-```
-
-The parent must already be private and caller-owned. Explicit macOS Unix endpoint
-only; no discovery, registry, daemon or second extension. The flag is read lazily
-at session start. Missing flag creates no socket. Occupied paths fail closed.
-Session replacement closes outstanding connections and rebinds the same endpoint
-to the new identity; old targets reject.
-
-`observed` / `message_end` means only the matching native extension event was seen.
-Pi 1.1.0 emits that event before final append. It is **not durable admission,
-final append, model processing, completion or display**. No branch polling or
-cross-extension transform compatibility is promised.
-
-Standalone extensions can register `createPiReceiver` from the package's `./pi`
-subpath and use `sendPiMessage` directly. Factory registration creates no
-resources; start/shutdown own them. Session replacement and shutdown await the
-pending observer's retirement, including cleanup already begun by run cancellation.
-Cancellation releases native landing waits; it does not leave the observer running
-behind a completed lifecycle hook. Restart after cancellation waits for the old
-observer before opening its successor. Shutdown waits for in-flight automatic
-startup before ending that session, and awaits the session-end work. Raw SDK hosts
-must emit and await `session_shutdown` before `dispose()`;
-disposal alone does not retire extension-owned observers or receivers.
-
-Transport frame/key constraints, client
-`connectExisting`/`sendText` usage, receipt states, bounds and the exact validated
-runtime evidence live in `@astrosheep/agent-delivery` `README.md` and
-`VALIDATION.md`. Reproducer:
-
-```sh
-npm run build
-node --import ./test/sandbox-env.js packages/agent-delivery/test/pi-runtime.mjs /absolute/installed/pi-1.1.0-package-root
-```
-
-No real accounts/settings/sessions are used. Terminal keystrokes/rendering, other
-Pi builds and platforms are not dynamically validated.
+`plugins/pi/square-pi.js` is the Square Pi extension. It watches the host delivery ledger and uses
+the shared Pi send leaf for native injection. A receiver-pull presentation and producer-push handoff
+compete through ledger attempt state, not route declarations. Accepted or uncertain handoff is not a
+presentation receipt and must not be blindly replayed. The boundary's bounded batch renderer records
+receipts only for presented cards. Square folds a receipt into read state only when its activity card
+contained the full body; shortened cards point to catch.
+
+Display items come directly from validated producer-neutral card details (`origin`, optional `author`,
+`ref` and `badge`, and full Markdown `body`). Display never opens Square history. Missing or invalid
+details fall back to card text. Model-facing reminder text is unchanged, and a full display body does
+not make a shortened model-facing card eligible to consume producer unread activity.
+
+Pi session start and shutdown attach and detach the ledger session, not Square seats. Interactive
+cancellation suppresses outstanding local deliveries without marking activity seen; activity after
+cancellation can notify normally. A send already past its final check cannot be recalled.
+
+The `message_end` event is a native observation, not proof of model comprehension or final durable
+append. Independent existing-session Pi delivery, socket constraints and runtime evidence are in
+[agent-delivery's README](../packages/agent-delivery/README.md) and `VALIDATION.md`.

package/guides/pi-tools.md

@@ -37,14 +37,12 @@ Use `catch` for consumption or `history` for archives. Exact parameters and sema
 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).
+Pi `session_shutdown` detaches that exact owner's ledger session without ending membership: no `done`
+lands, listens and the read horizon remain, and mentions received while away stay unread. Detached
+participants cannot write or receive proactive delivery. `session_start` attaches the same owner in the
+ledger before watching; it does not restore individual seats. New/forked harness owners do not inherit
+another owner's membership, 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.