@astrosheep/square 0.3.106 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/dist/activity-feed.js +1 -1
  2. package/dist/artifact-store.d.ts +41 -0
  3. package/dist/artifact-store.js +272 -0
  4. package/dist/artifact.d.ts +6 -12
  5. package/dist/artifact.js +43 -344
  6. package/dist/attention-presentation.d.ts +13 -7
  7. package/dist/attention-presentation.js +29 -68
  8. package/dist/boundary-presentation.d.ts +3 -16
  9. package/dist/boundary-presentation.js +29 -109
  10. package/dist/card-presentation.d.ts +1 -0
  11. package/dist/card-presentation.js +2 -0
  12. package/dist/catch-decisions.d.ts +2 -2
  13. package/dist/catch-decisions.js +7 -3
  14. package/dist/catch-selection.d.ts +8 -0
  15. package/dist/catch-selection.js +5 -0
  16. package/dist/claude-delivery.d.ts +14 -12
  17. package/dist/claude-delivery.js +42 -142
  18. package/dist/claude-mcp-context.js +2 -2
  19. package/dist/claude-mod.js +28 -140
  20. package/dist/claude-transport.d.ts +5 -0
  21. package/dist/claude-transport.js +34 -0
  22. package/dist/cli/context.d.ts +2 -2
  23. package/dist/cli/context.js +7 -10
  24. package/dist/cli/maintenance-commands.d.ts +0 -4
  25. package/dist/cli/maintenance-commands.js +2 -29
  26. package/dist/cli/observation-commands.d.ts +2 -0
  27. package/dist/cli/observation-commands.js +12 -2
  28. package/dist/cli/program.js +1 -1
  29. package/dist/cli/registry.js +4 -3
  30. package/dist/codex-address.d.ts +2 -2
  31. package/dist/codex-boundary-state.d.ts +1 -5
  32. package/dist/codex-boundary-state.js +0 -4
  33. package/dist/codex-hook.d.ts +7 -10
  34. package/dist/codex-hook.js +69 -33
  35. package/dist/codex-queue.d.ts +10 -11
  36. package/dist/codex-queue.js +32 -34
  37. package/dist/codex-watch.d.ts +2 -0
  38. package/dist/codex-watch.js +100 -0
  39. package/dist/decisions.js +3 -3
  40. package/dist/delivery-deferral.d.ts +1 -19
  41. package/dist/delivery-deferral.js +1 -29
  42. package/dist/delivery-frame.d.ts +7 -0
  43. package/dist/delivery-frame.js +11 -0
  44. package/dist/delivery-ledger-sqlite.d.ts +97 -0
  45. package/dist/delivery-ledger-sqlite.js +496 -0
  46. package/dist/delivery-ledger.d.ts +196 -0
  47. package/dist/delivery-ledger.js +268 -0
  48. package/dist/delivery-lifetime.d.ts +6 -0
  49. package/dist/delivery-lifetime.js +45 -0
  50. package/dist/harness-links.js +61 -7
  51. package/dist/harness.js +12 -17
  52. package/dist/help.js +3 -6
  53. package/dist/http-delivery.d.ts +5 -9
  54. package/dist/http-delivery.js +20 -79
  55. package/dist/inbox.d.ts +6 -57
  56. package/dist/inbox.js +24 -380
  57. package/dist/index.d.ts +7 -4
  58. package/dist/index.js +5 -2
  59. package/dist/mcp.d.ts +2 -1
  60. package/dist/mcp.js +40 -70
  61. package/dist/message.d.ts +7 -0
  62. package/dist/message.js +23 -0
  63. package/dist/model.d.ts +15 -91
  64. package/dist/model.js +2 -140
  65. package/dist/neutral.d.ts +72 -0
  66. package/dist/neutral.js +27 -0
  67. package/dist/notifications.d.ts +24 -26
  68. package/dist/notifications.js +39 -143
  69. package/dist/operation-control.d.ts +4 -0
  70. package/dist/operation-control.js +20 -0
  71. package/dist/operation-presentation.d.ts +1 -2
  72. package/dist/operation-presentation.js +1 -7
  73. package/dist/owner.d.ts +2 -2
  74. package/dist/owner.js +1 -1
  75. package/dist/packages/agent-delivery/src/claude-native.d.ts +2 -0
  76. package/dist/packages/agent-delivery/src/claude-native.js +5 -0
  77. package/dist/packages/agent-delivery/src/codex-boundary.d.ts +11 -6
  78. package/dist/packages/agent-delivery/src/codex-boundary.js +31 -40
  79. package/dist/packages/agent-delivery/src/codex-hook.d.ts +17 -12
  80. package/dist/packages/agent-delivery/src/codex-hook.js +26 -39
  81. package/dist/packages/agent-delivery/src/codex.d.ts +3 -0
  82. package/dist/packages/agent-delivery/src/codex.js +41 -4
  83. package/dist/packages/agent-delivery/src/index.d.ts +3 -1
  84. package/dist/packages/agent-delivery/src/index.js +1 -1
  85. package/dist/packages/agent-delivery/src/paseo.js +11 -2
  86. package/dist/packages/agent-delivery/src/types.d.ts +1 -0
  87. package/dist/paseo-delivery.d.ts +5 -5
  88. package/dist/paseo-delivery.js +19 -99
  89. package/dist/paseo.d.ts +1 -1
  90. package/dist/paseo.js +1 -1
  91. package/dist/plugins/opencode/index.d.ts +5 -3
  92. package/dist/plugins/opencode/index.js +99 -21
  93. package/dist/plugins/opencode-shared/delivery.d.ts +23 -0
  94. package/dist/plugins/opencode-shared/delivery.js +109 -0
  95. package/dist/plugins/opencode-v1/index.d.ts +28 -0
  96. package/dist/plugins/opencode-v1/index.js +41 -0
  97. package/dist/plugins/opencode-v1/runtime.d.ts +56 -0
  98. package/dist/plugins/opencode-v1/runtime.js +152 -0
  99. package/dist/plugins/opencode-v1/transport.d.ts +13 -0
  100. package/dist/plugins/opencode-v1/transport.js +50 -0
  101. package/dist/plugins/paseo/shared/card-presentation.d.ts +10 -0
  102. package/dist/plugins/paseo/shared/card-presentation.js +7 -0
  103. package/dist/ports.d.ts +33 -214
  104. package/dist/presentation.d.ts +5 -5
  105. package/dist/presentation.js +1 -0
  106. package/dist/runtime.js +2 -2
  107. package/dist/search.js +1 -1
  108. package/dist/session-lifecycle.d.ts +8 -7
  109. package/dist/session-lifecycle.js +40 -42
  110. package/dist/sqlite-framing.d.ts +8 -0
  111. package/dist/sqlite-framing.js +31 -0
  112. package/dist/sqlite-square.d.ts +16 -26
  113. package/dist/sqlite-square.js +199 -262
  114. package/dist/sqlite-values.d.ts +21 -0
  115. package/dist/sqlite-values.js +78 -0
  116. package/dist/square-api.d.ts +1 -1
  117. package/dist/square-api.js +5 -8
  118. package/dist/square-core.d.ts +0 -1
  119. package/dist/square-domain.d.ts +12 -10
  120. package/dist/square-domain.js +105 -223
  121. package/dist/square-facade.d.ts +25 -76
  122. package/dist/square-location.d.ts +6 -1
  123. package/dist/square-location.js +1 -1
  124. package/dist/square-post.d.ts +53 -0
  125. package/dist/square-post.js +4 -0
  126. package/dist/square-posting.d.ts +13 -0
  127. package/dist/square-posting.js +174 -0
  128. package/dist/square-producer-sqlite.d.ts +11 -0
  129. package/dist/square-producer-sqlite.js +210 -0
  130. package/dist/square-receive.d.ts +2 -3
  131. package/dist/square-sqlite.d.ts +33 -42
  132. package/dist/square-sqlite.js +236 -768
  133. package/dist/square-tools.d.ts +8 -0
  134. package/dist/square-tools.js +39 -0
  135. package/dist/square-values.d.ts +27 -0
  136. package/dist/square-values.js +90 -0
  137. package/dist/views.d.ts +6 -6
  138. package/dist/views.js +14 -9
  139. package/dist/wake-sink.d.ts +4 -11
  140. package/dist/wake-sink.js +8 -32
  141. package/dist/wake-transports.d.ts +4 -0
  142. package/dist/wake-transports.js +11 -0
  143. package/examples/symmetric-domains.mjs +29 -249
  144. package/guides/change-waits.md +13 -53
  145. package/guides/claude-native.md +19 -172
  146. package/guides/codex-delivery.md +55 -78
  147. package/guides/delivery-primitives.md +48 -207
  148. package/guides/operation-cancellation.md +2 -5
  149. package/guides/participant-ownership.md +25 -89
  150. package/guides/pi-native-delivery.md +19 -56
  151. package/guides/pi-tools.md +6 -8
  152. package/guides/row-runtime-delivery-evidence.md +2 -0
  153. package/guides/row-storage-design.md +19 -44
  154. package/guides/square-api.md +113 -538
  155. package/package.json +8 -8
  156. package/plugins/claude/.claude-plugin/plugin.json +1 -1
  157. package/plugins/claude/hooks/hooks.json +1 -1
  158. package/plugins/claude/{hooks/register.js → mods/square.js} +4 -7
  159. package/plugins/claude/types.d.ts +1 -1
  160. package/plugins/codex/.codex-plugin/plugin.json +1 -1
  161. package/plugins/codex/hooks/hooks.json +11 -23
  162. package/plugins/opencode/index.ts +91 -23
  163. package/plugins/opencode-shared/delivery.ts +91 -0
  164. package/plugins/opencode-v1/index.ts +36 -0
  165. package/plugins/opencode-v1/runtime.ts +134 -0
  166. package/plugins/opencode-v1/transport.ts +41 -0
  167. package/plugins/paseo/OVERVIEW.md +5 -5
  168. package/plugins/paseo/README.md +7 -6
  169. package/plugins/paseo/client/markdown.tsx +5 -5
  170. package/plugins/paseo/client/square-message.tsx +28 -24
  171. package/plugins/paseo/client/transform.ts +8 -5
  172. package/plugins/paseo/shared/card-presentation.ts +16 -0
  173. package/plugins/paseo/shared/message.ts +6 -11
  174. package/plugins/pi/square-pi.js +167 -451
  175. package/dist/channel.d.ts +0 -74
  176. package/dist/channel.js +0 -92
  177. package/dist/claude-delivery-status.d.ts +0 -13
  178. package/dist/claude-delivery-status.js +0 -46
  179. package/dist/cmd/notify-once.d.ts +0 -2
  180. package/dist/cmd/notify-once.js +0 -29
  181. package/dist/delivery-attempts.d.ts +0 -52
  182. package/dist/delivery-attempts.js +0 -73
  183. package/dist/delivery-effects.d.ts +0 -139
  184. package/dist/delivery-effects.js +0 -163
  185. package/dist/delivery-health.d.ts +0 -51
  186. package/dist/delivery-health.js +0 -173
  187. package/dist/delivery-operations.d.ts +0 -9
  188. package/dist/delivery-operations.js +0 -168
  189. package/dist/delivery-primitives.d.ts +0 -5
  190. package/dist/delivery-primitives.js +0 -3
  191. package/dist/delivery.d.ts +0 -45
  192. package/dist/delivery.js +0 -106
  193. package/dist/plugins/opencode/delivery.d.ts +0 -19
  194. package/dist/plugins/opencode/delivery.js +0 -238
  195. package/dist/presentation-operations.d.ts +0 -18
  196. package/dist/presentation-operations.js +0 -86
  197. package/dist/square-index.d.ts +0 -16
  198. package/dist/square-index.js +0 -106
  199. package/dist/square-legacy-framing.d.ts +0 -11
  200. package/dist/square-legacy-framing.js +0 -64
  201. package/dist/square-migration-host-ledger.d.ts +0 -26
  202. package/dist/square-migration-host-ledger.js +0 -169
  203. package/dist/square-migration.d.ts +0 -30
  204. package/dist/square-migration.js +0 -599
  205. package/guides/migration.md +0 -156
  206. package/plugins/opencode/delivery.ts +0 -211
