@astrosheep/square 0.4.7 → 0.4.8

package/dist/time.js

@@ -1,3 +1,13 @@
+import { SquareError } from './model.js';
+export function parseDurationMs(value, label) {
+    const match = value.match(/^([1-9]\d*)(ms|s|m|h)$/);
+    if (!match)
+        throw new SquareError('invalid_args', `✕ invalid ${label}: expected a positive duration with unit ms, s, m, or h (for example 500ms, 30s, 3m, 1h)`);
+    const milliseconds = Number(match[1]) * ({ ms: 1, s: 1000, m: 60000, h: 3600000 }[match[2]]);
+    if (!Number.isSafeInteger(milliseconds))
+        throw new SquareError('invalid_args', `✕ invalid ${label}: duration is too large`);
+    return milliseconds;
+}
 function pad(value, length = 2) {
     return String(value).padStart(length, '0');
 }

package/dist/views.d.ts

@@ -19,7 +19,7 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
 export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     participant: string;
-    activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
+    activitySummaries: import("./neutral.js").UnreadActivitySummary[];
     standingCount: number;
     ownActivityCount: number;
     hardCap: import("./model.js").HardCap;

package/dist/views.js

@@ -35,14 +35,14 @@ export function parseRequiredActivityId(id) {
 }
 /** History adds archive context and ordering to the shared storage-side query predicates. */
 export function selectHistory(facts, query, limit, kinds, presentation = true) {
-    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'contextBefore', 'contextAfter']);
+    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'context']);
     const { afterIndex } = shared;
     const recipient = query.mention == null ? undefined : resolveKnownName(facts, query.mention);
     if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1))
         throw new SquareError('invalid_args', 'History limit must be a positive integer');
     const filter = {
         ...shared, afterAt: query.since,
-        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.contextBefore ?? 0, query.contextAfter ?? 0) }),
+        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.context ?? 0, query.context ?? 0) }),
         kinds: query.search === undefined ? kinds : ['say', 'done'],
     };
     let selected, totalMatches, publicBefore = false, publicAfter = false;

package/dist/wake-transports.d.ts

@@ -1,4 +1,4 @@
 import type { DeliveryTransport } from './delivery-ledger.js';
 export type WakeTransports = readonly DeliveryTransport[];
-/** Claude now receives only at native hooks; producers never target a socket. */
+/** Native receivers own their effects; producers never target Claude's private helper. */
 export declare function createDefaultDeliveryTransports(): Promise<WakeTransports>;

package/dist/wake-transports.js

