@astrosheep/square 0.3.88 → 0.3.90

package/guides/participant-ownership.md

@@ -1,186 +1,60 @@
-# Participant Ownership
-
-This document defines the ownership boundary for a participant name, a host
-session, and its wake route. It is the contract for ordinary `join`, automatic
-session startup, explicit `--kick`, and session shutdown.
-
-The central invariant is simple:
-
-> At most one live host session owns a participant name in one square.
-
-An artifact participant and a host session are related, but they are not the
-same fact. The artifact is authoritative for the participant lifecycle. The
-host ledger is authoritative for the local session binding. A wake route is
-only a callable address for an existing binding.
-
-The uniqueness key is the canonical square location plus `nameKey(name)` (the
-same normalized identity used by the artifact). Display spelling does not
-create a second participant.
-
-## Owners
-
-| Fact | Authority | May change it |
-| --- | --- | --- |
-| Participant name is known, active, or done | Square artifact (`SquareState`) | Square actions in an artifact transaction |
-| Session owns a name at a location | Host ledger presence | Registry/ledger binding operations |
-| Session can be woken | Wake route in the square artifact | Route operations after the lifecycle commit |
-| CLI or hook requested join, kick, or shutdown | CLI or host adapter input | The caller only; it does not become a new authority |
-
-No layer may use display text, a route row, or an old registry row as a
-replacement for the authoritative fact it does not own.
-
-## Call Boundaries
-
-The artifact boundary and the host boundary exchange facts, not each other's
-storage objects:
-
-- `square-core` and participant lifecycle actions decide and commit activities
-  (`join`, `done`, takeover) and artifact-owned wake routes. Their post-commit
-  presence refresh is best effort; they do not discover foreign sessions,
-  claim names, or remove another session's presence.
-- The host ledger claims and releases `(location, name, session, channel)`
-  bindings. It does not append participant activities and it does not decide
-  whether a name is active in the artifact.
-- The name claim must be an atomic compare-and-set on `(location, name)`:
-  observe-then-upsert (`listPresence` followed by `ensurePresence`) is not a
-  claim and cannot enforce the one-owner invariant under concurrency.
-- CLI and hook orchestration obtains the current session identity, sequences
-  the two boundaries, and performs exact-session cleanup. It may pass a
-  participant name and a lifecycle intent to an artifact operation; it must
-  not pass host binding rows or `oldSessionIds` into a square action.
-- Route publication and retirement write the artifact route set. A route is
-  useful only while its exact session binding is owned; route rows are not a
-  second name-ownership ledger.
-
-The intended shape is therefore `claim/verify -> artifact transaction ->
-presence/route effects`. A helper that combines those steps is an orchestration
-helper, not a square action. In particular, a `takeover(name,
-oldSessionIds)`-style API is the wrong boundary: the artifact can retire the
-active participant routes by name, while the host adapter cleans old presence
-by the exact sessions it observed.
-
-## Ordinary Join
-
-`join` is a name claim, not a reconnect heuristic.
-
-1. Validate the requested participant name.
-2. Ask the host ledger to claim the `(location, name)` binding for the current
-   session. An existing binding for another session is a hard refusal. A
-   binding that this same session already held is an idempotent reconnect. A
-   newly-created claim is provisional until the artifact check below passes.
-3. In one artifact transaction, decide and commit the participant `join`
-   activity when the name is not active. If the artifact already says that the
-   name is active, only a pre-existing binding for this exact session may
-   reconnect; release a provisional claim and refuse every other caller.
-4. After the artifact commit, ensure presence for the current session only.
-5. After presence is established, publish the current session's primary wake
-   route.
-6. Render the entry result from the committed artifact snapshot. Rendering
-   does not perform another ownership decision.
-
-If any precondition fails, no join activity, presence row, or route is created
-left behind for the refused session. A reconnect does not append another `join`
-activity.
-
-## Automatic Session Startup
-
-Automatic startup is a host adapter around the same ownership semantics. It is
-not an implicit kick and it does not get a separate exception for configured
-names.
-
-1. Derive the participant name from the provider session and environment.
-2. Attempt the host-ledger binding claim.
-3. If another session owns the name, return the coded `already_joined`
-   refusal. Do not rewrite the artifact, remove the other session, or create a
-   second binding.
-4. If the current session already owns the binding, refresh its presence and
-   route without another artifact `join`.
-5. If the name is new, commit the single artifact `join`, then establish
-   presence and route as in ordinary join.
-
-The hook boundary catches and reports this refusal according to host policy;
-the hook must not silently turn it into a takeover.
-
-## Explicit Kick
-
-`join --kick` is the only name-takeover operation. It is an explicit human
-action and must leave an observable lifecycle, not merely overwrite a ledger
-row.
-
-1. Resolve the requested name and collect the currently active bindings for
-   that name. The current session is excluded from the old-owner set only when
-   it is already the owner and this is a reconnect, not a kick.
-2. In one artifact transaction, commit two lifecycle activities:
-   `done` for the standing participant, followed immediately by `join` for the
-   reclaimed name. If this transaction cannot commit, nothing is kicked.
-3. In the same artifact transaction, remove every route for the kicked
-   participant. The artifact operation receives only the participant name; it
-   does not receive host session rows. The new route is not published until
-   after the transaction succeeds.
-4. After the artifact commit, remove every old owner's presence from both
-   readable ledger scopes. The cleanup is keyed by the exact old session and
-   channel; never remove by participant name alone.
-5. Establish the new session's presence and publish its route.
-6. Reconcile once from the committed artifact and ledger facts. Reconciliation
-   may remove stale external rows, but it may not invent a join or undo the
-   committed takeover.
-
-The resulting history must contain `join -> done -> join`. A successful kick
-must leave no old binding and no old callable route. If external cleanup is
-temporarily unavailable, the artifact still records the kick and the cleanup
-remains retryable and session-scoped.
-
-## Session Shutdown
-
-Session shutdown is owner-scoped.
-
-1. Look up the binding by the exact session id and square location in the host
-   ledger.
-2. If no binding exists, stop without changing the artifact.
-3. If the binding exists and its participant is still active, ask the artifact
-   boundary to commit that participant's `done` activity. The artifact action
-   does not need the session id.
-4. Remove that exact session's presence in the host ledger and retire that
-   exact session's route in the artifact.
-5. Do not mark a replacement session done, even when it uses the same display
-   name. Under the invariant, such a replacement should have been rejected or
-   created through `--kick`.
-
-A shutdown arriving after a kick is an idempotent cleanup of an already-removed
-owner. It must not append a second `done` for the new owner.
-
-## Concurrency and Recovery
-
-The artifact transaction serializes participant lifecycle activities. The host
-ledger lock serializes binding rows. They protect different facts and must not
-be replaced with a copied sidecar or a display-level mutex.
-
-The safe ordering is:
-
-1. Claim or verify the session binding.
-2. Check the artifact state and commit its lifecycle transaction.
-3. Apply presence and route effects for the committed result.
-4. Retry or reconcile only the external effects that did not commit.
-
-An operation must never claim success from a partially completed sequence. A
-failed precondition produces no artifact mutation. A post-commit ledger or
-route failure produces a diagnosed, retryable external inconsistency while
-preserving the artifact's committed lifecycle.
-
-## Acceptance Evidence
-
-The implementation is complete only when these invariants are directly tested:
-
-- two sessions cannot concurrently own the same `(location, name)`;
-- same-session reconnect is idempotent and appends no second `join`;
-- automatic startup refuses a foreign owner and never performs a kick;
-- `join --kick` records `done -> join` atomically;
-- kick cleanup removes old presence and routes by exact session identity;
-- a kicked session's later shutdown cannot close the replacement;
-- a failed external cleanup is retryable without duplicating lifecycle
-  activities;
-- reconciliation removes stale external rows only when the artifact proves
-  the participant is no longer active.
-
-Tests should assert the authoritative facts and their ownership boundaries,
-not the order of helper calls or the wording of CLI output.
+# 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.
+
+## 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.
+
+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.
+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.
+
+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.
+
+## 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).

