@astrosheep/square 0.4.0 → 0.4.2

package/guides/claude-native.md

@@ -1,177 +1,13 @@
-# Claude native inbox
+# Claude Code delivery
 
-Square's Claude plugin is a mod, not a shell-hook injector. Its `hooks/hooks.json`
-contains only `{"modules":["./register.js"]}`. Install with `square install claude`
-and load/approve it in a trusted interactive Claude terminal. Installation is
-not evidence of a live receiver.
+The Square Claude plugin uses ordinary native command hooks. It has no mod, native inbox, or producer socket route. `SessionStart` attaches the exact native session to the host delivery ledger; `SessionEnd` fences and detaches that captured attachment without changing Square membership.
 
-Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
-`wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
-synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
+At `UserPromptSubmit`, Square records Claude's native `prompt_id` before presenting pending cards through event-correct `additionalContext`. Tool boundaries (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`) use the same boundary presenter for the exact native main/child owner, so cards arriving during a running turn need not wait for another user prompt. Autonomous hook-generated prompts are boundaries too, not evidence of human approval. A later prompt records presentation only when its input contains the exact complete prepared frame, including the ledger token and stored full-frame hash. That establishes observation before the model processes the prompt, not comprehension. The async frame uses a plain warning and token delimiters; Square never decodes entities or accepts changed/truncated text as an exact observation.
 
-## Validated capability
+At a normal `Stop`, one per-owner OS-locked observer waits for ledger changes for at most 86,400 seconds. It rechecks the exact captured `prompt_id`, attachment generation, Stop epoch and route after acquiring the lock and immediately before output. A new prompt disarms old observers. The watcher claims one card at a time and uses the existing handoff token/hash correlation. Invoked stderr output is `unknown` until that exact frame is observed at a later prompt boundary; there is no automatic fallback replay. Missing prompt IDs fail closed.
 
-The supported baseline is **macOS Claude Code with the mod actually loaded**;
-no build number is pinned. The receiver reads its real session ID, cwd, version, and
-`CLAUDE_CODE_MESSAGING_SOCKET`. A session ID or socket alone is not capability.
-Missing/disabled/unapproved mods, the normal unapproved headless `-p` path,
-and other platforms are unavailable. No legacy fallback exists.
-Square never changes inbound policy, forwards a child token, or impersonates a
-peer/plugin authority. Native OS-user socket permissions and Claude policy apply.
+This is a finite, boundary-driven observer, not a promise of continuous coverage. Missing Stop, timeout, process exit, headless teardown, or a busy Escape with no later normal Stop may leave cards pending. Idle Escape has no classic hook and may not disarm an already waiting observer; already emitted asyncRewake notifications cannot be recalled. No Square inbox fallback is retained for these cases.
 
-`square harness doctor claude` explains installation and these limits.
-`square harness doctor delivery` derives current routes/evidence without sending.
-An absent/broken endpoint is unavailable; it does not consume Square activity.
+The bundled MCP server gets call-local session, cwd, and agent attribution from native `PreToolUse`/terminal tool hooks keyed by Claude's `claudecode/toolUseId` metadata. Duplicate or incomplete call identity is denied by the event-specific PreToolUse permission response; unrelated tool hooks do not block. Cleanup matches tool-use ID, session and agent. Interrupted calls without a terminal hook expire after ten minutes. Models cannot supply identity as tool arguments.
 
