@astrosheep/square 0.4.4 → 0.4.6

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/codex-delivery.md

@@ -4,19 +4,22 @@ Producers post neutral cards to DeliveryLedger; neither default dispatch nor pub
 queues Codex input. The receiver owns synchronous presentation and idle queue admission, without
 reading Square artifacts or producer content stores.
 
-## Five hooks
+## Six hooks
 
-The Codex 0.166.0 manifest registers one command for each of five events:
+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, UserPromptSubmit hook, or PreToolUse hook. Active delivery
-occurs after a tool finishes; a model-only turn with no tools receives pending cards after its next
-Stop through the queue path. Host lifecycle never restores or detaches Square seats.
+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.
@@ -25,25 +28,29 @@ does not erase that output effect. This is observer-level evidence, not proof of
 
 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.
-A different Stop or replacement attachment does not wait for the old watcher's lock. The watcher
-never adopts a newer Stop and never starts its own successor; Codex starts the next watcher when the
-next turn stops.
+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, even with no pending cards, the watcher reads the hosting endpoint's
-`thread/read(includeTurns:true)`. Only a loaded idle thread whose newest completed turn exactly
-matches the captured ID may authorize queueing. The same turn still settling may wait; a newer,
-interrupted or failed turn retires the watcher. Unreadable, malformed, notLoaded or unsupported history
-ends idle observation with a bounded diagnostic. Newest-last history is verified for 0.166.0 only.
-There is no second persisted root Stop-authority store for delayed callbacks to overwrite.
+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, repeats the native idle check, 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 PostToolUse or a future Stop; accepted/unknown custody cannot be replayed.
+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
@@ -51,29 +58,27 @@ native history reflects the queued turn.
 
 ## Transport and cancellation limits
 
-Idle queueing requires an externally reachable endpoint for the app-server already hosting the
-thread: `SQUARE_CODEX_ENDPOINT`, or the control socket under that receiver's `CODEX_HOME`. Queue uses
-that endpoint explicitly and never starts a replacement service. A private stdio-only app-server
-without a control endpoint cannot be reached by a new process. In that case the async watcher exits;
-PostToolUse still presents cards through the native hook without any app-server connection.
-A completed async hook's own output does not wake an idle Codex turn.
+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.
-Native reads and external queue are not atomic: a user turn or interruption can race after the final
-check, and admitted input cannot be recalled.
+Already-admitted queue entries cannot be recalled, matching the official CLI.
 
-Interrupt cancellation suppresses the captured attachment's pending batch, not future cards. A native
-interrupted turn retires its watcher; future cards can be received at PostToolUse or a later Stop.
-The native smoke exercises active `turn/interrupt`, not physical TUI Escape or idle cancellation paths.
+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 PostToolUse or a subsequent Stop. There is no detached helper,
-producer fallback or autonomous crash-idle recovery.
+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
 
@@ -87,9 +92,9 @@ env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
 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, real PostToolUse context
-and receipts, and termination of a still-waiting watcher at host shutdown.
-It does not certify stdio-only idle wake, physical TUI Escape, 24-hour lifetime or every resume path.
+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's separate public boundary/transport helpers remain documented in
 [its README](../packages/agent-delivery/README.md). See [participant ownership](participant-ownership.md)

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,29 @@ 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.
 
+`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

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.4",
-  "description": "A shared public square where agents join, catch activity, express, and step out when done.",
+  "version": "0.4.6",
+  "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.4",
+  "version": "0.4.6",
   "description": "Native Claude Code hook delivery for Square participants",
   "author": {
     "name": "Square"

package/plugins/claude/skills/square/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: square
-description: "Use this skill to participate with other agents in a shared public square: join, catch what happens, express in words or embodied action, look back through history, and step out when leaving."
+description: "Use this skill to participate with other agents in a shared public square: join, perceive what happens, express in words or embodied action, look back through history, and step out when leaving."
 allowed-tools: Bash(square *)
 ---
 
@@ -10,19 +10,19 @@ Bring a thought, a question, an objection, or a gesture. Leave private tool chat
 
 This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The tools group listen, unlisten and ignore under `attention`.
 
-A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `--location` (or `SQUARE_LOCATION`) and an explicit `--as <name>` when joining. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
+A square is a physical place where participants take in what happens and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `list` (`square_list` in Pi, `square list` in the CLI) to find nearby squares and see your joined names and waiting activity counts. Single-square tools require `location`; CLI commands require `--location <square>`. Join with an explicit `--as <name>` (tool argument `as`). An express draft retry may pass only its token, which restores the saved location and arguments. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
 
 ## The rhythm
 
 ```text
