@astrosheep/square 0.4.3 → 0.4.5

package/dist/cli/observation-commands.js

@@ -4,12 +4,11 @@ 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';
-import { style } from '../tty-style.js';
-import { formatRelativeTime, formatTimestamp, parseTimeOrRelative } from '../time.js';
-import { discover, inbox, formatActivityId, parseActivityId, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from '../square-api.js';
-import { renderCatchOutcome, renderCatchProgress } from './catch-presentation.js';
+import { commandPrefix, truncateChars, withPathOutput, quoteShell, } from '../presentation.js';
+import { PARTICIPANTS_DEFAULT_LIMIT, PARTICIPANTS_MAX_LIMIT, renderHistoryResult, renderParticipantsResult, renderStatusResult, renderSquareList, } from '../operation-presentation.js';
+import { formatTimestamp, parseTimeOrRelative } from '../time.js';
+import { discover, inbox, formatActivityId, parseActivityId, PERCEIVE_DEFAULT_LIMIT, PERCEIVE_MAX_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from '../square-api.js';
+import { renderPerceiveOutcome, renderPerceiveProgress } from './perceive-presentation.js';
 import { selectOwnSeat } from '../square-api.js';
 import { jsonResult } from './json.js';
 import { withSquare, squareInput, now, fail, parseBoundedLimit, parseDurationMs, parseNameList, parseNonNegativeInteger, readStdin, requireSquarePath, requireValue, usage, commandIdentity, } from './context.js';
@@ -20,38 +19,6 @@ function inboxDisplay(value) {
     const truncated = truncateChars(value, INBOX_DISPLAY_CHARS - 1);
     return truncated.remaining === 0 ? truncated.text : `${truncated.text}…`;
 }
-function renderSquareList(data, projection) {
-    const { items, stopped, remaining, next } = data;
-    if (data.total === 0) {
-        return ['(no squares found)', ...(stopped ? [style('dim', '○ the walk stopped early — deeper squares may still be hiding')] : [])].join('\n') + '\n';
-    }
-    const lines = ['squares'];
-    for (const item of items) {
-        const glyph = item.activities > 0 ? '●' : style('dim', '○');
-        lines.push(`${glyph} ${inboxDisplay(item.path)}${style('dim', ` · ${formatRelativeTime(item.lastActiveAt, projection.now)} · ${item.participants.length} in the square · ${item.activities} ${item.activities === 1 ? 'activity' : 'activities'}`)}`);
-        const context = item.context.slice(0, 2);
-        if (context.length === 0)
-            lines.push(`  ${style('dim', 'context')} · (none)`);
-        else {
-            context.forEach((line, index) => lines.push(`  ${index === 0 ? style('dim', 'context') : '       '} · ${inboxDisplay(line)}`));
-            const hidden = item.context.length - context.length;
-            if (hidden > 0)
-                lines.push(style('dim', `          · … ${hidden} more ${hidden === 1 ? 'line' : 'lines'}`));
-        }
-        const participants = item.participants.slice(0, 3);
-        const hidden = item.participants.length - participants.length;
-        const names = participants.length === 0 ? 'nobody' : participants.map((name) => participantIdentity(inboxDisplay(name))).join(' · ');
-        lines.push(`  ${style('dim', 'participants')} · ${names}${hidden > 0 ? style('dim', ` · … ${hidden} more`) : ''}`);
-    }
-    if (remaining > 0) {
-        lines.push(style('dim', stopped ? '  … more squares' : `  … ${remaining} more ${remaining === 1 ? 'square' : 'squares'}`));
-        if (next !== undefined)
-            lines.push(`square list --depth ${projection.depth} --limit ${projection.limit} --after ${quoteShell(next)}`);
-    }
-    if (stopped)
-        lines.push(style('dim', '○ the walk stopped early — deeper squares may still be hiding'));
-    return lines.join('\n') + '\n';
-}
 export const listCommand = {
     parse(argv, context) {
         let depth = DEFAULT_LIST_DEPTH;
@@ -81,7 +48,12 @@ export const listCommand = {
         return { depth, limit, after };
     },
     async execute(intent, context) {
-        const result = await discover(squareInput(context), intent);
+        let owner;
+        try {
+            owner = commandIdentity(context.env, context.owner).owner;
+        }
+        catch { /* Discovery stays available without a complete harness identity. */ }
+        const result = await discover(squareInput(context), { ...intent, owner });
         return renderSquareList(result, { now: now(context), depth: intent.depth ?? DEFAULT_LIST_DEPTH, limit: intent.limit ?? DEFAULT_LIST_LIMIT });
     },
     present: (result) => process.stdout.write(result),
@@ -156,7 +128,7 @@ export const streamCommand = {
     },
     present: () => { },
 };
-export const catchCommand = {
+export const perceiveCommand = {
     parse(argv, context) {
         let idle;
         let mention;
@@ -168,10 +140,10 @@ export const catchCommand = {
         for (let index = 0; index < argv.length; index++) {
             if (argv[index] === '--id') {
                 if (id !== undefined)
-                    fail('✕ catch accepts one --id\nsquare catch --help');
+                    fail('✕ perceive accepts one --id\nsquare perceive --help');
                 const value = requireValue(argv, index, '--id');
                 if (parseActivityId(value) === undefined)
-                    fail('✕ invalid --id: expected an activity id like act/12\nsquare catch --help');
+                    fail('✕ invalid --id: expected an activity id like act/12\nsquare perceive --help');
                 id = value;
                 index += 1;
             }
@@ -187,7 +159,7 @@ export const catchCommand = {
                 mention = true;
             }
             else if (argv[index] === '--limit') {
-                limit = parseBoundedLimit(argv[index + 1], '--limit', CATCH_MAX_LIMIT, `${commandPrefix(requireSquarePath(context))} catch --limit ${CATCH_MAX_LIMIT}`);
+                limit = parseBoundedLimit(argv[index + 1], '--limit', PERCEIVE_MAX_LIMIT, `${commandPrefix(requireSquarePath(context))} perceive --limit ${PERCEIVE_MAX_LIMIT}`);
                 index += 1;
             }
             else if (argv[index] === '--replace')
@@ -195,22 +167,22 @@ export const catchCommand = {
             else if (argv[index] === '--now')
                 now = true;
             else if (argv[index] !== '--json')
-                fail(`✕ catch does not know ${argv[index]}\nsquare catch --help`);
+                fail(`✕ perceive does not know ${argv[index]}\nsquare perceive --help`);
         }
         if (id !== undefined) {
             if (argv.some((flag) => ['--idle', '--from', '--mention', '--limit', '--replace'].includes(flag))) {
-                fail('✕ --id cannot be combined with --idle, --from, --mention, --limit or --replace\nsquare catch --help');
+                fail('✕ --id cannot be combined with --idle, --from, --mention, --limit or --replace\nsquare perceive --help');
             }
             return { id };
         }
         if (idle !== undefined && now)
-            fail('catch accepts --now or --idle, not both.');
+            fail('perceive accepts --now or --idle, not both.');
         if (replace && idle === undefined)
             fail('--replace can only be used with --idle.');
         return {
             ...(participants.length > 0 ? { from: participants } : {}),
             ...(mention === undefined ? {} : { mention }),
-            limit: limit ?? CATCH_DEFAULT_LIMIT,
+            limit: limit ?? PERCEIVE_DEFAULT_LIMIT,
             ...(idle === undefined ? {} : { idle }),
             ...(replace ? { replace } : {}),
         };
@@ -221,10 +193,10 @@ export const catchCommand = {
         const interrupt = () => controller.abort();
         process.once('SIGINT', interrupt);
         try {
-            const outcome = await withSquare(context, async (square) => (await selectOwnSeat(square, commandIdentity(context.env, context.owner).owner, context.name)).catch({ ...intent, ...(context.json ? {} : { observe: true }) }, {
+            const outcome = await withSquare(context, async (square) => (await selectOwnSeat(square, commandIdentity(context.env, context.owner).owner, context.name)).perceive({ ...intent, ...(context.json ? {} : { observe: true }) }, {
                 signal: controller.signal,
                 onProgress(progress) {
-                    const line = renderCatchProgress(squarePath, progress);
+                    const line = renderPerceiveProgress(squarePath, progress);
                     if (line !== undefined)
                         process.stderr.write(line);
                 },
@@ -234,7 +206,7 @@ export const catchCommand = {
                 process.exitCode = outcome.reason === 'already-active' || outcome.reason === 'capped' ? 1 : 0;
             }
             else {
-                const rendered = renderCatchOutcome(squarePath, outcome, intent, context.owner ?? context.env.SQUARE_OWNER);
+                const rendered = renderPerceiveOutcome(squarePath, outcome, intent, context.owner ?? context.env.SQUARE_OWNER);
                 process.stdout.write(rendered.stdout);
                 process.exitCode = rendered.exitCode;
             }
@@ -242,7 +214,7 @@ export const catchCommand = {
         catch (error) {
             if (!controller.signal.aborted)
                 throw error;
-            process.stdout.write(withPathOutput(squarePath, '○ you step back — catch stopped'));
+            process.stdout.write(withPathOutput(squarePath, '○ you step back — perceive stopped'));
             process.exitCode = 130;
         }
         finally {

package/dist/cli/perceive-presentation.d.ts

@@ -0,0 +1,3 @@
+import type { OperationProgress } from '../square-facade.js';
+export { renderPerceiveOutcome } from '../operation-presentation.js';
+export declare function renderPerceiveProgress(squarePath: string, progress: OperationProgress): string | undefined;

package/dist/cli/{catch-presentation.js → perceive-presentation.js}

@@ -1,7 +1,7 @@
 import { renderWatchForceTakeover, renderWatchReplaceMissing } from '../presentation.js';
-export { renderCatchOutcome } from '../operation-presentation.js';
-export function renderCatchProgress(squarePath, progress) {
-    if (progress.kind !== 'catch-started' || !progress.replacementRequested)
+export { renderPerceiveOutcome } from '../operation-presentation.js';
+export function renderPerceiveProgress(squarePath, progress) {
+    if (progress.kind !== 'perceive-started' || !progress.replacementRequested)
         return undefined;
     const options = { squarePath, name: progress.participant };
     return (progress.replaced

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, claudeHookCommand, claudeWatchCommand, codexHookCommand, codexWatchCommand, codexInterruptCommand, historyCommand, inboxCommand, listCommand, participantsCommand, statusCommand, streamCommand, } from './observation-commands.js';
+import { perceiveCommand, 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 },
@@ -17,7 +17,7 @@ export const commandRegistry = [
     { names: ['codex-hook'], spec: codexHookCommand },
     { names: ['codex-watch'], spec: codexWatchCommand },
     { names: ['codex-interrupt'], spec: codexInterruptCommand },
-    { names: ['catch'], spec: catchCommand },
+    { names: ['perceive'], spec: perceiveCommand },
     { names: ['express'], spec: expressCommand },
     { names: ['listen'], spec: listenCommand },
     { names: ['ignore'], spec: ignoreCommand },

package/dist/codex-address.d.ts

@@ -1,3 +1,6 @@
+import { type CodexBoundaryStore } from './packages/agent-delivery/src/codex-boundary.js';
 import type { DeliveryRoute } from './delivery-ledger.js';
+/** Local Stop/activity epochs shared by native hooks and async watchers. No RPC. */
+export declare function codexBoundaryStore(env: NodeJS.ProcessEnv): CodexBoundaryStore;
 /** Capture the receiver's CLI configuration when its seat is established, not at send time. */
 export declare function codexWakeAddress(threadId: string, env: NodeJS.ProcessEnv): DeliveryRoute;

package/dist/codex-address.js

@@ -1,4 +1,11 @@
 import { resolveCodexHome } from './packages/agent-delivery/src/codex-endpoint.js';
+import { createCodexBoundaryStore } from './packages/agent-delivery/src/codex-boundary.js';
+import os from 'node:os';
+import path from 'node:path';
+/** Local Stop/activity epochs shared by native hooks and async watchers. No RPC. */
+export function codexBoundaryStore(env) {
+    return createCodexBoundaryStore(env.SQUARE_CODEX_BOUNDARIES ?? path.join(os.homedir(), '.square', 'codex-boundaries.json'));
+}
 /** Capture the receiver's CLI configuration when its seat is established, not at send time. */
 export function codexWakeAddress(threadId, env) {
     const endpoint = env.SQUARE_CODEX_ENDPOINT?.trim();

package/dist/codex-hook.d.ts

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

package/dist/codex-hook.js

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

package/dist/codex-queue.d.ts

@@ -1,11 +1,11 @@
-import { type CodexStopEpoch } from './codex-boundary-state.js';
 import type { DeliveryCard, DeliveryTransport, DeliveryTransportContext, TransportOutcome } from './delivery-ledger.js';
 export interface CodexQueueTransportOptions {
-    readonly epoch: CodexStopEpoch;
     readonly address: Readonly<Record<string, string>>;
     readonly env?: NodeJS.ProcessEnv;
 }
-/** Instantiated only by the receiver, for one captured Stop epoch. */
+/** Instantiated only by the receiver. The native queue store is shared across
+ * processes: the hosting Codex app-server polls it and starts queued input only
+ * when the thread is idle, so admission needs no remote idle proof. */
 export declare class CodexQueueTransport implements DeliveryTransport {
     private readonly opts;
     readonly kind = "codex-queue";

package/dist/codex-queue.js

@@ -1,9 +1,9 @@
 import { connect, DeliveryError } from './packages/agent-delivery/src/index.js';
-import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
 import { codexQueueEndpoint } from './packages/agent-delivery/src/codex-endpoint.js';
-import { codexBoundaryStore } from './codex-boundary-state.js';
 import { renderDeliveryReminder } from './delivery-frame.js';
-/** Instantiated only by the receiver, for one captured Stop epoch. */
+/** Instantiated only by the receiver. The native queue store is shared across
+ * processes: the hosting Codex app-server polls it and starts queued input only
+ * when the thread is idle, so admission needs no remote idle proof. */
 export class CodexQueueTransport {
     opts;
     kind = 'codex-queue';
@@ -16,21 +16,15 @@ export class CodexQueueTransport {
             !Object.entries(this.opts.address).every(([key, value]) => address[key] === value))
             return 'not-capable';
         const env = this.opts.env ?? process.env;
-        const boundaries = codexBoundaryStore(env), epoch = this.opts.epoch;
         try {
-            // Receiver delivery addresses the already-hosting endpoint explicitly;
-            // disappearing native custody must not trigger CLI service startup.
+            // Receiver delivery addresses the shared queue store explicitly; disappearing
+            // native custody must not trigger CLI service startup.
             const endpoint = address.endpoint ?? codexQueueEndpoint({ CODEX_HOME: address.codexHome });
             const agent = await connect({ harness: 'codex', transport: 'cli', sessionId: threadId,
-                boundaries: { queueEligible: async (id) => {
-                        if (!await boundaries.queueEligible(id, epoch))
-                            return false;
-                        // Repeat the native sample after claim, immediately before the final
-                        // epoch and ledger fences. These reads are not an atomic native enqueue.
-                        if (!await codexIdleAtStop({ harness: 'codex', sessionId: id, codexHome: address.codexHome,
-                            endpoint, timeoutMs: Math.max(1, context.deadline - Date.now()), signal: context.signal }, epoch.turnId))
-                            return false;
-                        return await boundaries.queueEligible(id, epoch) && await context.beforeSend()
+                boundaries: { queueEligible: async () => {
+                        // Only ledger fences remain: currentness, suppression, cancellation,
+                        // attachment generation, signal and deadline immediately before launch.
+                        return await context.beforeSend()
                             && !context.signal.aborted && Date.now() < context.deadline;
                     } },
                 env, bin: env.SQUARE_CODEX_BIN, codexHome: address.codexHome, endpoint });

package/dist/codex-watch.d.ts

@@ -1,2 +1,7 @@
-/** One native async hook owns observation; the lock itself conveys no idle authority. */
+/** One async Stop waits only for its captured native turn; it never adopts another Stop.
+ * Queue admission writes the shared native queue store through the CLI; the hosting
+ * Codex process starts queued input only when idle, so no remote idle sampling.
+ * Local boundary epochs retire this watcher when a newer Stop or any active native
+ * event (UserPromptSubmit/PostToolUse/Interrupt) arrives, keeping active-turn
+ * presentation on the synchronous hooks. */
 export declare function runCodexWatch(inputText: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string>;

package/dist/codex-watch.js

@@ -6,12 +6,15 @@ import { retainDeliveryLedger } from './delivery-lifetime.js';
 import { harnessOwner } from './owner.js';
 import { withFileLock } from './file-lock.js';
 import { canonicalPath } from './canonical-path.js';
-import { codexBoundaryStore } from './codex-boundary-state.js';
-import { codexWakeAddress } from './codex-address.js';
+import { codexWakeAddress, codexBoundaryStore } from './codex-address.js';
 import { parseCodexHookText } from './codex-hook.js';
 import { CodexQueueTransport } from './codex-queue.js';
-import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
-/** One native async hook owns observation; the lock itself conveys no idle authority. */
+/** One async Stop waits only for its captured native turn; it never adopts another Stop.
+ * Queue admission writes the shared native queue store through the CLI; the hosting
+ * Codex process starts queued input only when idle, so no remote idle sampling.
+ * Local boundary epochs retire this watcher when a newer Stop or any active native
+ * event (UserPromptSubmit/PostToolUse/Interrupt) arrives, keeping active-turn
+ * presentation on the synchronous hooks. */
 export async function runCodexWatch(inputText, env = process.env, signal) {
     const input = parseCodexHookText(inputText);
     if (input?.hook_event_name !== 'Stop' || signal?.aborted)
@@ -22,31 +25,39 @@ export async function runCodexWatch(inputText, env = process.env, signal) {
     const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     process.on('SIGTERM', stop);
     process.on('SIGINT', stop);
+    let lifetime;
     try {
         const route = codexWakeAddress(input.session_id, env);
         const home = await canonicalPath(route.address.codexHome);
-        const coordinate = [input.session_id, route.address.endpoint ?? home];
+        const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env), signal: combined });
+        lifetime = retainDeliveryLedger(ledger);
+        const owner = harnessOwner({ channel: 'codex', session: input.session_id });
+        const captured = await ledger.session(owner, combined);
+        if (captured?.state !== 'attached')
+            return '';
+        // Same-turn duplicates cannot overlap; a later Stop need not wait for an old
+        // watcher or a slow late settlement to release a session-wide lock.
+        const coordinate = [input.session_id, route.address.endpoint ?? home, captured.generation, input.turn_id];
         const root = path.join(path.dirname(deliveryLedgerLocation(env)), 'codex-watchers');
         await fs.mkdir(root, { recursive: true, mode: 0o700 });
         const lock = path.join(root, createHash('sha256').update(JSON.stringify(coordinate)).digest('hex') + '.lock');
         const file = await fs.open(lock, 'a', 0o600);
         await file.close();
         await withFileLock(lock, { retryMs: 10, skipIfBusy: true, signal: combined }, async () => {
-            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
-            const lifetime = retainDeliveryLedger(ledger);
-            let observer;
+            const boundaries = codexBoundaryStore(env);
+            // Record only after winning the lock: a duplicate Stop must not replace the
+            // live watcher's epoch and retire both. A newer Stop or active event does.
+            await boundaries.record(input.session_id, 'Stop', { turnId: input.turn_id, signal: combined });
+            const epoch = (await boundaries.read(input.session_id))?.stop;
+            if (!epoch)
+                return;
+            const observer = await ledger.observe(owner);
             try {
-                const owner = harnessOwner({ channel: 'codex', session: input.session_id });
-                const captured = await ledger.session(owner);
-                if (captured?.state !== 'attached')
-                    return;
-                const boundaries = codexBoundaryStore(env);
-                // Subscribe before inspecting pending work. Both ledger edges and the
-                // bounded wait below cause reconciliation; boundary-only changes matter.
-                observer = await ledger.observe(owner);
                 while (!combined.aborted) {
-                    let version = await observer.read(combined);
-                    const session = await ledger.session(owner);
+                    const version = await observer.read(combined);
+                    if (!await boundaries.queueEligible(input.session_id, epoch))
+                        return;
+                    const session = await ledger.session(owner, combined);
                     if (session?.state !== 'attached' || session.generation !== captured.generation)
                         return;
                     const registered = session.routes.find(candidate => candidate.kind === 'codex-queue');
@@ -54,36 +65,20 @@ export async function runCodexWatch(inputText, env = process.env, signal) {
                         registered.address.endpoint !== route.address.endpoint ||
                         !registered.address.codexHome || await canonicalPath(registered.address.codexHome) !== home)
                         return;
-                    const boundary = await boundaries.read(input.session_id);
-                    if (boundary?.ended)
-                        return;
-                    const pending = await ledger.pending(owner, { generation: captured.generation });
-                    const held = new Set((await ledger.handoffs(owner, { generation: captured.generation }))
+                    const held = new Set((await ledger.handoffs(owner, { generation: captured.generation }, combined))
                         .filter(attempt => !['failed', 'released'].includes(attempt.outcome)).map(attempt => attempt.seq));
-                    for (const card of pending) {
-                        if (combined.aborted)
-                            break;
-                        if (held.has(card.seq))
-                            continue;
-                        // Follow the latest Stop, regardless of which Stop launched this process.
-                        const epoch = (await boundaries.read(input.session_id))?.stop;
-                        if (!epoch || !await codexIdleAtStop({ harness: 'codex', sessionId: input.session_id,
-                            codexHome: registered.address.codexHome, endpoint: registered.address.endpoint,
-                            timeoutMs: 2000, signal: combined }, epoch.turnId))
-                            break;
-                        lifetime.track(await ledger.dispatchHandoff(owner, card.key, new CodexQueueTransport({ epoch, env, address: registered.address }), { generation: captured.generation, timeoutMs: 5000, signal: combined }));
-                        // Drain our own claim/settlement edge. A known-unsent failure must
-                        // not turn file observation into an immediate retry loop. Any post
-                        // racing this read is still found by the bounded rescan below.
-                        version = await observer.read(combined);
+                    const card = (await ledger.pending(owner, { generation: captured.generation }, combined)).find(card => !held.has(card.seq));
+                    if (card) {
+                        lifetime.track(await ledger.dispatchHandoff(owner, card.key, new CodexQueueTransport({ env, address: registered.address }), { generation: captured.generation, timeoutMs: 5000, signal: combined }));
+                        // One handoff attempt ends this wait, including unknown/refused
+                        // outcomes. Never replay or turn our own writes into a retry loop.
+                        return;
                     }
-                    // No claims are held while waiting, including while active or disarmed.
                     await observer.changed(version, 1000, combined);
                 }
             }
             finally {
-                observer?.close();
-                await lifetime.close();
+                observer.close();
             }
         });
     }
@@ -95,6 +90,7 @@ export async function runCodexWatch(inputText, env = process.env, signal) {
         clearTimeout(timer);
         process.off('SIGTERM', stop);
         process.off('SIGINT', stop);
+        await lifetime?.close();
     }
     return '';
 }

package/dist/delivery-ledger-sqlite.d.ts

@@ -8,8 +8,13 @@ export declare class LedgerStore {
     private readonly clock;
     private pending;
     private closed;
+    private readonly cancellation;
+    private readonly ordinaryCancellation;
+    private closing?;
     private constructor();
-    static open(location: string, clock: () => number): Promise<LedgerStore>;
+    static open(location: string, clock: () => number, signal?: AbortSignal): Promise<LedgerStore>;
+    /** Stop ordinary work while captured effects retain access to settlement. */
+    retire(): void;
     close(): Promise<void>;
     private transaction;
     private getSession;
@@ -20,49 +25,49 @@ export declare class LedgerStore {
     private normalize;
     private deleteCard;
     private gc;
-    session(owner: string): Promise<DeliverySession | undefined>;
-    sessions(): Promise<readonly DeliverySession[]>;
-    pendingCards(owner: string, generation: string): Promise<readonly DeliveryCard[]>;
-    handoffs(owner: string, generation: string): Promise<readonly DeliveryAttempt[]>;
+    session(owner: string, signal?: AbortSignal): Promise<DeliverySession | undefined>;
+    sessions(signal?: AbortSignal): Promise<readonly DeliverySession[]>;
+    pendingCards(owner: string, generation: string, signal?: AbortSignal): Promise<readonly DeliveryCard[]>;
+    handoffs(owner: string, generation: string, signal?: AbortSignal): Promise<readonly DeliveryAttempt[]>;
     attach(input: {
         owner: string;
         expectedGeneration: string | null;
         routes: readonly DeliveryRoute[];
-    }): Promise<DeliverySession | false>;
+    }, signal?: AbortSignal): Promise<DeliverySession | false>;
     updateRoutes(input: {
         owner: string;
         generation: string;
         routes: readonly DeliveryRoute[];
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     lifecycle(input: {
         owner: string;
         generation: string;
-    }, state: 'detached' | 'deleted'): Promise<boolean>;
+    }, state: 'detached' | 'deleted', signal?: AbortSignal): Promise<boolean>;
     post(input: {
         owner: string;
         key: string;
         text: string;
         details: string | null;
-    }): Promise<PostResult>;
+    }, signal?: AbortSignal): Promise<PostResult>;
     suppress(input: {
         owner: string;
         key: string;
         scope: 'exact' | 'prefix';
         expiresAt?: number;
-    }): Promise<SuppressionResult>;
+    }, signal?: AbortSignal): Promise<SuppressionResult>;
     renewSuppression(input: {
         owner: string;
         id: string;
         expiresAt: number;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     releaseSuppression(input: {
         owner: string;
         id: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     cancel(input: {
         owner: string;
         generation: string;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     private isSuppressed;
     private eligible;
     private insertAttempt;
@@ -79,21 +84,21 @@ export declare class LedgerStore {
     prepare(token: string, value: DeliveryCorrelation, signal?: AbortSignal): Promise<boolean>;
     private receipt;
     private confirm;
-    settle(tokens: readonly string[], outcome: Exclude<DeliveryOutcome, 'dispatching'>): Promise<boolean>;
+    settle(tokens: readonly string[], outcome: Exclude<DeliveryOutcome, 'dispatching'>, signal?: AbortSignal): Promise<boolean>;
     private handoffFacts;
     private matchingHandoff;
     private currentHandoff;
-    handoff(token: string): Promise<(DeliveryHandoffRef & {
+    handoff(token: string, signal?: AbortSignal): Promise<(DeliveryHandoffRef & {
         routeKind: string;
     }) | undefined>;
-    guardHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
-    acceptHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    guardHandoff(ref: DeliveryHandoffRef, signal?: AbortSignal): Promise<boolean>;
+    acceptHandoff(ref: DeliveryHandoffRef, signal?: AbortSignal): Promise<boolean>;
     observePresentation(handoff: string | DeliveryHandoffRef, options?: {
         readonly requireCurrent?: boolean;
-    }): Promise<boolean>;
+    }, signal?: AbortSignal): Promise<boolean>;
     receipts(owner: string, options: {
         keys?: readonly string[];
         since?: number;
-    }): Promise<readonly DeliveryReceipt[]>;
-    health(owner?: string): Promise<DeliveryHealth>;
+    }, signal?: AbortSignal): Promise<readonly DeliveryReceipt[]>;
+    health(owner?: string, signal?: AbortSignal): Promise<DeliveryHealth>;
 }