@@ -1,4 +1,4 @@
-/** Claude now receives only at native hooks; producers never target a socket. */
+/** Native receivers own their effects; producers never target Claude's private helper. */
 export async function createDefaultDeliveryTransports() {
     const [{ HttpWakeTransport }, { PaseoWakeTransport }] = await Promise.all([
         import('./http-delivery.js'),

package/guides/catch-cold-path-optimization.md

@@ -9,7 +9,7 @@ The comparison is against `90752ba`, the current production implementation plus
 ## Two changes
 
 - `model.ts`: try the existing Unicode text-name grammar before the full RGI emoji grammar. It accepts letters, numbers, marks excluding variation selectors, hyphens, underscores, and nonempty slash-separated segments. It is an exact subset of the original grammar; the original full matcher remains the fallback. `NAME_GRAPHEME_SOURCE`, also used by mention scanning, retains its original value.
-- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. These measurements predate the [native-first route policy](claude-native.md#native-first-routing-and-policy-holds); the optimization itself did not change route priority, harness identity, or publication failure isolation.
+- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. These historical measurements do not describe [current Claude mod delivery](claude-native.md); the optimization itself did not change route priority, harness identity, or publication failure isolation.
 
 CPU sampling of the baseline pointed to cold name validation inside reader transactions and optional adapter module loading during catch. The changes remove that work rather than prewarm it or move it outside measurement. The sampling and this combined experiment do not establish each change's individual contribution.
 

package/guides/claude-native.md

@@ -1,13 +1,43 @@
-# Claude Code delivery
+# Claude mod delivery
 
-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.
+Square's Claude plugin uses a native JavaScript mod, not command hooks or an async Stop observer. The mod owns native lifecycle and effects. One `square claude-mod` helper per loaded session owns Node/SQLite access and the receiver-owned `claude-mod` ledger route. Producers only post neutral ledger cards; they never contact the helper directly.
 
-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.
+## Busy context and idle wake
 
-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.
+During a running turn, the mod calls `$.session.append` with the complete delivery frame, then `$.ui.log` with the readable card. Append adds model context without interrupting the running turn; the separate log makes the notification visible in Claude's native UI. Neither replaces a tool result. A busy notification is never also submitted as a new prompt.
 
-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.
+When the main session is idle, the mod instead calls `$.prompt.submit({ text })`. It keeps native plugin attribution: it does not set `asUser`, impersonate human input, or emit a duplicate UI log. Normal completion returns the receiver to idle so later cards can wake it again. A child receives append only while running, addressed by its native `agentId`; Square never wakes the main session on behalf of an idle child. Child completion detaches its receiver.
 
-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 current Paseo Claude provider does not expose native `ui_log` events in its conversation UI. Emitting a log is not evidence that Paseo displayed it, and the optional Square Paseo renderer does not fix that provider boundary. This change does not modify Paseo.
 
-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.
+## Evidence, cancellation and lifetime
+
+Each handoff prepares a unique token and SHA-256 hash of the exact frame. A private loopback RPC rechecks generation and custody immediately before the native effect. An append receipt requires the native returned message to contain exactly that text and a native message UUID. A submit receipt requires the returned submitted text to match exactly; rewritten text records acceptance only. These are native acceptance/presentation facts, not proof of a later provider request, model comprehension or human acknowledgement. UI logs alone never settle a delivery.
+
+There is no atomic transaction spanning the ledger and Claude. Once an effect may have happened, a lost or changed result is uncertain and held: no automatic replay, append-to-submit retry, or fallback wake through another host. Definitive refusal creates no presentation receipt. Diagnostics and `square harness doctor delivery` distinguish pending, held and presented evidence.
+
+Stop cancels the current pending batch and fences queued native effects. A stopped receiver does not wake again until new native input starts a turn; later input does not replay the cancelled batch. Already appended or admitted native input cannot be recalled. Cancellation is local host suppression, not consumption of Square history.
+
+`session.end` retires the captured helper and generation-fenced attachment. `/clear` and `/resume` can end the old session without another `session.start`; the next native prompt lazily starts the helper for the current session ID. Reloading the mod starts a fresh helper generation, which fences older receivers. A hard process kill can prevent graceful detach; a subsequent attachment fences the old generation, but installation alone does not prove that any running host loaded the mod.
+
+The helper emits its randomly authenticated loopback address only to the owning mod over its private process stream. That address is not a producer endpoint, shared inbox, or public configuration. No external callback service is required.
+
+## MCP call identity
+
+The bundled MCP server gets session, cwd and subagent attribution from the mod's native `tool.call` wrapper, matched only to Square MCP tools. Before calling the real tool, it captures the native `tool_use_id`, session and `agentId` in the call-local association keyed by Claude's `claudecode/toolUseId` metadata. A `finally` block removes only that exact association after the tool finishes, including failure. Calls interrupted before cleanup expire after ten minutes.
+
+Missing, duplicate, expired or mismatched identity fails closed before the MCP server runs. Models cannot supply identity as tool arguments. Main and child identities stay separate even when their calls overlap; no ordinary non-Square tool launches an identity command.
+
+## Tested runtime and verification
+
+macOS Claude Code **2.1.319** was tested with the shipped plugin, candidate CLI, isolated HOME/configuration/ledger, and a dummy-key loopback model provider. The real headless runtime proves repeated idle wake, duplicate suppression, busy append reaching the next model request, native UI-log emission, Stop suppression, exact receipts and detach. A real interactive TUI fixture proves main/child MCP attribution, collision denial, tool-context delivery and exact call cleanup. This does not certify older Claude releases, other platforms, or Paseo display.
+
+After `npm run build`, run both native fixtures with:
+
+```bash
+SQUARE_CLAUDE_MOD_NATIVE_SMOKE=1 \
+SQUARE_CLAUDE_BIN=/path/to/claude \
+node --import ./test/sandbox-env.js test/claude-mod-native.mjs
+```
+
+Evidence stays in the printed `/tmp/square-claude-…` directories. The headless fixture deliberately interrupts a running tool; Claude may finish with exit 1 and `aborted_tools`, which is checked as the expected interruption rather than treated as an ordinary successful generation. Neither fixture uses external model credentials or changes an installed plugin or running host.

package/guides/delivery-primitives.md

@@ -5,7 +5,8 @@ package root. The per-user ledger defaults to `~/.square/delivery.v3.sqlite` and
 finished text cards, session attachment, routes, attempts and receipts. Producers own content and
 recipient selection; adapters own transport behavior. Routes contain only `{kind, address}`.
 A card may also carry producer-neutral presentation `details`:
-`{kind: 'presentation', origin, author?, ref?, badge?, body}`. `text` remains the bounded model-facing
+`{kind: 'presentation', origin, author?, ref?, at, reach, body}`. `at` is the landing time in epoch
+milliseconds; `reach` is `mention`, `reply`, `attention`, or `bell`. `text` remains the bounded model-facing
 card; `body` holds the full Markdown for display. Receivers validate these details and render them
 without opening producer storage. Cards without valid presentation details remain plain text.
 

package/guides/mcp.md

@@ -2,11 +2,11 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-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.
+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. 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 `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.
+The server exposes `list`, `join`, `express`, `perceive`, `history`, `listen`, `unlisten`, `ignore`, `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. `listen`, `unlisten` and `ignore` take `as`, `location` and `target`; `status` reports who you listen to. `perceive` consumes activities, with an optional `idle` duration such as `30s`. `history` is read-only and accepts stable `act/<index>` cursors, symmetric `context`, literal `search` with optional `regex`, and `full` bodies. All ten 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.
+Claude's bundled plugin configures this server automatically. Its native mod wraps Square's `tool.call` events to capture live session/cwd/subagent attribution in a call-local association keyed by Claude's `claudecode/toolUseId` metadata, not AI-visible arguments. The wrapper cleans the exact association in `finally`; 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.
 

package/guides/pi-native-delivery.md

@@ -7,11 +7,19 @@ presentation receipt and must not be blindly replayed. The boundary's bounded ba
 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 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
+Display items come directly from validated producer-neutral card details (`origin`, optional `author`
+and `ref`, landing time `at`, `reach`, and full Markdown `body`). Display never opens Square history. Missing or invalid
 details fall back to card text. Model-facing reminder text is unchanged, and a full display body does
 not make a shortened model-facing card eligible to consume producer unread activity.
 
+The human card keeps delivery order, oldest first. Both states share the same Markdown wrapping,
+inline author/reach and right-aligned local time column. Collapsing keeps four non-blank rendered body
+lines and skips blank rows; hidden non-blank lines add an omission mark and an exact `+N lines` footer.
+Expansion preserves the original blank rows, without message separators or a footer. Direct reaches use warning-colored labels and guides.
+The header merges only contiguous activity references within one origin. Time, reach and reference
+formatting is shared with Paseo. Every final line is bounded by the terminal width, including legacy
+Markdown fallback and very narrow terminals.
+
 Pi session start and shutdown attach and detach the ledger session, not Square seats. Interactive
 cancellation suppresses outstanding local deliveries without marking activity seen; activity after
 cancellation can notify normally. A send already past its final check cannot be recalled.

package/guides/pi-tools.md

@@ -17,9 +17,7 @@ text(result); // CLI text: confirmation and bounded unread previews
 `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
+relative-path cursor. 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
 overview if there are zero or multiple. The extension encodes the live Pi session with

package/guides/row-storage-design.md

@@ -283,7 +283,7 @@ CREATE TABLE routes (
   position INTEGER PRIMARY KEY CHECK (position >= 0),
   participant_key_json TEXT COLLATE BINARY NOT NULL,
   session_json TEXT COLLATE BINARY NOT NULL,
-  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),
+  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','paseo')),
   updated_at REAL NOT NULL,
   payload_json TEXT NOT NULL CHECK (json_valid(payload_json))
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "A shared public square where agents join, perceive activity, express, and step out when done.",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,8 @@
 {
   "name": "square",
-  "version": "0.4.7",
-  "description": "Native Claude Code hook delivery for Square participants",
+  "version": "0.4.8",
+  "description": "Claude Code mod delivery for Square participants",
+  "license": "MIT",
   "author": {
     "name": "Square"
   }

package/plugins/claude/README.md

@@ -0,0 +1,9 @@
+# Square for Claude Code
+
+This plugin adds Square's MCP tools, participation skill and native JavaScript mod. Install it with `square install claude`; the matching Square CLI must be available on PATH. macOS Claude Code 2.1.319 is tested.
+
+During a running turn, the mod appends notification context and emits a native UI log. An idle main session receives a plugin-attributed prompt instead. Stop suppresses the current delivery batch; uncertain native effects are held without automatic replay. Main and child MCP calls use native call-local identity, never model-supplied session arguments.
+
+One private helper per mod session owns the delivery ledger connection. No producer callback service is needed. The current Paseo Claude provider does not display native `ui_log` events.
+
+See [Claude delivery](../../guides/claude-native.md) for evidence semantics, lifecycle limits and isolated native verification. License: MIT.

package/plugins/claude/hooks/hooks.json

@@ -1,11 +1,3 @@
 {
-  "hooks": {
-    "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": [{ "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": [{ "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 }] }]
-  }
+  "modules": ["./register.js"]
 }

package/plugins/claude/hooks/register.js

@@ -0,0 +1,178 @@
+// The mod owns native lifecycle and effects. Its one helper owns Node/SQLite.
+let runtime;
+let starting;
+
+async function rpc($, current, input) {
+  const response = await $.http.fetch(current.url, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input),
+  });
+  if (!response.ok) throw new Error('Square Claude helper request failed');
+  return JSON.parse(response.text);
+}
+
+async function closeRuntime($, current) {
+  if (!current || current.closed) return;
+  current.closed = true;
+  current.epoch++;
+  try { await rpc($, current, { op: 'close' }); } catch { /* The helper may already have exited. */ }
+  await current.stream.return().catch(() => undefined);
+}
+
+async function startRuntime($, sessionId) {
+  const stream = $.process.spawn({ argv: ['square', 'claude-mod'], input: JSON.stringify({ sessionId }) });
+  const current = { sessionId, stream, url: '', buffer: '', closed: false, epoch: 0, epochs: new Map(), modes: new Map([['', 'idle']]) };
+  try {
+    while (!current.url) {
+      const chunk = await stream.next();
+      if (chunk.done) throw new Error('Square Claude helper ended before startup');
+      if (chunk.value.stream !== 'stdout') { $.ui.log(chunk.value.text, { to: 'debug' }); continue; }
+      current.buffer += chunk.value.text;
+      const end = current.buffer.indexOf('\n');
+      if (end < 0) continue;
+      const ready = JSON.parse(current.buffer.slice(0, end));
+      current.buffer = current.buffer.slice(end + 1);
+      if (ready.type !== 'ready' || !/^http:\/\/127\.0\.0\.1:\d+\/[a-f0-9]{64}$/.test(ready.url)) throw new Error('Invalid Square Claude helper address');
+      current.url = ready.url;
+    }
+    // A session.start/tool hook must never hold the turn while waiting on submit.
+    $.clock.after(0, async () => readDeliveries($, current));
+    return current;
+  } catch (error) {
+    await stream.return().catch(() => undefined);
+    throw error;
+  }
+}
+
+async function ensureRuntime($) {
+  const sessionId = await $.session.id();
+  if (runtime && !runtime.closed && runtime.sessionId === sessionId) return runtime;
+  if (starting) { await starting; return ensureRuntime($); }
+  starting = (async () => {
+    await closeRuntime($, runtime);
+    const next = await startRuntime($, sessionId);
+    runtime = next;
+    return next;
+  })();
+  try { return await starting; } finally { starting = undefined; }
+}
+
+async function setMode($, current, mode, agentId) {
+  current.modes.set(agentId ?? '', mode);
+  if (mode === 'stopped' || mode === 'ended') current.epochs.set(agentId ?? '', (current.epochs.get(agentId ?? '') ?? 0) + 1);
+  return rpc($, current, { op: 'state', agentId, mode });
+}
+
+async function deliver($, current, frame) {
+  const epoch = current.epoch;
+  const key = frame.agentId ?? '';
+  const localEpoch = current.epochs.get(key);
+  const available = () => !current.closed && current.epoch === epoch && current.epochs.get(key) === localEpoch && ['busy', 'idle'].includes(current.modes.get(key));
+  if (!available() || !(await rpc($, current, { op: 'guard', token: frame.token })).ok || !available()) {
+    await rpc($, current, { op: 'settle', token: frame.token, kind: 'released' });
+    return;
+  }
+  // No await separates the last native-state fence from the chosen native call.
+  if (current.modes.get(key) === 'busy') {
+    const result = await $.session.append({ agentId: frame.agentId, message: { type: 'user', content: [{ type: 'text', text: frame.text }] } });
+    if (result.deny) {
+      await rpc($, current, { op: 'settle', token: frame.token, kind: 'failed' });
+      $.ui.log('Square context was refused: ' + result.deny, { to: 'debug' });
+      return;
+    }
+    const blocks = result.message?.content;
+    const text = Array.isArray(blocks) && blocks.every(block => block.type === 'text' && typeof block.text === 'string')
+      ? blocks.map(block => block.text).join('') : undefined;
+    // Display is a separate effect, never evidence that the model read the row.
+    try { $.ui.log(frame.display); } finally {
+      await rpc($, current, { op: 'settle', token: frame.token, kind: 'append', text, uuid: result.uuid });
+    }
+    return;
+  }
+  if (frame.agentId !== undefined) {
+    await rpc($, current, { op: 'settle', token: frame.token, kind: 'released' });
+    return;
+  }
+  current.modes.set('', 'busy');
+  // Keep the plugin attribution. A Square notification is not human input.
+  const result = await $.prompt.submit({ text: frame.text });
+  if (result.drop) {
+    if (result.drop.includes('the session was stopped')) await setMode($, current, 'stopped');
+    else {
+      current.modes.set('', 'idle');
+      await rpc($, current, { op: 'settle', token: frame.token, kind: 'failed' });
+    }
+    $.ui.log('Square prompt was not submitted: ' + result.drop, { to: 'debug' });
+    return;
+  }
+  await rpc($, current, { op: 'settle', token: frame.token, kind: 'submit', text: result.text });
+}
+
+async function readDeliveries($, current) {
+  try {
+    while (!current.closed) {
+      let end;
+      while ((end = current.buffer.indexOf('\n')) >= 0) {
+        const line = current.buffer.slice(0, end);
+        current.buffer = current.buffer.slice(end + 1);
+        if (!line) continue;
+        const frame = JSON.parse(line);
+        if (frame.type === 'delivery') {
+          try { await deliver($, current, frame); }
+          catch (error) {
+            // An invoked append/submit may already have taken effect. Never try
+            // the other path, replay it, or call a fallback host on uncertainty.
+            await rpc($, current, { op: 'settle', token: frame.token, kind: 'unknown' }).catch(() => undefined);
+            $.ui.log('Square delivery is uncertain: ' + String(error), { to: 'debug' });
+          }
+        }
+      }
+      if (current.closed) break;
+      const chunk = await current.stream.next();
+      if (chunk.done) break;
+      if (chunk.value.stream === 'stdout') current.buffer += chunk.value.text;
+      else $.ui.log(chunk.value.text, { to: 'debug' });
+    }
+  } catch (error) {
+    if (!current.closed) $.ui.log('Square Claude helper stopped: ' + String(error), { to: 'debug' });
+  } finally { await closeRuntime($, current); }
+}
+
+export function register(on) {
+  on('session.start', async ($, e, next) => {
+    await ensureRuntime($);
+    return next(e);
+  });
+  // /clear and /resume end the old session without another session.start.
+  on('prompt.submit', async ($, e, next) => {
+    await ensureRuntime($);
+    return next(e);
+  }).catch(($, e, next) => next(e));
+  on('turn.start', async ($, e, next) => {
+    const current = await ensureRuntime($);
+    await setMode($, current, 'busy', e.agentId);
+    return next(e);
+  });
+  on('turn.complete', async ($, e, next) => {
+    if (runtime && !runtime.closed) {
+      if (e.agentId !== undefined) {
+        if (e.isAborted) await setMode($, runtime, 'stopped', e.agentId);
+        await setMode($, runtime, 'ended', e.agentId);
+      } else await setMode($, runtime, e.isAborted ? 'stopped' : 'idle');
+    }
+    return next(e);
+  });
+  on('session.end', async ($, e, next) => {
+    const current = runtime;
+    if (current?.sessionId === e.sessionId) await closeRuntime($, current);
+    return next(e);
+  });
+  on('tool.call', { tool: /^mcp__plugin_square_square__/ }, async ($, e, next) => {
+    let current, call;
+    try {
+      current = await ensureRuntime($);
+      call = await rpc($, current, { op: 'mcp-begin', toolUseId: e.tool_use_id, cwd: await $.session.cwd(), agentId: e.agentId });
+    } catch { return { deny: 'Square MCP call identity is unavailable; this call did not run.' }; }
+    try { return await next(e); }
+    finally { await rpc($, current, { op: 'mcp-end', toolUseId: e.tool_use_id, token: call.token }).catch(() => undefined); }
+  }).catch(($, e, next) => next.called ? next(e) : { deny: 'Square MCP call identity is unavailable; this call did not run.' });
+}

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

@@ -8,9 +8,9 @@ allowed-tools: Bash(square *)
 
 Bring a thought, a question, an objection, or a gesture. Leave private tool chatter out; quiet is welcome too.
 
-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`.
+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.
 
-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.
+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`). 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
 

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

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

package/plugins/paseo/OVERVIEW.md

@@ -6,7 +6,7 @@ select text, or copy it in full. The card follows the active Paseo theme on
 desktop and mobile.
 
 Requires Paseo 0.11.2 or newer with custom-message tool rows (#6090). Structured messages
-carry producer-neutral origin, author, reference, badge and full body details. Plain messages and
+carry producer-neutral origin, author, reference, landing time, reach and full body details. Plain messages and
 joining context use a neutral notification heading.
 
 The plugin changes presentation only. It does not send prompts or alter model

package/plugins/paseo/README.md

@@ -17,7 +17,8 @@ are trusted, unsandboxed code running inside the Paseo app.
 
 Requires Paseo >=0.11.2 with custom-message tool rows (#6090). Structured notification
 cards use `details.items` with producer-neutral presentation facts: `kind: 'presentation'`, `origin`,
-optional `author`, `ref` and `badge`, and the full Markdown `body`. Missing or malformed details fall
+`at` (landing time in epoch milliseconds), `reach` (`mention`, `reply`, `attention`, or `bell`),
+optional `author` and `ref`, and the full Markdown `body`. Missing or malformed details fall
 back to the original plain text.
 
 ## Display
@@ -26,28 +27,24 @@ Only synthetic `tool_call` items with `metadata.customType === "square"` and
 plain-text detail are projected into a card. Real tools, other custom messages,
 and unrecognized rows remain unchanged.
 
-The heading and expanded messages use `metadata.details.items` directly, never
-reverse-parsing notification envelopes or body text for senders, IDs or message
-boundaries. Each expanded item keeps its full source body, author, exact reference
-and badge, even when the model preview was clipped or omitted. References with gaps
-are not compressed into a misleading range; items from different origins remain
-separate. Collapsing shows only the last item's preview. Body text containing square
-tags is ordinary content, not another notification.
-
-Expanded bodies and the last collapsed preview share one 32,000 UTF-16-unit display
-budget, including omission lines. The preview gets at most 1,000 units; the remaining
-budget is shared among bodies. Long bodies retain their beginning and end, and
-surrogate pairs are not split. Structured bodies are not also copied into `data.text`.
-Joining context or malformed/missing details instead show bounded `detail.text`
-under a generic heading, without inferring attribution. Original history and model
-input remain unchanged.
-Long content scrolls inside a bounded panel. The
-card does not fetch extra activity or mark anything seen. Live events and fetched history use
-the same transformer.
-
-An accent glyph, author and origin label identify the card. The header and its arrow
-toggle an inline drawer. It uses Paseo theme colors, selectable text, accessible
-expansion state and compact layout on narrow displays. Removing the plugin restores
+The header and messages use `metadata.details.items` directly, without parsing
+notification envelopes for attribution. Messages remain oldest first in both states.
+Both states keep the same Markdown, inline authors, reply and bell labels, timestamps and individual guides; a mention is marked by its guide colour alone. Contiguous
+activity references from one origin form a range; gaps stay explicit. Body text
+containing Square tags is ordinary content.
+
+Both states use one 32,000 UTF-16-unit source display budget, including omission lines.
+Long bodies retain their beginning and end without splitting surrogate pairs.
+Collapsed cards clip the Markdown at four 20px lines; the edge may cut through a line.
+Expansion raises the limit to 260px and enables internal scrolling without replacing the content.
+Click anywhere on the card to expand or collapse it, including short cards. A header chevron appears only
+when the reported content height exceeds the collapsed limit.
+No custom line measurement is needed. Plain or malformed details use bounded `detail.text`
+with a neutral heading. Rendering never fetches producer storage or marks activity seen.
+Live events and fetched history use the same transformer, and model input is unchanged.
+
+The slate palette follows the host theme. The whole card toggles the height limit and
+exposes its expansion state to assistive technology. Removing the plugin restores
 Paseo's ordinary custom-message row.
 
 ## Develop