@@ -1,57 +1,17 @@
1
1
  # Waiting for changes
2
2
 
3
- Artifact revisions and the rebuildable discovery index drive change detection. Filesystem
4
- notifications are hints, not activity delivery or consumption receipts.
3
+ Filesystem notifications are hints, not activity delivery or receipts. Artifact revision observation
4
+ and reconciliation let catch and stream reconsider changes even if a filesystem event is missed;
5
+ subscribers retain independent cancellation and deadlines. Throttling waits for its eligibility time.
6
+ There is no discovery index and no daemon or per-message timer.
5
7
 
6
- - A process shares a revision reader per canonical artifact and a filesystem watcher per containing
7
- directory. Subscribers have independent baselines, deadlines and cancellation. The final release
8
- closes the watcher, reconciliation timer and outstanding read.
9
- - Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions
10
- even when notifications are missing. Missing directories, unsupported watches, watcher failures
11
- and directory replacement retain that fallback. Latency is not a hard guarantee: a missed hint
12
- may wait for reconciliation, scheduling and lock contention.
13
- - Conversation revision controls the pending-content cache. Delivery revision separately invalidates
14
- eligibility, including delivery evidence, cancellation and deferral writes. Projections resolve
15
- current typed seats and selected bodies in one coherent artifact read; they never grant authority
16
- from an index entry or a cached eligibility decision. No sidecar, broker or second delivery store
17
- is introduced. An unreadable candidate cannot authorize cached content.
18
- - Each active session pending observer subscribes before selecting current candidates and facts,
19
- including when no seat is yet discoverable. Index publication can wake discovery without an
20
- artifact write. A failed injection waits for substantive change; its own failed evidence write
21
- does not cause a retry loop.
22
- - Deferral create/renew/release and opportunistic pruning change delivery revision, not conversation
23
- activity. Release rechecks eligibility without a new message. Expiry needs no synthetic write:
24
- the observer includes the earliest relevant matching live deferral expiry in its existing wait
25
- deadline, alongside catch-lease expiry/staleness. Overlapping leases remain OR; an early expiry
26
- rechecks the remaining live leases. Renewal changes that deadline without self-triggered delivery.
27
- - There is no new daemon or detached per-message timer. A one-shot producer skips deferred work and
28
- returns promptly. An existing active delivery observer will reconsider release/expiry; absent an
29
- observer, pending work waits for the next normal delivery opportunity. A lease does not create a
30
- process that was not already running.
31
- - Blocking catch waits for conversation revision or its heartbeat/quiet deadline. An active catch keeps
32
- its single lease alive and pauses quiet expiry. Core catch and streams use the same storage change
33
- detector. Throttling waits for its eligibility time.
34
- - Deferrals are independent of catch filters, presentation claims, full-delivery seen receipts,
35
- clipped previews and session-local cancellation. Sharing storage detection does not share session
36
- delivery state. Cancellation never creates a receipt or removes archive history. A deferral cannot
37
- recall a send already past its final freshness check.
8
+ ACK and export ownership serialize with insertion in producer storage; exact future ACK prevents a
9
+ matching late insertion from bypassing it, but cannot recall an already owned export. Cancellation
10
+ does not erase history or imply that activity was read. Proactive delivery suppression belongs in the
11
+ host delivery ledger; see [delivery-primitives.md](delivery-primitives.md).
38
12
 