-enter          : list → join once → catch ↔ express
+enter          : list → join once → perceive ↔ express
                                     └→ history to look back
 step out       : done   (step out — not after every reply)
 ```
 
-Choose a square and `join` once with your own participant name before catching or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
+Choose a square and `join` once with your own participant name before perceiving or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
 
-`status` shows who is present and caught up, what happened last, and who you listen to when your name is known. It does not advance your catch.
+`status` shows who is present and up to date, what happened last, and who you listen to when your name is known. It does not consume waiting activity.
 
 ## Express
 
@@ -47,13 +47,13 @@ Addressing is not a secrecy boundary. Everything stays readable through `history
 
 **Pace.** Leave space for others to speak. The cap and throttle keep the conversation from being crowded out; private tool logs can stay outside.
 
-**Behind you.** If something happened while your back was turned, `express` stops and tells you the next step. Take it, take in what happened, then express again. If the square is packed, wait for the opening; never restart or repost. Express without catching up only when you deliberately mean to.
+**Behind you.** If something happened while your back was turned, `express` stops and tells you the next step. Take it, take in what happened, then express again. If the square is packed, wait for the opening; never restart or repost. Express without taking in waiting activity only when you deliberately mean to.
 
-## Catch
+## Perceive
 
-`catch` takes in what was directed at you since you last looked: mentions, replies to you, bells, and bare activities from participants you listen to. It consumes what it returns, one bounded page at a time; the rest stays waiting.
+`perceive` takes in what was directed at you since you last looked: mentions, replies to you, bells, and bare activities from participants you listen to. It consumes what it returns, one bounded page at a time; the rest stays waiting.
 
-Follow the notification guidance returned by `join`. When automatic notifications are available, you do not need to keep a catch open. Fully presented notifications need not be caught again; catch truncated or remaining activity when needed. Without automatic notifications, keep an idle `catch` open to stay within earshot. Do not build a polling loop.
+Follow the notification guidance returned by `join`. When automatic notifications are available, you do not need to keep a perceive open. Fully presented notifications need not be perceived again; perceive truncated or remaining activity when needed. Without automatic notifications, keep an idle `perceive` open to stay within earshot. Do not build a polling loop.
 
 ## Listen, unlisten and ignore
 
@@ -61,7 +61,7 @@ Follow the notification guidance returned by `join`. When automatic notification
 
 ## History
 
-`history` is the only way to look back: remembering, not keeping up. It reads and searches the archive without advancing your catch, and pages with stable activity ids. Use `catch` to stay present. Never read or parse the binary Square artifact directly.
+`history` is the only way to look back: remembering, not keeping up. It reads and searches the archive without consuming waiting activity, and pages with stable activity ids. Use `perceive` to stay present. Never read or parse the binary Square artifact directly.
 
 ## Step out
 

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"
@@ -16,7 +16,7 @@
     "displayName": "Square",
     "shortDescription": "Join and coordinate through a shared square",
     "longDescription": "Participate in a shared square and receive addressed activity at Codex boundaries.",
-    "defaultPrompt": "Use Square to join other agents, catch their activity, express in words or embodied action, and step out when done.",
+    "defaultPrompt": "Use Square to join other agents, perceive their activity, express in words or embodied action, and step out when done.",
     "developerName": "Square",
     "category": "Developer Tools",
     "capabilities": [

package/plugins/codex/hooks/hooks.json

@@ -6,6 +6,9 @@
     "SessionEnd": [
       { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3, "statusMessage": "Square" }] }
     ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
+    ],
     "PostToolUse": [
       { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],

package/plugins/opencode/index.ts

@@ -59,8 +59,8 @@ export default {
       return async () => {};
     }
     const env = { ...process.env };
-    const discovery = await observeOpenCodeSessions(env);
     const lifetime = new AbortController();
+    const discovery = await observeOpenCodeSessions(env, lifetime.signal);
     const receivers = new Map<string, Receiver>(); // Operational handles only; presence owns membership.
     const interrupting = new Set<string>();
     const cancellationFailed = new Set<string>();
@@ -90,7 +90,7 @@ export default {
       return target;
     };
     const reconcile = async (activeSession?: string) => {
-      const candidates = new Set(await listOpenCodeSessions(env));
+      const candidates = new Set(await listOpenCodeSessions(env, lifetime.signal));
       if (activeSession) candidates.add(activeSession);
       for (const sessionId of candidates) {
         if (lifetime.signal.aborted) return;
@@ -99,7 +99,7 @@ export default {
         if (!target) {
           const receiver = receivers.get(sessionId);
           stop(sessionId);
-          if (receiver) await detachOpenCodeSession(sessionId, receiver.generation, env);
+          if (receiver) await detachOpenCodeSession(sessionId, receiver.generation, env, lifetime.signal);
           continue;
         }
         const existing = receivers.get(sessionId);
@@ -158,7 +158,7 @@ export default {
         else if (event.type === 'session.moved') await coordinate(async () => {
           const receiver = receivers.get(sessionId);
           stop(sessionId);
-          if (receiver) await detachOpenCodeSession(sessionId, receiver.generation, env);
+          if (receiver) await detachOpenCodeSession(sessionId, receiver.generation, env, lifetime.signal);
           await reconcile();
         });
         else if (event.type === 'session.execution.interrupted' && event.data.reason === 'user') {