package/guides/square-api.md

@@ -71,7 +71,8 @@ replacement is visible even while the resource holds its original connection. It
 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.
-Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `hold`, `resume`, `done`;
+Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `hold`, `resume`, `done`,
+`deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`;
 its `history` delegates to the same Square history operation.
 
 - Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
@@ -86,10 +87,11 @@ its `history` delegates to the same Square history operation.
   catch, status/latest, unread projections and stream records through the SDK, stdio, 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, delivery,
-  ordering, consumption or permissions. Metadata may nest up to 256 levels; the bound is enforced before
+  the same activities without it. 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
   persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
-  metadata JSON. There is no metadata filter, query language or index; CLI `--metadata <json>` is the only
+  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,
@@ -112,6 +114,64 @@ its `history` delegates to the same Square history operation.
 Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
 Listener/lifecycle operations take optional observation options before that control argument.
 
+## Temporary proactive delivery deferral
+
+SDK and stdio Participants expose the same three operations. There are no CLI/MCP/Pi authoring
+commands or listing operation in this delivery. Existing proactive adapters still obey deferrals.
+
+```ts
+const lease = await alice.deferDelivery({
+  match: { fields: [
+    { path: ['job', 'kind'], equals: 'outcome' },
+    { path: ['job', 'id'], equals: 7 },
+  ] },
+  durationMs: 60_000,
+});
+try {
+  // Explicit history and catch remain available, including catch({id}).
+  const renewed = await alice.renewDeliveryDeferral(lease.id, 60_000);
+  // null means absent, expired, or not owned by this current generation.
+} finally {
+  await alice.releaseDeliveryDeferral(lease.id);
+}
+```
+
+- `MetadataScalar` is `null | boolean | number | string`; numbers must be finite. `MetadataMatch`
+  has nonempty `fields`, each `{path: readonly string[], equals: MetadataScalar}`. Paths have one
+  or more nonempty string segments, with no duplicates. Only JSON object own properties are
+  traversed: arrays, missing/nonobject intermediates and inherited properties do not match.
+  Equalities are exact and type-sensitive. A dot inside one segment is a literal key, not path
+  syntax. All fields combine with AND; any matching live lease blocks delivery (OR across leases).
+- Each acquire returns a fresh UUID and an operation-clock ISO `expiresAt`: `{id, expiresAt}`.
+  Match objects are not returned. `durationMs` must be a positive safe integer and is capped at
+  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
+  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
+  consumes normally; a caught record is not replayed when a deferral ends. The catch lease is a
+  separate, single quiet-wait lease with its existing filters and lifecycle.
+- Producer/sweep, atomic claims, session/native projections, final pre-send checks and proactive
+  presentation all share current-generation unexpired matching. Suppressed items get no seen or
+  presented receipt. An active pending observer rechecks on release and the earliest relevant
+  expiry, including renewed deadlines, without needing a new conversation activity. A one-shot
+  producer skips and returns promptly. With no active observer, eligibility is reconsidered at
+  the next normal opportunity; no daemon or per-message timer is created.
+- Acquiring a lease is not recall. An external send already past its final freshness check can race
+  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
+  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.
+  A rejected/cancelled native landing is not a successful sink. Items filtered
+  out before the sink receive no success receipt.
+  Cancellation before commit prevents the lease mutation; after commit it remains until explicit
+  release, expiry, or seat retirement. See [operation-cancellation.md](operation-cancellation.md).
+
 ## Optional observations, not another execution path
 
 Request `observe: true` on the **same method** when rendering needs additional facts. Each operation
