@astrosheep/square 0.3.90 → 0.3.92

package/dist/packages/agent-delivery/src/file-lock.js

@@ -0,0 +1,64 @@
+import { DatabaseSync } from 'node:sqlite';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+export class FileLockError extends Error {
+    code = 'not_a_database';
+    constructor(lockPath, cause) {
+        super(`File lock is not a database: ${lockPath}`);
+        this.name = 'FileLockError';
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+function isBusy(error) {
+    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
+}
+function isNotADatabase(error) {
+    return error instanceof Error && /not a database|file is not a database/i.test(error.message);
+}
+export async function withFileLock(lockPath, options, fn) {
+    if (options.createParent !== false)
+        await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    while (true) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error('File lock acquisition aborted');
+        let database;
+        try {
+            database = new DatabaseSync(lockPath);
+            database.exec(`PRAGMA busy_timeout = 0;
+        BEGIN EXCLUSIVE;
+        CREATE TABLE IF NOT EXISTS __agent_delivery_lock (id INTEGER PRIMARY KEY CHECK (id = 1));`);
+        }
+        catch (error) {
+            try {
+                database?.close();
+            }
+            catch { }
+            if (isBusy(error)) {
+                if (options.skipIfBusy)
+                    return undefined;
+                await sleep(options.retryMs, undefined, { signal: options.signal });
+                continue;
+            }
+            if (isNotADatabase(error))
+                throw new FileLockError(lockPath, error);
+            throw error;
+        }
+        try {
+            const result = await fn();
+            database.exec('COMMIT;');
+            return result;
+        }
+        catch (error) {
+            try {
+                database.exec('ROLLBACK;');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            database.close();
+        }
+    }
+}

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

@@ -1,6 +1,6 @@
 import { DeliveryError } from './errors.js';
-import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
-export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
+import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
+export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
 export interface SendOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -34,10 +34,24 @@ export type PaseoAgent = Steerable<KeyedSendOptions> & {
     readonly harness: 'paseo';
     readonly agentId: string;
 };
-export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent;
+export type CodexAppServerAgent = Steerable & Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'app-server';
+    readonly sessionId: string;
+};
+export type CodexCliAgent = Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'cli';
+    readonly sessionId: string;
+};
+export type CodexAgent = CodexAppServerAgent | CodexCliAgent;
+export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent | CodexAgent;
 export declare function connect(options: OpenCodeConnectOptions): Promise<OpenCodeAgent>;
 export declare function connect(options: ClaudeConnectOptions): Promise<ClaudeAgent>;
 export declare function connect(options: PiConnectOptions): Promise<PiAgent>;
 export declare function connect(options: PaseoConnectOptions): Promise<PaseoAgent>;
+export declare function connect(options: CodexCliConnectOptions): Promise<CodexCliAgent>;
+export declare function connect(options: CodexAppServerConnectOptions): Promise<CodexAppServerAgent>;
+export declare function connect(options: CodexConnectOptions): Promise<CodexAgent>;
 export { DeliveryError };
 export type { DeliveryErrorCode } from './errors.js';

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

