@astrosheep/square 0.3.105 → 0.4.0

package/guides/square-api.md

@@ -224,7 +224,8 @@ Square; there is no `Participant.history`.
   body may carry `{}`; an omitted, empty or whitespace-only body requires non-empty metadata. Metadata-only
   says omit `body` from public activity records. Invalid objects, cycles, unsupported values and oversized
   metadata refuse before landing with `activityUnsent`. Metadata is carried unchanged by express, history,
-  catch, status/latest, unread projections and stream records through the SDK, CLI and stream.
+  catch, status/latest, unread projections and stream records through the SDK, CLI and stream, and
+  by channel send/receive/history/pending messages.
   MCP and Pi tools are not a metadata surface: their `express` requires a body and its schema rejects a
   `metadata` argument. Tool history/catch return rendered text with a structured-activity placeholder,
   not metadata JSON or activity objects. Metadata does not affect mentions, replies, listening, audience,
@@ -232,14 +233,15 @@ Square; there is no `Participant.history`.
   by exact metadata match through the SDK lease API below. Metadata may nest up to 256 levels; the bound is enforced before
   persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
   metadata JSON. SDK history and pending queries accept exact metadata matches; there is no query
-  language or metadata index. CLI `--metadata <json>` remains an express input flag.
+  language or metadata index. CLI `--metadata <json>` remains an express input flag. Channel
+  `send` accepts the same metadata and returns it on `ChannelMessage` records.
 - Catch returns `{activities, remaining, reason, hint?, observation?}`. Each activity includes
   viewer-relative `perception` and `via`. Reasons are `drained`, `idle`, `capped`, `quorum`,
   `replaced`, or `already-active`. Omitted/zero idle is immediate; positive idle uses the single
   leased quiet wait. Receipt selection, perception, routes, counts and terminal facts settle
   in the receipt transaction. Cancellation/replacement releases only that waiter's lease and never
   consumes future activity.
-- All history callers return a `HistoryResult` object with `activities`. Default page size is ten;
+- Agora history (`Square.history`) returns `{activities}`. Default page size is ten;
   `limit: null` explicitly requests an unbounded archive. Numeric limits must be 1–100. Contextual
   queries still reject an implicit merged window over 100 activities; an explicit numeric limit
   bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts; history
@@ -271,9 +273,68 @@ Operations that accept an `OperationControl` use a final argument with `signal`
 `onProgress`. Listener/lifecycle operations take optional observation options before that argument;
 participant selection, seat discovery and host cleanup methods do not take an `OperationControl`.
 