@@ -145,13 +205,16 @@ opening a valid current-format Square first.
 
 ## Artifact format and explicit migration
 
-The current artifact format is 4. It owns participant seats, delivery evidence and cancellation,
-separate from conversation activities; `unlisten` remains a real history activity. Ordinary opens
+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.
 
-Stop all sessions and services using the artifact and freeze its legacy HostLedger, back them up
-offline, then run `square --location <path.square> migrate` and `doctor` before reopening with upgraded
-runtimes. Supported row formats 2/3 convert transactionally only when owner/route/join mappings are
+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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.88",
+  "version": "0.3.90",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.88",
+  "version": "0.3.90",
   "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.88",
+  "version": "0.3.90",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/paseo/README.md

@@ -29,16 +29,17 @@ The collapsed heading uses `metadata.details.items`; it never reverse-parses
 the content. Expansion shows `metadata.details.fullText` when available: complete
 notification bodies, even when the model preview was clipped or omitted. Older
 messages fall back to `detail.text`, including clipping notices and catch commands.
+Each displayed body is capped at 32,000 UTF-16 units (omission line included), keeping
+the beginning and end; collapsed previews are capped at 1,000 units before layout.
+Surrogate pairs are not split. Original messages and model input remain unchanged.
 Long content scrolls inside a bounded panel. The
 card does not fetch extra activity or mark anything seen. Live events and fetched history use
 the same transformer.
 
-The card is visually marked as Square: an accent glyph, a SQUARE badge, and the
-square's name sit above the actor line, on a raised surface distinct from ordinary
-tool output. It uses Paseo theme colors, selectable text, accessible expansion state,
-and compact layout on narrow displays. Expansion starts at the top-right arrow;
-collapse returns from the arrow below the expanded content. Removing the plugin restores Paseo's
-ordinary custom-message row.
+An accent glyph, actor and square name identify the card. The header and its arrow
+toggle an inline drawer. It uses Paseo theme colors, selectable text, accessible
+expansion state and compact layout on narrow displays. Removing the plugin restores
+Paseo's ordinary custom-message row.
 
 ## Develop