@astrosheep/square 0.4.0 → 0.4.1

package/guides/delivery-primitives.md

@@ -1,207 +1,48 @@
-# Delivery custody primitives
-
-`@astrosheep/square/delivery` provides storage-independent attempt transitions, suppression predicates,
-and four bound effect functions: `dispatchEffect`, `preparePresentation`, `presentPrepared`, and
-`presentPreparedBatch`. It does not open a square, interpret identities, own transactions, or schedule
-retries. Square's actual dispatch, single presentation and boundary batch adapters compose these same
-lifecycles; its SQLite adapter uses the attempt transitions with existing tables. Ownership, membership,
-cancellation and delivery-deferral policy remain in the bound application capability.
-
-## Bind a series inside a transaction
-
-`AttemptRows<D>` is a capability for **one logical item / recipient / authority / purpose series**.
-The caller chooses those coordinates, including arbitrary opaque strings, and binds the store to them.
-No Square name, seat, generation, activity-id codec or composite-key format is required.
-
-- `list()` returns that series newest ordinal first.
-- `byToken(token)` returns only a matching attempt in that series.
-- `insert(attempt)` and `replace(attempt)` write within the caller's current transaction.
-- Replacements preserve purpose, token, ordinal and the caller's external series coordinates.
-
-The caller guarantees isolation against competing claims, token uniqueness within its token lookup
-scope, atomic commit/rollback, and durable storage where needed. Run each operation and its reads and
-writes inside that boundary; an asynchronous read followed later by an unguarded write is not custody.
-Stores must not retain mutable references that allow a caller to change durable rows without a write.
-`D` belongs entirely to the caller. The primitive does not merge, serialize or interpret it.
-
-```ts
-import { claimAttempt, prepareAttempt, settleAttempt, type AttemptRows } from '@astrosheep/square/delivery';
-
-type Payload = { route?: string; nativeToken?: string; ack?: string };
-// Supplied by the application, already scoped and transaction-bound:
-declare const rows: AttemptRows<Payload>;
-
-const claim = claimAttempt(rows, {
-  purpose: 'dispatch', token: 'application-generated-unique-token',
-  at: 1000, leaseMs: 30_000, data: { route: 'opaque endpoint' },
-});
-if (claim.status === 'acquired') {
-  prepareAttempt(rows, { token: claim.token, data: { route: 'opaque endpoint', nativeToken: 'correlation' } });
-}
-// In a later transaction, only after external proof of acceptance:
-settleAttempt(rows, {
-  token: 'application-generated-unique-token', outcome: 'accepted', at: 1100,
-  data: { route: 'opaque endpoint', nativeToken: 'correlation', ack: 'external proof' },
-});
-```
-
-The example shows only transaction-scoped transitions. Commit a successful claim before external I/O;
-settle its exact token in a new transaction after observing the result. The bound effect capability
-below connects those operations without introducing a generic transaction runtime. Authority fencing,
-currentness policy and the meaning of external proof remain the application's responsibility.
-An `accepted` dispatch is not proof of presentation or consumption. Only the responsible presentation
-boundary may assert `presented`; consuming an item is a separate application operation.
-
-## Square content custody
-
-Dispatch and presentation remain separate evidence series, but they are not independent permission
-to inject content. Square's transaction-scoped domain gate checks both series for the same artifact,
-recipient, seat generation and activity before admitting a new injection. A claim in either series
-blocks the other; accepted, presented, clipped and unknown evidence also block it. Only failed or
-released evidence permits another injection. An expired opposing claim is normalized to unknown in
-that transaction rather than stolen. No lock is held over host or network I/O.
-
-A native receiver that has verified the exact existing wake may pass its claim token as
-`observationOf` to the presentation adapter. The gate verifies the wake belongs to the same captured
-recipient/generation/activity and remains dispatching, accepted or unknown. This records observation
-of that message; its sink must not inject another message. Claude and OpenCode retain their exact
-native correlation/content checks. A successful wake alone never creates a consumption receipt.
-Paseo currently has no corresponding native Pi observation correlation: its accepted/unknown attempt
-stays unconsumed, available to explicit catch, without automatic native reinjection.
-
-Session pending projections used for automatic injection suppress claimed, accepted and uncertain
-items as well as presented ones. Failed/released attempts make them eligible again through delivery
-revision observation. Native payload construction and exact-token observation read their captured
-activity directly, not this injection queue. Cancellation and seat replacement retain their existing
-fences. Uncertainty deliberately favors no automatic duplicate over automatic recovery; no
-exactly-once processing or guaranteed eventual delivery is claimed.
-
-These checks use the existing artifact evidence and transactions; no new registry or artifact format
-is introduced. All running injectors must load the updated code before the guarantee applies.
-
-## Transitions
-
-An `Attempt<D>` has `purpose: 'dispatch' | 'presentation'`, `token`, zero-based `ordinal`, `outcome`,
-finite `at`, optional `expiresAt`, and `data`.
-
-- `claimAttempt` first returns terminal evidence: dispatch `accepted`/`unknown`, presentation
-  `presented`/`unknown`. Otherwise a live `dispatching` attempt is `busy`; missing expiry is live.
-- At exact expiry or later, an interrupted `dispatching` attempt becomes `unknown`, keeps its original
-  payload, loses expiry, and returns `terminal` with `interrupted: true`. There is no new attempt and
-  **no automatic replay of uncertainty**. Square maps that flag to its interruption diagnostic.
-- With neither terminal nor dispatching evidence, claim inserts `dispatching` at the next ordinal.
-  Failed/released attempts can therefore be retried. Purpose-specific terminal meanings are not
-  inferred from other completion labels.
-- `prepareAttempt` replaces only the data of the exact `dispatching` token. Pass the complete merged
-  payload. It returns false for an absent or no-longer-dispatching token. Callers that already know
-  the payload is unchanged may skip the replacement; core performs no JSON equality checks.
-- `settleAttempt` allows `dispatching` to any defined completion, and late `unknown` to `accepted`.
-  It clears expiry and sets time/outcome/data. `accepted` to `accepted` returns true **without any
-  write or payload/time mutation**. All other transitions return false, including `unknown` to
-  `presented`. Missing or foreign tokens cannot settle another series.
-
-Invalid purpose/completion/token/time, non-positive or unsafe lease durations, non-finite expiry, and
-unsafe next ordinals reject before mutation with `TypeError` or `RangeError`, not `SquareError`.
-The caller supplies valid stored attempts and consistently scoped, ordered rows.
-
-## Suppression without payloads
-
-`presentationBlocksDispatch(attempts, now)` and `automaticDispatchEligible(attempts, now)` accept only
-`purpose`, `outcome`, and optional `expiresAt`; no dummy payload or identity is needed. These predicates
-may see both purposes for the same logical delivery.
-
-Presentation `presented`, `clipped`, `unknown`, or `dispatching` blocks dispatch, including an
-expired presentation claim: loss of its lease is uncertainty, not permission to send again. Automatic dispatch additionally requires no dispatch
-`accepted`, `unknown`, or `dispatching`; even expired dispatch custody blocks automatic replay.
-These are preselection predicates, not substitutes for a transactional claim or application gates.
-
-
-## Bound effects: one captured capability, four functions
-
-`EffectPort<C>` is bound by the caller to **one captured work item / recipient / authority / purpose**.
-It exposes only:
-
-- `claim(signal?)`: the application's existing atomic claim, returning `{ token, ordinal }` or
-  `undefined` when busy, terminal, stale or deferred. The runner does not claim the attempt twice.
-- `current(signal?)`: pre-effect policy; a rejected check is unverifiable and treated as false.
-- `settle(claim, completion)`: one captured settlement operation, with no request signal. Return true
-  only when it commits, false when not recorded (not necessarily stale), or throw on persistence error.
-
-The application owns tokens, leases, semantic timestamps, authority, proof/diagnostic payloads and
-resource lifetimes. There is no public transaction type, series-key codec or extra persisted lifecycle.
-`Settlement<C>` keeps the selected completion separate from persistence: `recorded`, `not-recorded`,
-or `error` with the original error. Observations are never erased by persistence refusal/error.
-
-### Dispatch
-
-```ts
-import { dispatchEffect, type EffectPort, type DispatchCompletion } from '@astrosheep/square/delivery';
-
-declare const port: EffectPort<DispatchCompletion>; // bound claim/current/settle
-// A sender must check its absolute deadline/cancellation immediately before external mutation.
-const report = await dispatchEffect(port, async context => {
-  if (!await context.beforeSend()) return { outcome: 'not-capable' };
-  if (context.signal?.aborted || Date.now() >= context.deadline) return { outcome: 'unknown' };
-  // Call the application's transport here, passing the remaining budget and captured claim.
-  return { outcome: 'accepted', data: { proof: 'application acknowledgement' } };
-}, { timeoutMs: 5000 });
-```
-
-`dispatchEffect` owns claim → initial currentness → send → settlement. Cancellation suppresses
-pre-effect work. It starts its timer immediately before invoking the sender, not during claim,
-initial policy reads or persistence. Exactly one returned/thrown/timeout decision is frozen before
-settlement. A sender exception defaults to `unknown`, not failed; returned `not-capable` releases
-custody. A denied final gate releases with `not-current / final` under the sender's obligation to
-obey it. No automatic retry occurs.
-
-`beforeSend()` is **policy currentness, not an elapsed-budget gate**. A stalled policy check may
-return true after the outer timeout. The sender must recheck `deadline` and `signal` after that await
-and immediately before I/O; true does not authorize a late send. Outer timeout stays unknown even
-when no I/O is known to have started. Late gates and late promise results cannot rewrite the frozen
-settlement. Separately correlated native proof may still use the attempt transition's permitted late
-unknown → accepted path; the timed-out runner does not reconcile itself.
-
-### Prepared presentation
-
-`preparePresentation({ payload, coverage, port }, { signal? })` acquires custody without running a
-sink. A returned `PreparedPresentation<P>` exposes `payload`, pre-effect `eligible(signal?)`, and
-promise-cached `release()` for abandonment. It is a local one-shot capability, not a durable row and
-not a public success writer.
-
-`presentPrepared(handle, sink, control?)` specializes the batch lifecycle to one item.
-`presentPreparedBatch(handles, render, sink, control?)` takes all supplied custody before its first
-await. It rejects duplicate, foreign or used handles before any effect, checks eligibility, then calls
-synchronous side-effect-free `render(eligible)` returning `{ payload, included }`. Included handles
-must be a unique exact subset of those eligible handles; invalid rendering releases custody and
-rejects without presentation evidence. No included items means no sink call.
-
-Cancellation is checked immediately before the one sink invocation. There is **no presentation timer**
-and no post-effect cancellation, deferral or currentness veto. The runner awaits the sink and marks
-**all included handles** effect-observed before starting asynchronous settlements. Full coverage
-settles `presented`; clipped coverage settles `clipped`. A thrown sink defaults to `unknown`;
-`classifyError` may explicitly return `failed` (classifier failure stays unknown). Unused handles are
-released, all sibling settlements and cleanup drain even on persistence failure, and later cleanup
-cannot overwrite success or uncertainty.
-
-### Mandatory atomic full-consumption settlement
-
-The presentation binding's single `settle` operation must enforce:
-
-| Completion | Atomic persistence |
-| --- | --- |
-| `presented` | Complete the captured attempt **and all captured full-consumption receipts in the same transaction**. Return true only when the combined operation commits. |
-| `clipped` | Complete the attempt; no full-consumption receipt. |
-| `failed`, `unknown`, `released` | Complete the attempt; no success consumption receipt. |
-
-If receipt writing throws, both receipt writes and attempt completion must roll back. Do not reselect
-items or split `complete` and `recordConsumed` into separately awaited callbacks. Captured ownership
-still fences settlement; request cancellation and new delivery deferrals do not. TypeScript cannot
-supply isolation for a caller, so this is a mandatory port contract, tested in Square's real transaction.
-
-Presentation reports distinguish observed sink behavior from durable persistence. A returned sink
-with `not-recorded` or `error` still returned successfully; that alone proves only the supplied sink's
-documented effect, not model consumption or human display. Square retains throwing sinks as unknown and rethrows the original exception after draining.
-A missing native landing event or a canceled wait cannot prove the message never entered the host. Its single result stays
-`{ presented: true, activity }` only on recorded success, false on ownership refusal; unexpected
-success-settlement errors propagate. Batch returns its original sink value after all settlements,
-with the same error propagation. No schema, storage format or public Square result changes are needed.
+# Delivery ledger
+
+`@astrosheep/square/delivery-ledger` exports `DeliveryLedger` and its types, also available from the
+package root. The per-user ledger defaults to `~/.square/delivery.v3.sqlite` and stores producer-neutral,
+finished text cards, session attachment, routes, attempts and receipts. Producers own content and
+recipient selection; adapters own transport behavior. Routes contain only `{kind, address}`.
+A card may also carry producer-neutral presentation `details`:
+`{kind: 'presentation', origin, author?, ref?, badge?, body}`. `text` remains the bounded model-facing
+card; `body` holds the full Markdown for display. Receivers validate these details and render them
+without opening producer storage. Cards without valid presentation details remain plain text.
+
+Posting is idempotent by owner and key. Producer-push handoff and receiver-pull presentation have
+separate attempt tracks, with cross-track exclusion based on ledger attempt state. Accepted or unknown
+handoff does not establish presentation; uncertain effects must not be blindly replayed. Presentation
+receipts record only the cards confirmed by the receiving boundary. A receipt means observed at that
+boundary, not model comprehension. An observer may not detect a later plugin removing a card.
+Receipt retention is finite: once evidence expires, Square retains unproved local unread until catch
+or ACK, rather than inventing consumption or reinserting an uncertain old card.
+
+The ledger is an outbox. Accepted and unknown attempts drop card text and details in the same
+transaction, retaining only custody so an exact late observation can still write a receipt. A presented
+presentation attempt deletes its card and attempts once no attempt is dispatching; a permanent exact
+suppression prevents reposting the key. Unconfirmed accepted/unknown custody expires only after
+30 days from its latest settlement. Failed and released attempts keep content for retry. Receipts and
+permanent suppressions expire in bounded batches after 30 days. Deleted sessions lose cards, attempts
+and suppressions; sessions detached longer than 30 days lose cards and attempts. Session rows remain:
+a deleted row is the authority for producer reconciliation and cannot be registered again.
+
+Square folds receipts lazily into its own read state only for full activity cards; a shortened activity
+card points to `square_catch` and cannot consume the full activity. Catch permanently suppresses the
+corresponding ledger card where possible. Cancellation suppresses outstanding work without claiming it was seen and cannot
+recall an external send already past its final check. Producers can call
+`ledger.suppress({owner, key, scope: 'exact' | 'prefix', expiresAt?})` to suppress one key or a key
+prefix. Omit `expiresAt` for permanent suppression within ledger retention, or supply an expiry for
+temporary suppression. This does not consume Square activity; producer-owned exact ACK is described
+in [square-api.md](square-api.md). The ledger does not match producer metadata.
+
+Square posting, the Codex Stop watcher and OpenCode receivers retain their original ledger connection while
+an already-invoked handoff has a pending `lateSettlement`. Timeout or cancellation returns promptly;
+the connection closes after the last captured effect settles. It holds no open SQLite transaction and
+grants no further send authority after the caller stops. An effect that never settles may retain an
+idle connection until process exit. Late persistence failures produce redacted diagnostics rather than
+reopening the ledger or retrying the effect. Pi presentation and Claude's independent exact-reference
+confirmation callbacks retain their existing lifetimes.
+
+Codex producers only post. Its native async Stop receiver observes the ledger without holding claims
+while waiting; active UserPromptSubmit, PreToolUse and PostToolUse boundaries present synchronously.
+See [Codex delivery](codex-delivery.md) for exact idle-epoch fencing, cancellation and recovery limits.

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.