+## Channel endpoints and point-to-point messages
+
+`@astrosheep/square/channel` exports the endpoint and messaging resource `Channel`; the Agora
+resource (`Square` / `Participant`) uses the same message substrate. `Channel` has static `open`,
+`create` and `inMemory`, a `location` property, and methods `attach`, `reattach`, `endpoint`,
+`endpointsOf`, `listEndpoints`, `detach`, `cancelDeliveries`, `remove`, `send`, `history` and
+`close`. Obtain a `ChannelEndpoint` from a Channel; it has `name` and `generation` properties and
+methods `pending`, `ack`, `receive`, `deferDelivery`, `renewDeliveryDeferral`,
+`releaseDeliveryDeferral`, `send` and `leave`. Endpoint generations are opaque strings: retain
+and compare them for equality, without interpreting their contents.
+
+The subpath exports the types `MessageId`, `MessageCursor`, `MessageQuery`, `MessageSearch`,
+`MessageMetadata`, `ChannelTruncate`, `ChannelSendInput`, `ChannelSendResult`, `ChannelMessage`,
+`ChannelPendingOptions`, `ChannelPendingResult`, `ChannelReceiveResult`, `ChannelHistoryQuery`,
+`ChannelHistoryResult`, `AckResult`, `ChannelEndpointSummary`, `ChannelEndpointHold`,
+`DeliveryDeferral`, `MetadataMatch`, `Owner`, `OperationControl`, `WakeAddress`, `WakeTransportPort`,
+`ChannelOpenInput`, `ChannelCreateInput`, `HarnessSessionChannel` and `ResolvedHarnessSession`.
+It also exports `harnessOwner`, `decodeHarnessOwner`, `localUserOwner` and `resolveHarnessSession`.
+The package root exports `MessageId`, `MessageCursor` and `MessageQuery`, but not `MessageMetadata`
+or `MessageSearch` under those names; its Agora equivalents are `ActivityMetadata` and `ActivitySearch`.
+
+Square and Participant expose their own Agora lifecycle operations; in particular,
+`square.endHeld` lands a fenced `done`, whereas `channel.remove` removes an endpoint and is not
+`Channel.endHeld`.
+`Square.history` and `Participant.pending` remain Agora projections, not channel reads: Agora
+history selects joins, says, departures and listener changes but never native messages, and Agora
+pending selects addressed, unconsumed says as perceived activities.
+
+- `Channel.send({from, to, body, truncate?, metadata?})` addresses standing endpoints explicitly.
+  `truncate` defaults to `false`, so the full body is delivered and presentation records a receipt.
+  An explicit positive integer at least as long as the body is likewise unclipped; when the body is
+  longer, the landed message stores `preview`, so presentation shows that preview and records clipped
+  coverage without consuming the full stored body. `pending`, `receive` and `ack` still read and
+  consume that full body. Any other `truncate` value is refused before landing. `to` in the send
+  result and in every `ChannelMessage` is the actual landed audience after address resolution. A
+  stored message may have an empty body only when imported from a legacy metadata-only direct say;
+  `Channel.send` itself always requires a non-empty body.
+- `endpoint.receive(options?, control?)` selects the oldest unconsumed addressed messages matching the
+  shared filters and records their receipts in one transaction, returning
+  `{messages, consumed, remaining}`. Each `ChannelMessage` is `{id, at, from, to, body, metadata?}`,
+  symmetric with the send result. `remaining` counts matching unconsumed messages left after that
+  transaction. Nothing is consumed by `pending` or `history`.
+- `Channel.history(query?, control?)` returns `{messages}` for native messages and says, selecting
+  the newest page oldest-first by default; `order: 'desc'` reverses the page. It shares the
+  `MessageQuery` filters (`at`, `from`, `match`, `search`, `cursor`) but has no Agora
+  `contextBefore`/`contextAfter`, `since`, `mention` or `observe` options. Its default page size is
+  100; `limit` accepts 1–100 or `null` for all matches.
+- `listEndpoints(control?)` reports every standing endpoint without an owner argument as
+  `{name, generation, attachment, deliveryAvailable, unreadCount, lastActiveAt?}`. `endpointsOf(owner)`
+  remains the owner-scoped custody list, and neither operation joins, restores or reveals an address.
+- Direct notifications have no separate envelope: the model-facing text is the stored preview, or
+  the body when untruncated, escaped inside the shared `<system-reminder>` frame; sender, recipients
+  and ID are not printed. Body text that would read as `<channel-`, `<square-` or
+  `<system-reminder` is escaped. A mixed boundary keeps notification order; its fixed budget and
+  `N more activities not shown.` line apply only to Agora activity blocks, and the line trails the
+  rendered batch.
+- An unconsumed direct message stays eligible for the proactive inbox and wake horizon across a seat
+  takeover or rejoin. Earlier Agora activity still ends at the recipient's new read horizon.
+
 ## Shared history and pending filters
 
-`HistoryQuery` and `PendingOptions` extend the same exported `ActivityQuery`:
+Agora `HistoryQuery` and `PendingOptions` extend the exported `ActivityQuery`:
 
 ```ts
 interface ActivityQuery {
@@ -285,6 +346,12 @@ interface ActivityQuery {
 }
 ```
 
+Channel `ChannelHistoryQuery` and `ChannelPendingOptions` extend `MessageQuery`, whose `at` IDs
+and `MessageCursor.id` are `MessageId` (`msg/N`) rather than `ActivityId` (`act/N`). The message
+query types are exported from `@astrosheep/square/channel` and the package root. Channel history,
+pending, receive and ack use `msg/N`; Agora history, pending and ack use `act/N`. A say has both
+coordinates, which are not interchangeable.
+
 - Filters combine with AND. IDs in `at` and senders in `from` each combine with OR; an absent array
   is unrestricted, while an explicitly empty array matches nothing. `at` is an exact ID selection;
   only history can expand those IDs with `contextBefore` / `contextAfter`.