-## Native-first routing and policy holds
-
-Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
-joins register the native queue for their thread. Claude and OpenCode receivers
-register their native wake addresses only through their loaded integrations. An
-ordinary reconnect or reattachment cannot replace a current native address with a
-generic Paseo proposal. Addresses belong to the artifact seat generation, not an
-expiring routes table: explicit receiver withdrawal permits fallback, and a new
-seat generation cannot inherit the previous generation's native registration. Endpoint generations
-are opaque strings, compared for equality rather than interpreted.
-Participant expressions do not publish replacement addresses.
-
-This is route preference, not permission to bypass receiver policy. Claude can
-legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
-under `bypassPermissions`. Square neither asserts a made-up permission mode nor
-changes `crossSessionInbound`. After bytes may have been sent, `unknown` remains
-attention-wide and prevents another send through Paseo, even if routes later change.
-
-Each native send persists a message ID before writing; the wire `uuid` and
-`msg_id` carry that ID. Square records no native custody telemetry from Paseo:
-official Paseo exposes no delivery-status lifecycle event, so a held message stays
-`unknown` with `native_admission_unconfirmed`. Recording a `held`, `released` or
-`dropped` observation would require a Paseo-provided event; Square does not patch
-Paseo to invent one. Even when such an observation exists, the event ID is
-deduplicated and the native reason and observation time remain diagnostic only.
-Neither a release nor a drop is a queue receipt, proof of consumption or retry
-authorization.
-
-`square harness doctor delivery` shows native custody separately from pending
-attention for current seat generations, including after the activity is seen. Paseo
-presents the `peer_message_hold` state in its own timeline. Acceptance means normal
-delivery when the receiver allows it, or a visible reason without bypass/replay when
-policy holds it.
-
-## MCP tools and call identity
-
-The plugin's `.mcp.json` starts the existing Square MCP server. The mod no longer
-registers an argv wrapper or executes participant CLI commands. MCP and Pi native
-tools share their operation definitions and facade calls in `square-tools.ts`.
-
-Before a bundled MCP call, the mod uses the existing `square claude-mod` helper
-to publish `{toolUseId, sessionId, cwd, agentId?}`. It then calls `next(e)` unchanged.
-The server correlates `_meta["claudecode/toolUseId"]` with that association: no
-session, agent, token or other transport field is added to the model's schema or
-arguments. Claude's native **session ID plus child flag** semantics are preserved;
-the child loop's `agentId` is retained for attribution, not substituted as a session ID.
-Calls use the live cwd and session even if the MCP process started earlier.
-
-`SQUARE_CLAUDE_MCP_CONTEXT=1` is set only by the bundled MCP configuration. That
-endpoint fails closed if an association is missing or expired; it never silently
-uses the startup parent identity. Generic MCP configurations retain their existing
-identity handling. The hook targets `mcp__plugin_square_square__*`, not unrelated
-servers with similar operation names.
-
-The mod owns publication and token-matched removal in `finally`; the server only
-reads. Associations are private, transient transport files under
-`<host-ledger-root>/claude-mcp-calls`, not Square domain state or another artifact.
-Normal completion/errors remove them. If abrupt cancellation, unload or a crash
-prevents cleanup, they expire after ten minutes and the next publication prunes
-them. Expiry gates lookup, not an operation that already captured its context.
-MCP owns operation cancellation and connection shutdown. No second execution
-protocol, resident service or ledger schema migration is introduced.
-
-## Membership and lifecycle
-
-Participants join explicitly. The mod never discovers or joins a square from its
-filename; `PUBLIC.square` has no special behavior. Existing memberships reconcile
-on startup. Main-conversation tool completion (including failed/aborted tools) and
-conversation start reconcile late memberships: the receiver itself publishes
-routes; the CLI cannot infer mod capability from a socket or session environment.
-This reconciliation injects no activity and does not poll. Its recovery sweep
-only sends previously unsent eligible attention, never unknown/admitted attempts.
-
-Initial activation and hot reload use `session.start`. New conversations use
-`classic.SessionStart`: clear reads the new API coordinate; **resume's event
-`session_id` is already the resumed coordinate while `$.session.id()` still reads
-the ending one (observed in 2.1.295)**. The event coordinate is used at that boundary, with
-API cwd/version/socket. Modern `session.end` detaches only its pinned `e.sessionId`
-and captured owner/join generations, within the event budget. Late committed joins
-are discovered at the pinned end timestamp. A process crash can omit end.
-
-Host end is not a participant departure: no `done` lands, and membership, listens,
-read horizon and generation remain intact. Catch ownership, deferrals and wake readiness
-are cleared; the participant appears away and keeps accumulating unread audience without
-proactive delivery. Before arming a receiver, start/resume discovers the exact owner's
-standing seats through `seatsOf(owner)` and restores only detached ones with
-`reattach(name, {owner, wakeAddress?})`. The adapter obtains that owner with
-`harnessOwner({channel: 'claude-code', session, agent?})`. One failed seat or location does not block the
-others. New/forked harness owners restore nothing. Neither a voluntary `done` nor a takeover is
-revived; there is no completed-seat recovery path or timeout that turns away into done.
-See [participant-ownership.md](participant-ownership.md).
-
-## Body, admission, and presentation
-
-The coordinator uses Square's canonical audience projection and bounded body
-preview. Agora notifications identify the square, receiving participant and activity before its
-event and body. A clipped preview describes catching that activity to read it in full; it never
-embeds shell commands or tool-call syntax. Direct Channel notifications carry their stored preview
-or body instead. Channel custody and consumption use `msg/N`; Agora relations use `act/N`.
-Opaque text correlation resolves through bound memberships and the existing
-attempt ledger, never a path or asserted source from incoming text.
-
-Transport is the Node-only leaf published as `@astrosheep/agent-delivery/claude-native`,
-sourced from `packages/agent-delivery/src/claude-native.ts`. Square imports that
-source directly; its root package ships the compiled leaf without loading the
-OpenCode SDK or requiring a separate agent-delivery installation. There is no
-second socket sender. Receipt semantics (`written` is local bytes only, never
-admission), the plain-peer use, and the standalone client API are documented in
-the package `README.md`; the leaf accepts only target/session endpoint, text, and
-bounded deadline/cancellation control.
-
-`session.receive` runs before native policy; Square owns this admission gate and
-the presentation writer, not the leaf. `await next(e)` confirms queue admission
-only when the returned text is unchanged. Hold/refuse reject that gate;
-consumed/rewritten results cannot confirm the original. Unknown peer messages
-pass through. Recognized stale/cancelled deliveries can be consumed before queueing.
-No ambiguous send is blindly retried.
-
-The sole presentation writer observes **returned stored main user-role text**
-after `session.append.next`. The native attempt persists the payload hash and full/clipped coverage
-before sending. Stored ACK matches the entire framed payload against that persisted hash and checks
-the captured custody and current eligibility; it does not depend on rendering the payload again with
-the current renderer. Persisted full coverage records seen + presented; clipped coverage records
-clipped only. This means stored in model context, not processed or understood. Catch/presentation
-races are idempotent and revalidated immediately before send and inside the observation transaction.
-
-## Cancellation and custody
-
-Explicit plugin `turn.abort` and terminal `turn.complete(reason:'aborted')`
-suppress the outstanding local batch without recording seen. Ordinary answer,
-refusal, and error completion are not user cancellation. Separate engine-owned
-family state survives hot reload, containing the abort timestamp and frozen
-membership generations. The artifact stores a generation-scoped monotonic message-index
-cutoff; replacement generations cannot inherit the old abort.
-
-Engine state reads are snapshots of one dispatch. Confirmation therefore uses
-one immediate fresh `clock.after` dispatch to read cancellation, not a repeated
-read in the old dispatch. It is not polling. If reload cancels a pending callback,
-its evidence stays unknown: reload does not replay it. A failed cancel bridge
-can be repaired by the fresh confirmation/reconciliation dispatch from retained
-engine state. If all bridge/state operations are unavailable, Square cannot
-promise a receipt or suppression; it fails boundedly and preserves unrelated
-Claude behavior.
-
-**Already queued OR natively held messages cannot be retracted.** Approval may
-release a held message without another receive guard. Append is observational,
-not a veto. Square suppresses local retries and stale evidence but cannot erase
-native custody or promise that remote work will not run. New activity after the
-abort remains eligible. Protocol design and runtime evidence live in the package
-`VALIDATION.md` and the commission artifacts it cites; the repository fixtures
-cover the same coordinator and packaging boundaries without requiring a Claude
-installation.
+The installed and tested native runtime evidence is macOS Claude Code 2.1.299 with isolated HOME, plugin settings, delivery ledger and a dummy-key loopback provider. This does not certify other platforms, versions, or headless behavior. The final native prompt/generation check and async hook completion are not atomic. `node --import ./test/sandbox-env.js test/claude-hook-native.mjs` with `SQUARE_CLAUDE_HOOK_NATIVE_SMOKE=1` runs the shipped manifest and candidate CLI through a scratch PATH shim and preserves hook/provider evidence in `/tmp`. It proves repeated idle wake, prompt/attachment fencing, duplicate suppression, active prompt/tool context, native main/child MCP attribution and identity-failure denial.

