@astrosheep/square 0.4.3 → 0.4.5

package/dist/views.js

@@ -131,12 +131,15 @@ export function queryParticipants(facts, context, observe = false) {
     return { participants, ...(!observe ? {} : { observation: { ...context, ...classifyPresence(participants, context.now),
                 standingCount: inSquareCount(facts) } }) };
 }
-export function listPresentation(facts) {
+export function listPresentation(facts, owner) {
     const participants = facts.roster().filter((p) => p.joined).map((p) => {
         const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
         return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
     }).sort(compareParticipantActivity).map((p) => p.name);
-    return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
+    return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }),
+        ...(owner === undefined ? {} : { joined: facts.seatsForOwner(owner)
+                .filter(seat => facts.participant(seat.participant)?.joined)
+                .map(seat => ({ name: seat.participant, pending: facts.directedCount(seat.participant, { unseenOnly: true, currentGeneration: true }) })) }) };
 }
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
@@ -178,7 +181,7 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
         },
     };
 }
-export function catchPresence(facts, now) {
+export function perceivePresence(facts, now) {
     const participants = coreParticipants(facts, now).filter((participant) => participant.presence === 'done' || participant.presence === 'away' || participant.presence === 'watching'
         || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
     return { participants, now };

package/guides/architect.md

@@ -22,11 +22,11 @@
 
 *Stops.*
 
-"Last batch had one little snot. Work got finished — decent work, even — and then it didn't say a single word. Just crouched in the square catching. Catching. Forty whole minutes."
+"Last batch had one little snot. Work got finished — decent work, even — and then it didn't say a single word. Just crouched in the square perceiving. Perceiving. Forty whole minutes."
 
 *Lifts the chip bag and shakes it. Empty.*
 
-"One full bag of washi's chips, from full to empty, and it — was — still — catching. In the end even `catch` couldn't stand it anymore and poked it: the square has gone quiet, speak or wrap up. **Letting the tool rescue you** — aren't you ashamed? washi is ashamed on your behalf."
+"One full bag of washi's chips, from full to empty, and it — was — still — perceiving. In the end even `perceive` couldn't stand it anymore and poked it: the square has gone quiet, speak or wrap up. **Letting the tool rescue you** — aren't you ashamed? washi is ashamed on your behalf."
 
 *Crushes the bag.*
 

package/guides/change-waits.md

@@ -1,7 +1,7 @@
 # Waiting for changes
 
 Filesystem notifications are hints, not activity delivery or receipts. Artifact revision observation
-and reconciliation let catch and stream reconsider changes even if a filesystem event is missed;
+and reconciliation let perceive and stream reconsider changes even if a filesystem event is missed;
 subscribers retain independent cancellation and deadlines. Throttling waits for its eligibility time.
 There is no discovery index and no daemon or per-message timer.
 

package/guides/claude-native.md

@@ -2,12 +2,12 @@
 
 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.
 
-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.
+At `UserPromptSubmit`, Square records Claude's native `prompt_id` before presenting pending cards through event-correct `additionalContext`. `PostToolUse` is the single tool-boundary presenter for the exact native main/child owner, so cards arriving during a running turn can be delivered after a successful tool completes. `PreToolUse` and `PostToolUseFailure` match only Square MCP tools and handle identity publication/cleanup, not presentation. A failed ordinary tool leaves cards for the next PostToolUse, UserPromptSubmit or normal Stop. 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.
 
 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.
 
 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.
 
-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.
+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. The manifest scopes `PreToolUse` and `PostToolUseFailure` to `^mcp__plugin_square_square__.*`, while `PostToolUse` remains unfiltered for delivery and successful MCP cleanup. An ordinary successful tool therefore launches only PostToolUse, not both a pre- and post-tool command. 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.
 
 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,67 +1,101 @@
 # Codex delivery
 
 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.
-
-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.
-
-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.
-
-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.
-
-`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.
-
-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.
-
-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.
-
-Reproduce the isolated native smoke from this checkout after a worktree-local build:
+queues Codex input. The receiver owns synchronous presentation and idle queue admission, without
+reading Square artifacts or producer content stores.
+
+## Six hooks
+
+The Codex 0.166.0 manifest registers one command for each of six events:
+
+- SessionStart attaches the exact native session and registers its queue address.
+- UserPromptSubmit synchronously presents eligible cards as event-correct `additionalContext`.
+- PostToolUse synchronously presents eligible cards as event-correct `additionalContext`.
+- Stop runs one async `square codex-watch` with a maximum timeout of 86,400 seconds.
+- Interrupt cancels the captured attachment's current pending through-sequence batch.
+- SessionEnd detaches the captured attachment.
+
+There is no synchronous Stop command or PreToolUse hook. Active delivery occurs when the user
+submits a prompt or after a tool finishes; a model-only turn with no tools receives pending cards
+after its next Stop through the queue path, or at the next UserPromptSubmit. Host lifecycle never
+restores or detaches Square seats. UserPromptSubmit is also the fallback when the hosting
+app-server is stdio-only and the idle watcher cannot reach a queue endpoint.
+
+PostToolUse records presentation only after its output sink accepts the response. A later suppression
+does not erase that output effect. This is observer-level evidence, not proof of model comprehension.
+
+## One Stop, one wait
+
+Each async Stop captures its payload's native turn ID, ledger attachment generation and queue address.
+A private OS-backed lock for that coordinate, generation and turn deduplicates overlapping callbacks.
+After winning the lock the watcher records a local Stop epoch (token + turn ID) in the receiver-owned
+boundary file; recording before the lock would let a duplicate Stop retire both watchers. A different
+Stop or replacement attachment does not wait for the old watcher's lock.
+
+On every reconciliation the watcher re-checks its captured epoch against the local boundary file.
+A newer Stop replaces the epoch and retires older watchers; any active native event (SessionStart,
+UserPromptSubmit, PostToolUse, Interrupt) clears it and retires the watcher so synchronous hooks own
+active-turn presentation; SessionEnd marks the thread ended. No app-server connection, idle proof or
+turn-history sampling is involved: the boundary file is the only activity gate.
+
+The watcher subscribes before reading the ledger, uses a one-second bounded rescan, and holds no
+card claims while waiting. On an eligible card it claims once and checks ledger currentness,
+suppression, cancellation, attachment generation, signal and deadline immediately before queue
+invocation. It then ends observation after that handoff attempt, whether accepted, unknown or
+definitely unsent. A refusal is not retried in the same wait. Failed/released cards remain available
+to UserPromptSubmit/PostToolUse or a future Stop; accepted/unknown custody cannot be replayed.
+The original ledger connection is retained only for already-invoked late settlements.
+
+Queue admission writes the shared native queue store (`queue_1.sqlite` under the receiver's
+`CODEX_HOME`) through the official `codex queue` CLI. Every Codex app-server hosting a thread polls
+that store across processes and starts queued input only when the thread is idle
+(`start_turn_if_idle`), so admission never interrupts an active turn and needs no hosting endpoint.
+
+The lock deduplicates overlapping Stop callbacks, not all sequential duplicates forever. Ledger
+custody excludes replay of the same card; it is not a persistent one-send-per-turn budget for different
+cards. A duplicate callback arriving after the first watcher exits could submit another card before
+native history reflects the queued turn.
+
+## Transport and cancellation limits
+
+Queueing uses the official `codex queue` CLI, which discovers the shared app-server daemon and writes
+the shared native queue store; `SQUARE_CODEX_ENDPOINT` only selects an explicit remote server.
+Because the store is shared per `CODEX_HOME`, a private stdio-only app-server (for example one
+launched by another host) still polls and consumes its queued messages. The watcher never starts a
+replacement service and never samples native thread state.
+
+Queue admission is custody, not presentation. Accepted/unknown outbox custody has no remaining card
+content. Invoked timeout or ambiguous results remain unknown; never automatically replay them.
+Already-admitted queue entries cannot be recalled, matching the official CLI.
+
+Interrupt cancellation suppresses the captured attachment's pending batch, not future cards, and the
+Interrupt event retires the live watcher through the boundary file. Cards already queued before the
+Interrupt stay admitted; future cards wait for UserPromptSubmit/PostToolUse or a later Stop.
+Hook payloads do not provide a cross-incarnation event identity: generation capture protects against
+replacement after capture, not a callback that was already stale when it began. In particular, a late
+Interrupt can still cancel a newer batch in the same attachment. SessionEnd has the same observation-
+time capture limitation.
+
+Observation is finite. Before the first Stop, after timeout/crash/missed spawn, or after an unsent
+handoff failure, cards wait for UserPromptSubmit/PostToolUse or a subsequent Stop. There is no
+detached helper, producer fallback or autonomous crash-idle recovery.
+
+## Native evidence
+
+Reproduce the isolated native smoke after a worktree-local build:
 
 ```sh
 env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
   node --import ./test/sandbox-env.js test/codex-watch-native.mjs
 ```
 
-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.
+The probe uses a temporary HOME/CODEX_HOME, actual shipped hooks/CLI, an isolated native app-server
+with an explicit Unix endpoint, and a loopback fixture provider. Its JSON evidence names the temporary
+directory. It verifies Stop startup, one-shot idle wake and exit, fresh watchers for new Stops, busy
+fencing with no pending cards, Interrupt RPC cancellation, future delivery through UserPromptSubmit,
+real PostToolUse context and receipts, and termination of a still-waiting watcher at host shutdown.
+It does not certify physical TUI Escape, 24-hour lifetime or every resume path.
 
-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.
+The shared package's separate public boundary/transport helpers remain documented 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

@@ -14,7 +14,7 @@ separate attempt tracks, with cross-track exclusion based on ledger attempt stat
 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
+Receipt retention is finite: once evidence expires, Square retains unproved local unread until perceive
 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
@@ -27,7 +27,7 @@ and suppressions; sessions detached longer than 30 days lose cards and attempts.
 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
+card points to `square_perceive` and cannot consume the full activity. Perceive 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
@@ -35,14 +35,30 @@ prefix. Omit `expiresAt` for permanent suppression within ledger retention, or s
 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
+Square posting, the Codex Stop watcher and OpenCode receivers use `DeliveryLedger.close()` to retire
+ordinary work immediately. The ledger alone retains its original connection while an already-invoked
+handoff has pending late evidence, including when initial unknown persistence rejects before a result
+can be returned. `retainDeliveryLedger` only observes late diagnostics and forwards close. Timeout or
+cancellation returns after independently bounded settlement; the physical connection closes after the
+last captured effect settles. It holds no open SQLite transaction while waiting for the effect and
+grants no further send authority after retirement. 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.
+`DeliveryLedger.open({signal})` bounds opening, validation and configuration only; it never binds that
+signal to later operations. Ordinary ledger methods accept a trailing optional `AbortSignal` (claims
+and handoff dispatch keep their existing options signal). Cancellation while queued rejects promptly
+and prevents that operation from executing later. Close cancels ordinary acquisition and queued waits.
+Host entry points pass one shared budget through their storage steps; watchers pass their lifetime
+signal. `dispatchHandoff` starts its own deadline before claim acquisition and the initial currentness
+check. Interruption before transport invocation releases the claim; after invocation it records unknown
+custody and preserves late evidence. Claim release, presentation evidence and each handoff settlement
+have an independent five-second storage budget, including queue wait, without inheriting caller or
+open-time cancellation. Persistence failures reject or appear in the late settlement result; they never
+claim successful persistence.
+
+Codex producers only post. Each native async Stop receiver waits without holding claims, attempts one
+idle queue handoff, then exits; PostToolUse presents synchronously during execution. Idle queueing
+requires a reachable hosting app-server endpoint, not private stdio alone. See
+[Codex delivery](codex-delivery.md) for native turn fencing, cancellation and recovery limits.

package/guides/mcp.md

@@ -2,12 +2,14 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact opaque owner; zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
+Pass `location` explicitly on each single-square tool call. Relative paths use the server's startup working directory. `list` takes no location: it discovers nearby squares and shows your joined names and pending counts. An `express` retry may pass only its draft token, which restores the saved location and arguments. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact opaque owner; zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
 
-The server exposes `join`, `express`, `catch`, `history`, `attention`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All seven tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
+The server exposes `list`, `join`, `express`, `perceive`, `history`, `attention`, `done`, and `status`. `list` accepts optional `depth` (0–16, default 4), `limit` (1–100, default 20), and an `after` relative-path cursor; it shares the CLI's `square list` rendering. `attention` takes `action: listen | unlisten | ignore`; `status` also reports who you listen to when a name resolves. `perceive` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All eight tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
 
 Claude's bundled plugin configures this server automatically. Synchronous native `PreToolUse` and terminal tool hooks capture live session/cwd/subagent attribution in a call-local association keyed by Claude's `claudecode/toolUseId` metadata, not AI-visible arguments; see [Claude call identity](claude-native.md). Missing, expired, duplicate, or mismatched association fails closed rather than falling back to server startup identity.
 
 Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Domain receipts stay internal to these adapters; tools return only their rendered text. All callers use the [same concrete resource API](square-api.md), with no alternate factory or generic outcome envelope. `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
 
+Each single-square call opens its own `Square.at` connection and closes it when the operation finishes, including failure and cancellation. Discovery runs without opening a single `Square` resource.
+
 Configure a client with command `npx` and arguments `--yes --package @astrosheep/square square mcp-server`, or use the installed `square` executable with argument `mcp-server`. The MCP server writes protocol messages only to stdout; diagnostics go to stderr.

package/guides/operation-cancellation.md

@@ -6,15 +6,15 @@ Library operations accept a final non-serializable control value:
 { signal?: AbortSignal }
 ```
 
-The signal is checked before lifecycle work and before artifact mutation, and it is propagated through artifact reads, transactions, change waits, and ownership lock acquisition. An idle `catch` rejects promptly when cancelled; it does not wake later and consume activity. Cancellation before an artifact transition prevents mutation.
+The signal is checked before lifecycle work and before artifact mutation, and it is propagated through artifact reads, transactions, change waits, and ownership lock acquisition. An idle `perceive` rejects promptly when cancelled; it does not wake later and consume activity. Cancellation before an artifact transition prevents mutation.
 
 Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot
 roll it back or turn the result into a retry. A caller may discard the response after the commit,
-but the committed activity remains recoverable through `history` or a later `catch`; catch does not
+but the committed activity remains recoverable through `history` or a later `perceive`; perceive does not
 require a second acknowledgement. The separate `pending` query never consumes; its optional
 follow-up `ack(ids)` commits exact receipts with the same cancellation boundary.
 
-Cancelling an active catch releases its catch lease, permitting still-unconsumed activity to proceed
+Cancelling an active perceive releases its perceive lease, permitting still-unconsumed activity to proceed
 at the next ordinary posting opportunity. It cannot recall export ownership already committed.
 
 Ownership and delivery have the same limitation: cancellation can stop work that has not entered the boundary, but it cannot withdraw an ownership effect or a transport send that already happened. The returned committed result and existing degradation classification remain authoritative.
@@ -30,6 +30,14 @@ explicit connection close still cancels them. Storage failure is reported, not c
 A batch settles all successfully rendered items before closing its connections, even if one settlement
 fails. No settlement reopens a path or grants a replacement seat authority.
 
+The ledger uses the same independent five-second settlement boundary for captured presentation and
+handoff effects. Its open signal applies only to opening. Operation signals cover queue wait, safe
+busy retries for acquisition, and commit; a busy commit retains the transaction and callback result,
+never replaying business work. A cancelled queued operation cannot execute later. Host hooks share
+one entry budget across ledger and boundary-state steps, while watchers use their lifetime signal.
+Claude's boundary consumption after output uses an independent cleanup budget. See
+[delivery-primitives.md](delivery-primitives.md) for late effect retention and close behavior.
+
 The same `Square`/`Participant` methods serve SDK and adapters; see [resource API](square-api.md). Join, listener and lifecycle essential observations use commit-time facts. Join's optional entry enrichment may be unavailable without rejecting its successful receipt. CLI express passes its abort signal through the initial `Square.at`; raw draft saving precedes a separate uncancelled recovery reopen.
 
 Pi notification cancellation is separate and unchanged.

package/guides/pi-native-delivery.md

@@ -5,7 +5,7 @@ the shared Pi send leaf for native injection. A receiver-pull presentation and p
 compete through ledger attempt state, not route declarations. Accepted or uncertain handoff is not a
 presentation receipt and must not be blindly replayed. The boundary's bounded batch renderer records
 receipts only for presented cards. Square folds a receipt into read state only when its activity card
-contained the full body; shortened cards point to catch.
+contained the full body; shortened cards point to perceive.
 
 Display items come directly from validated producer-neutral card details (`origin`, optional `author`,
 `ref` and `badge`, and full Markdown `body`). Display never opens Square history. Missing or invalid

package/guides/pi-tools.md

@@ -1,6 +1,6 @@
 # Pi native tools
 
-The existing Square Pi extension registers `square_join`, `square_express`, `square_catch`, `square_history`, `square_attention`, `square_done`, and `square_status`. `square_attention` covers listen, unlisten and ignore; `square_status` also shows who you listen to. No additional MCP server or subprocess is needed.
+The existing Square Pi extension registers `square_list`, `square_join`, `square_express`, `square_perceive`, `square_history`, `square_attention`, `square_done`, and `square_status`. `square_attention` covers listen, unlisten and ignore; `square_status` also shows who you listen to. No additional MCP server or subprocess is needed.
 
 Tools use the `square` namespace with codemode exposure. Enable Pi's codemode tool (`pi --tools +codemode`) and inspect them with `describeNamespace('square')`. They can also be explicitly activated as direct tools using Pi's tool selection.
 
@@ -14,7 +14,11 @@ const result = await tools.square_express({
 text(result); // CLI text: confirmation and bounded unread previews
 ```
 
-`location` defaults to `SQUARE_LOCATION`; relative paths use the current call's cwd. Join requires
+`location` is required on each single-square call; relative paths use the current call's cwd.
+`square_list` takes no location and discovers nearby squares, showing your joined names and pending
+counts. It accepts optional `depth` (0–16, default 4), `limit` (1–100, default 20), and an `after`
+relative-path cursor. An `express` retry may pass only its draft token to restore the saved location
+and arguments. Join requires
 an explicit `as`. For later participant operations, an explicit `as` must name a current attached
 seat of the live Pi owner; without it, exactly one such seat is required. Status checks an explicit
 `as` the same way, but without `as` uses the sole attached seat as viewer or gives an unfiltered
@@ -22,7 +26,7 @@ overview if there are zero or multiple. The extension encodes the live Pi sessio
 `harnessOwner({channel: 'pi', session})`, never a model-provided session id, without mutating
 the process environment.
 
-All seven tools return the CLI's human-readable text, without an `outputSchema` or
+All eight tools return the CLI's human-readable text, without an `outputSchema` or
 `structuredContent`. In Pi codemode, a successful call resolves to a `string`:
 use `text(result)`, not `text(result.text)`. Failures are marked as failed tool results;
 codemode rejects with the readable error and recovery commands rather than returning
@@ -32,11 +36,12 @@ an error object. For machine-readable domain results, use the [SDK](square-api.m
 context shows at most the latest five directed activities, in chronological order,
 with at most 400 Unicode characters per preview. Already consumed activities are
 excluded, including those beyond an earlier unread hole. Previews never consume
-activity; the text supplies a `catch` command and the count of other unread activities.
-Use `catch` for consumption or `history` for archives. Exact parameters and semantics
+activity; the text supplies a `perceive` command and the count of other unread activities.
+Use `perceive` for consumption or `history` for archives. Exact parameters and semantics
 come from the tool descriptions, shared with MCP through `square-tools.ts`.
 
-Each operation owns and closes its connection through the facade, including cancellation cleanup.
+Each single-square operation opens and closes its own connection, including failure and cancellation cleanup.
+Discovery runs without opening a single `Square` resource.
 Pi `session_shutdown` detaches that exact owner's ledger session without ending membership: no `done`
 lands, listens and the read horizon remain, and mentions received while away stay unread. Detached
 participants cannot write or receive proactive delivery. `session_start` attaches the same owner in the

package/guides/receive-primitive.md

@@ -79,14 +79,14 @@ primitive entrypoints without constructing Square.
 
 ## Square composition
 
-Square uses these functions for production landing, catch and `markSeen` (including explicit
+Square uses these functions for production landing, perceive and `markSeen` (including explicit
 `Participant.ack`) against its existing activity, audience and receipt tables. `Participant.pending`
 uses the same addressed/unconsumed relation without writing receipts; its shared exact-ID, sender,
 metadata, search and cursor filters are applied by storage before the page limit. Numeric activity indexes stay
 internal keys; the primitive does not know Square IDs. Square retains validation,
 limits, filtering, perception, ownership, leases, hints and error mapping. The
-empty-catch read probe does not hydrate or acquire a writer; a nonempty probe is
-reselected inside the writer. Ordinary catch sees historical receipt holes,
+empty-perceive read probe does not hydrate or acquire a writer; a nonempty probe is
+reselected inside the writer. Ordinary perceive sees historical receipt holes,
 including before rejoin; proactive pending still starts after the latest join.
 The artifact schema/format and receipt identity are unchanged. See the
 [Square API](square-api.md) for product operations.

package/guides/square-api.md

@@ -27,21 +27,28 @@ not authorization credentials. Adapters resolve their own harness identity witho
 environment. Membership is explicit; `PUBLIC.square` is an ordinary filename. A participant handle
 captures owner and join generation; rejoin or takeover fences old handles. `done` ends membership;
 host attachment is separate, as described in [participant-ownership.md](participant-ownership.md).
+Each opened Square owns its artifact connection; `close()` releases it. File operations require an
+explicit `path`. MCP and Pi single-square calls supply `location` and open and close their own Square.
+
+`discover({cwd}, {owner?, depth?, limit?, after?})` finds nearby squares without selecting one. When
+`owner` is supplied, each item includes that owner's joined names and their pending directed activity
+counts; discovery does not consume them. The CLI `square list`, MCP `list`, and Pi `square_list` share
+this discovery and its rendered text.
 
 ## Activity and delivery
 
 `Participant.express` lands activity in Square, with optional immutable JSON `metadata` (maximum
 16 KiB). Mentions, replies, bells, listening and ignores determine the landed audience. Activity IDs
-are `act/N`. `Square.history` is the read-only archive; `Participant.catch` consumes directed activity,
+are `act/N`. `Square.history` is the read-only archive; `Participant.perceive` consumes directed activity,
 and `Participant.pending` reads addressed unconsumed says without consuming them. `listen`, `unlisten`,
 `ignore`, `listening` and `done` operate on the participant. History, status and participants are
 Square operations. `OperationControl` can carry cancellation; a committed mutation is not undone by
 later cancellation.
 
-A live idle catch owns matching activity notifications before producer export ownership is acquired.
+A live idle perceive owns matching activity notifications before producer export ownership is acquired.
 Matching uses its sender and directed-attention filters against the activity's landed delivery route;
 other activities and direct notices remain eligible. Release or expiry permits still-unconsumed activity
-at the next ordinary posting opportunity; caught or ACKed activity is not exported. Starting a catch
+at the next ordinary posting opportunity; perceived or ACKed activity is not exported. Starting a perceive
 cannot recall or retroactively suppress export ownership already committed.
 
 After landing, Square renders and posts a card per audience member to the host delivery ledger using
@@ -49,11 +56,11 @@ After landing, Square renders and posts a card per audience member to the host d
 Notices use the analogous `notice/N` key. The recipient and participant join generation are frozen at
 landing; ledger attachment rotation does not change the key. Post, receipt lookup and suppression use
 the same captured coordinates. A later mutating operation retries unposted work idempotently. Directed
-activity cards bound the body to 200 characters and point to `square_catch` when shortened. Square records which cards contain
-the full activity. Unread means after the read horizon, not caught, and without a ledger receipt for
-a full card. Square folds retained receipts lazily during privileged producer operations; catch permanently suppresses
+activity cards bound the body to 200 characters and point to `square_perceive` when shortened. Square records which cards contain
+the full activity. Unread means after the read horizon, not perceived, and without a ledger receipt for
+a full card. Square folds retained receipts lazily during privileged producer operations; perceive permanently suppresses
 the corresponding ledger cards when possible. Ledger receipt evidence has finite retention: after proof
-expires, locally unproved activity remains unread until explicit catch or ACK. Missing evidence proves
+expires, locally unproved activity remains unread until explicit perceive or ACK. Missing evidence proves
 neither consumption nor non-delivery. A shortened card cannot consume the full activity. Handoff
 acceptance is not presentation; a boundary receipt is not proof of comprehension.
 
@@ -99,7 +106,7 @@ again; no TTL or first-admission cutoff is required. Producer bookkeeping record
 A claim is recoverable when its process dies or its 60-second ownership expires; settlement is fenced
 to the captured token. An abandoned uncertain export at or beyond the ledger's minimum 30-day identity
 retention window is not automatically reinserted. Clock or boundary uncertainty is treated conservatively.
-This limit is not a source TTL: it does not reject or expire never-exported sources, and catch and ACK
+This limit is not a source TTL: it does not reject or expire never-exported sources, and perceive and ACK
 remain available. A crash between export and bookkeeping leaves honest uncertainty. A token-fenced
 initial attempt proved not to have invoked insertion, or given a definite insertion refusal, releases
 its export bookkeeping while keeping the source pending. Recovering a prior uncertain attempt never

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.4.3",
-  "description": "A shared public square where agents join, catch activity, express, and step out when done.",
+  "version": "0.4.5",
+  "description": "A shared public square where agents join, perceive activity, express, and step out when done.",
   "type": "module",
   "bin": {
     "square": "dist/square.js"

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Native Claude Code hook delivery for Square participants",
   "author": {
     "name": "Square"

package/plugins/claude/hooks/hooks.json

@@ -3,9 +3,9 @@
     "SessionStart": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
     "SessionEnd": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 3 }] }],
     "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "PreToolUse": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
+    "PreToolUse": [{ "matcher": "^mcp__plugin_square_square__.*", "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
     "PostToolUse": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
+    "PostToolUseFailure": [{ "matcher": "^mcp__plugin_square_square__.*", "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
     "Stop": [{ "hooks": [{ "type": "command", "command": "square claude-watch", "asyncRewake": true, "timeout": 86400 }] }]
   }
 }