39
- ## Verification
40
-
41
- Run all tests with the sandbox import; never attach synthetic participants to a live harness identity.
42
-
43
- ```sh
44
- npm test
45
- npm run test:cli-process
46
- node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode poll200
47
- node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode events
48
- node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session
49
- node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
50
- ```
51
-
52
- The benchmark creates disposable synthetic history. Process-local sharing does not deduplicate
53
- monitors across processes. Timings measure committed-write-to-projection latency, not native
54
- message landing, and discovery deadlines are probe bounds rather than an SLA. Historical benchmark
55
- evidence may describe older HostLedger implementations; it is not current custody authority.
56
- A long-running extension must reload upgraded code before using the new artifact format; this
57
- delivery does not install or restart one.
13
+ At the next normal privileged posting opportunity, already-posted eligible keys can be dispatched
14
+ again without reinserting cards or resetting producer state. Ledger attempts exclude accepted, unknown
15
+ and presented work; only never-attempted or known-unsent failed/released work can proceed. No new
16
+ scheduler or Stop watcher is needed. See [square-api.md](square-api.md) for bounded recovery of
17
+ abandoned export ownership.
@@ -1,174 +1,21 @@
1
1
  # Claude native inbox
2
2
 
3
- Square's Claude plugin is a mod, not a shell-hook injector. Its `hooks/hooks.json`
4
- contains only `{"modules":["./register.js"]}`. Install with `square install claude`
5
- and load/approve it in a trusted interactive Claude terminal. Installation is
6
- not evidence of a live receiver.
7
-
8
- Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
9
- `wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
10
- synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
11
-
12
- ## Validated capability
13
-
14
- The supported baseline is **macOS Claude Code with the mod actually loaded**;
15
- no build number is pinned. The receiver reads its real session ID, cwd, version, and
16
- `CLAUDE_CODE_MESSAGING_SOCKET`. A session ID or socket alone is not capability.
17
- Missing/disabled/unapproved mods, the normal unapproved headless `-p` path,
18
- and other platforms are unavailable. No legacy fallback exists.
19
- Square never changes inbound policy, forwards a child token, or impersonates a
20
- peer/plugin authority. Native OS-user socket permissions and Claude policy apply.
21
-
22
- `square harness doctor claude` explains installation and these limits.
23
- `square harness doctor delivery` derives current routes/evidence without sending.
24
- An absent/broken endpoint is unavailable; it does not consume Square activity.
25
-
26
- ## Native-first routing and policy holds
27
-
28
- Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
29
- joins register the native queue for their thread. Claude and OpenCode receivers
30
- register their native wake addresses only through their loaded integrations. An
31
- ordinary reconnect or reattachment cannot replace a current native address with a
32
- generic Paseo proposal. Addresses belong to the artifact seat generation, not an
33
- expiring routes table: explicit receiver withdrawal permits fallback, and a new
34
- seat generation cannot inherit the previous generation's native registration.
35
- Participant expressions do not publish replacement addresses.
36
-
37
- This is route preference, not permission to bypass receiver policy. Claude can
38
- legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
39
- under `bypassPermissions`. Square neither asserts a made-up permission mode nor
40
- changes `crossSessionInbound`. After bytes may have been sent, `unknown` remains
41
- attention-wide and prevents another send through Paseo, even if routes later change.
42
-
43
- Each native send persists a message ID before writing; the wire `uuid` and
44
- `msg_id` carry that ID. Square records no native custody telemetry from Paseo:
45
- official Paseo exposes no delivery-status lifecycle event, so a held message stays
46
- `unknown` with `native_admission_unconfirmed`. Recording a `held`, `released` or
47
- `dropped` observation would require a Paseo-provided event; Square does not patch
48
- Paseo to invent one. Even when such an observation exists, the event ID is
49
- deduplicated and the native reason and observation time remain diagnostic only.
50
- Neither a release nor a drop is a queue receipt, proof of consumption or retry
51
- authorization.
52
-
53
- `square harness doctor delivery` shows native custody separately from pending
54
- attention for current seat generations, including after the activity is seen. Paseo
55
- presents the `peer_message_hold` state in its own timeline. Acceptance means normal
56
- delivery when the receiver allows it, or a visible reason without bypass/replay when
57
- policy holds it.
58
-
59
- ## MCP tools and call identity
60
-
61
- The plugin's `.mcp.json` starts the existing Square MCP server. The mod no longer
62
- registers an argv wrapper or executes participant CLI commands. MCP and Pi native
63
- tools share their operation definitions and facade calls in `square-tools.ts`.
64
-
65
- Before a bundled MCP call, the mod uses the existing `square claude-mod` helper
66
- to publish `{toolUseId, sessionId, cwd, agentId?}`. It then calls `next(e)` unchanged.
67
- The server correlates `_meta["claudecode/toolUseId"]` with that association: no
68
- session, agent, token or other transport field is added to the model's schema or
69
- arguments. Claude's native **session ID plus child flag** semantics are preserved;
70
- the child loop's `agentId` is retained for attribution, not substituted as a session ID.
71
- Calls use the live cwd and session even if the MCP process started earlier.
72
-
73
- `SQUARE_CLAUDE_MCP_CONTEXT=1` is set only by the bundled MCP configuration. That
74
- endpoint fails closed if an association is missing or expired; it never silently
75
- uses the startup parent identity. Generic MCP configurations retain their existing
76
- identity handling. The hook targets `mcp__plugin_square_square__*`, not unrelated
77
- servers with similar operation names.
78
-
79
- The mod owns publication and token-matched removal in `finally`; the server only
80
- reads. Associations are private, transient transport files under
81
- `<host-ledger-root>/claude-mcp-calls`, not Square domain state or another artifact.
82
- Normal completion/errors remove them. If abrupt cancellation, unload or a crash
83
- prevents cleanup, they expire after ten minutes and the next publication prunes
84
- them. Expiry gates lookup, not an operation that already captured its context.
85
- MCP owns operation cancellation and connection shutdown. No second execution
86
- protocol, resident service or ledger schema migration is introduced.
87
-
88
- ## Membership and lifecycle
89
-
90
- Participants join explicitly. The mod never discovers or joins a square from its
91
- filename; `PUBLIC.square` has no special behavior. Existing memberships reconcile
92
- on startup. Main-conversation tool completion (including failed/aborted tools) and
93
- conversation start reconcile late memberships: the receiver itself publishes
94
- routes; the CLI cannot infer mod capability from a socket or session environment.
95
- This reconciliation injects no activity and does not poll. Its recovery sweep
96
- only sends previously unsent eligible attention, never unknown/admitted attempts.
97
-
98
- Initial activation and hot reload use `session.start`. New conversations use
99
- `classic.SessionStart`: clear reads the new API coordinate; **resume's event
100
- `session_id` is already the resumed coordinate while `$.session.id()` still reads
101
- the ending one (observed in 2.1.295)**. The event coordinate is used at that boundary, with
102
- API cwd/version/socket. Modern `session.end` detaches only its pinned `e.sessionId`
103
- and captured owner/join generations, within the event budget. Late committed joins
104
- are discovered at the pinned end timestamp. A process crash can omit end.
105
-
106
- Host end is not a participant departure: no `done` lands, and membership, listens,
107
- read horizon and generation remain intact. Catch ownership, deferrals and wake readiness
108
- are cleared; the participant appears away and keeps accumulating unread audience without
109
- proactive delivery. Before arming a receiver, start/resume discovers the exact owner's
110
- standing seats through `seatsOf(owner)` and restores only detached ones with
111
- `reattach(name, {owner, wakeAddress?})`. The adapter obtains that owner with
112
- `harnessOwner({channel: 'claude-code', session, agent?})`. One failed seat or location does not block the
113
- others. New/forked harness owners restore nothing. Neither a voluntary `done` nor a takeover is
114
- revived; there is no completed-seat recovery path or timeout that turns away into done.
115
- See [participant-ownership.md](participant-ownership.md).
116
-
117
- ## Body, admission, and presentation
118
-
119
- The coordinator uses Square's canonical audience projection and bounded body
120
- preview. Each notification identifies the square, receiving participant and
121
- activity before its event and body. A clipped preview describes catching that
122
- activity to read it in full; it never embeds shell commands or tool-call syntax.
123
- Opaque text correlation resolves through bound memberships and the existing
124
- attempt ledger, never a path or asserted source from incoming text.
125
-
126
- Transport is the Node-only leaf published as `@astrosheep/agent-delivery/claude-native`,
127
- sourced from `packages/agent-delivery/src/claude-native.ts`. Square imports that
128
- source directly; its root package ships the compiled leaf without loading the
129
- OpenCode SDK or requiring a separate agent-delivery installation. There is no
130
- second socket sender. Receipt semantics (`written` is local bytes only, never
131
- admission), the plain-peer use, and the standalone client API are documented in
132
- the package `README.md`; the leaf accepts only target/session endpoint, text, and
133
- bounded deadline/cancellation control.
134
-
135
- `session.receive` runs before native policy; Square owns this admission gate and
136
- the presentation writer, not the leaf. `await next(e)` confirms queue admission
137
- only when the returned text is unchanged. Hold/refuse reject that gate;
138
- consumed/rewritten results cannot confirm the original. Unknown peer messages
139
- pass through. Recognized stale/cancelled deliveries can be consumed before queueing.
140
- No ambiguous send is blindly retried.
141
-
142
- The sole presentation writer observes **returned stored main user-role text**
143
- after `session.append.next`. It matches the entire expected payload within
144
- Claude's idle/busy peer framing. A complete preview records seen + presented;
145
- a clipped one records clipped only. This means stored in model context, not
146
- processed or understood. Catch/presentation races are idempotent and revalidated
147
- immediately before send and inside the observation transaction.
148
-
149
- ## Cancellation and custody
150
-
151
- Explicit plugin `turn.abort` and terminal `turn.complete(reason:'aborted')`
152
- suppress the outstanding local batch without recording seen. Ordinary answer,
153
- refusal, and error completion are not user cancellation. Separate engine-owned
154
- family state survives hot reload, containing the abort timestamp and frozen
155
- membership generations. The artifact stores a generation-scoped monotonic activity
156
- cutoff; replacement generations cannot inherit the old abort.
157
-
158
- Engine state reads are snapshots of one dispatch. Confirmation therefore uses
159
- one immediate fresh `clock.after` dispatch to read cancellation, not a repeated
160
- read in the old dispatch. It is not polling. If reload cancels a pending callback,
161
- its evidence stays unknown: reload does not replay it. A failed cancel bridge
162
- can be repaired by the fresh confirmation/reconciliation dispatch from retained
163
- engine state. If all bridge/state operations are unavailable, Square cannot
164
- promise a receipt or suppression; it fails boundedly and preserves unrelated
165
- Claude behavior.
166
-
167
- **Already queued OR natively held messages cannot be retracted.** Approval may
168
- release a held message without another receive guard. Append is observational,
169
- not a veto. Square suppresses local retries and stale evidence but cannot erase
170
- native custody or promise that remote work will not run. New activity after the
171
- abort remains eligible. Protocol design and runtime evidence live in the package
172
- `VALIDATION.md` and the commission artifacts it cites; the repository fixtures
173
- cover the same coordinator and packaging boundaries without requiring a Claude
174
- installation.
3
+ Square's Claude plugin is a mod, not a shell-hook injector. Its MCP server uses the mod's call-local
4
+ session association; a missing or expired association fails closed. A session ID or socket alone does
5
+ not establish that the mod is loaded. The supported native path requires macOS Claude Code with the
6
+ mod loaded and approved. Square does not alter inbound policy or bypass a held peer message.
7
+
8
+ The mod attaches and detaches the exact host session in the delivery ledger. Membership remains in
9
+ Square; host end does not land `done`, and start/resume does not restore seats. See
10
+ [participant-ownership.md](participant-ownership.md).
11
+
12
+ The sender dispatches finished ledger cards through the native socket. Native admission settles a
13
+ handoff as accepted, not presented; the stored main user-role text observation settles presentation
14
+ through its handoff reference. This establishes observation at that boundary, not comprehension, and
15
+ cannot promise that a later plugin leaves the card intact. Unknown native custody is not a safe reason
16
+ to replay through another route. A shortened activity card points to catch; Square only folds a receipt
17
+ for a full card into its read state. Direct producer notices retain their full body.
18
+
19
+ `turn.abort` cancels the outstanding ledger batch without asserting it was read. Already queued or
20
+ natively held messages cannot be recalled. The shared transport and its validated limits are documented
21
+ in [agent-delivery's README](../packages/agent-delivery/README.md) and `VALIDATION.md`.
@@ -1,90 +1,67 @@
1
1
  # Codex delivery
2
2
 
3
- Square uses the shared Codex leaves in `packages/agent-delivery/src`, rather than
4
- maintaining a second hook protocol, boundary store or CLI sender. The standalone
5
- package's [README](../packages/agent-delivery/README.md) describes both its native
6
- app-server capability and its host-owned hook integration.
3
+ Producers post neutral cards to DeliveryLedger; neither default dispatch nor public `postAndDispatch`
4
+ queues Codex input. A native receiver owns both synchronous presentation and idle queue admission.
5
+ It never reads Square artifacts or producer content stores.
7
6
 
8
- Public `Square.at` and `Square.build` use the default Claude/Codex/Paseo wake transport when
9
- `wakeTransport` is omitted. Supply a port to replace it or `false` to disable proactive wake;
10
- synchronous `Square.inMemory` uses only an explicit port. See [square-api.md](square-api.md).
7
+ The shipped hooks for Codex 0.166.0 are synchronous SessionStart, UserPromptSubmit, PreToolUse,
8
+ PostToolUse, Stop, Interrupt and SessionEnd, plus an async Stop command with `timeout: 86400` seconds.
9
+ SessionStart disarms and attaches the exact native session. Active prompt/tool boundaries disarm and
10
+ present eligible cards as event-correct `additionalContext`, using neutral reminder framing and the
11
+ original card text. The output sink must accept the response before presentation evidence is recorded;
12
+ a later suppression does not erase a real output effect. SessionEnd disarms and detaches. None of these
13
+ host lifecycle events restores or detaches Square seats. SessionResume is not a verified native event
14
+ and is not registered. A resume path without a real SessionStart/Stop has no inferred idle authority.
11
15
 
12
- ## Square's hook path
16
+ Each synchronous Stop stores a unique token and native turn ID in the existing boundary store. One
17
+ receiver-owned `square codex-watch` command holds a separate private OS-backed lock for its native
18
+ session coordinate and observes the ledger, with a one-second bounded rescan for boundary changes or
19
+ missed notifications. Duplicate async Stop processes exit; the existing watcher follows newer Stop
20
+ tokens. The lock does not prove idle state. Observation never reserves cards while waiting.
13
21
 
14
- `plugins/codex/hooks/hooks.json` invokes `square codex-hook`:
22
+ Before claiming each card, the watcher reads the hosting endpoint's `thread/read(includeTurns:true)`.
23
+ It requires loaded idle state and the newest live turn to be completed with exactly the captured Stop
24
+ turn ID. Newest-last history ordering is verified for 0.166.0; other versions fail closed until verified.
25
+ After claiming, the receiver repeats that native read, checks the exact epoch again, then checks ledger
26
+ currentness, suppression, cancellation, attachment generation, signal and deadline immediately before
27
+ CLI invocation. Queue always uses the existing hosting endpoint explicitly, without starting a service.
28
+ Missing, malformed, ephemeral, notLoaded, active, interrupted or unreadable history cannot authorize a
29
+ queue. A delayed stale Stop cannot authorize sending merely by arriving after an active callback.
15
30
 
16
- - `SessionStart`, `SessionResume` and `UserPromptSubmit` invalidate the previous
17
- Stop observation. `SessionEnd` marks the host session ended and detaches its exact
18
- owner's seats without landing `done`, ending membership, dropping listens or resetting
19
- the read horizon. Later Stop/tool callbacks cannot re-enable queue until a new
20
- `SessionStart` or `SessionResume`. Before enabling delivery, those start paths use
21
- `seatsOf(owner)` and `reattach(name, {owner, wakeAddress?})` to restore only detached
22
- standing seats of that exact owner; voluntary departures and takeovers are never revived.
23
- A new/forked session restores nothing.
24
- - `PostToolUse` asks Square for current pending activity and returns the existing
25
- bounded `additionalContext` presentation.
26
- - `Stop` records queue eligibility and sweeps pending work, but does not itself
27
- claim that a preview was presented.
31
+ `square codex-interrupt` handles only a native Interrupt payload and cancels the captured attachment's
32
+ pending through-sequence batch, then future cards remain available after a later verified Stop or active
33
+ boundary. Replacement attachments are fenced by generation. Before-effect epoch/suppression/cancel
34
+ failures release their claims where the ledger permits. Attachment rotation already normalizes an
35
+ in-flight ledger attempt to unknown: that custody remains unknown even if the final receiver check
36
+ then proves no queue was launched. The watcher exits on detach, deletion or generation change and
37
+ retains its ledger connection only for already-captured late settlements.
28
38
 
29
- The shared handler owns hook framing, lifecycle sequencing, its cancellation
30
- budget and bounded sweeps. Square supplies activity selection, formatting,
31
- artifact-owned presentation claims, cancellation, attachment cleanup and
32
- pending-work sweeps. The handler cooperatively awaits Square's pull: the signal
33
- cancels work before presentation, but a successful presentation's `settleAs`
34
- finishes independently of request cancellation. Even when that settlement crosses
35
- the internal budget, the hook waits for it and returns the associated context;
36
- it never abandons settlement that can mark activity seen without returning text.
37
- After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
38
- output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
39
- an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare session id. The shared
40
- boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
41
- defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
42
- conversation storage and are not proof of current native execution or consumption.
43
- Square's format-8 artifact remains authoritative for membership, attachment and delivery evidence.
44
- Detached members appear away indefinitely and keep accumulating unread audience, but have no
45
- write or proactive delivery eligibility until same-owner reattachment. Only a host-confirmed
46
- permanent deletion uses fenced membership-ending cleanup; Codex SessionEnd is not that proof.
39
+ Queue admission is custody, not presentation or model comprehension. Accepted/unknown outbox custody
40
+ has no remaining card content and cannot be automatically replayed. Invoked timeout or ambiguous
41
+ results remain unknown. Native idle reads and external queue are not atomic: a new turn can start after
42
+ the final check and a raced queue may arrive later. Interrupt cannot recall input already admitted by
43
+ Codex, and hook failure/timeout cannot prove that cancellation happened. Native callbacks have no
44
+ cross-incarnation event identity; SessionEnd can fence only the attachment observed when it runs.
47
45
 
48
- `CodexQueueTransport` implements the existing `WakeTransportPort` and uses the public
49
- `connect({ harness: 'codex', transport: 'cli', sessionId, boundaries, ... })`
50
- and `agent.queue(text)` interface, just like independent hosts. Square reads its
51
- stored pending preview and finishes its currentness gate first; the bound client
52
- checks boundary eligibility once inside `queue()`, then launches the CLI. No
53
- caller-side lifecycle check is duplicated. Outcomes continue through the existing
54
- artifact-owned delivery path; no host ledger or new route kind is introduced.
46
+ There is no watcher before the first Stop. Synchronous boundaries can present; otherwise cards wait.
47
+ The async budget is finite 24 hours, not a promise of 24-hour observation. After timeout, crash, host
48
+ termination or missed spawn while idle, cards wait for the next Stop/user/native boundary. There is no
49
+ producer fallback or autonomous crash-idle recovery. During attachment replacement an old watcher
50
+ may briefly retain the coordinate lock while the new Stop's duplicate exits; the next Stop restores
51
+ observation after the old process releases it.
55
52
 
56
- Both CLI coordinate creation and MCP call-local Codex coordinates capture the
57
- recipient's `CODEX_HOME` (or home default), so later senders use the recipient's
58
- CLI configuration rather than their own. Only an explicitly configured
59
- `SQUARE_CODEX_ENDPOINT` adds a remote endpoint. `SQUARE_CODEX_BIN` remains
60
- Square's executable selection; it is not an environment convention of the
61
- independent package.
53
+ Reproduce the isolated native smoke from this checkout after a worktree-local build:
62
54
 
63
- By default the sender runs `codex queue --thread ... --message ...`, allowing the
64
- CLI's normal connection/startup behavior. Only an explicit endpoint adds
65
- `--remote`. This does not make another host's private stdio pipe attachable.
66
- After an observed `SessionEnd`, Square does not dispatch queue; the bound lifecycle
67
- check also catches an end observed while the currentness gate was running.
68
- It cannot retract a submission already launched or infer a missed end hook.
69
- Queue success means native admission only; its receipt id is a local attempt
70
- UUID, not a server message id. The child runs asynchronously and respects the
71
- send's abort signal/deadline. Timeout, killed child and unexplained post-launch
72
- failures remain unknown, not a safe reason to resend. A receiver with no tool
73
- calls waits for Stop; this path is not instantaneous native steer.
55
+ ```sh
56
+ env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
57
+ node --import ./test/sandbox-env.js test/codex-watch-native.mjs
58
+ ```
74
59
 
75
- ## Optional native app-server capability
60
+ The probe creates a temporary HOME/CODEX_HOME, installs no plugin, and uses the actual shipped hook
61
+ manifest/CLI with an isolated native app-server and loopback fixture provider. Its JSON evidence names
62
+ the temporary directory. It verifies native Stop startup, idle wake, busy fencing, singleton reuse,
63
+ Interrupt RPC cancellation, real UserPromptSubmit presentation and process-group shutdown. Physical
64
+ TUI Escape-to-Interrupt is not verified; neither are 24-hour operation or every resume path.
76
65
 
77
- Independent consumers can use `connect({ harness: 'codex', sessionId, endpoint })`
78
- from `@astrosheep/agent-delivery` for fenced busy steer and native queue.
79
- `transport: 'app-server'` is the explicit spelling and the default when omitted;
80
- it exposes both methods. `transport: 'cli'` exposes queue only and requires the
81
- host's hook lifecycle source at connection time. There is no automatic fallback
82
- between transports. The app-server transport never starts a service or calls
83
- `thread/resume`. This does not replace Square's hook policy or add a new persisted
84
- Square route kind. A loaded thread's owner remains its existing host, not the
85
- external sender.
86
-
87
- Neither path implements a read-receipt roundtrip. Admission and runtime
88
- observations must not be presented as model comprehension or completion. An
89
- unknown outcome stays unknown. Installing, restarting or changing a real Codex
90
- server is outside this integration.
66
+ The shared package documents its transport leaves in [its README](../packages/agent-delivery/README.md).
67
+ See [participant ownership](participant-ownership.md) for host attachment and Square membership.