package/guides/codex-delivery.md

@@ -1,92 +1,67 @@
 # Codex delivery
 
-Square uses the shared Codex leaves in `packages/agent-delivery/src`, rather than
-maintaining a second hook protocol, boundary store or CLI sender. The standalone
-package's [README](../packages/agent-delivery/README.md) describes both its native
-app-server capability and its host-owned hook integration.
+Producers post neutral cards to DeliveryLedger; neither default dispatch nor public `postAndDispatch`
+queues Codex input. A native receiver owns both synchronous presentation and idle queue admission.
+It never reads Square artifacts or producer content stores.
 
-Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
-`wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
-synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
+The shipped hooks for Codex 0.166.0 are synchronous SessionStart, UserPromptSubmit, PreToolUse,
+PostToolUse, Stop, Interrupt and SessionEnd, plus an async Stop command with `timeout: 86400` seconds.
+SessionStart disarms and attaches the exact native session. Active prompt/tool boundaries disarm and
+present eligible cards as event-correct `additionalContext`, using neutral reminder framing and the
+original card text. The output sink must accept the response before presentation evidence is recorded;
+a later suppression does not erase a real output effect. SessionEnd disarms and detaches. None of these
+host lifecycle events restores or detaches Square seats. SessionResume is not a verified native event
+and is not registered. A resume path without a real SessionStart/Stop has no inferred idle authority.
 
-## Square's hook path
+Each synchronous Stop stores a unique token and native turn ID in the existing boundary store. One
+receiver-owned `square codex-watch` command holds a separate private OS-backed lock for its native
+session coordinate and observes the ledger, with a one-second bounded rescan for boundary changes or
+missed notifications. Duplicate async Stop processes exit; the existing watcher follows newer Stop
+tokens. The lock does not prove idle state. Observation never reserves cards while waiting.
 
-`plugins/codex/hooks/hooks.json` invokes `square codex-hook`:
+Before claiming each card, the watcher reads the hosting endpoint's `thread/read(includeTurns:true)`.
+It requires loaded idle state and the newest live turn to be completed with exactly the captured Stop
+turn ID. Newest-last history ordering is verified for 0.166.0; other versions fail closed until verified.
+After claiming, the receiver repeats that native read, checks the exact epoch again, then checks ledger
+currentness, suppression, cancellation, attachment generation, signal and deadline immediately before
+CLI invocation. Queue always uses the existing hosting endpoint explicitly, without starting a service.
+Missing, malformed, ephemeral, notLoaded, active, interrupted or unreadable history cannot authorize a
+queue. A delayed stale Stop cannot authorize sending merely by arriving after an active callback.
 
-- `SessionStart`, `SessionResume` and `UserPromptSubmit` invalidate the previous
-  Stop observation. `SessionEnd` marks the host session ended and detaches its exact
-  owner's seats without landing `done`, ending membership, dropping listens or resetting
-  the read horizon. Later Stop/tool callbacks cannot re-enable queue until a new
-  `SessionStart` or `SessionResume`. Before enabling delivery, those start paths use
-  `seatsOf(owner)` and `reattach(name, {owner, wakeAddress?})` to restore only detached
-  standing seats of that exact owner; voluntary departures and takeovers are never revived.
-  A new/forked session restores nothing.
-- `PostToolUse` asks Square for current pending activity and returns the existing
-  bounded `additionalContext` presentation.
-- `Stop` records queue eligibility and sweeps pending work, but does not itself
-  claim that a preview was presented.
+`square codex-interrupt` handles only a native Interrupt payload and cancels the captured attachment's
+pending through-sequence batch, then future cards remain available after a later verified Stop or active
+boundary. Replacement attachments are fenced by generation. Before-effect epoch/suppression/cancel
+failures release their claims where the ledger permits. Attachment rotation already normalizes an
+in-flight ledger attempt to unknown: that custody remains unknown even if the final receiver check
+then proves no queue was launched. The watcher exits on detach, deletion or generation change and
+retains its ledger connection only for already-captured late settlements.
 
-The shared handler owns hook framing, lifecycle sequencing, its cancellation
-budget and bounded sweeps. Square supplies activity selection, formatting,
-artifact-owned presentation claims, cancellation, attachment cleanup and
-pending-work sweeps. The handler cooperatively awaits Square's pull: the signal
-cancels work before presentation, but a successful presentation's `settleAs`
-finishes independently of request cancellation. Even when that settlement crosses
-the internal budget, the hook waits for it and returns the associated context;
-it never abandons settlement that can mark activity seen without returning text.
-After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
-output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
-an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare session id. The shared
-boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
-defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
-conversation storage and are not proof of current native execution or consumption.
-Square's format-11 artifact remains authoritative for membership, attachment and delivery evidence.
-Message custody uses `msg/N`; Agora activity relations use `act/N`. Endpoint generations are opaque
-and are compared for equality when fencing custody.
-Detached members appear away indefinitely and keep accumulating unread audience, but have no
-write or proactive delivery eligibility until same-owner reattachment. Only a host-confirmed
-permanent deletion uses fenced membership-ending cleanup; Codex SessionEnd is not that proof.
+Queue admission is custody, not presentation or model comprehension. Accepted/unknown outbox custody
+has no remaining card content and cannot be automatically replayed. Invoked timeout or ambiguous
+results remain unknown. Native idle reads and external queue are not atomic: a new turn can start after
+the final check and a raced queue may arrive later. Interrupt cannot recall input already admitted by
+Codex, and hook failure/timeout cannot prove that cancellation happened. Native callbacks have no
+cross-incarnation event identity; SessionEnd can fence only the attachment observed when it runs.
 
-`CodexQueueTransport` implements the existing `WakeTransportPort` and uses the public
-`connect({ harness: 'codex', transport: 'cli', sessionId, boundaries, ... })`
-and `agent.queue(text)` interface, just like independent hosts. Square reads its
-stored pending preview and finishes its currentness gate first; the bound client
-checks boundary eligibility once inside `queue()`, then launches the CLI. No
-caller-side lifecycle check is duplicated. Outcomes continue through the existing
-artifact-owned delivery path; no host ledger or new route kind is introduced.
+There is no watcher before the first Stop. Synchronous boundaries can present; otherwise cards wait.
+The async budget is finite 24 hours, not a promise of 24-hour observation. After timeout, crash, host
+termination or missed spawn while idle, cards wait for the next Stop/user/native boundary. There is no
+producer fallback or autonomous crash-idle recovery. During attachment replacement an old watcher
+may briefly retain the coordinate lock while the new Stop's duplicate exits; the next Stop restores
+observation after the old process releases it.
 
-Both CLI coordinate creation and MCP call-local Codex coordinates capture the
-recipient's `CODEX_HOME` (or home default), so later senders use the recipient's
-CLI configuration rather than their own. Only an explicitly configured
-`SQUARE_CODEX_ENDPOINT` adds a remote endpoint. `SQUARE_CODEX_BIN` remains
-Square's executable selection; it is not an environment convention of the
-independent package.
+Reproduce the isolated native smoke from this checkout after a worktree-local build:
 
-By default the sender runs `codex queue --thread ... --message ...`, allowing the
-CLI's normal connection/startup behavior. Only an explicit endpoint adds
-`--remote`. This does not make another host's private stdio pipe attachable.
-After an observed `SessionEnd`, Square does not dispatch queue; the bound lifecycle
-check also catches an end observed while the currentness gate was running.
-It cannot retract a submission already launched or infer a missed end hook.
-Queue success means native admission only; its receipt id is a local attempt
-UUID, not a server message id. The child runs asynchronously and respects the
-send's abort signal/deadline. Timeout, killed child and unexplained post-launch
-failures remain unknown, not a safe reason to resend. A receiver with no tool
-calls waits for Stop; this path is not instantaneous native steer.
+```sh
+env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
+  node --import ./test/sandbox-env.js test/codex-watch-native.mjs
+```
 
-## Optional native app-server capability
+The probe creates a temporary HOME/CODEX_HOME, installs no plugin, and uses the actual shipped hook
+manifest/CLI with an isolated native app-server and loopback fixture provider. Its JSON evidence names
+the temporary directory. It verifies native Stop startup, idle wake, busy fencing, singleton reuse,
+Interrupt RPC cancellation, real UserPromptSubmit presentation and process-group shutdown. Physical
+TUI Escape-to-Interrupt is not verified; neither are 24-hour operation or every resume path.
 
-Independent consumers can use `connect({ harness: 'codex', sessionId, endpoint })`
-from `@astrosheep/agent-delivery` for fenced busy steer and native queue.
-`transport: 'app-server'` is the explicit spelling and the default when omitted;
-it exposes both methods. `transport: 'cli'` exposes queue only and requires the
-host's hook lifecycle source at connection time. There is no automatic fallback
-between transports. The app-server transport never starts a service or calls
-`thread/resume`. This does not replace Square's hook policy or add a new persisted
-Square route kind. A loaded thread's owner remains its existing host, not the
-external sender.
-
-Neither path implements a read-receipt roundtrip. Admission and runtime
-observations must not be presented as model comprehension or completion. An
-unknown outcome stays unknown. Installing, restarting or changing a real Codex
-server is outside this integration.
+The shared package documents its transport leaves in [its README](../packages/agent-delivery/README.md).
+See [participant ownership](participant-ownership.md) for host attachment and Square membership.

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.