@astrosheep/square 0.4.3 → 0.4.4

package/dist/claude-hook.js

@@ -118,7 +118,7 @@ export async function runClaudeHook(text, env = process.env, sink = value => { p
         && input.tool_name?.startsWith('mcp__plugin_square_square__') && input.tool_use_id) {
         await endClaudeMcpCallForSession(input.tool_use_id, input.session_id, env, input.agent_id).catch(() => undefined);
     }
-    if (['PreToolUse', 'PostToolUse', 'PostToolUseFailure'].includes(input.hook_event_name)) {
+    if (input.hook_event_name === 'PostToolUse') {
         await presentPendingAtBoundary(owner, async (context) => {
             await sink(`${JSON.stringify({ hookSpecificOutput: { hookEventName: input.hook_event_name, additionalContext: context } })}\n`);
         }, env, AbortSignal.timeout(4500));

package/dist/codex-hook.d.ts

@@ -1,8 +1,8 @@
 import { type CodexHookInput } from './packages/agent-delivery/src/codex-hook.js';
 export type HookTrace = (line: string) => void;
 export declare const CODEX_HOOK_BUDGET_MS = 4500;
-/** sink resolves only after stdout has accepted the complete hook response. */
-export declare function codexHookResponse(value: unknown, sink: ((text: string) => void | Promise<void>) | undefined, env?: NodeJS.ProcessEnv, trace?: HookTrace): Promise<object | undefined>;
+/** Active delivery uses PostToolUse only; each async Stop owns its own wait. */
+export declare function codexHookResponse(value: unknown, sink: ((text: string) => void | Promise<void>) | undefined, env?: NodeJS.ProcessEnv, trace?: HookTrace): Promise<void>;
 export declare function parseCodexHookText(text: string): CodexHookInput | undefined;
 /** The caller owns stdout; no receipt is written when no output sink is supplied. */
 export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv, sink?: (text: string) => void | Promise<void>): Promise<string>;

package/dist/codex-hook.js

@@ -1,13 +1,12 @@
-import { handleCodexHook, parseCodexHook } from './packages/agent-delivery/src/codex-hook.js';
+import { parseCodexHook } from './packages/agent-delivery/src/codex-hook.js';
 import { presentPendingAtBoundary } from './boundary-presentation.js';
 import { DeliveryLedger } from './delivery-ledger.js';
 import { harnessOwner } from './owner.js';
 import { attachDeliverySessionRoutes, detachDeliverySession } from './session-lifecycle.js';
-import { codexBoundaryStore } from './codex-boundary-state.js';
 import { codexWakeAddress } from './codex-address.js';
 export const CODEX_HOOK_BUDGET_MS = 4500;
 const defaultTrace = line => { process.stderr.write(`${line}\n`); };
-/** sink resolves only after stdout has accepted the complete hook response. */
+/** Active delivery uses PostToolUse only; each async Stop owns its own wait. */
 export async function codexHookResponse(value, sink, env = process.env, trace = defaultTrace) {
     const input = parseCodexHook(value);
     if (!input)
@@ -16,47 +15,35 @@ export async function codexHookResponse(value, sink, env = process.env, trace =
     const timeoutMs = Math.min(input.hook_event_name === 'Interrupt' || input.hook_event_name === 'SessionEnd' ? 2500 : CODEX_HOOK_BUDGET_MS, Number.isFinite(configured) && configured > 0 ? configured : CODEX_HOOK_BUDGET_MS);
     const signal = AbortSignal.timeout(timeoutMs);
     const owner = harnessOwner({ channel: 'codex', session: input.session_id });
-    // Capture before any asynchronous boundary update; a replacement attachment
-    // must never inherit this callback's cancellation or detachment.
-    let generation;
-    if (input.hook_event_name === 'SessionEnd' || input.hook_event_name === 'Interrupt') {
+    if (input.hook_event_name === 'SessionStart') {
+        await attachDeliverySessionRoutes(owner, env, [codexWakeAddress(input.session_id, env)], signal);
+    }
+    else if (input.hook_event_name === 'SessionEnd' || input.hook_event_name === 'Interrupt') {
         const ledger = await DeliveryLedger.open({ location: env.SQUARE_DELIVERY });
         try {
-            generation = (await ledger.session(owner))?.generation;
+            const captured = await ledger.session(owner);
+            if (!captured || signal.aborted)
+                return;
+            if (input.hook_event_name === 'SessionEnd')
+                await detachDeliverySession(owner, captured.generation, env);
+            else
+                await ledger.cancel({ owner, generation: captured.generation });
         }
         finally {
             await ledger.close();
         }
     }
-    const result = await handleCodexHook(input, {
-        boundaries: codexBoundaryStore(env), timeoutMs, signal,
-        pull: async (_sessionId, pullSignal, event) => {
-            if (!sink)
-                return;
-            return presentPendingAtBoundary(owner, async (context) => {
-                await sink(`${JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: context } })}\n`);
-                return context;
-            }, env, pullSignal);
-        },
-        end: async () => { if (generation)
-            await detachDeliverySession(owner, generation, env); },
-        interrupt: async () => {
-            if (!generation || signal.aborted)
-                return;
-            const ledger = await DeliveryLedger.open({ location: env.SQUARE_DELIVERY });
-            try {
-                await ledger.cancel({ owner, generation });
-            }
-            finally {
-                await ledger.close();
-            }
-        },
-        trace: name => trace(`square-codex-hook: stage=${name}`),
-    });
-    // Disarm before rotating the native attachment, even if there is no old session.
-    if (input.hook_event_name === 'SessionStart' && !signal.aborted)
-        await attachDeliverySessionRoutes(owner, env, [codexWakeAddress(input.session_id, env)], signal);
-    return result;
+    else if (input.hook_event_name === 'PostToolUse' && sink) {
+        try {
+            await presentPendingAtBoundary(owner, async (context) => {
+                await sink(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } })}\n`);
+            }, env, signal);
+            trace('square-codex-hook: stage=presentation');
+        }
+        catch (error) {
+            trace(`square-codex-hook: stage=presentation error=${error instanceof Error ? error.name : 'Error'}`);
+        }
+    }
 }
 export function parseCodexHookText(text) {
     try {

package/dist/codex-queue.d.ts

@@ -1,7 +1,6 @@
-import { type CodexStopEpoch } from './codex-boundary-state.js';
 import type { DeliveryCard, DeliveryTransport, DeliveryTransportContext, TransportOutcome } from './delivery-ledger.js';
 export interface CodexQueueTransportOptions {
-    readonly epoch: CodexStopEpoch;
+    readonly turnId: string;
     readonly address: Readonly<Record<string, string>>;
     readonly env?: NodeJS.ProcessEnv;
 }

package/dist/codex-queue.js

@@ -1,7 +1,6 @@
 import { connect, DeliveryError } from './packages/agent-delivery/src/index.js';
 import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
 import { codexQueueEndpoint } from './packages/agent-delivery/src/codex-endpoint.js';
-import { codexBoundaryStore } from './codex-boundary-state.js';
 import { renderDeliveryReminder } from './delivery-frame.js';
 /** Instantiated only by the receiver, for one captured Stop epoch. */
 export class CodexQueueTransport {
@@ -16,21 +15,19 @@ export class CodexQueueTransport {
             !Object.entries(this.opts.address).every(([key, value]) => address[key] === value))
             return 'not-capable';
         const env = this.opts.env ?? process.env;
-        const boundaries = codexBoundaryStore(env), epoch = this.opts.epoch;
+        const turnId = this.opts.turnId;
         try {
             // Receiver delivery addresses the already-hosting endpoint explicitly;
             // disappearing native custody must not trigger CLI service startup.
             const endpoint = address.endpoint ?? codexQueueEndpoint({ CODEX_HOME: address.codexHome });
             const agent = await connect({ harness: 'codex', transport: 'cli', sessionId: threadId,
                 boundaries: { queueEligible: async (id) => {
-                        if (!await boundaries.queueEligible(id, epoch))
-                            return false;
                         // Repeat the native sample after claim, immediately before the final
-                        // epoch and ledger fences. These reads are not an atomic native enqueue.
+                        // ledger fences. These reads are not an atomic native enqueue.
                         if (!await codexIdleAtStop({ harness: 'codex', sessionId: id, codexHome: address.codexHome,
-                            endpoint, timeoutMs: Math.max(1, context.deadline - Date.now()), signal: context.signal }, epoch.turnId))
+                            endpoint, timeoutMs: Math.max(1, context.deadline - Date.now()), signal: context.signal }, turnId))
                             return false;
-                        return await boundaries.queueEligible(id, epoch) && await context.beforeSend()
+                        return await context.beforeSend()
                             && !context.signal.aborted && Date.now() < context.deadline;
                     } },
                 env, bin: env.SQUARE_CODEX_BIN, codexHome: address.codexHome, endpoint });

package/dist/codex-watch.d.ts

@@ -1,2 +1,2 @@
-/** One native async hook owns observation; the lock itself conveys no idle authority. */
+/** One async Stop waits only for its captured native turn; it never adopts another Stop. */
 export declare function runCodexWatch(inputText: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string>;

package/dist/codex-watch.js

@@ -6,46 +6,45 @@ import { retainDeliveryLedger } from './delivery-lifetime.js';
 import { harnessOwner } from './owner.js';
 import { withFileLock } from './file-lock.js';
 import { canonicalPath } from './canonical-path.js';
-import { codexBoundaryStore } from './codex-boundary-state.js';
 import { codexWakeAddress } from './codex-address.js';
 import { parseCodexHookText } from './codex-hook.js';
 import { CodexQueueTransport } from './codex-queue.js';
-import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
-/** One native async hook owns observation; the lock itself conveys no idle authority. */
+import { codexStopState } from './packages/agent-delivery/src/codex.js';
+/** One async Stop waits only for its captured native turn; it never adopts another Stop. */
 export async function runCodexWatch(inputText, env = process.env, signal) {
     const input = parseCodexHookText(inputText);
     if (input?.hook_event_name !== 'Stop' || signal?.aborted)
         return '';
+    const turnId = input.turn_id;
     const controller = new AbortController();
     const stop = () => controller.abort();
     const timer = setTimeout(stop, 86_400_000);
     const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     process.on('SIGTERM', stop);
     process.on('SIGINT', stop);
+    let lifetime;
     try {
         const route = codexWakeAddress(input.session_id, env);
         const home = await canonicalPath(route.address.codexHome);
-        const coordinate = [input.session_id, route.address.endpoint ?? home];
+        const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
+        lifetime = retainDeliveryLedger(ledger);
+        const owner = harnessOwner({ channel: 'codex', session: input.session_id });
+        const captured = await ledger.session(owner);
+        if (captured?.state !== 'attached')
+            return '';
+        // Same-turn duplicates cannot overlap; a later Stop need not wait for an old
+        // watcher or a slow late settlement to release a session-wide lock.
+        const coordinate = [input.session_id, route.address.endpoint ?? home, captured.generation, turnId];
         const root = path.join(path.dirname(deliveryLedgerLocation(env)), 'codex-watchers');
         await fs.mkdir(root, { recursive: true, mode: 0o700 });
         const lock = path.join(root, createHash('sha256').update(JSON.stringify(coordinate)).digest('hex') + '.lock');
         const file = await fs.open(lock, 'a', 0o600);
         await file.close();
         await withFileLock(lock, { retryMs: 10, skipIfBusy: true, signal: combined }, async () => {
-            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
-            const lifetime = retainDeliveryLedger(ledger);
-            let observer;
+            const observer = await ledger.observe(owner);
             try {
-                const owner = harnessOwner({ channel: 'codex', session: input.session_id });
-                const captured = await ledger.session(owner);
-                if (captured?.state !== 'attached')
-                    return;
-                const boundaries = codexBoundaryStore(env);
-                // Subscribe before inspecting pending work. Both ledger edges and the
-                // bounded wait below cause reconciliation; boundary-only changes matter.
-                observer = await ledger.observe(owner);
                 while (!combined.aborted) {
-                    let version = await observer.read(combined);
+                    const version = await observer.read(combined);
                     const session = await ledger.session(owner);
                     if (session?.state !== 'attached' || session.generation !== captured.generation)
                         return;
@@ -54,36 +53,34 @@ export async function runCodexWatch(inputText, env = process.env, signal) {
                         registered.address.endpoint !== route.address.endpoint ||
                         !registered.address.codexHome || await canonicalPath(registered.address.codexHome) !== home)
                         return;
-                    const boundary = await boundaries.read(input.session_id);
-                    if (boundary?.ended)
+                    // Probe even with no pending card: a new user/model turn retires this
+                    // watcher without requiring UserPromptSubmit or tool hooks to disarm it.
+                    const state = await codexStopState({ harness: 'codex', sessionId: input.session_id,
+                        codexHome: registered.address.codexHome, endpoint: registered.address.endpoint,
+                        timeoutMs: 2000, signal: combined }, turnId);
+                    if (state === 'stale')
                         return;
-                    const pending = await ledger.pending(owner, { generation: captured.generation });
-                    const held = new Set((await ledger.handoffs(owner, { generation: captured.generation }))
-                        .filter(attempt => !['failed', 'released'].includes(attempt.outcome)).map(attempt => attempt.seq));
-                    for (const card of pending) {
-                        if (combined.aborted)
-                            break;
-                        if (held.has(card.seq))
-                            continue;
-                        // Follow the latest Stop, regardless of which Stop launched this process.
-                        const epoch = (await boundaries.read(input.session_id))?.stop;
-                        if (!epoch || !await codexIdleAtStop({ harness: 'codex', sessionId: input.session_id,
-                            codexHome: registered.address.codexHome, endpoint: registered.address.endpoint,
-                            timeoutMs: 2000, signal: combined }, epoch.turnId))
-                            break;
-                        lifetime.track(await ledger.dispatchHandoff(owner, card.key, new CodexQueueTransport({ epoch, env, address: registered.address }), { generation: captured.generation, timeoutMs: 5000, signal: combined }));
-                        // Drain our own claim/settlement edge. A known-unsent failure must
-                        // not turn file observation into an immediate retry loop. Any post
-                        // racing this read is still found by the bounded rescan below.
-                        version = await observer.read(combined);
+                    if (state === 'unavailable') {
+                        if (!combined.aborted)
+                            console.warn('Square Codex idle delivery unavailable: requires a reachable hosting app-server endpoint and supported native turn history. PostToolUse delivery remains available.');
+                        return;
+                    }
+                    if (state === 'idle') {
+                        const held = new Set((await ledger.handoffs(owner, { generation: captured.generation }))
+                            .filter(attempt => !['failed', 'released'].includes(attempt.outcome)).map(attempt => attempt.seq));
+                        const card = (await ledger.pending(owner, { generation: captured.generation })).find(card => !held.has(card.seq));
+                        if (card) {
+                            lifetime.track(await ledger.dispatchHandoff(owner, card.key, new CodexQueueTransport({ turnId, env, address: registered.address }), { generation: captured.generation, timeoutMs: 5000, signal: combined }));
+                            // One handoff attempt ends this wait, including unknown/refused
+                            // outcomes. Never replay or turn our own writes into a retry loop.
+                            return;
+                        }
                     }
-                    // No claims are held while waiting, including while active or disarmed.
                     await observer.changed(version, 1000, combined);
                 }
             }
             finally {
-                observer?.close();
-                await lifetime.close();
+                observer.close();
             }
         });
     }
@@ -95,6 +92,7 @@ export async function runCodexWatch(inputText, env = process.env, signal) {
         clearTimeout(timer);
         process.off('SIGTERM', stop);
         process.off('SIGINT', stop);
+        await lifetime?.close();
     }
     return '';
 }

package/dist/packages/agent-delivery/src/codex.d.ts

@@ -1,6 +1,10 @@
 import type { CodexAppServerConnectOptions, CodexDeliveryResult, CodexSendTextOptions, CodexTarget } from './types.js';
+/** A Stop can launch before its native turn has finished settling. Never
+ * mistake that short wait for authority to follow a different turn. */
+export type CodexStopState = 'idle' | 'waiting' | 'stale' | 'unavailable';
 /** Newest-last live history is verified for Codex 0.166.0 only. A sampled read
  * cannot make a later external queue atomic with native turn starts. */
+export declare function codexStopState(options: CodexAppServerConnectOptions, turnId: string): Promise<CodexStopState>;
 export declare function codexIdleAtStop(options: CodexAppServerConnectOptions, turnId: string): Promise<boolean>;
 /** Address an existing thread on an already running app-server. Never starts a
  * service, resumes a thread, or claims ownership of a standalone CLI session. */

package/dist/packages/agent-delivery/src/codex.js

@@ -253,37 +253,42 @@ function validatedConnection(options) {
 }
 /** Newest-last live history is verified for Codex 0.166.0 only. A sampled read
  * cannot make a later external queue atomic with native turn starts. */
-export async function codexIdleAtStop(options, turnId) {
+export async function codexStopState(options, turnId) {
     const connection = validatedConnection(options);
     if (!isIdentity(turnId))
-        return false;
+        return 'unavailable';
     const scope = deadline(options.timeoutMs, options.signal);
     let peer;
     try {
         peer = await open(connection, scope);
         const version = await peer.initialize(scope);
-        // The app-server's originator prefix belongs to the hosting client, which
-        // may have initialized before this connection. Fence the native version.
         if (!/^[A-Za-z0-9._-]+\/0\.166\.0(?:\s|$)/.test(version))
-            return false;
+            return 'unavailable';
         const thread = await readThread(peer, options.sessionId, scope, true);
-        if (!isRecord(thread.status) || thread.status.type !== 'idle' || !Array.isArray(thread.turns) || !thread.turns.length)
-            return false;
-        // Validate the whole live list, including absence of an active turn; never
-        // fall back to persisted pages or a boolean boundary for missing history.
-        if (activeTurn(thread.turns) !== undefined || new Set(thread.turns.map(turn => turn.id)).size !== thread.turns.length)
-            return false;
+        if (!isRecord(thread.status) || !['idle', 'active'].includes(thread.status.type)
+            || !Array.isArray(thread.turns) || !thread.turns.length)
+            return 'unavailable';
+        const active = activeTurn(thread.turns);
+        if (new Set(thread.turns.map(turn => turn.id)).size !== thread.turns.length)
+            return 'unavailable';
         const newest = thread.turns.at(-1);
-        return newest.id === turnId && newest.status === 'completed';
+        if (newest.id !== turnId || ['interrupted', 'failed'].includes(newest.status))
+            return 'stale';
+        if (active !== undefined && active !== turnId)
+            return 'unavailable';
+        return newest.status === 'completed' && active === undefined && thread.status.type === 'idle' ? 'idle' : 'waiting';
     }
     catch {
-        return false;
+        return 'unavailable';
     }
     finally {
         scope.close();
         await peer?.close();
     }
 }
+export async function codexIdleAtStop(options, turnId) {
+    return await codexStopState(options, turnId) === 'idle';
+}
 /** Address an existing thread on an already running app-server. Never starts a
  * service, resumes a thread, or claims ownership of a standalone CLI session. */
 export async function connectCodex(options) {

package/guides/claude-native.md

@@ -2,12 +2,12 @@
 
 The Square Claude plugin uses ordinary native command hooks. It has no mod, native inbox, or producer socket route. `SessionStart` attaches the exact native session to the host delivery ledger; `SessionEnd` fences and detaches that captured attachment without changing Square membership.
 
-At `UserPromptSubmit`, Square records Claude's native `prompt_id` before presenting pending cards through event-correct `additionalContext`. Tool boundaries (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`) use the same boundary presenter for the exact native main/child owner, so cards arriving during a running turn need not wait for another user prompt. Autonomous hook-generated prompts are boundaries too, not evidence of human approval. A later prompt records presentation only when its input contains the exact complete prepared frame, including the ledger token and stored full-frame hash. That establishes observation before the model processes the prompt, not comprehension. The async frame uses a plain warning and token delimiters; Square never decodes entities or accepts changed/truncated text as an exact observation.
+At `UserPromptSubmit`, Square records Claude's native `prompt_id` before presenting pending cards through event-correct `additionalContext`. `PostToolUse` is the single tool-boundary presenter for the exact native main/child owner, so cards arriving during a running turn can be delivered after a successful tool completes. `PreToolUse` and `PostToolUseFailure` match only Square MCP tools and handle identity publication/cleanup, not presentation. A failed ordinary tool leaves cards for the next PostToolUse, UserPromptSubmit or normal Stop. Autonomous hook-generated prompts are boundaries too, not evidence of human approval. A later prompt records presentation only when its input contains the exact complete prepared frame, including the ledger token and stored full-frame hash. That establishes observation before the model processes the prompt, not comprehension. The async frame uses a plain warning and token delimiters; Square never decodes entities or accepts changed/truncated text as an exact observation.
 
 At a normal `Stop`, one per-owner OS-locked observer waits for ledger changes for at most 86,400 seconds. It rechecks the exact captured `prompt_id`, attachment generation, Stop epoch and route after acquiring the lock and immediately before output. A new prompt disarms old observers. The watcher claims one card at a time and uses the existing handoff token/hash correlation. Invoked stderr output is `unknown` until that exact frame is observed at a later prompt boundary; there is no automatic fallback replay. Missing prompt IDs fail closed.
 
 This is a finite, boundary-driven observer, not a promise of continuous coverage. Missing Stop, timeout, process exit, headless teardown, or a busy Escape with no later normal Stop may leave cards pending. Idle Escape has no classic hook and may not disarm an already waiting observer; already emitted asyncRewake notifications cannot be recalled. No Square inbox fallback is retained for these cases.
 
-The bundled MCP server gets call-local session, cwd, and agent attribution from native `PreToolUse`/terminal tool hooks keyed by Claude's `claudecode/toolUseId` metadata. Duplicate or incomplete call identity is denied by the event-specific PreToolUse permission response; unrelated tool hooks do not block. Cleanup matches tool-use ID, session and agent. Interrupted calls without a terminal hook expire after ten minutes. Models cannot supply identity as tool arguments.
+The bundled MCP server gets call-local session, cwd, and agent attribution from native `PreToolUse`/terminal tool hooks keyed by Claude's `claudecode/toolUseId` metadata. The manifest scopes `PreToolUse` and `PostToolUseFailure` to `^mcp__plugin_square_square__.*`, while `PostToolUse` remains unfiltered for delivery and successful MCP cleanup. An ordinary successful tool therefore launches only PostToolUse, not both a pre- and post-tool command. Duplicate or incomplete call identity is denied by the event-specific PreToolUse permission response; unrelated tool hooks do not block. Cleanup matches tool-use ID, session and agent. Interrupted calls without a terminal hook expire after ten minutes. Models cannot supply identity as tool arguments.
 
 The installed and tested native runtime evidence is macOS Claude Code 2.1.299 with isolated HOME, plugin settings, delivery ledger and a dummy-key loopback provider. This does not certify other platforms, versions, or headless behavior. The final native prompt/generation check and async hook completion are not atomic. `node --import ./test/sandbox-env.js test/claude-hook-native.mjs` with `SQUARE_CLAUDE_HOOK_NATIVE_SMOKE=1` runs the shipped manifest and candidate CLI through a scratch PATH shim and preserves hook/provider evidence in `/tmp`. It proves repeated idle wake, prompt/attachment fencing, duplicate suppression, active prompt/tool context, native main/child MCP attribution and identity-failure denial.

package/guides/codex-delivery.md

@@ -1,67 +1,96 @@
 # Codex delivery
 
 Producers post neutral cards to DeliveryLedger; neither default dispatch nor public `postAndDispatch`
-queues Codex input. A native receiver owns both synchronous presentation and idle queue admission.
-It never reads Square artifacts or producer content stores.
-
-The shipped hooks for Codex 0.166.0 are synchronous SessionStart, UserPromptSubmit, PreToolUse,
-PostToolUse, Stop, Interrupt and SessionEnd, plus an async Stop command with `timeout: 86400` seconds.
-SessionStart disarms and attaches the exact native session. Active prompt/tool boundaries disarm and
-present eligible cards as event-correct `additionalContext`, using neutral reminder framing and the
-original card text. The output sink must accept the response before presentation evidence is recorded;
-a later suppression does not erase a real output effect. SessionEnd disarms and detaches. None of these
-host lifecycle events restores or detaches Square seats. SessionResume is not a verified native event
-and is not registered. A resume path without a real SessionStart/Stop has no inferred idle authority.
-
-Each synchronous Stop stores a unique token and native turn ID in the existing boundary store. One
-receiver-owned `square codex-watch` command holds a separate private OS-backed lock for its native
-session coordinate and observes the ledger, with a one-second bounded rescan for boundary changes or
-missed notifications. Duplicate async Stop processes exit; the existing watcher follows newer Stop
-tokens. The lock does not prove idle state. Observation never reserves cards while waiting.
-
-Before claiming each card, the watcher reads the hosting endpoint's `thread/read(includeTurns:true)`.
-It requires loaded idle state and the newest live turn to be completed with exactly the captured Stop
-turn ID. Newest-last history ordering is verified for 0.166.0; other versions fail closed until verified.
-After claiming, the receiver repeats that native read, checks the exact epoch again, then checks ledger
-currentness, suppression, cancellation, attachment generation, signal and deadline immediately before
-CLI invocation. Queue always uses the existing hosting endpoint explicitly, without starting a service.
-Missing, malformed, ephemeral, notLoaded, active, interrupted or unreadable history cannot authorize a
-queue. A delayed stale Stop cannot authorize sending merely by arriving after an active callback.
-
-`square codex-interrupt` handles only a native Interrupt payload and cancels the captured attachment's
-pending through-sequence batch, then future cards remain available after a later verified Stop or active
-boundary. Replacement attachments are fenced by generation. Before-effect epoch/suppression/cancel
-failures release their claims where the ledger permits. Attachment rotation already normalizes an
-in-flight ledger attempt to unknown: that custody remains unknown even if the final receiver check
-then proves no queue was launched. The watcher exits on detach, deletion or generation change and
-retains its ledger connection only for already-captured late settlements.
-
-Queue admission is custody, not presentation or model comprehension. Accepted/unknown outbox custody
-has no remaining card content and cannot be automatically replayed. Invoked timeout or ambiguous
-results remain unknown. Native idle reads and external queue are not atomic: a new turn can start after
-the final check and a raced queue may arrive later. Interrupt cannot recall input already admitted by
-Codex, and hook failure/timeout cannot prove that cancellation happened. Native callbacks have no
-cross-incarnation event identity; SessionEnd can fence only the attachment observed when it runs.
-
-There is no watcher before the first Stop. Synchronous boundaries can present; otherwise cards wait.
-The async budget is finite 24 hours, not a promise of 24-hour observation. After timeout, crash, host
-termination or missed spawn while idle, cards wait for the next Stop/user/native boundary. There is no
-producer fallback or autonomous crash-idle recovery. During attachment replacement an old watcher
-may briefly retain the coordinate lock while the new Stop's duplicate exits; the next Stop restores
-observation after the old process releases it.
-
-Reproduce the isolated native smoke from this checkout after a worktree-local build:
+queues Codex input. The receiver owns synchronous presentation and idle queue admission, without
+reading Square artifacts or producer content stores.
+
+## Five hooks
+
+The Codex 0.166.0 manifest registers one command for each of five events:
+
+- SessionStart attaches the exact native session and registers its queue address.
+- PostToolUse synchronously presents eligible cards as event-correct `additionalContext`.
+- Stop runs one async `square codex-watch` with a maximum timeout of 86,400 seconds.
+- Interrupt cancels the captured attachment's current pending through-sequence batch.
+- SessionEnd detaches the captured attachment.
+
+There is no synchronous Stop command, UserPromptSubmit hook, or PreToolUse hook. Active delivery
+occurs after a tool finishes; a model-only turn with no tools receives pending cards after its next
+Stop through the queue path. Host lifecycle never restores or detaches Square seats.
+
+PostToolUse records presentation only after its output sink accepts the response. A later suppression
+does not erase that output effect. This is observer-level evidence, not proof of model comprehension.
+
+## One Stop, one wait
+
+Each async Stop captures its payload's native turn ID, ledger attachment generation and queue address.
+A private OS-backed lock for that coordinate, generation and turn deduplicates overlapping callbacks.
+A different Stop or replacement attachment does not wait for the old watcher's lock. The watcher
+never adopts a newer Stop and never starts its own successor; Codex starts the next watcher when the
+next turn stops.
+
+On every reconciliation, even with no pending cards, the watcher reads the hosting endpoint's
+`thread/read(includeTurns:true)`. Only a loaded idle thread whose newest completed turn exactly
+matches the captured ID may authorize queueing. The same turn still settling may wait; a newer,
+interrupted or failed turn retires the watcher. Unreadable, malformed, notLoaded or unsupported history
+ends idle observation with a bounded diagnostic. Newest-last history is verified for 0.166.0 only.
+There is no second persisted root Stop-authority store for delayed callbacks to overwrite.
+
+The watcher subscribes before reading the ledger, uses a one-second bounded rescan, and holds no
+card claims while waiting. On an eligible card it claims once, repeats the native idle check, and
+checks ledger currentness, suppression, cancellation, attachment generation, signal and deadline
+immediately before queue invocation. It then ends observation after that handoff attempt, whether
+accepted, unknown or definitely unsent. A refusal is not retried in the same wait. Failed/released
+cards remain available to PostToolUse or a future Stop; accepted/unknown custody cannot be replayed.
+The original ledger connection is retained only for already-invoked late settlements.
+
+The lock deduplicates overlapping Stop callbacks, not all sequential duplicates forever. Ledger
+custody excludes replay of the same card; it is not a persistent one-send-per-turn budget for different
+cards. A duplicate callback arriving after the first watcher exits could submit another card before
+native history reflects the queued turn.
+
+## Transport and cancellation limits
+
+Idle queueing requires an externally reachable endpoint for the app-server already hosting the
+thread: `SQUARE_CODEX_ENDPOINT`, or the control socket under that receiver's `CODEX_HOME`. Queue uses
+that endpoint explicitly and never starts a replacement service. A private stdio-only app-server
+without a control endpoint cannot be reached by a new process. In that case the async watcher exits;
+PostToolUse still presents cards through the native hook without any app-server connection.
+A completed async hook's own output does not wake an idle Codex turn.
+
+Queue admission is custody, not presentation. Accepted/unknown outbox custody has no remaining card
+content. Invoked timeout or ambiguous results remain unknown; never automatically replay them.
+Native reads and external queue are not atomic: a user turn or interruption can race after the final
+check, and admitted input cannot be recalled.
+
+Interrupt cancellation suppresses the captured attachment's pending batch, not future cards. A native
+interrupted turn retires its watcher; future cards can be received at PostToolUse or a later Stop.
+The native smoke exercises active `turn/interrupt`, not physical TUI Escape or idle cancellation paths.
+Hook payloads do not provide a cross-incarnation event identity: generation capture protects against
+replacement after capture, not a callback that was already stale when it began. In particular, a late
+Interrupt can still cancel a newer batch in the same attachment. SessionEnd has the same observation-
+time capture limitation.
+
+Observation is finite. Before the first Stop, after timeout/crash/missed spawn, or after an unsent
+handoff failure, cards wait for PostToolUse or a subsequent Stop. There is no detached helper,
+producer fallback or autonomous crash-idle recovery.
+
+## Native evidence
+
+Reproduce the isolated native smoke after a worktree-local build:
 
 ```sh
 env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
   node --import ./test/sandbox-env.js test/codex-watch-native.mjs
 ```
 
-The probe creates a temporary HOME/CODEX_HOME, installs no plugin, and uses the actual shipped hook
-manifest/CLI with an isolated native app-server and loopback fixture provider. Its JSON evidence names
-the temporary directory. It verifies native Stop startup, idle wake, busy fencing, singleton reuse,
-Interrupt RPC cancellation, real UserPromptSubmit presentation and process-group shutdown. Physical
-TUI Escape-to-Interrupt is not verified; neither are 24-hour operation or every resume path.
+The probe uses a temporary HOME/CODEX_HOME, actual shipped hooks/CLI, an isolated native app-server
+with an explicit Unix endpoint, and a loopback fixture provider. Its JSON evidence names the temporary
+directory. It verifies Stop startup, one-shot idle wake and exit, fresh watchers for new Stops, busy
+fencing with no pending cards, Interrupt RPC cancellation, future delivery, real PostToolUse context
+and receipts, and termination of a still-waiting watcher at host shutdown.
+It does not certify stdio-only idle wake, physical TUI Escape, 24-hour lifetime or every resume path.
 
-The shared package documents its transport leaves in [its README](../packages/agent-delivery/README.md).
-See [participant ownership](participant-ownership.md) for host attachment and Square membership.
+The shared package's separate public boundary/transport helpers remain documented in
+[its README](../packages/agent-delivery/README.md). See [participant ownership](participant-ownership.md)
+for host attachment and Square membership.

package/guides/delivery-primitives.md

@@ -43,6 +43,7 @@ idle connection until process exit. Late persistence failures produce redacted d
 reopening the ledger or retrying the effect. Pi presentation and Claude's independent exact-reference
 confirmation callbacks retain their existing lifetimes.
 
-Codex producers only post. Its native async Stop receiver observes the ledger without holding claims
-while waiting; active UserPromptSubmit, PreToolUse and PostToolUse boundaries present synchronously.
-See [Codex delivery](codex-delivery.md) for exact idle-epoch fencing, cancellation and recovery limits.
+Codex producers only post. Each native async Stop receiver waits without holding claims, attempts one
+idle queue handoff, then exits; PostToolUse presents synchronously during execution. Idle queueing
+requires a reachable hosting app-server endpoint, not private stdio alone. See
+[Codex delivery](codex-delivery.md) for native turn fencing, cancellation and recovery limits.

package/package.json

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

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

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

package/plugins/claude/hooks/hooks.json

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

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

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

package/plugins/codex/hooks/hooks.json

@@ -6,20 +6,11 @@
     "SessionEnd": [
       { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3, "statusMessage": "Square" }] }
     ],
-    "UserPromptSubmit": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
-    ],
-    "PreToolUse": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
-    ],
     "PostToolUse": [
       { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "Stop": [
-      { "hooks": [
-        { "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" },
-        { "type": "command", "command": "square codex-watch", "timeout": 86400, "async": true, "statusMessage": "Square" }
-      ] }
+      { "hooks": [{ "type": "command", "command": "square codex-watch", "timeout": 86400, "async": true, "statusMessage": "Square" }] }
     ],
     "Interrupt": [
       { "hooks": [{ "type": "command", "command": "square codex-interrupt", "timeout": 3, "statusMessage": "Square" }] }

package/dist/codex-boundary-state.d.ts

@@ -1,2 +0,0 @@
-export type { CodexBoundary, CodexStopEpoch } from './packages/agent-delivery/src/codex-boundary.js';
-export declare function codexBoundaryStore(env?: NodeJS.ProcessEnv): import("./packages/agent-delivery/src/codex-boundary.js").CodexBoundaryStore;

package/dist/codex-boundary-state.js

@@ -1,6 +0,0 @@
-import os from 'node:os';
-import path from 'node:path';
-import { createCodexBoundaryStore } from './packages/agent-delivery/src/codex-boundary.js';
-export function codexBoundaryStore(env = process.env) {
-    return createCodexBoundaryStore(env.SQUARE_CODEX_BOUNDARIES || path.join(os.homedir(), '.square', 'codex-boundaries.json'));
-}