@astrosheep/square 0.4.0 → 0.4.2

package/dist/notifications.js

@@ -1,117 +1,48 @@
-import { createDefaultWakeTransport } from './wake-transports.js';
-export { createDefaultWakeTransport, createWakeTransport } from './wake-transports.js';
-import { squareWakeProjection } from './wake-preview.js';
-import path from 'node:path';
-import { canonicalPath } from './canonical-path.js';
-import fs from 'node:fs';
-import { indexedSquareEntries } from './square-index.js';
-import { InternalSquareError, SquareError } from './model.js';
-import { channelArtifact, createArtifactPort } from './artifact.js';
-import { deliverPending, sweepPending } from './delivery-operations.js';
-import { formatMessageId } from './message.js';
-export const PRIVILEGED_HOOK_BUDGET_MS = 3000;
-export function wakeGraceMs(env = process.env) {
-    const value = Number.parseInt(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? '5000', 10);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new SquareError('invalid_args', 'Invalid SQUARE_NOTIFY_DELIVERY_WAIT_MS: expected a positive integer.');
-    }
-    return value;
+import { createDefaultDeliveryTransports } from './wake-transports.js';
+export { createDefaultDeliveryTransports } from './wake-transports.js';
+/** Best-effort dispatch for currently eligible cards, including cards restored by release. */
+export async function dispatchEligibleCards(ledger, owner, options = {}) {
+    const session = await ledger.session(owner);
+    if (!session || session.state !== 'attached' || options.signal?.aborted)
+        return;
+    const pending = await ledger.pending(owner, { generation: session.generation });
+    for (const card of pending)
+        await dispatchPostedCard(ledger, owner, card.key, options.track ?? (() => undefined), options.env, options.signal, options.transports);
 }