@@ -25,11 +25,30 @@ function failure(error, phase, id) {
     const code = attempt.state === 'unavailable'
         ? attempt.code === 'aborted' ? 'aborted' : attempt.code === 'timeout' ? 'timeout'
             : attempt.code === 'authentication_failed' ? 'authentication_failed' : 'unavailable'
-        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found' : 'rejected'
+        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found'
+            : attempt.code === 'unsupported_version' ? 'unsupported_version' : 'rejected'
             : codes[attempt.code ?? 'transport'] ?? 'transport';
     return new DeliveryError(code, attempt.state === 'unknown', id ?? attempt.inputId, attempt.status);
 }
 const harnesses = {
+    'codex-cli': {
+        harness: 'codex', transport: 'cli', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true, steer: false,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodexCli } = await import('./codex-cli.js');
+            const target = await connectCodexCli(options);
+            return { coordinate: target.coordinate, send: (text, value) => target.send(text, value) };
+        },
+    },
+    codex: {
+        harness: 'codex', transport: 'app-server', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodex, sendCodexText } = await import('./codex.js');
+            const target = await connectCodex(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendCodexText(target, text, value) };
+        },
+    },
     opencode: {
         harness: 'opencode', proof: 'admitted', accepted: 'accepted', coordinate: 'sessionId', keyed: true, queue: true,
         id: (result) => result.inputId,
@@ -70,8 +89,9 @@ const harnesses = {
 export async function connect(options) {
     const harness = isRecord(options) && typeof options.harness === 'string' ? options.harness : undefined;
     // An own-key check keeps Object.prototype names out of the transport table.
-    const spec = harness !== undefined && Object.hasOwn(harnesses, harness) ? harnesses[harness] : undefined;
-    if (spec === undefined)
+    const key = harness === 'codex' && isRecord(options) && options.transport === 'cli' ? 'codex-cli' : harness;
+    const spec = key !== undefined && Object.hasOwn(harnesses, key) ? harnesses[key] : undefined;
+    if (spec === undefined || spec.harness !== harness)
         throw new DeliveryError('invalid_arguments');
     let opened;
     try {
@@ -86,6 +106,8 @@ export async function connect(options) {
             throw new DeliveryError('invalid_arguments');
         // An unusable caller id is an argument precondition; the native sender rejects it.
         const id = options.id;
+        if (!spec.keyed && id !== undefined)
+            throw new DeliveryError('invalid_arguments');
         try {
             const result = await opened.send(text, spec.keyed
                 ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal }
@@ -101,8 +123,11 @@ export async function connect(options) {
     const agent = {
         harness: spec.harness,
         [spec.coordinate]: opened.coordinate,
-        steer: (text, value) => send(text, value, 'steer'),
     };
+    if (spec.transport)
+        agent.transport = spec.transport;
+    if (spec.steer !== false)
+        agent.steer = (text, value) => send(text, value, 'steer');
     if (spec.queue)
         agent.queue = (text, value) => send(text, value, 'queue');
     return Object.freeze(agent);

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

@@ -1,3 +1,4 @@
+import type { CodexBoundaryStore } from './codex-boundary.js';
 declare const targetBrand: unique symbol;
 export interface OpenCodeTarget {
     readonly harness: 'opencode';
@@ -19,7 +20,12 @@ export interface PaseoTarget {
     readonly agentId: string;
     readonly [targetBrand]: true;
 }
-export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget;
+export interface CodexTarget {
+    readonly harness: 'codex';
+    readonly sessionId: string;
+    readonly [targetBrand]: true;
+}
+export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget | CodexTarget;
 export type Delivery = 'steer' | 'queue';
 export interface OpenCodeSendTextOptions {
     readonly delivery?: Delivery;
@@ -45,7 +51,13 @@ export interface PaseoSendTextOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions;
+export interface CodexSendTextOptions {
+    readonly delivery?: Delivery;
+    readonly inputId?: never;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions | CodexSendTextOptions;
 export interface OpenCodeConnectOptions {
     readonly harness: 'opencode';
     readonly sessionId: string;
@@ -88,6 +100,32 @@ export interface PaseoConnectOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
+/** Connect only to an existing app-server; never starts a service or resumes a thread. */
+export interface CodexAppServerConnectOptions {
+    readonly harness: 'codex';
+    readonly transport?: 'app-server';
+    readonly sessionId: string;
+    readonly endpoint?: string;
+    readonly token?: string;
+    readonly codexHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Bind CLI coordinates and the same lifecycle source used by the receiver's hooks. */
+export interface CodexCliConnectOptions {
+    readonly harness: 'codex';
+    readonly transport: 'cli';
+    readonly sessionId: string;
+    readonly boundaries: Pick<CodexBoundaryStore, 'queueEligible'>;
+    readonly codexHome?: string;
+    readonly endpoint?: string;
+    readonly bin?: string;
+    readonly args?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type CodexConnectOptions = CodexAppServerConnectOptions | CodexCliConnectOptions;
 interface OpenCodeAttempt {
     readonly harness: 'opencode';
     readonly sessionId: string;
@@ -158,5 +196,22 @@ export type PaseoDeliveryResult = (PaseoAttempt & {
     readonly state: 'unknown';
     readonly code: 'timeout' | 'aborted' | 'transport';
 });
-export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult;
+interface CodexAttempt {
+    readonly harness: 'codex';
+    readonly sessionId: string;
+    readonly inputId: string;
+}
+export type CodexDeliveryResult = (CodexAttempt & {
+    readonly state: 'admitted';
+}) | (CodexAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'invalid_response';
+}) | (CodexAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'authentication_failed';
+}) | (CodexAttempt & {
+    readonly state: 'rejected';
+    readonly code: 'not_found' | 'refused' | 'unsupported_version';
+});
+export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult | CodexDeliveryResult;
 export {};

package/dist/square-migration.d.ts

@@ -6,6 +6,10 @@ export interface MigrationCounts {
     readonly receipts: number;
     readonly leases: number;
     readonly routes: number;
+    readonly recoveredSeats: number;
+    readonly unownedStanding: number;
+    readonly sharedBodySeats: number;
+    readonly skippedEvidence: number;
 }
 export interface MigrationOutcome {
     readonly status: 'migrated' | 'already-current';

package/dist/square-migration.js

@@ -229,25 +229,24 @@ function establishingJoin(driver, participant) {
     return join.index;
 }
 function planSeats(location, roster, routes, owners, driver) {
-    const standing = roster.filter((participant) => participant.joined);
-    return standing.map((participant) => {
+    const seats = [];
+    const localRoutes = routes.filter(route => canonicalPathSync(route.location) === location);
+    for (const participant of roster.filter((participant) => participant.joined)) {
         const joined = establishingJoin(driver, participant);
-        const candidates = routes.filter((route) => canonicalPathSync(route.location) === location && nameKey(route.participant) === nameKey(participant.name));
+        const candidates = localRoutes.filter((route) => nameKey(route.participant) === nameKey(participant.name));
         const owner = owners.find(row => nameKey(row.participant) === nameKey(participant.name));
-        assertSource(owner !== undefined, `standing participant ${participant.name} has no legacy owner.`);
-        const { body } = owner;
-        assertSource(candidates.length > 0 && candidates.every(route => sameBody(route.body, body)), `standing participant ${participant.name} has no unique legacy body agreeing with its owner.`);
-        const shared = [...owners, ...routes.filter(route => canonicalPathSync(route.location) === location)]
-            .some(row => nameKey(row.participant) !== nameKey(participant.name) && sameBody(row.body, body));
-        assertSource(!shared, `standing participant ${participant.name} shares a legacy body with another owner.`);
+        const body = owner?.body ?? candidates[0]?.body;
+        if (body === undefined || !candidates.every(route => sameBody(route.body, body)))
+            continue;
         const address = uniqueSeatAddress(candidates);
-        return {
+        seats.push({
             participant: participant.name,
             body,
             generation: formatActivityId(joined),
             ...(address === undefined ? {} : { wakeAddress: address }),
-        };
-    });
+        });
+    }
+    return seats;
 }
 function tableToken(database, table, order) {
     const rows = database.prepare(`SELECT * FROM ${table} ORDER BY ${order}`).all();
@@ -313,15 +312,20 @@ function inspectLegacyRowArtifact(database, location, host) {
             leaseGenerations.push({ ownerJson: row.owner_json, generation: formatActivityId(ownerParticipant.lastJoinIndex) });
     }
     const seats = planSeats(location, roster, routes, host.owners, driver);
+    const standingCount = roster.filter(participant => participant.joined).length;
+    const deliveries = planLegacyDeliveries(host.evidence, seats, driver);
     const counts = {
         activities: activityCount,
         receipts: Number(database.prepare('SELECT COUNT(*) AS n FROM receipts').get().n),
         leases: leaseOwners.length,
         routes: routes.length,
+        recoveredSeats: seats.length,
+        unownedStanding: standingCount - seats.length,
+        sharedBodySeats: seats.filter(seat => seats.some(other => other !== seat && sameBody(other.body, seat.body))).length,
+        skippedEvidence: host.evidence.length - deliveries.length,
     };
     const sourceToken = legacySourceToken(database);
-    return { standing: seats.length, seats, leaseGenerations, sourceToken, counts,
-        deliveries: planLegacyDeliveries(host.evidence, seats, driver) };
+    return { standing: standingCount, seats, leaseGenerations, sourceToken, counts, deliveries };
 }
 function legacyPayloadHash(payload) {
     return createHash('sha256').update(payload).digest('hex');
@@ -348,47 +352,49 @@ function legacyDeliveryPayload(source, current) {
 }
 function planLegacyDeliveries(records, seats, driver) {
     const byGroup = new Map();
-    const tokens = new Set(), completedBodies = new Map();
+    const completedBodies = new Map();
     for (const source of records) {
+        // Validate structure even when no surviving owner can accept this row.
+        assertSource(source.kind === 'wake' || source.kind === 'presentation', 'delivery evidence kind is unsupported.');
+        assertSource(['dispatching', 'accepted', 'failed', 'unknown', 'released', 'presented', 'clipped'].includes(source.outcome), 'delivery evidence outcome is unsupported.');
+        assertSource(source.session.length > 0
+            && (source.channel === undefined || typeof source.channel === 'string' && source.channel.length > 0)
+            && (source.agent === undefined || typeof source.agent === 'string' && source.agent.length > 0), 'delivery evidence body is malformed.');
+        const index = parseActivityId(source.activity);
+        assertSource(index !== undefined, 'delivery evidence activity id is malformed.');
+        const at = sourceFinite(source.at);
+        const expiresAt = source.expiresAt === undefined ? undefined : sourceFinite(source.expiresAt);
+        const claimToken = source.claimToken;
+        assertSource(claimToken === undefined || typeof claimToken === 'string' && claimToken.length > 0, 'delivery claim token is malformed.');
+        assertSource(source.attemptN === undefined || Number.isSafeInteger(source.attemptN) && source.attemptN >= 0, 'delivery attempt number is malformed.');
         const participant = driver.participant(source.participant);
+        const seat = seats.find(seat => nameKey(seat.participant) === nameKey(source.participant));
+        const payload = legacyDeliveryPayload(source, seat?.wakeAddress);
         const native = source.kind === 'wake' && source.nativeDelivery !== undefined;
-        if (!participant?.joined && !native)
-            continue; // Noncritical completed diagnostics are not imported.
-        assertSource(participant?.joined || participant?.done, `native delivery evidence for ${source.participant} has no unique participant.`);
+        if (!participant?.joined && !(participant?.done && native))
+            continue;
+        if (participant.joined && (seat === undefined || seat.body.session !== source.session
+            || source.agent !== seat.body.agent || source.channel !== undefined && source.channel !== seat.body.channel))
+            continue;
+        const harness = source.nativeDelivery?.harness;
+        if (native && seat !== undefined && harness !==
+            (seat.body.channel === 'claude-code' ? 'claude' : seat.body.channel === 'opencode' ? 'opencode' : undefined))
+            continue;
         const joined = establishingJoin(driver, participant);
         const generation = formatActivityId(joined);
-        const seat = seats.find(seat => nameKey(seat.participant) === nameKey(participant.name));
-        if (participant.joined)
-            assertSource(seat !== undefined && seat.body.session === source.session
-                && source.agent === seat.body.agent && (source.channel === undefined || source.channel === seat.body.channel), `delivery evidence for standing participant ${source.participant} has no unique owner.`);
-        if (native && seat !== undefined)
-            assertSource(source.nativeDelivery?.harness ===
-                (seat.body.channel === 'claude-code' ? 'claude' : seat.body.channel === 'opencode' ? 'opencode' : undefined), 'native delivery harness conflicts with its owner body.');
-        const index = parseActivityId(source.activity);
-        assertSource(index !== undefined && index > joined && driver.activity(index)?.kind === 'say'
-            && driver.directedAt(participant.name, index) !== undefined, `delivery evidence for ${source.participant} has no unique activity in its join generation.`);
-        const payload = legacyDeliveryPayload(source, seat?.wakeAddress);
+        if (index <= joined || driver.activity(index)?.kind !== 'say' || driver.directedAt(participant.name, index) === undefined)
+            continue;
         if (participant.done) {
             const done = driver.activityHeads({ actors: [participant.name], kinds: ['done'] }, { edge: 'newest', limit: 1 }).items[0];
-            assertSource(done !== undefined && index < done.index && source.session.length > 0, `native delivery evidence for ${source.participant} has no unique completed generation.`);
-            const harness = source.nativeDelivery.harness;
+            if (done === undefined || index >= done.index)
+                continue;
             const body = { channel: harness === 'claude' ? 'claude-code' : 'opencode', session: source.session,
                 ...(source.agent === undefined ? {} : { agent: source.agent }) };
-            validateBody(body);
+            if (source.channel !== undefined && source.channel !== body.channel)
+                continue;
             const coordinate = JSON.stringify([body.channel, body.session, body.agent]);
-            const previous = completedBodies.get(nameKey(participant.name));
-            assertSource(previous === undefined || previous === coordinate, 'completed native delivery owner mapping is ambiguous.');
-            completedBodies.set(nameKey(participant.name), coordinate);
-        }
-        assertSource(source.kind === 'wake' || source.kind === 'presentation', 'delivery evidence kind is unsupported.');
-        assertSource(['dispatching', 'accepted', 'failed', 'unknown', 'released', 'presented', 'clipped'].includes(source.outcome), 'delivery evidence outcome is unsupported.');
-        const at = sourceFinite(source.at);
-        const expiresAt = source.expiresAt === undefined ? undefined : sourceFinite(source.expiresAt);
-        const claimToken = source.claimToken;
-        assertSource(claimToken === undefined || typeof claimToken === 'string' && claimToken.length > 0, 'delivery claim token is malformed.');
-        if (claimToken !== undefined) {
-            assertSource(!tokens.has(claimToken), 'delivery claim token is ambiguous.');
-            tokens.add(claimToken);
+            const key = nameKey(participant.name), previous = completedBodies.get(key);
+            completedBodies.set(key, previous === undefined || previous === coordinate ? coordinate : null);
         }
         const group = JSON.stringify([nameKey(participant.name), generation, index, source.kind]);
         const row = {
@@ -409,14 +415,19 @@ function planLegacyDeliveries(records, seats, driver) {
     }
     const deliveries = [];
     for (const rows of byGroup.values()) {
-        const attempts = rows.map(row => row.attemptN);
-        const explicit = attempts.filter((attempt) => attempt !== undefined);
-        assertSource(explicit.every((attempt) => Number.isSafeInteger(attempt) && attempt >= 0) && new Set(explicit).size === explicit.length, 'delivery attempt mapping is ambiguous.');
-        if (explicit.length !== rows.length)
-            assertSource(rows.length === 1 && explicit.length === 0, 'delivery attempt mapping is ambiguous.');
+        if (completedBodies.get(nameKey(rows[0].participant)) === null)
+            continue;
+        const explicit = rows.flatMap(row => row.attemptN === undefined ? [] : [row.attemptN]);
+        if (new Set(explicit).size !== explicit.length || explicit.length !== rows.length && rows.length !== 1)
+            continue;
         rows.forEach((row, index) => deliveries.push({ ...row, attemptN: explicit.length === 0 ? 0 : explicit[index] }));
     }
-    return deliveries;
+    const tokens = new Map();
+    for (const row of deliveries) {
+        if (row.claimToken !== undefined)
+            tokens.set(row.claimToken, (tokens.get(row.claimToken) ?? 0) + 1);
+    }
+    return deliveries.filter(row => row.claimToken === undefined || tokens.get(row.claimToken) === 1);
 }
 const V4_REBUILT_TABLES = ['square_meta', 'catch_leases'];
 function tableDefinition(name) {

package/guides/codex-delivery.md

@@ -0,0 +1,79 @@
+# Codex delivery
+
+Square uses the shared Codex leaves in `packages/agent-delivery/src`, rather than
+maintaining a second hook protocol, boundary store or CLI sender. The standalone
+package's [README](../packages/agent-delivery/README.md) describes both its native
+app-server capability and its host-owned hook integration.
+
+## Square's hook path
+
+`plugins/codex/hooks/hooks.json` invokes `square codex-hook`:
+
+- `SessionStart`, `SessionResume` and `UserPromptSubmit` invalidate the previous
+  Stop observation. `SessionEnd` marks the session ended and ends Square's owned
+  memberships. Later Stop/tool callbacks cannot re-enable queue until a new
+  `SessionStart` or `SessionResume`.
+- `PostToolUse` asks Square for current pending activity and returns the existing
+  bounded `additionalContext` presentation.
+- `Stop` records queue eligibility and sweeps pending work, but does not itself
+  claim that a preview was presented.
+
+The shared handler owns hook framing, lifecycle sequencing, its cancellation
+budget and bounded sweeps. Square supplies activity selection, formatting,
+artifact-owned presentation claims, cancellation, membership cleanup and
+pending-work sweeps. The handler cooperatively awaits Square's pull: the signal
+cancels work before presentation, but a successful presentation's `settleAs`
+finishes independently of request cancellation. Even when that settlement crosses
+the internal budget, the hook waits for it and returns the associated context;
+it never abandons settlement that can mark activity seen without returning text.
+After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
+output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
+an exact Body (`{ channel: 'codex', session }`), not a bare session id. The shared
+boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
+defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
+conversation storage and are not proof of current native execution or consumption.
+Square's format5 artifact remains authoritative for seats and delivery evidence.
+
+`CodexQueueTransport` implements the existing `WakeTransportPort` and uses the public
+`connect({ harness: 'codex', transport: 'cli', sessionId, boundaries, ... })`
+and `agent.queue(text)` interface, just like independent hosts. Square reads its
+stored pending preview and finishes its currentness gate first; the bound client
+checks boundary eligibility once inside `queue()`, then launches the CLI. No
+caller-side lifecycle check is duplicated. Outcomes continue through the existing
+artifact-owned delivery path; no host ledger or new route kind is introduced.
+
+Both CLI coordinate creation and MCP call-local Codex coordinates capture the
+recipient's `CODEX_HOME` (or home default), so later senders use the recipient's
+CLI configuration rather than their own. Only an explicitly configured
+`SQUARE_CODEX_ENDPOINT` adds a remote endpoint. `SQUARE_CODEX_BIN` remains
+Square's executable selection; it is not an environment convention of the
+independent package.
+
+By default the sender runs `codex queue --thread ... --message ...`, allowing the
+CLI's normal connection/startup behavior. Only an explicit endpoint adds
+`--remote`. This does not make another host's private stdio pipe attachable.
+After an observed `SessionEnd`, Square does not dispatch queue; the bound lifecycle
+check also catches an end observed while the currentness gate was running.
+It cannot retract a submission already launched or infer a missed end hook.
+Queue success means native admission only; its receipt id is a local attempt
+UUID, not a server message id. The child runs asynchronously and respects the
+send's abort signal/deadline. Timeout, killed child and unexplained post-launch
+failures remain unknown, not a safe reason to resend. A receiver with no tool
+calls waits for Stop; this path is not instantaneous native steer.
+
+## Optional native app-server capability
+
+Independent consumers can use `connect({ harness: 'codex', sessionId, endpoint })`
+from `@astrosheep/agent-delivery` for fenced busy steer and native queue.
+`transport: 'app-server'` is the explicit spelling and the default when omitted;
+it exposes both methods. `transport: 'cli'` exposes queue only and requires the
+host's hook lifecycle source at connection time. There is no automatic fallback
+between transports. The app-server transport never starts a service or calls
+`thread/resume`. This does not replace Square's hook policy or add a new persisted
+Square route kind. A loaded thread's owner remains its existing host, not the
+external sender.
+
+Neither path implements a read-receipt roundtrip. Admission and runtime
+observations must not be presented as model comprehension or completion. An
+unknown outcome stays unknown. Installing, restarting or changing a real Codex
+server is outside this integration.

package/guides/migration.md

@@ -38,25 +38,44 @@ artifact. Its latest owner row for each participant at this artifact is selected
 by source `(effectiveAt, seq)` only: no wall clock, retention, expiry, or ownership
 history reconstruction is involved.
 
-- A standing seat requires an agreeing owner Body (`channel`, `session`, optional
-  `agent`), route Body, and verified establishing last join. Routes alone never
-  establish ownership. An absent agent means the top-level body; a known agent is
-  preserved and compared exactly. Repeated matching route registrations are
-  acceptable; a wake address is carried forward only when they agree on it.
-- Missing owners or routes, conflicting or shared body mappings, and unverifiable
-  joins refuse before publication. Resolve these in the old runtime before
-  retrying; migration does not guess or synthesize authority.
-- Standing wake/presentation evidence maps only to that verified current join
-  generation and an existing directed say after the join. Evidence older than the
-  current generation, conflicting owner/session mappings, duplicate claim tokens,
-  or ambiguous attempt numbers refuse. A single record without an attempt number
-  receives attempt 0; missing numbers among multiple attempts are ambiguous.
+- A legacy owner Body (`channel`, `session`, optional `agent`) establishes a
+  standing seat only when it agrees with all of that name's local route Bodies
+  and the establishing last join is verified. An owner without routes needs no
+  wake address. Without a legacy owner, one unambiguous Body recorded by that
+  participant's own routes establishes its seat instead. An absent agent means
+  the top-level body; a known agent is preserved and compared exactly. Repeated
+  matching registrations are acceptable; a wake address is carried forward only
+  when the routes agree on it. Routes are location-bound: moving an artifact copy
+  to another path does not establish that its original routes apply there. An
+  off-location copy is not ownership-recovery evidence for the original location.
+- Without an owner or any route Body, the participant stays standing without a
+  seat. Its source participant state, activities, attention, receipts, landed
+  audience and catch lease are preserved. No Body, route or departure is invented;
+  the name has no write authority or delivery eligibility. Doctor retains its
+  strict history-derived consistency checks.
+- A Body may own several participant seats. Each name retains its own seat,
+  establishing join generation and wake address; sharing does not merge names or
+  choose one name over another. All evidence for each name must agree: if its
+  routes disagree with each other or with its legacy owner Body, that name stays
+  standing without a seat. Disagreement does not abort migration and neither side
+  is chosen as authoritative. Unverifiable joins still refuse before publication.
+  Migration does not guess or synthesize authority.
+- Evidence structure is validated before placement, including rows that cannot be
+  imported. Malformed fields, invalid activity IDs or malformed native correlation
+  still refuse without changing either source.
+- Wake/presentation evidence for a recovered seat is imported only when its Body
+  agrees and it names an existing directed say after the verified current join.
+  A missing seat, conflicting session/agent/channel or native harness, unknown
+  participant, or activity outside the generation causes the row to be skipped,
+  not a failed conversion. Nothing is reassigned to another owner.
 - Done participants get **no seat or completed coordinate**. Only native wake
   correlation directly attributable to their verified latest join and a directed
   activity between that join and done is retained for retired-token recognition.
-  It does not authorize admission, completion, or presentation. Ambiguous critical
-  native mappings refuse rather than disappear. Migrated Claude native addresses
-  include `sessionId` on both seats and evidence routes.
+  It does not authorize admission, completion, or presentation. Conflicting
+  completed Body mappings, duplicate claim tokens and ambiguous attempt numbering
+  cause all affected rows to be skipped, rather than selecting a winner. A single
+  record without an attempt number receives attempt 0. Migrated Claude native
+  addresses include `sessionId` on both seats and evidence routes.
 
 This is deliberately a narrow, lossy conversion, not a general history importer.
 Conversation facts (activity IDs, bodies and audience), receipts and source revision
@@ -65,15 +84,23 @@ correlation survive direct mappings. Completed non-native evidence and noncritic
 metadata—including old presence history, epochs, diagnostic messages, native
 observation histories and arbitrary legacy fields—are not imported. The legacy
 ledger is read-only and remains untouched, so it is still available for offline
-diagnostics. An absent ledger cannot establish standing ownership; an unreadable
-or unsupported ledger refuses before changing the square.
-
-After successful preflight, one SQLite transaction creates ownership/evidence rows and the
-empty deferral table/index, then publishes format 5. Activity history and indices,
-receipts, lease contents, and the artifact revision are preserved. Legacy routes
-are decoded only during migration and their table is removed. Existing lease
-generations are resolved only for exact owner spellings that match a standing
-participant; other lease rows retain their legacy, unbound generation.
+diagnostics. An absent ledger still permits route-derived seats; an unreadable
+or unsupported ledger refuses before changing the square. Evidence without a
+current or verified completed owner is skipped and counted. The source ledger is
+retained for offline diagnosis; skipped evidence never grants delivery authority.
+
+After successful preflight, one SQLite transaction imports seats and evidence
+and adds delivery deferral support, then publishes the current format. All
+existing activities, their indices and audience, participant state, attention,
+receipts, lease contents, and the source revision are preserved. Legacy routes
+are consumed only during migration. Lease generations are resolved only for exact
+owner spellings that match a standing participant; other lease rows retain their
+legacy, unbound generation. The command reports recovered seats and unowned
+standing names, and recovered seats whose Body is shared with another recovered
+seat, and skipped evidence rows, alongside the activity, receipt, lease and source
+route counts. The shared count measures seats, not distinct Bodies or shared groups.
+The skipped count includes every wake/presentation row read from the selected
+legacy ledger but not imported, including completed non-native diagnostics.
 The new delivery revision starts at zero. There is no intermediate published
 format, and any failure before commit rolls back the conversion.
 
@@ -90,8 +117,7 @@ reader; migration consumes the old rows only to resolve seats, then drops the le
 table as part of the format change.
 
 Unrelated databases, unsupported formats, non-`DELETE` journal modes, unknown
-schemas, malformed headers or rows, unresolved standing ownership, and ambiguous
-standing or native delivery evidence are refused. The source artifact is preserved on every
+schemas, malformed headers, rows or native correlation are refused. The source artifact is preserved on every
 refusal. Migration is not a repair command and never rewrites journal mode to make
 conversion possible. A HostLedger that itself requires migration must be migrated
 separately before Square migration can import its delivery evidence.

package/package.json

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