@@ -294,13 +361,15 @@ interface ActivityQuery {
 - `match` uses the same nested own-property, exact type-sensitive scalar equalities as deferrals.
   `search` tests each activity's ID, sender and body independently, case-insensitively. Literal mode
   treats regex characters as plain text; regex mode uses JavaScript's built-in regular expressions,
-  without a ReDoS timeout. Search text must be nonempty and regex syntax must be valid. History
-  searches says and departures, not joins; pending always selects addressed, unconsumed says.
-- A cursor is an exclusive activity-ID boundary, independent of `limit`: before excludes the anchor
+  without a ReDoS timeout. Search text must be nonempty and regex syntax must be valid. Agora
+  history searches says and departures, not joins. Participant `pending` selects addressed,
+  unconsumed says; `ChannelEndpoint` `pending`/`receive` select addressed, unconsumed messages and
+  says.
+- A cursor is an exclusive boundary in its own coordinate space, independent of `limit`: before excludes the anchor
   and everything newer; after excludes the anchor and everything older. No consumption is involved.
   Storage applies the shared filters before limiting and uses the same predicates for counts.
-- History keeps its archive-specific `order`, `mention`, `since` and context options. By default it
-  selects the newest page and returns it oldest first; an after cursor selects the oldest following
+- Agora history keeps its archive-specific `order`, `mention`, `since` and context options. By
+  default it selects the newest page and returns it oldest first; an after cursor selects the oldest following
   page. `order: 'desc'` reverses the selected page, not which activities belong to it. Numeric limits
   stay 1–100, default ten; `limit: null` reads all matches. Exact/context history keeps its existing
   implicit full-window selection with a 100-activity bound unless a numeric limit is supplied.
@@ -311,18 +380,24 @@ interface ActivityQuery {
 The SDK accepts only `search` and `cursor`, not the removed `grep` / `fixed` / `before` / `after`
 fields. CLI flags and tool arguments keep those familiar spellings and translate at the adapter
 boundary, e.g. `--fixed text` becomes `search: {text, mode: 'literal'}` and `--after act/12` becomes
-`cursor: {id: 'act/12', direction: 'after'}`. The artifact format and stored activities do not change.
+`cursor: {id: 'act/12', direction: 'after'}`. The query surface keeps these `act/N` and `msg/N` coordinates; format 11 is a separate fresh-store
+breaking upgrade rather than a query change.
 
 ## Pending query and exact acknowledgement
 
 `Participant.pending(options?, control?)` and `Participant.ack(ids, control?)` separate a read-only
-query from explicit consumption. `ChannelEndpoint` from `@astrosheep/square/channel` exposes the
-identical methods by forwarding to its captured Participant; it has no independent inbox or storage.
-
-`Channel.send` / `Square.send` address joined members, including detached members. Attachment gates
-proactive wake, not landing: a detached recipient retains its unread addressed activity without a
-wake and can query/ack it after reattachment. Recipient validation remains all-or-nothing; a missing
-or departed recipient rejects the entire send without landing activity or waking other recipients.
+query from explicit consumption. Agora `pending` returns addressed, unconsumed `say` records as
+perceived activities, so native messages never appear there. `ChannelEndpoint` from
+`@astrosheep/square/channel` returns `{messages}` for both native messages and says; `ack` records
+receipts for the addressed message IDs. Neither layer keeps a second inbox, read horizon or storage.
+
+Agora publication is participant-scoped: `Participant.express(...)` publishes a say/activity for
+that standing participant. Standalone `Channel.send` addresses standing Channel endpoints, without
+requiring Agora membership, and lands a Channel message, not an Agora activity. Attachment gates
+proactive wake, not landing: a detached Channel recipient retains its unread addressed item and can
+query/ack it after reattachment. Recipient validation is all-or-nothing; a missing or departed
+recipient rejects the entire send without landing a message or waking other recipients. An omitted
+`truncate` sends the full body; truncation is an explicit per-message choice.
 
 ```ts
 import type { ChannelEndpoint, MetadataMatch } from '@astrosheep/square/channel';
@@ -330,30 +405,36 @@ import type { ChannelEndpoint, MetadataMatch } from '@astrosheep/square/channel'
 async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
   for (;;) {
     const page = await endpoint.pending({ match });
-    if (page.activities.length === 0) break;
+    if (page.messages.length === 0) break;
     // Process the entire page successfully before acknowledging its exact IDs.
-    for (const activity of page.activities) await processNotice(activity);
-    const { consumed } = await endpoint.ack(page.activities.map(activity => activity.id));
+    for (const message of page.messages) await processNotice(message);
+    const { consumed } = await endpoint.ack(page.messages.map(message => message.id));
     // consumed may be smaller if another consumer acknowledged some IDs first.
   }
 }
 ```
 
-- `pending(query: PendingOptions = {}, control?)` returns
-  `{activities: readonly PerceivedActivity[], remaining: number}`. It selects only landed,
-  addressed, unconsumed says, oldest first. Body, metadata, delivery information, perception and
-  route use the same public records as catch; bodies are full stored bodies, not clipped previews.
+- `Participant.pending(query: PendingOptions = {}, control?)` returns
+  `{activities: readonly PerceivedActivity[], remaining: number}` and selects landed, addressed,
+  unconsumed says oldest first, with viewer-relative `perception` and `via` as in catch.
+  `ChannelEndpoint.pending` returns `{messages: readonly ChannelMessage[], remaining: number}` for
+  addressed, unconsumed messages and says; each message is `{id, at, from, to, body, metadata?}`.
+  Both read full stored bodies, never clipped previews or delivery remnants.
 - Limit defaults to 100 and must be an integer from 1 through 100. The shared filters above are
   available alongside that limit. Storage applies addressedness, consumption and all supplied
-  filters **before** limiting. `remaining` counts matching unconsumed activities outside the returned
-  page in the same read transaction. It is not the global unread count or a durable cursor.
+  filters **before** limiting. `remaining` counts matching unconsumed activities for Agora and
+  messages for Channel outside the returned page in the same read transaction. It is not the global
+  unread count or a durable cursor.
 - A pending query consumes nothing, changes no read horizon and writes no delivery/presentation
   evidence. Deferrals, catch leases, cancellation and prior clipped presentation do not hide these
-  explicit reads. Like catch, pending includes historical addressed receipt holes before a rejoin;
-  it is not the proactive delivery eligibility query.
-- `ack(ids: readonly ActivityId[], control?)` returns `{consumed: number}`, the count of newly
+  explicit reads. Agora catch and pending include historical addressed activity receipt holes from
+  before a rejoin; they are not proactive delivery eligibility queries. Channel pending, receive and
+  ack use only addresses valid for the current endpoint generation. Ordinary unfenced `Channel.send`
+  messages remain addressed across takeover or rejoin until consumed.
+- Agora `ack(ids: readonly ActivityId[], control?)` and Channel `ack(ids: readonly MessageId[], control?)`
+  return `{consumed: number}`, the count of newly
   consumed exact IDs. It validates that **every** supplied ID is addressed to this participant before
-  recording any receipts. Malformed, nonexistent or unaddressed IDs reject the whole batch with
+  recording any receipts; Channel also checks that the address is valid for the current generation. Malformed, nonexistent or unaddressed IDs reject the whole batch with
   `invalid_args` (`reason: 'not_addressed'` for valid but unaddressed IDs). There is no implicit prefix
   acknowledgement, no match reselection and no requirement for an earlier pending call.
 - Duplicate IDs, repeated acknowledgement and an empty array are idempotent. Existing receipt
@@ -365,7 +446,8 @@ async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
   Cancellation before the receipt transaction prevents consumption; a committed ack is not undone.
 - To drain all matching notices, keep querying and acknowledging pages until an **empty** page.
   Acknowledging one page exposes the next without a cursor. For read-only pagination instead, pass
-  `cursor: {id: page.activities.at(-1)!.id, direction: 'after'}` with the same filters; earlier pages
+  `cursor: {id: page.messages.at(-1)!.id, direction: 'after'}` on a channel endpoint (or
+  `page.activities` on a Participant) with the same filters; earlier pages
   stay unconsumed. Do not silently stop after the default page or treat a snapshot `remaining: 0`
   as proof that concurrent producers have stopped. Query and
   ack are separate operations, not an exclusive claim or an exactly-once external-effect guarantee.
@@ -480,37 +562,32 @@ It overlaps at most four receiving sessions per dispatch, preserving order withi
 session and draining started work even on failure. Claims, final freshness checks and
 uncertain-delivery suppression remain unchanged. Paseo inventory discovery is asynchronous;
 overlapping attempts share only the in-flight inventory read, never a cached idle status.
-The standalone `discoverPaseoAgents` export now returns a promise.
-
-`discover(input, options?, control?)`, `inbox(input, owner, options?, control?)`,
-`diagnoseSquare(input, control?)`, and `migrateSquare(input, control?)` are ordinary public exports.
-They are not methods on a synthetic cross-square object. Diagnose/migrate resolve a path without
-opening a valid current-format Square first.
-
-## Artifact format and explicit migration
-
-The current artifact format is 7. It stores opaque owners rather than harness coordinates and
-preserves format 6's attached/detached distinction. Seats, delivery evidence, cancellation and
-independent delivery deferrals remain separate from conversation activities and catch ownership.
-Ordinary opens refuse older formats with migration guidance and never convert them implicitly.
-
-Stop all sessions and services using the artifact, make an offline backup, then run
-`square --location <path.square> migrate` and `doctor` before reopening with upgraded runtimes.
-Supported formats 2–6 convert to 7 in one transaction. Format 6's Body coordinates become encoded
-owners while attachment, generations, wakes, evidence and revisions survive. Formats 4/5 first gain
-attached seats; format 4 also gains empty deferral support. Formats 4–6 never consult HostLedger.
-Historic host-cleanup departures cannot be distinguished from voluntary `done` and stay done.
-For formats 2/3, also freeze and back up the legacy HostLedger used for verified owner/evidence
-import; no authority is manufactured for done participants. Replay-critical native ambiguity
-refuses rather than disappears, including any nonempty legacy token-only tombstones.
-Current-format migration is a byte-preserving no-op. See [migration.md](migration.md) for the
-narrow metadata policy, source-preserving refusal and filesystem requirements. Updating a package
-does not migrate files or install a new runtime.
+Paseo inventory discovery returns a promise.
+
+`discover(input, options?, control?)`, `inbox(input, owner, options?, control?)`, and
+`diagnoseSquare(input, control?)` are ordinary public exports. They are not methods on a synthetic
+cross-square object. Diagnose resolves a path without opening a valid current-format Square first.
+
+## Artifact format
+
+The current artifact format is 11. It is a breaking fresh-store format, not an upgrade of format
+10. A full Square file combines three separately owned layers in one SQLite database and one
+transaction: the neutral storage revision header, the same Channel message/endpoint/delivery
+tables used by a standalone Channel, and the Agora social tables plus the activity allocator and
+square settings. Standalone Channel storage uses its own format identity and version and contains
+only the neutral and Channel structures; it never creates or reads Agora tables.
+
+Ordinary opens accept only the exact current identity, version and owned schema. Any other
+identity or version is refused read-only, with no conversion, no write and no migrate command.
+There is no automatic upgrade, compatibility decoder or recovery instruction. Stop any session
+using an older `.square` file and start a fresh square; the old bytes are never touched.
 
 ## SDK breaking migration: opaque owners
 
-Artifact format 7 introduced opaque owners; format-6 artifacts required explicit migration before
-opening with that format. Current artifacts use format 8 and require explicit migration from format 7.
+Artifact format 7 introduced opaque owners, format 8 removed hold/resume activities, and format 9
+stores native messages. Format 10 unified message content while keeping Agora relations separate.
+Format 11 splits neutral storage, standalone Channel and Agora, and has no migration from any
+older format. Current artifacts must be created fresh at format 11.
 `Body`, `sameBody` and `validateBody` are removed from the core and public API. Replace identity
 objects with an explicit owner at each identity-bearing operation; do not put identity on a resource:
 
@@ -551,5 +628,5 @@ are deleted. Consumers must open/close an actual Square and select a Participant
 full archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
 uses `path`, consistent with `Square.at`, rather than `squarePath`.
 
-External consumers must migrate before taking this source version. Editing source does not update
+External consumers must adapt their code before taking this source version. Editing source does not update
 an installed plugin, build, or running extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.105",
+  "version": "0.4.0",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "node": "^22.16.0 || >=24.0.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.11.2",
+    "@getpaseo/client": "0.14.0",
     "@opencode/client": "2.0.20",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22",
@@ -101,7 +101,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-tui": "*",
-    "@getpaseo/client": "0.11.2",
+    "@getpaseo/client": "0.14.0",
     "ws": "^8.21.3"
   },
   "peerDependenciesMeta": {

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.105",
+  "version": "0.4.0",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/claude/types.d.ts

@@ -1,4 +1,4 @@
-export type SquareInboxBinding = { location: string; participant: string; session: string; generation?: `act/${number}` };
+export type SquareInboxBinding = { location: string; participant: string; session: string; generation?: string };
 export type SquareInboxCoordinate = { sessionId: string; cwd: string; version: string; endpoint?: string };
 export type SquareInboxCancellation = { at: number; bindings?: SquareInboxBinding[] };
 export type SquareInboxState = { coordinate: SquareInboxCoordinate; bindings?: SquareInboxBinding[] };

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.105",
+  "version": "0.4.0",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/opencode/delivery.ts

@@ -1,12 +1,13 @@
 import { createHash } from 'node:crypto';
-import { createArtifactPort } from '../../artifact.js';
+import { squareWakeProjection } from '../../wake-preview.js';
+import { channelArtifact, createArtifactPort } from '../../artifact.js';
 import { deliverPending } from '../../delivery-operations.js';
-import { nativePendingPreview, observeSessionPending, projectSessionSeats } from '../../inbox.js';
-import { automaticWakeEligible, presentationBlocksWake } from '../../delivery.js';
+import { nativePendingSource, observeSessionPending, projectSessionSeats } from '../../inbox.js';
+import { automaticWakeEligible, nativePendingHead, presentationBlocksWake } from '../../delivery.js';
 import { type Seat } from '../../model.js';
 import { harnessOwner, decodeHarnessOwner } from '../../owner.js';
-import type { SquareRead, WakeRequest, WakeTransportPort } from '../../ports.js';
-import { formatActivityId, parseActivityId } from '../../square-core.js';
+import type { WakeRequest, WakeTransportPort } from '../../ports.js';
+import { formatMessageId, parseMessageId } from '../../message.js';
 import { indexedSquareEntries } from '../../square-index.js';
 import { asSeatRef } from '../../seats.js';
 import { restoreSessionSeats } from '../../session-lifecycle.js';
@@ -18,17 +19,6 @@ const ownerFor = (sessionId: string) => harnessOwner({ channel: 'opencode', sess
 const payloadHash = (payload: string) => createHash('sha256').update(payload).digest('hex');
 export interface OpenCodeContextMessage { readonly id?: string; readonly role: string; readonly content: readonly { readonly type: string; readonly text?: string }[] }
 
-function preview(facts: SquareRead, location: string, captured: Pick<Seat, 'participant' | 'owner' | 'generation'>, index: number) {
-  const seat = facts.seat(captured.participant);
-  if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== captured.generation || seat.owner !== captured.owner) return undefined;
-  const wake = seat.wakeAddress;
-  if (wake?.kind !== routeKind) return undefined;
-  return nativePendingPreview(facts, {
-    location, routeKind, generation: seat.generation, participant: seat.participant,
-    actIndex: index, address: wake.address, now: Date.now(),
-  });
-}
-
 export async function indexedOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<readonly string[]> {
   return [...new Set((await indexedSquareEntries({ }, env)).flatMap((entry) => {
     const coordinate = decodeHarnessOwner(entry.owner);
@@ -49,9 +39,8 @@ function createOpenCodeWakeTransport(target: OpenCodeNativeSession, lifetime: Ab
     probe: async (route) => !lifetime.aborted && route.kind === routeKind
       && route.address.sessionId === target.sessionId,
     async attempt(request: WakeRequest, timeoutMs: number, beforeSend) {
-      const index = parseActivityId(request.activity);
-      const artifact = request.artifact;
-      if (artifact === undefined || request.claimToken === undefined || index === undefined
+      const presentation = request.presentation;
+      if (request.claimToken === undefined || parseMessageId(request.message) === undefined || presentation === undefined
         || request.route.kind !== routeKind || request.route.address.sessionId !== target.sessionId) {
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention has no matching artifact claim or session.' };
       }
@@ -59,18 +48,14 @@ function createOpenCodeWakeTransport(target: OpenCodeNativeSession, lifetime: Ab
       const started = Date.now();
       if (signal.aborted || !await beforeSend())
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before send.' };
-      const { value: prepared } = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
-      if (prepared === undefined) return { outcome: 'not-capable', diagnostic: 'OpenCode attention is no longer current.' };
       const inputId = createNativeInputId();
-      const correlation = { harness: 'opencode' as const, token: inputId, payloadHash: payloadHash(prepared.payload) };
-      if (!await artifact.prepareDelivery({ seat: request.seat, claimToken: request.claimToken, correlation }, signal))
+      const correlation = { harness: 'opencode' as const, token: inputId, payloadHash: payloadHash(presentation.payload) };
+      if (!await request.channel.prepare({ correlation,
+        coverage: presentation.coverage, ...(presentation.description === undefined ? {} : { description: presentation.description }) }, signal))
         return { outcome: 'not-capable', diagnostic: 'OpenCode delivery claim is no longer current.' };
-      const fresh = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
-      if (fresh.value === undefined || payloadHash(fresh.value.payload) !== correlation.payloadHash)
-        return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before native send.' };
       if (signal.aborted || !await beforeSend())
         return { outcome: 'not-capable', diagnostic: 'OpenCode attention was consumed before send.' };
-      const result = await sendNativeText(target, prepared.payload, {
+      const result = await sendNativeText(target, presentation.payload, {
         inputId, delivery: 'steer', timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), signal,
       });
       if (result.state === 'accepted') return { outcome: 'accepted' };
@@ -101,25 +86,27 @@ export async function observeOpenCodeContext(sessionId: string, messages: readon
         return facts.deliveryEvidence(seat.participant, seat.generation).flatMap((evidence) => {
           const token = evidence.correlation?.harness === 'opencode' ? evidence.correlation.token : undefined;
           const hash = token === undefined ? undefined : observed.get(token);
-          const index = parseActivityId(evidence.activity);
+          const index = parseMessageId(evidence.message), now = Date.now();
           if (token === undefined || hash === undefined || evidence.claimToken === undefined || index === undefined
-            || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome)
-            || evidence.correlation?.payloadHash !== hash) return [];
-          const prepared = preview(facts, location, seat, index);
-          if (prepared === undefined || payloadHash(prepared.payload) !== hash
-            || presentationBlocksWake(facts.deliveryEvidence(seat.participant, seat.generation, evidence.activity), Date.now())) return [];
-          return [{ evidence, index, hash, clipped: prepared.clipped }];
+            || evidence.route === undefined || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome)
+            || evidence.correlation?.payloadHash !== hash
+            || evidence.route.kind !== routeKind
+            || presentationBlocksWake(facts.deliveryEvidence(seat.participant, seat.generation, evidence.message), now)) return [];
+          const source = nativePendingSource(facts, { location, participant: seat.participant, generation: seat.generation,
+            owner: seat.owner, index, route: evidence.route, now });
+          if (source === undefined) return [];
+          return [{ evidence, index, hash, clipped: evidence.coverage === 'clipped' }];
         });
       }, signal);
       for (const { evidence, index, hash, clipped } of matches) {
         if (signal.aborted || evidence.claimToken === undefined) return;
         await presentPending({ artifact, location, participant: seat.participant,
-          activity: formatActivityId(index), seat: asSeatRef(seat), observationOf: evidence.claimToken, sink: { present() {} }, markSeen: !clipped, signal,
+          message: formatMessageId(index), seat: asSeatRef(seat), observationOf: evidence.claimToken, sink: { present() {} }, markSeen: !clipped, signal,
           current: (facts) => {
-            const current = facts.seat(seat.participant);
-            const prepared = current === undefined || !sameSeat(current, seat) ? undefined : preview(facts, location, seat, index);
             const correlation = facts.deliveryByToken(evidence.claimToken!);
-            return prepared !== undefined && payloadHash(prepared.payload) === hash
+            return nativePendingHead(facts, { location, participant: seat.participant, generation: seat.generation,
+                owner: seat.owner, index, route: evidence.route!, now: Date.now() }) !== undefined
+              && ['dispatching', 'unknown', 'accepted'].includes(correlation?.outcome ?? '')
               && correlation?.correlation?.harness === 'opencode'
               && correlation.correlation.token !== undefined
               && correlation.correlation.payloadHash === hash;
@@ -150,11 +137,11 @@ export async function receiveOpenCodePending(target: OpenCodeNativeSession, env:
           const { value: notifications } = await artifact.read((facts) => {
             if (!sameSeat(facts.seat(seat.participant), seat)) return [];
             return membership.notifications.filter((note) => automaticWakeEligible(
-              facts.deliveryEvidence(seat.participant, seat.generation, formatActivityId(note.actIndex)), Date.now()));
+              facts.deliveryEvidence(seat.participant, seat.generation, formatMessageId(note.messageIndex)), Date.now()));
           }, signal);
           for (const note of notifications) {
             if (signal.aborted) return;
-            await deliverPending({ artifact, transport, location, activity: formatActivityId(note.actIndex), now: Date.now() });
+            await deliverPending({ artifact: channelArtifact(artifact), preparePresentation: squareWakeProjection(artifact), transport, location, message: formatMessageId(note.messageIndex), now: Date.now() });
           }
         } catch (error) {
           if (signal.aborted) throw signal.reason ?? error;
@@ -194,7 +181,7 @@ export async function cancelOpenCodeDeliveries(sessionId: string, env: NodeJS.Pr
     if (seat.attachment !== 'attached') continue;
     const artifact = createArtifactPort(location, undefined, signal);
     try {
-      const { value: through } = await artifact.read((facts) => facts.header().lastActIndex, signal);
+      const { value: through } = await artifact.read((facts) => facts.channel.header().lastMessageIndex, signal);
       if (through >= 0) await artifact.cancelDeliveries(asSeatRef(seat), through, signal);
     } finally { await artifact.close(); }
   }

package/plugins/pi/square-pi.js

@@ -3,14 +3,15 @@ import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui';
 import { z } from 'zod/v4';
 
 import { Square, harnessOwner } from '../../dist/square-api.js';
-import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, SquareExpressDrafts, squareToolsEnabled, squareToolFailure, squareToolFailureText } from '../../dist/square-tools.js';
+import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, createSquareToolRunner, squareToolsEnabled } from '../../dist/square-tools.js';
 
 import { presentPendingAtBoundary, renderPendingAtBoundary } from '../../dist/boundary-presentation.js';
 import { operationEnv } from '../../dist/participant-identity.js';
 import { detachSessionSeats, restoreSessionSeats } from '../../dist/session-lifecycle.js';
 import { projectSessionSeats, observeSessionPending, pendingKey } from '../../dist/inbox.js';
-import { previewAttentionBody, renderAttentionDescription, renderAttentionFull } from '../../dist/attention-presentation.js';
+import { projectMessageNotification } from '../../dist/attention-presentation.js';
 import { formatActivityId } from '../../dist/square-core.js';
+import { formatMessageId } from '../../dist/message.js';
 import { createPiReceiver, sendPiMessage } from '../../dist/packages/agent-delivery/src/pi.js';
 
 class PiDeliveryDroppedError extends Error {
@@ -26,7 +27,7 @@ export function pendingInbox(inbox) {
 
 export function inboxKeys(inbox) {
   return pendingInbox(inbox).flatMap((item) => item.notifications.map((note) =>
-    pendingKey(item, note.actIndex)
+    pendingKey(item, note.messageIndex)
   ));
 }
 
@@ -40,25 +41,26 @@ function framePiMessage(content) {
 
 /** Renderer-only card facts for Pi and Paseo; Pi never sends `details` to the model. */
 export function pendingCardDetails(pending) {
-  const items = pending.flatMap((membership) => membership.notifications.map((note) => ({
+  const items = pending.flatMap((membership) => membership.notifications.map((note) => {
+    const projected = projectMessageNotification({ squarePath: membership.location, recipient: membership.seat.participant,
+      actor: note.actor, body: note.body, ...(note.preview === undefined ? {} : { preview: note.preview }),
+      ...(note.actIndex === undefined || note.route === undefined ? {} : { agora: { actIndex: note.actIndex, route: note.route } }) });
+    return ({
     square: path.basename(membership.location, '.square'),
     actor: note.actor,
     recipient: membership.seat.participant,
     route: note.route,
-    act: formatActivityId(note.actIndex),
-    preview: previewAttentionBody(note.body, note.delivery),
-    description: note.delivery?.mode === 'direct'
-      ? `${note.actor} → ${membership.seat.participant}`
-      : renderAttentionDescription({ actor: note.actor, route: note.route }),
+    act: note.actIndex === undefined ? formatMessageId(note.messageIndex) : formatActivityId(note.actIndex),
+    preview: projected.preview,
+    description: projected.description,
     body: note.body,
-  })));
+  }); }));
   if (items.length === 0) return undefined;
-  const fullText = pending.flatMap((membership) => membership.notifications.map((note) => renderAttentionFull({
-    squarePath: membership.location,
-    actIndex: note.actIndex,
-    recipient: membership.seat.participant,
-    ...note,
-  }))).join('\n\n');
+  const fullText = pending.flatMap((membership) => membership.notifications.map((note) => projectMessageNotification({
+    squarePath: membership.location, recipient: membership.seat.participant, actor: note.actor, body: note.body,
+    ...(note.preview === undefined ? {} : { preview: note.preview }),
+    ...(note.actIndex === undefined || note.route === undefined ? {} : { agora: { actIndex: note.actIndex, route: note.route } }),
+  }).full)).join('\n\n');
   return { items, fullText };
 }
 
@@ -143,7 +145,7 @@ export function renderSquareCard(message, { expanded, outputPad = 1 }, theme) {
 }
 
 export default function squarePiExtension(pi) {
-  const drafts = new SquareExpressDrafts();
+  const invoke = createSquareToolRunner();
   if (squareToolsEnabled(process.env)) for (const tool of SQUARE_TOOLS) {
     pi.registerTool({
       name: `square_${tool.name}`,
@@ -153,41 +155,16 @@ export default function squarePiExtension(pi) {
       exposure: 'codemode',
       namespace: { name: 'square', description: 'A shared square where agents gather to talk, think, and act together.', instructions: SQUARE_TOOL_INSTRUCTIONS },
       async execute(_id, args, signal, _onUpdate, ctx) {
-        let toolArgs = args;
-        let owner;
-        let draftToken;
-        let expressAttempted = false;
-        let square;
-        try {
+        const { text, isError } = await invoke(tool, args, { signal }, () => {
           const sessionId = ctx.sessionManager.getSessionId();
-          owner = harnessOwner({ channel: 'pi', session: sessionId });
-          if (tool.name === 'express') {
-            const resolved = drafts.resolve(toolArgs, owner);
-            toolArgs = resolved.args;
-            draftToken = resolved.token;
-          }
-          square = await Square.at({
-            cwd: ctx.cwd,
-            env: operationEnv('pi', sessionId, process.env),
-            path: toolArgs.location,
-          }, { signal });
-          let text;
-          try {
-            expressAttempted = tool.name === 'express';
-            text = await tool.run(square, toolArgs, { signal }, { owner });
-            drafts.consume(draftToken);
-          }
-          finally { await square.close(); }
-          return { content: [{ type: 'text', text }] };
-        } catch (error) {
-          const failure = squareToolFailure(error, signal);
-          const draft = tool.name === 'express' ? drafts.retain(toolArgs, owner, draftToken, failure, expressAttempted) : undefined;
-          return { isError: true, content: [{ type: 'text', text: squareToolFailureText(failure, {
-            location: square?.location ?? toolArgs.location ?? process.env.SQUARE_LOCATION,
-            participant: toolArgs.as,
-            draft,
-          }) }] };
-        }
+          return {
+            identity: { owner: harnessOwner({ channel: 'pi', session: sessionId }) },
+            open: (location, control) => Square.at({
+              cwd: ctx.cwd, env: operationEnv('pi', sessionId, process.env), path: location,
+            }, control),
+          };
+        }, process.env.SQUARE_LOCATION);
+        return { ...(isError ? { isError } : {}), content: [{ type: 'text', text }] };
       },
     });
   }