-export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
-    const env = opts.env ?? process.env;
-    const now = opts.now ?? Date.now;
-    squarePath = await canonicalPath(squarePath);
-    const artifact = createArtifactPort(squarePath);
-    try {
-        await artifact.read(facts => facts.header());
-        const transport = await createDefaultWakeTransport(env, opts.transports);
+/** Post, then best-effort dispatch without consulting producer storage. */
+export async function postAndDispatch(ledger, input, options = {}) {
+    const result = await ledger.post(input);
+    if (result.status === 'posted' || result.status === 'duplicate') {
         try {
-            const message = (await artifact.read(facts => { const activity = facts.activity(actIndex); return activity?.kind === 'say' ? activity.messageIndex : undefined; })).value;
-            if (message === undefined)
-                return;
-            await deliverPending({ artifact: channelArtifact(artifact), preparePresentation: squareWakeProjection(artifact), transport, location: squarePath, message: formatMessageId(message), timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
+            await dispatchEligibleCards(ledger, input.owner, options);
         }
-        catch { /* Delivery failure does not undo the activity. */ }
-    }
-    catch (error) {
-        if (error instanceof InternalSquareError && error.code === 'not_found')
-            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
-        throw error;
-    }
-    finally {
-        await artifact.close();
+        catch { /* Posting is already committed. */ }
     }
+    return result;
 }
-/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
-export async function sweepPrivilegedPending(cwd, env = process.env, suppliedTransports, deadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS, signal) {
-    const remainingMs = () => Math.max(0, deadline - Date.now());
-    if (remainingMs() === 0 || signal?.aborted)
+/** Best-effort dispatch after a card has been posted; never inspect producer storage. */
+export async function dispatchPostedCard(ledger, owner, key, track, env = process.env, signal, suppliedTransports) {
+    if (signal?.aborted)
         return;
-    const indexed = await indexedSquareEntries({}, env).catch(() => []);
-    const paths = new Set(indexed.map((binding) => binding.location));
-    try {
-        for (const entry of await fs.promises.readdir(path.join(cwd, '.square'))) {
-            if (entry.endsWith('.square'))
-                paths.add(path.join(cwd, '.square', entry));
-        }
-    }
-    catch { /* no local square directory */ }
-    if (remainingMs() === 0 || signal?.aborted)
+    const session = await ledger.session(owner);
+    if (!session || session.state !== 'attached')
         return;
-    const transport = await createDefaultWakeTransport(env, suppliedTransports);
-    for (const candidate of paths) {
-        if (remainingMs() === 0 || signal?.aborted)
-            break;
-        try {
-            const squarePath = await canonicalPath(candidate);
-            const artifact = createArtifactPort(squarePath, undefined, signal);
-            try {
-                await artifact.read(facts => facts.header(), signal);
-                if (remainingMs() === 0 || signal?.aborted)
-                    break;
-                const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
-                const graceMs = 0;
-                const selected = await sweepPending({ artifact: channelArtifact(artifact), location: squarePath, now: Date.now(), graceMs, limit: Number.isFinite(limit) && limit > 0 ? limit : 8 }).catch(() => []);
-                for (const messageIndex of selected) {
-                    const remaining = remainingMs();
-                    if (remaining === 0 || signal?.aborted)
-                        break;
-                    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
-                    const timeoutMs = Math.max(1, Math.min(Number.isFinite(configured) && configured > 0 ? configured : 5000, remaining));
-                    await deliverPending({ artifact: channelArtifact(artifact), preparePresentation: squareWakeProjection(artifact), transport, location: squarePath, message: formatMessageId(messageIndex), timeoutMs, now: Date.now() }).catch(() => undefined);
-                }
-            }
-            finally {
-                await artifact.close();
-            }
-        }
-        catch { /* stale index entries are ignored by the hook */ }
-    }
-}
-/** Select old pending attention at a bounded action boundary for an explicit executor. */
-export async function sweepPendingNotifications(squarePath, opts = {}) {
-    const env = opts.env ?? process.env;
-    if (env.SQUARE_DISABLE_PASEO_WAKE === '1')
-        return [];
-    const now = opts.now ?? Date.now();
-    const limit = opts.limit ?? 8;
-    const artifact = createArtifactPort(squarePath);
-    let selected;
-    try {
-        await artifact.read(facts => facts.header());
-        selected = await sweepPending({ artifact: channelArtifact(artifact), location: squarePath, now, graceMs: wakeGraceMs(env), limit });
-    }
-    catch (error) {
-        if (error instanceof InternalSquareError && error.code === 'not_found')
-            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
-        throw error;
-    }
-    finally {
-        await artifact.close();
-    }
-    if (opts.dispatchCandidate !== undefined) {
-        for (const messageIndex of selected)
-            await opts.dispatchCandidate(messageIndex);
+    const transports = suppliedTransports ?? await createDefaultDeliveryTransports(env);
+    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
+    const timeoutMs = Number.isSafeInteger(configured) && configured > 0 ? configured : 5000;
+    for (const route of session.routes) {
+        // Claude and Codex custody belongs to their native receivers, including for
+        // callers that supply transports explicitly to the producer API.
+        if (['codex-queue', 'claude-async-hook', 'claude-native'].includes(route.kind))
+            continue;
+        if (signal?.aborted)
+            return;
+        const transport = transports.find(candidate => candidate.kind === route.kind);
+        if (!transport)
+            continue;
+        const result = await ledger.dispatchHandoff(owner, key, transport, { generation: session.generation, timeoutMs, signal });
+        track(result);
+        if (result.outcome === 'accepted' || result.outcome === 'presented' || result.outcome === 'unknown')
+            return;
     }
-    return selected;
 }

package/dist/operation-control.d.ts

@@ -0,0 +1,4 @@
+import type { OperationControl, OperationFailureDetail } from './neutral.js';
+export declare function checkControl(control?: OperationControl): void;
+export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
+export declare function failure(error: unknown, detail: OperationFailureDetail): Error;

package/dist/operation-control.js

@@ -0,0 +1,20 @@
+import { SquareError } from './neutral.js';
+export function checkControl(control) {
+    if (control?.signal?.aborted)
+        throw control.signal.reason ?? new Error('Square operation was cancelled');
+}
+export function squareClock(env, clock) {
+    if (clock !== undefined)
+        return clock;
+    if (env.SQUARE_NOW_MS === undefined)
+        return Date.now;
+    const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
+    if (!Number.isFinite(value))
+        throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
+    return () => value;
+}
+export function failure(error, detail) {
+    const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
+    Object.assign(normalized, { operation: detail });
+    return normalized;
+}

package/dist/packages/agent-delivery/src/claude-native.d.ts

@@ -11,6 +11,8 @@ export interface ClaudeNativeTarget {
 export interface ClaudeNativeControl {
     readonly deadline: number;
     readonly signal?: AbortSignal;
+    /** Final asynchronous eligibility check after connecting, before writing bytes. */
+    readonly beforeSend?: () => Promise<boolean>;
 }
 export type NativeWriteResult = {
     readonly outcome: 'written';

package/dist/packages/agent-delivery/src/claude-native.js

@@ -43,6 +43,11 @@ export async function writeClaudeNative(target, text, control) {
             throw new LocalEndpointError('timeout');
         socket = await connectLocal(endpoint, { signal: scope.signal });
         scope.check();
+        if (Date.now() >= control.deadline)
+            throw new LocalEndpointError('timeout');
+        if (control.beforeSend && !await scope.wait(control.beforeSend()))
+            return { outcome: 'unavailable', code: 'aborted', message: 'Native inbox write suppressed.' };
+        scope.check();
         if (Date.now() >= control.deadline)
             throw new LocalEndpointError('timeout');
         // A receiver that never drains must not hold the caller past its deadline.

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

@@ -1,13 +1,18 @@
+export interface CodexStopEpoch {
+    readonly token: string;
+    readonly turnId: string;
+}
 export interface CodexBoundary {
-    readonly lastStop: number;
-    readonly lastNonStop: number;
+    readonly stop?: CodexStopEpoch;
     readonly ended?: true;
 }
 export interface CodexBoundaryStore {
     read(sessionId: string): Promise<CodexBoundary | undefined>;
-    queueEligible(sessionId: string): Promise<boolean>;
-    record(sessionId: string, event: 'Stop' | 'non-stop' | 'start' | 'end', signal?: AbortSignal): Promise<void>;
-    clear(sessionId: string, signal?: AbortSignal): Promise<void>;
+    queueEligible(sessionId: string, epoch?: CodexStopEpoch): Promise<boolean>;
+    record(sessionId: string, event: 'Stop' | 'non-stop' | 'start' | 'end', options?: {
+        readonly signal?: AbortSignal;
+        readonly turnId?: string;
+    }): Promise<void>;
 }
-/** Caller-owned observation file, shared by independent hook and sender processes. */
+/** Receiver-owned idle authority. Old or unverifiable records never arm a send. */
 export declare function createCodexBoundaryStore(file: string): CodexBoundaryStore;

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

@@ -1,8 +1,9 @@
 import { promises as fs } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { withFileLock } from './file-lock.js';
-const empty = () => ({ v: 1, nextSequence: 0, threads: Object.create(null) });
-/** Caller-owned observation file, shared by independent hook and sender processes. */
+const empty = () => ({ v: 2, threads: Object.create(null) });
+const identity = (value) => typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+/** Receiver-owned idle authority. Old or unverifiable records never arm a send. */
 export function createCodexBoundaryStore(file) {
     const load = async () => {
         let raw;
@@ -16,16 +17,14 @@ export function createCodexBoundaryStore(file) {
         }
         try {
             const value = JSON.parse(raw);
-            if (value?.v !== 1 || !Number.isSafeInteger(value.nextSequence) || value.nextSequence < 0 ||
-                !value.threads || typeof value.threads !== 'object')
+            if (value?.v !== 2 || !value.threads || typeof value.threads !== 'object' || Array.isArray(value.threads))
                 return empty();
             const result = empty();
-            result.nextSequence = value.nextSequence;
-            for (const [id, boundary] of Object.entries(value.threads)) {
-                const item = boundary;
-                if (item && Number.isSafeInteger(item.lastStop) && item.lastStop >= 0 &&
-                    Number.isSafeInteger(item.lastNonStop) && item.lastNonStop >= 0)
-                    result.threads[id] = item;
+            for (const [id, item] of Object.entries(value.threads)) {
+                if (!item || typeof item !== 'object')
+                    continue;
+                result.threads[id] = item.ended === true ? { ended: true }
+                    : identity(item.stop?.token) && identity(item.stop?.turnId) ? { stop: { token: item.stop.token, turnId: item.stop.turnId } } : {};
             }
             return result;
         }
@@ -33,43 +32,35 @@ export function createCodexBoundaryStore(file) {
             return empty();
         }
     };
-    const update = (change, signal) => withFileLock(`${file}.lock`, { retryMs: 10, signal }, async () => {
-        const state = await load();
-        change(state);
-        signal?.throwIfAborted();
-        const temporary = `${file}.${randomUUID()}.tmp`;
-        try {
-            await fs.writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
-            await fs.rename(temporary, file);
-        }
-        finally {
-            await fs.unlink(temporary).catch(() => { });
-        }
-    });
     const read = async (id) => id ? (await load()).threads[id] : undefined;
     return {
         read,
-        async queueEligible(id) {
+        async queueEligible(id, epoch) {
             const boundary = await read(id);
-            return boundary !== undefined && boundary.ended !== true && boundary.lastStop > boundary.lastNonStop;
+            return boundary?.ended !== true && boundary?.stop !== undefined &&
+                (epoch === undefined || boundary.stop.token === epoch.token && boundary.stop.turnId === epoch.turnId);
         },
-        async record(id, event, signal) {
-            if (!id)
+        async record(id, event, options = {}) {
+            if (!identity(id))
                 return;
-            await update((state) => {
-                const previous = state.threads[id] ?? { lastStop: 0, lastNonStop: 0 };
-                // A late Stop/tool callback must not reopen an ended session.
-                if (previous.ended && event !== 'start')
+            await withFileLock(`${file}.lock`, { retryMs: 10, signal: options.signal }, async () => {
+                const state = await load();
+                // A late callback cannot reopen an ended native session.
+                if (state.threads[id]?.ended && event !== 'start')
                     return;
-                state.nextSequence += 1;
-                state.threads[id] = event === 'start'
-                    ? { lastStop: 0, lastNonStop: state.nextSequence }
-                    : event === 'end' ? { ...previous, lastNonStop: state.nextSequence, ended: true }
-                        : event === 'Stop' ? { ...previous, lastStop: state.nextSequence }
-                            : { ...previous, lastNonStop: state.nextSequence };
-            }, signal);
+                state.threads[id] = event === 'end' ? { ended: true }
+                    : event === 'Stop' && identity(options.turnId) ? { stop: { token: randomUUID(), turnId: options.turnId } } : {};
+                options.signal?.throwIfAborted();
+                const temporary = `${file}.${randomUUID()}.tmp`;
+                try {
+                    await fs.writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
+                    options.signal?.throwIfAborted();
+                    await fs.rename(temporary, file);
+                }
+                finally {
+                    await fs.unlink(temporary).catch(() => { });
+                }
+            });
         },
-        async clear(id, signal) { if (id)
-            await update((state) => { delete state.threads[id]; }, signal); },
     };
 }

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

@@ -1,26 +1,31 @@
 import type { CodexBoundaryStore } from './codex-boundary.js';
 export { createCodexBoundaryStore } from './codex-boundary.js';
-export type { CodexBoundary, CodexBoundaryStore } from './codex-boundary.js';
+export type { CodexBoundary, CodexBoundaryStore, CodexStopEpoch } from './codex-boundary.js';
+export { codexIdleAtStop } from './codex.js';
+export type CodexActiveEvent = 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse';
+export type CodexHookEvent = CodexActiveEvent | 'SessionStart' | 'SessionEnd' | 'Stop' | 'Interrupt';
+export interface CodexHookInput {
+    readonly session_id: string;
+    readonly hook_event_name: CodexHookEvent;
+    readonly turn_id?: string;
+}
 export interface CodexHookResponse {
     readonly hookSpecificOutput: {
-        readonly hookEventName: 'PostToolUse';
+        readonly hookEventName: CodexActiveEvent;
         readonly additionalContext: string;
     };
 }
 export interface CodexHookOptions {
     readonly boundaries: CodexBoundaryStore;
-    /** The host owns pending text, claims and cancellation. Honor signal before presenting;
-     * if cancelled before an effect, release custody and resolve undefined or reject.
-     * After presenting, finish any cancellation-independent settlement and return its text,
-     * even if signal aborts meanwhile. This callback is awaited, never raced or abandoned. */
-    readonly pull?: (sessionId: string, signal: AbortSignal) => Promise<string | undefined>;
-    /** Dispatch the host's pending work; Stop merely makes queue eligible. */
-    readonly sweep?: (cwd: string | undefined, deadline: number, signal: AbortSignal) => Promise<void>;
+    /** The host owns claims and cancellation. After an external effect, finish its
+     * cancellation-independent settlement and retain the output. Never abandon it. */
+    readonly pull?: (sessionId: string, signal: AbortSignal, event: CodexActiveEvent) => Promise<string | undefined>;
     readonly end?: (sessionId: string, signal: AbortSignal) => Promise<void>;
+    readonly interrupt?: (sessionId: string, signal: AbortSignal) => Promise<void>;
     readonly trace?: (stage: string, detail?: string) => void;
     readonly timeoutMs?: number;
-    readonly sweepTimeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-/** Stateless hook protocol. No message source, session identity or service is invented here. */
-export declare function handleCodexHook(input: unknown, options: CodexHookOptions): Promise<CodexHookResponse | undefined>;
+export declare function parseCodexHook(input: unknown): CodexHookInput | undefined;
+/** Native synchronous boundaries; Stop only records authority for its async receiver. */
+export declare function handleCodexHook(value: unknown, options: CodexHookOptions): Promise<CodexHookResponse | undefined>;

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

@@ -1,57 +1,44 @@
 import { deadline, validSignal, validTimeout } from './deadline.js';
 import { isRecord } from './guards.js';
 export { createCodexBoundaryStore } from './codex-boundary.js';
-/** Stateless hook protocol. No message source, session identity or service is invented here. */
-export async function handleCodexHook(input, options) {
-    if (!isRecord(input) || typeof input.session_id !== 'string' || !input.session_id.trim())
+export { codexIdleAtStop } from './codex.js';
+export function parseCodexHook(input) {
+    const identity = (value) => typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+    if (!isRecord(input) || !identity(input.session_id) ||
+        !['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'SessionEnd', 'Stop', 'Interrupt'].includes(input.hook_event_name) ||
+        (['Stop', 'Interrupt'].includes(input.hook_event_name) && !identity(input.turn_id)))
         return;
-    const event = input.hook_event_name;
-    if (!['SessionStart', 'SessionResume', 'UserPromptSubmit', 'SessionEnd', 'PostToolUse', 'Stop'].includes(event))
+    return input;
+}
+/** Native synchronous boundaries; Stop only records authority for its async receiver. */
+export async function handleCodexHook(value, options) {
+    const input = parseCodexHook(value);
+    if (!input)
         return;
-    if (!validTimeout(options.timeoutMs) || !validTimeout(options.sweepTimeoutMs) || !validSignal(options.signal)) {
+    if (!validTimeout(options.timeoutMs) || !validSignal(options.signal))
         throw new TypeError('Invalid hook control.');
-    }
     const scope = deadline(options.timeoutMs ?? 4500, options.signal);
-    const sweepDeadline = Date.now() + Math.min(options.sweepTimeoutMs ?? 3000, options.timeoutMs ?? 4500);
-    const id = input.session_id;
+    const event = input.hook_event_name, id = input.session_id;
     try {
         scope.check();
-        if (event === 'SessionEnd') {
-            await scope.wait(options.boundaries.record(id, 'end', scope.signal));
-            await scope.wait(options.end?.(id, scope.signal) ?? Promise.resolve()).catch(() => { });
-            return;
-        }
-        await scope.wait(options.boundaries.record(id, event === 'SessionStart' || event === 'SessionResume' ? 'start' : event === 'Stop' ? 'Stop' : 'non-stop', scope.signal));
+        await scope.wait(options.boundaries.record(id, event === 'SessionStart' ? 'start' : event === 'SessionEnd' ? 'end' : event === 'Stop' ? 'Stop' : 'non-stop', { signal: scope.signal, turnId: input.turn_id }));
         options.trace?.('boundary-record');
-        if (event !== 'Stop' && event !== 'PostToolUse')
+        if (event === 'SessionEnd' || event === 'Interrupt') {
+            await (event === 'SessionEnd' ? options.end : options.interrupt)?.(id, scope.signal);
             return;
-        let context;
-        if (event === 'PostToolUse') {
-            try {
-                // A host's successful presentation settlement may outlive this signal. Retain
-                // its output instead of leaving background work to consume it without a response.
-                context = await options.pull?.(id, scope.signal);
-                options.trace?.('presentation');
-            }
-            catch (error) {
-                options.trace?.('presentation', `error=${error instanceof Error ? error.name : 'Error'}`);
-            }
         }
-        if (!scope.signal.aborted && Date.now() < sweepDeadline) {
-            await scope.wait(options.sweep?.(typeof input.cwd === 'string' ? input.cwd : undefined, sweepDeadline, scope.signal) ?? Promise.resolve()).catch(() => { });
+        if (event !== 'UserPromptSubmit' && event !== 'PreToolUse' && event !== 'PostToolUse')
+            return;
+        try {
+            const context = await options.pull?.(id, scope.signal, event);
+            options.trace?.('presentation');
+            if (context !== undefined)
+                return { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
         }
-        options.trace?.('sweep', scope.signal.aborted ? 'aborted=true' : '');
-        // A successful pull may already have committed host presentation evidence.
-        // A later, unrelated sweep timeout must not discard its completed output.
-        if (context !== undefined) {
-            return { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } };
+        catch (error) {
+            options.trace?.('presentation', `error=${error instanceof Error ? error.name : 'Error'}`);
         }
     }
-    catch (error) {
-        if (scope.signal.aborted)
-            throw scope.signal.reason;
-        throw error;
-    }
     finally {
         scope.close();
     }

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

@@ -1,4 +1,7 @@
 import type { CodexAppServerConnectOptions, CodexDeliveryResult, CodexSendTextOptions, CodexTarget } from './types.js';
+/** 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 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. */
 export declare function connectCodex(options: CodexAppServerConnectOptions): Promise<CodexTarget>;

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

@@ -143,6 +143,7 @@ class Peer {
             throw new Fault('invalid_response');
         scope.check();
         this.socket.send(JSON.stringify({ method: 'initialized' }));
+        return result.userAgent;
     }
     call(method, params, scope, dispatch) {
         scope.check();
@@ -239,9 +240,7 @@ async function discoverTurn(peer, metadata, sessionId, scope) {
         cursors.add(cursor);
     }
 }
-/** 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) {
+function validatedConnection(options) {
     if (!isRecord(options) || options.harness !== 'codex' ||
         (options.transport !== undefined && options.transport !== 'app-server') || !isIdentity(options.sessionId) ||
         !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
@@ -250,7 +249,45 @@ export async function connectCodex(options) {
         (options.token !== undefined && (!isIdentity(options.token) || /[\r\n]/.test(options.token)))) {
         throw new ConnectionError('invalid_arguments');
     }
-    const connection = resolveConnection(options);
+    return resolveConnection(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) {
+    const connection = validatedConnection(options);
+    if (!isIdentity(turnId))
+        return false;
+    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;
+        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;
+        const newest = thread.turns.at(-1);
+        return newest.id === turnId && newest.status === 'completed';
+    }
+    catch {
+        return false;
+    }
+    finally {
+        scope.close();
+        await peer?.close();
+    }
+}
+/** 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) {
+    const connection = validatedConnection(options);
     const scope = deadline(options.timeoutMs, options.signal);
     let peer;
     try {

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

@@ -30,7 +30,9 @@ export type PiAgent = Steerable & Queueable & {
     readonly harness: 'pi';
     readonly sessionId: string;
 };
-export type PaseoAgent = Steerable<KeyedSendOptions> & {
+export type PaseoAgent = Steerable<KeyedSendOptions & {
+    readonly beforeSend?: () => Promise<boolean>;
+}> & {
     readonly harness: 'paseo';
     readonly agentId: string;
 };

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

@@ -110,7 +110,7 @@ export async function connect(options) {
             throw new DeliveryError('invalid_arguments');
         try {
             const result = await opened.send(text, spec.keyed
-                ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal }
+                ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal, ...(spec.harness === 'paseo' ? { beforeSend: options.beforeSend } : {}) }
                 : { delivery, timeoutMs: options.timeoutMs, signal: options.signal });
             if (result.state !== spec.accepted)
                 throw failure(result, 'send', id);

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

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { deadline, validSignal, validTimeout } from './deadline.js';
+import { deadline, DEFAULT_TIMEOUT_MS, validSignal, validTimeout } from './deadline.js';
 import { ConnectionError } from './errors.js';
 import { isIdentity, isRecord } from './guards.js';
 import { daemonCredential, openPaseoClient, paseoHome, resolvePaseoDaemon, } from './paseo-native.js';
@@ -59,26 +59,35 @@ export async function sendPaseoText(target, text, options = {}) {
     if (connection === undefined || typeof text !== 'string' || text.length === 0 ||
         !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
         (options.inputId !== undefined && !isIdentity(options.inputId)) ||
+        (options.beforeSend !== undefined && typeof options.beforeSend !== 'function') ||
         (options.delivery !== undefined && options.delivery !== 'steer')) {
         throw new TypeError('Invalid sendText arguments.');
     }
     const inputId = options.inputId ?? randomUUID();
     const attempt = { harness: 'paseo', agentId: target.agentId, inputId };
     const scope = deadline(options.timeoutMs, options.signal);
+    const until = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const client = await openPaseoClient(connection.target, connection.credential, options.timeoutMs);
     // The connection is the uncertainty boundary: before it, nothing was written.
     let connected = false;
+    let sent = false;
     try {
         scope.check();
         await scope.wait(client.connect());
         connected = true;
         scope.check();
+        if (options.beforeSend && !await scope.wait(options.beforeSend()))
+            return { ...attempt, state: 'unavailable', code: 'aborted' };
+        scope.check();
+        if (Date.now() >= until)
+            return { ...attempt, state: 'unavailable', code: 'timeout' };
+        sent = true;
         await scope.wait(client.sendAgentMessage(target.agentId, text, { messageId: inputId, activeTurnBehavior: 'steer' }));
         return { ...attempt, state: 'admitted' };
     }
     catch (error) {
         if (scope.code !== undefined) {
-            return { ...attempt, state: connected ? 'unknown' : 'unavailable', code: scope.code };
+            return { ...attempt, state: sent ? 'unknown' : 'unavailable', code: scope.code };
         }
         if (error instanceof Error && error.name === 'DaemonAuthenticationError') {
             return { ...attempt, state: 'unavailable', code: 'authentication_failed' };

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

@@ -50,6 +50,7 @@ export interface PaseoSendTextOptions {
     readonly inputId?: string;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
+    readonly beforeSend?: () => Promise<boolean>;
 }
 export interface CodexSendTextOptions {
     readonly delivery?: Delivery;