@astrosheep/square 0.4.0 → 0.4.2

package/dist/claude-hook.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+import { claudeBoundaryStore } from './claude-boundary-state.js';
+import { harnessOwner } from './owner.js';
+import { attachDeliverySessionRoutes, detachDeliverySession } from './session-lifecycle.js';
+import { presentPendingAtBoundary } from './boundary-presentation.js';
+import { renderDeliveryReminder } from './delivery-frame.js';
+import { beginClaudeMcpCall, endClaudeMcpCallForSession } from './claude-mcp-context.js';
+import { retainDeliveryLedger } from './delivery-lifetime.js';
+import { z } from 'zod/v4';
+const nativeId = z.string().min(1).max(4096).regex(/^[^\x00-\x1f\x7f]+$/u);
+const hookInput = z.object({
+    hook_event_name: nativeId, session_id: nativeId, cwd: z.string().optional(),
+    prompt_id: nativeId.optional().catch(undefined), prompt: z.string().optional(),
+    tool_use_id: nativeId.optional().catch(undefined), tool_name: z.string().optional(), agent_id: nativeId.optional(),
+});
+const route = 'claude-async-hook';
+const ownerFor = (input) => harnessOwner({ channel: 'claude-code', session: input.session_id });
+function parseInput(text) {
+    try {
+        const value = hookInput.safeParse(JSON.parse(text));
+        return value.success ? value.data : undefined;
+    }
+    catch {
+        return;
+    }
+}
+function observedFrames(prompt) {
+    const prefix = renderDeliveryReminder([''], { tagged: false });
+    const result = [];
+    for (const match of prompt.matchAll(/\[square-delivery:([a-f0-9-]+)\]\n[\s\S]*?\n\[\/square-delivery:\1\]/g)) {
+        const start = match.index - prefix.length;
+        if (start < 0 || prompt.slice(start, match.index) !== prefix)
+            continue;
+        result.push({ token: match[1], payloadHash: createHash('sha256').update(prefix + match[0]).digest('hex') });
+    }
+    return result;
+}
+function claudeFrame(card, token) {
+    return renderDeliveryReminder([`[square-delivery:${token}]\n${card.text}\n[/square-delivery:${token}]`], { tagged: false });
+}
+export async function runClaudeHook(text, env = process.env, sink = value => { process.stdout.write(value); }) {
+    const input = parseInput(text);
+    if (!input) {
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            return '';
+        }
+        if (raw?.hook_event_name === 'PreToolUse' && typeof raw.tool_name === 'string' && raw.tool_name.startsWith('mcp__plugin_square_square__'))
+            await denyMcpTool(sink);
+        return '';
+    }
+    const boundaries = claudeBoundaryStore(input.session_id, env);
+    const mainOwner = ownerFor(input);
+    const owner = harnessOwner({ channel: 'claude-code', session: input.session_id, ...(input.agent_id === undefined ? {} : { agent: input.agent_id }) });
+    if (input.hook_event_name === 'SessionStart') {
+        await boundaries.start(async () => {
+            const session = await attachDeliverySessionRoutes(mainOwner, env, [{ kind: route, address: { sessionId: input.session_id } }], AbortSignal.timeout(4500));
+            if (!session)
+                return false;
+            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
+            try {
+                await ledger.updateRoutes({ owner: mainOwner, generation: session.generation, routes: session.routes.filter(item => item.kind !== 'claude-native') });
+            }
+            finally {
+                await ledger.close();
+            }
+            return session.generation;
+        });
+        return '';
+    }
+    if (input.hook_event_name === 'SessionEnd') {
+        const captured = await boundaries.end();
+        if (captured)
+            await detachDeliverySession(mainOwner, captured.generation, env);
+        return '';
+    }
+    if (input.hook_event_name === 'UserPromptSubmit') {
+        await boundaries.prompt(input.prompt_id);
+        if (!input.prompt_id)
+            return '';
+        if (input.prompt) {
+            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
+            try {
+                for (const frame of observedFrames(input.prompt)) {
+                    const handoff = await ledger.handoff(frame.token);
+                    if (!handoff || handoff.owner !== owner || handoff.routeKind !== route || handoff.payloadHash !== frame.payloadHash)
+                        continue;
+                    await ledger.observePresentation(handoff);
+                }
+            }
+            finally {
+                await ledger.close();
+            }
+        }
+        await presentPendingAtBoundary(owner, async (context) => {
+            await sink(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: context } })}\n`);
+        }, env, AbortSignal.timeout(4500));
+        return '';
+    }
+    if (input.hook_event_name === 'PreToolUse' && input.tool_name?.startsWith('mcp__plugin_square_square__')) {
+        if (!input.tool_use_id || !input.cwd) {
+            await denyMcpTool(sink);
+            return '';
+        }
+        try {
+            await beginClaudeMcpCall({ toolUseId: input.tool_use_id, sessionId: input.session_id, cwd: input.cwd, agentId: input.agent_id }, env);
+        }
+        catch {
+            await denyMcpTool(sink);
+            return '';
+        }
+    }
+    if ((input.hook_event_name === 'PostToolUse' || input.hook_event_name === 'PostToolUseFailure')
+        && 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)) {
+        await presentPendingAtBoundary(owner, async (context) => {
+            await sink(`${JSON.stringify({ hookSpecificOutput: { hookEventName: input.hook_event_name, additionalContext: context } })}\n`);
+        }, env, AbortSignal.timeout(4500));
+    }
+    return '';
+}
+async function denyMcpTool(sink) {
+    try {
+        await sink(`${JSON.stringify({ hookSpecificOutput: {
+                hookEventName: 'PreToolUse', permissionDecision: 'deny',
+                permissionDecisionReason: 'Square MCP call identity is unavailable; this call did not run.',
+            } })}\n`);
+    }
+    catch {
+        process.exitCode = 2;
+    }
+}
+export async function runClaudeWatch(text, env = process.env, signal, output = frame => new Promise((resolve, reject) => {
+    process.stderr.write(frame, error => error ? reject(error) : resolve());
+})) {
+    const input = parseInput(text);
+    if (!input || input.hook_event_name !== 'Stop' || !input.prompt_id)
+        return '';
+    const owner = ownerFor(input);
+    const boundaries = claudeBoundaryStore(input.session_id, env);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 86_400_000);
+    const stop = () => controller.abort();
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    try {
+        const captured = await boundaries.capture(input.prompt_id);
+        if (!captured)
+            return '';
+        await boundaries.watch(combined, async () => {
+            if (!await boundaries.current(captured))
+                return;
+            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
+            const lifetime = retainDeliveryLedger(ledger);
+            const observer = await ledger.observe(owner);
+            try {
+                while (!combined.aborted) {
+                    let version = await observer.read(combined);
+                    const live = await boundaries.current(captured);
+                    const session = await ledger.session(owner);
+                    if (!live || session?.state !== 'attached' || session.generation !== captured.generation || !session.routes.some(item => item.kind === route))
+                        return;
+                    const cards = 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 cards) {
+                        if (held.has(card.seq))
+                            continue;
+                        const transport = {
+                            kind: route,
+                            async send(deliveryCard, address, context) {
+                                if (address.sessionId !== input.session_id)
+                                    return 'not-capable';
+                                const frame = claudeFrame(deliveryCard, context.token);
+                                const payloadHash = createHash('sha256').update(frame).digest('hex');
+                                if (!await context.prepare({ token: context.token, messageId: context.token, payloadHash }))
+                                    return 'not-capable';
+                                const currentSession = await ledger.session(owner);
+                                if (currentSession?.state !== 'attached' || currentSession.generation !== captured.generation
+                                    || !currentSession.routes.some(item => item.kind === route) || !await context.beforeSend())
+                                    return 'not-capable';
+                                const native = await boundaries.current(captured);
+                                if (!native || context.signal.aborted || Date.now() >= context.deadline)
+                                    return 'not-capable';
+                                try {
+                                    await output(frame);
+                                }
+                                finally {
+                                    await boundaries.consume(captured);
+                                }
+                                process.exitCode = 2;
+                                return 'unknown';
+                            },
+                        };
+                        const result = await ledger.dispatchHandoff(owner, card.key, transport, {
+                            generation: captured.generation, timeoutMs: 5000, signal: combined,
+                        });
+                        lifetime.track(result);
+                        if (result.outcome === 'unknown' || result.outcome === 'accepted' || result.outcome === 'presented')
+                            return;
+                        // Drain our own unsuccessful claim/settlement edge before waiting;
+                        // a not-capable route must not make filesystem hints a retry loop.
+                        version = await observer.read(combined);
+                    }
+                    await observer.changed(version, 1000, combined);
+                }
+            }
+            finally {
+                observer.close();
+                await lifetime.close();
+            }
+        });
+    }
+    catch {
+        if (!combined.aborted)
+            return '';
+    }
+    finally {
+        clearTimeout(timer);
+        process.off('SIGTERM', stop);
+        process.off('SIGINT', stop);
+    }
+    return '';
+}

package/dist/claude-mcp-context.d.ts

@@ -10,6 +10,6 @@ export declare function beginClaudeMcpCall(input: ClaudeMcpCall, env?: NodeJS.Pr
     token: string;
 }>;
 export declare function endClaudeMcpCall(toolUseId: string, token: string, env?: NodeJS.ProcessEnv): Promise<void>;
-/** Expiry gates lookup only; an executing tool keeps its captured coordinate. */
+export declare function endClaudeMcpCallForSession(toolUseId: string, sessionId: string, env?: NodeJS.ProcessEnv, agentId?: string): Promise<void>;
 export declare function readClaudeMcpCall(toolUseId: unknown, env?: NodeJS.ProcessEnv): Promise<ClaudeMcpCall>;
 export {};

package/dist/claude-mcp-context.js

@@ -1,9 +1,9 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
+import { deliveryLedgerLocation } from './delivery-ledger.js';
 import { z } from 'zod/v4';
 import { withFileLock } from './file-lock.js';
-import { squareIndexPath } from './square-index.js';
 import { SquareError } from './model.js';
 const LEASE_MS = 10 * 60 * 1000;
 const text = z.string().max(4096).refine(value => value.trim().length > 0 && !/[\x00-\x1f\x7f]/u.test(value));
@@ -12,7 +12,7 @@ const coordinate = z.object({
 });
 const record = coordinate.extend({ token: z.string().regex(/^[a-f0-9]{64}$/u), expiresAt: z.number() });
 const unavailable = () => new SquareError('unavailable', 'Claude MCP call context unavailable');
-const storeRoot = (env) => path.join(path.dirname(squareIndexPath(env)), 'claude-mcp-calls');
+const storeRoot = (env) => path.join(path.dirname(deliveryLedgerLocation(env)), 'claude-mcp-calls');
 const callFile = (root, id) => path.join(root, `${createHash('sha256').update(id).digest('hex')}.json`);
 async function readRecord(file) {
     try {
@@ -71,7 +71,16 @@ export async function endClaudeMcpCall(toolUseId, token, env = process.env) {
             await fs.unlink(file);
     });
 }
-/** Expiry gates lookup only; an executing tool keeps its captured coordinate. */
+export async function endClaudeMcpCallForSession(toolUseId, sessionId, env = process.env, agentId) {
+    if (!text.safeParse(toolUseId).success || !text.safeParse(sessionId).success)
+        throw unavailable();
+    await mutate(env, async (root) => {
+        const file = callFile(root, toolUseId);
+        const stored = await readRecord(file);
+        if (stored?.toolUseId === toolUseId && stored.sessionId === sessionId && stored.agentId === agentId)
+            await fs.unlink(file);
+    });
+}
 export async function readClaudeMcpCall(toolUseId, env = process.env) {
     if (!text.safeParse(toolUseId).success)
         throw unavailable();

package/dist/cli/context.js

@@ -150,22 +150,20 @@ export function squareInput(context) {
 export function commandIdentity(env, explicit) {
     if (explicit !== undefined)
         return { owner: explicit };
-    const configured = env.SQUARE_OWNER;
-    if (configured !== undefined)
-        return { owner: configured };
-    const selected = harnessSessionSources.flatMap(({ variable, channel }) => env[variable]?.trim() ? [{ channel, session: env[variable].trim() }] : []);
-    const native = selected.filter(source => source.channel !== 'paseo');
+    if (env.SQUARE_OWNER !== undefined)
+        return { owner: env.SQUARE_OWNER };
     if (env.CLAUDE_CODE_CHILD_SESSION === '1')
         throw new Error('Harness identity is incomplete; provide --owner explicitly.');
+    const selected = harnessSessionSources.flatMap(({ variable, channel }) => env[variable]?.trim() ? [{ channel, session: env[variable].trim() }] : []);
+    const native = selected.filter(source => source.channel !== 'paseo');
     if (native.length > 1)
         throw new Error('Multiple harness execution coordinates are present; select one explicit owner.');
-    const paseo = selected.find(source => source.channel === 'paseo');
-    const coordinate = native[0] ?? paseo;
+    const coordinate = native[0] ?? selected[0];
     if (coordinate === undefined)
         return { owner: localUserOwner() };
     const owner = harnessOwner({ channel: coordinate.channel, session: coordinate.session });
-    const wakeAddress = coordinate.channel === 'codex' ? codexWakeAddress(coordinate.session, env)
-        : paseo === undefined ? undefined : { kind: 'paseo', address: { agentId: paseo.session } };
+    const wakeAddress = coordinate.channel === 'codex' ? { ...codexWakeAddress(coordinate.session, env), kind: 'codex-queue' }
+        : coordinate.channel === 'paseo' ? { kind: 'paseo', address: { agentId: coordinate.session } } : undefined;
     return { owner, ...(wakeAddress === undefined ? {} : { wakeAddress }) };
 }
 /** Adapter lifetime only; each callback uses the actual public resource API. */

package/dist/cli/observation-commands.d.ts

@@ -25,6 +25,9 @@ interface InboxIntent {
     limit: number;
 }
 export declare const inboxCommand: CommandSpec<InboxIntent, string>;
-export declare const claudeModCommand: CommandSpec<undefined, string>;
+export declare const claudeHookCommand: CommandSpec<undefined, string>;
+export declare const claudeWatchCommand: CommandSpec<undefined, string>;
 export declare const codexHookCommand: CommandSpec<undefined, string>;
+export declare const codexWatchCommand: CommandSpec<undefined, string>;
+export declare const codexInterruptCommand: CommandSpec<undefined, string>;
 export {};

package/dist/cli/observation-commands.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { once } from 'node:events';
-import { runClaudeMod } from '../claude-mod.js';
-import { runCodexHook } from '../codex-hook.js';
+import { runClaudeHook, runClaudeWatch } from '../claude-hook.js';
+import { runCodexHook, runCodexInterrupt } from '../codex-hook.js';
+import { runCodexWatch } from '../codex-watch.js';
 import { isSquareError } from '../model.js';
 import { commandPrefix, participantIdentity, truncateChars, withPathOutput, quoteShell, } from '../presentation.js';
 import { PARTICIPANTS_DEFAULT_LIMIT, PARTICIPANTS_MAX_LIMIT, renderHistoryResult, renderParticipantsResult, renderStatusResult, } from '../operation-presentation.js';
@@ -525,5 +526,37 @@ function hookCommand(runHook) {
         present: (result) => process.stdout.write(result),
     };
 }
-export const claudeModCommand = hookCommand(runClaudeMod);
-export const codexHookCommand = hookCommand(runCodexHook);
+export const claudeHookCommand = {
+    parse(argv, context) { if (argv.length > 0)
+        usage(context.command); return undefined; },
+    execute: async () => {
+        try {
+            return await runClaudeHook(await readStdin(), process.env, text => new Promise((resolve, reject) => {
+                process.stdout.write(text, error => { if (error)
+                    reject(error);
+                else
+                    resolve(); });
+            }));
+        }
+        catch {
+            return '';
+        }
+    },
+    present: () => { },
+};
+export const claudeWatchCommand = {
+    parse(argv, context) { if (argv.length > 0)
+        usage(context.command); return undefined; },
+    execute: async () => runClaudeWatch(await readStdin(), process.env),
+    present: () => { },
+};
+export const codexHookCommand = {
+    parse(argv, context) { if (argv.length > 0)
+        usage(context.command); return undefined; },
+    execute: async () => runCodexHook(await readStdin(), process.env, text => new Promise((resolve, reject) => {
+        process.stdout.write(text, error => error ? reject(error) : resolve());
+    })),
+    present: () => { },
+};
+export const codexWatchCommand = hookCommand(input => runCodexWatch(input, process.env));
+export const codexInterruptCommand = hookCommand(input => runCodexInterrupt(input, process.env));

package/dist/cli/registry.js

@@ -4,7 +4,7 @@ import { harnessCommand, installCommand, uninstallCommand } from './harness-comm
 import { helpCommand, versionCommand } from './meta-commands.js';
 import { mcpServerCommand } from './mcp-server-command.js';
 import { JSON_COMMANDS } from './json.js';
-import { catchCommand, claudeModCommand, codexHookCommand, historyCommand, inboxCommand, listCommand, participantsCommand, statusCommand, streamCommand, } from './observation-commands.js';
+import { catchCommand, claudeHookCommand, claudeWatchCommand, codexHookCommand, codexWatchCommand, codexInterruptCommand, historyCommand, inboxCommand, listCommand, participantsCommand, statusCommand, streamCommand, } from './observation-commands.js';
 /** Every public command is an executable adapter, including aliases and utility commands. */
 export const commandRegistry = [
     { names: ['build'], spec: buildCommand },
@@ -12,8 +12,11 @@ export const commandRegistry = [
     { names: ['join'], spec: joinCommand },
     { names: ['stream'], spec: streamCommand },
     { names: ['inbox'], spec: inboxCommand },
-    { names: ['claude-mod'], spec: claudeModCommand },
+    { names: ['claude-hook'], spec: claudeHookCommand },
+    { names: ['claude-watch'], spec: claudeWatchCommand },
     { names: ['codex-hook'], spec: codexHookCommand },
+    { names: ['codex-watch'], spec: codexWatchCommand },
+    { names: ['codex-interrupt'], spec: codexInterruptCommand },
     { names: ['catch'], spec: catchCommand },
     { names: ['express'], spec: expressCommand },
     { names: ['listen'], spec: listenCommand },

package/dist/codex-address.d.ts

@@ -1,3 +1,3 @@
-import type { WakeAddress } from './channel-values.js';
+import type { DeliveryRoute } from './delivery-ledger.js';
 /** Capture the receiver's CLI configuration when its seat is established, not at send time. */
-export declare function codexWakeAddress(threadId: string, env: NodeJS.ProcessEnv): WakeAddress;
+export declare function codexWakeAddress(threadId: string, env: NodeJS.ProcessEnv): DeliveryRoute;

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

@@ -1,6 +1,2 @@
-export type { CodexBoundary } from './packages/agent-delivery/src/codex-boundary.js';
+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;
-export declare const readCodexBoundary: (id: string, env?: NodeJS.ProcessEnv) => Promise<import("./packages/agent-delivery/src/codex-boundary.js").CodexBoundary | undefined>;
-export declare const codexQueueEligible: (id: string, env?: NodeJS.ProcessEnv) => Promise<boolean>;
-export declare const recordCodexBoundary: (id: string, event: "Stop" | "non-stop" | "start" | "end", env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<void>;
-export declare const clearCodexBoundary: (id: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<void>;

package/dist/codex-boundary-state.js

@@ -4,7 +4,3 @@ import { createCodexBoundaryStore } from './packages/agent-delivery/src/codex-bo
 export function codexBoundaryStore(env = process.env) {
     return createCodexBoundaryStore(env.SQUARE_CODEX_BOUNDARIES || path.join(os.homedir(), '.square', 'codex-boundaries.json'));
 }
-export const readCodexBoundary = (id, env) => codexBoundaryStore(env).read(id);
-export const codexQueueEligible = (id, env) => codexBoundaryStore(env).queueEligible(id);
-export const recordCodexBoundary = (id, event, env, signal) => codexBoundaryStore(env).record(id, event, signal);
-export const clearCodexBoundary = (id, env, signal) => codexBoundaryStore(env).clear(id, signal);

package/dist/codex-hook.d.ts

@@ -1,12 +1,9 @@
-import { type Owner } from './owner.js';
-import type { PendingMembership } from './model.js';
-import type { WakeTransports } from './notifications.js';
-export interface CodexHookInput {
-    session_id?: unknown;
-    hook_event_name?: unknown;
-    cwd?: unknown;
-}
+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;
-export declare function codexHookResponse(input: CodexHookInput, lookup?: (identity: Owner, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<PendingMembership[]> | PendingMembership[], env?: NodeJS.ProcessEnv, deliveryTransports?: WakeTransports, trace?: HookTrace): Promise<object | undefined>;
-export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
+/** 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>;
+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>;
+export declare function runCodexInterrupt(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/codex-hook.js

@@ -1,49 +1,85 @@
-import { handleCodexHook } from './packages/agent-delivery/src/codex-hook.js';
+import { handleCodexHook, parseCodexHook } from './packages/agent-delivery/src/codex-hook.js';
 import { presentPendingAtBoundary } from './boundary-presentation.js';
-import { sessionInbox } from './inbox.js';
+import { DeliveryLedger } from './delivery-ledger.js';
 import { harnessOwner } from './owner.js';
-import { detachSessionSeats, restoreSessionSeats } from './session-lifecycle.js';
+import { attachDeliverySessionRoutes, detachDeliverySession } from './session-lifecycle.js';
 import { codexBoundaryStore } from './codex-boundary-state.js';
 import { codexWakeAddress } from './codex-address.js';
-import { PRIVILEGED_HOOK_BUDGET_MS, sweepPrivilegedPending } from './notifications.js';
 export const CODEX_HOOK_BUDGET_MS = 4500;
-const defaultTrace = (line) => { process.stderr.write(`${line}\n`); };
-export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryTransports, trace = defaultTrace) {
+const defaultTrace = line => { process.stderr.write(`${line}\n`); };
+/** sink resolves only after stdout has accepted the complete hook response. */
+export async function codexHookResponse(value, sink, env = process.env, trace = defaultTrace) {
+    const input = parseCodexHook(value);
+    if (!input)
+        return;
     const configured = Number(env.SQUARE_CODEX_HOOK_BUDGET_MS ?? CODEX_HOOK_BUDGET_MS);
-    const startedAt = Date.now();
-    let mark = startedAt;
-    const timeoutMs = Number.isFinite(configured) && configured > 0 ? configured : CODEX_HOOK_BUDGET_MS;
+    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);
-    if ((input.hook_event_name === 'SessionStart' || input.hook_event_name === 'SessionResume')
-        && typeof input.session_id === 'string' && input.session_id.trim()) {
-        await restoreSessionSeats(harnessOwner({ channel: 'codex', session: input.session_id }), env, codexWakeAddress(input.session_id, env), signal);
+    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') {
+        const ledger = await DeliveryLedger.open({ location: env.SQUARE_DELIVERY });
+        try {
+            generation = (await ledger.session(owner))?.generation;
+        }
+        finally {
+            await ledger.close();
+        }
     }
-    return handleCodexHook(input, {
-        boundaries: codexBoundaryStore(env),
-        timeoutMs,
-        signal,
-        sweepTimeoutMs: PRIVILEGED_HOOK_BUDGET_MS,
-        pull: (id, signal) => presentPendingAtBoundary(harnessOwner({ channel: 'codex', session: id }), (context) => context, lookup, env, signal),
-        sweep: (cwd, deadline, signal) => sweepPrivilegedPending(cwd ?? process.cwd(), env, deliveryTransports, deadline, signal),
-        end: async (id) => { await detachSessionSeats('codex', id, env); },
-        trace: (name, detail = '') => {
-            const now = Date.now();
-            const durationMs = now - mark;
-            mark = now;
-            trace(`square-codex-hook: stage=${name} durationMs=${durationMs} totalMs=${now - startedAt}${detail ? ` ${detail}` : ''}`);
+    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;
 }
-export async function runCodexHook(inputText, env = process.env) {
-    let input;
+export function parseCodexHookText(text) {
     try {
-        input = JSON.parse(inputText);
+        return parseCodexHook(JSON.parse(text));
     }
     catch {
-        return '';
+        return;
+    }
+}
+/** The caller owns stdout; no receipt is written when no output sink is supplied. */
+export async function runCodexHook(inputText, env = process.env, sink) {
+    await codexHookResponse(parseCodexHookText(inputText), sink, env);
+    return '';
+}
+export async function runCodexInterrupt(inputText, env = process.env) {
+    const input = parseCodexHookText(inputText);
+    if (input?.hook_event_name === 'Interrupt') {
+        try {
+            await codexHookResponse(input, undefined, env);
+        }
+        catch {
+            throw new Error('Codex interrupt unavailable.');
+        }
     }
-    if (input === null || typeof input !== 'object')
-        return '';
-    const result = await codexHookResponse(input, sessionInbox, env);
-    return result === undefined ? '' : `${JSON.stringify(result)}\n`;
+    return '';
 }

package/dist/codex-queue.d.ts

@@ -1,15 +1,14 @@
-import { type CodexCliAgent, type CodexCliConnectOptions } from './packages/agent-delivery/src/index.js';
-export { sendCodexQueue, CodexQueueSendError } from './packages/agent-delivery/src/codex-queue.js';
-export type { CodexQueueRequest, CodexQueueFailureKind } from './packages/agent-delivery/src/codex-queue.js';
-import type { WakeRequest, WakeOutcome, WakeTransportPort } from './channel-transport.js';
-import type { WakeRoute } from './channel-values.js';
+import { type CodexStopEpoch } from './codex-boundary-state.js';
+import type { DeliveryCard, DeliveryTransport, DeliveryTransportContext, TransportOutcome } from './delivery-ledger.js';
 export interface CodexQueueTransportOptions {
-    env?: NodeJS.ProcessEnv;
-    connect?: (options: CodexCliConnectOptions) => Promise<CodexCliAgent>;
+    readonly epoch: CodexStopEpoch;
+    readonly address: Readonly<Record<string, string>>;
+    readonly env?: NodeJS.ProcessEnv;
 }
-export declare class CodexQueueTransport implements WakeTransportPort {
+/** Instantiated only by the receiver, for one captured Stop epoch. */
+export declare class CodexQueueTransport implements DeliveryTransport {
     private readonly opts;
-    constructor(opts?: CodexQueueTransportOptions);
-    attempt(request: WakeRequest, timeoutMs: number, beforeSend: () => Promise<boolean>): Promise<WakeOutcome>;
+    readonly kind = "codex-queue";
+    constructor(opts: CodexQueueTransportOptions);
+    send(card: DeliveryCard, address: Readonly<Record<string, string>>, context: DeliveryTransportContext): Promise<TransportOutcome>;
 }
-export type { WakeRoute };