@astrosheep/square 0.4.0 → 0.4.1

package/guides/claude-native.md

@@ -1,177 +1,21 @@
 # Claude native inbox
 
-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.
-
-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).
-
-## Validated capability
-
-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.
-
-`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.
-
-## 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.
+Square's Claude plugin is a mod, not a shell-hook injector. Its MCP server uses the mod's call-local
+session association; a missing or expired association fails closed. A session ID or socket alone does
+not establish that the mod is loaded. The supported native path requires macOS Claude Code with the
+mod loaded and approved. Square does not alter inbound policy or bypass a held peer message.
+
+The mod attaches and detaches the exact host session in the delivery ledger. Membership remains in
+Square; host end does not land `done`, and start/resume does not restore seats. See
+[participant-ownership.md](participant-ownership.md).
+
+The sender dispatches finished ledger cards through the native socket. Native admission settles a
+handoff as accepted, not presented; the stored main user-role text observation settles presentation
+through its handoff reference. This establishes observation at that boundary, not comprehension, and
+cannot promise that a later plugin leaves the card intact. Unknown native custody is not a safe reason
+to replay through another route. A shortened activity card points to catch; Square only folds a receipt
+for a full card into its read state. Direct producer notices retain their full body.
+
+`turn.abort` cancels the outstanding ledger batch without asserting it was read. Already queued or
+natively held messages cannot be recalled. The shared transport and its validated limits are documented
+in [agent-delivery's README](../packages/agent-delivery/README.md) and `VALIDATION.md`.

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.