@noetic-tools/core 0.2.1 → 1.0.0

package/dist/runtime/channel-store.js

@@ -1,9 +1,14 @@
-import { NoeticErrorImpl } from '../errors/noetic-error.js';
-import { frameworkCast } from '../util/framework-cast.js';
-function isExternalChannel(ch) {
-    return 'external' in ch && ch.external === true;
-}
+import { frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
 const MAX_TOPIC_TIMEOUT = 300_000; // 5 minutes
+const DEFAULT_SEND_TIMEOUT = 30_000;
+const RESOLVED = Promise.resolve();
+/** Build the `cancelled` error a blocked channel operation rejects with on abort. */
+function cancelledError(signal) {
+    return new NoeticErrorImpl({
+        kind: 'cancelled',
+        reason: typeof signal.reason === 'string' ? signal.reason : undefined,
+    });
+}
 export class ChannelStore {
     channels = new Map();
     closedExecutions = new Set();
@@ -17,6 +22,7 @@ export class ChannelStore {
                 queue: [],
                 capacity: channel.capacity ?? 1_000,
                 queueWaiters: [],
+                pendingSenders: [],
                 topicSubscribers: new Set(),
                 wakeSubscribers: new Set(),
             };
@@ -40,14 +46,38 @@ export class ChannelStore {
             subscribers.delete(callback);
         };
     }
-    send(channel, value) {
+    /**
+     * Internal-sender write with back-pressure (spec 06). Delivery is
+     * synchronous when possible; the returned promise only parks when a queue
+     * channel is at capacity:
+     *
+     * - **value**: store last-write-wins value, drain ALL parked recv waiters,
+     *   resolve immediately.
+     * - **queue**: hand off to a parked recv waiter or push below capacity —
+     *   resolve immediately. At capacity, park the sender FIFO until a consumer
+     *   dequeues an item; reject `channel_timeout` after `opts.timeout`
+     *   (default 30s) or `cancelled` when `opts.signal` aborts.
+     * - **topic**: deliver to current subscribers, resolve immediately.
+     *
+     * External callers use `ChannelHandle.send` (sync, drop-oldest) instead.
+     */
+    send(channel, value, opts) {
         const state = this.getOrCreate(channel);
+        let result = RESOLVED;
         switch (state.mode) {
             case 'value':
                 state.currentValue = value;
                 state.hasValue = true;
+                // Value-mode reads are non-consuming (last-write-wins), so once
+                // hasValue flips true EVERY parked waiter must be drained — waking
+                // only one would strand the rest until channel_timeout while new
+                // recv calls succeed instantly. Splice in place: timeout timers and
+                // abort listeners close over the array identity.
                 if (state.valueWaiters.length > 0) {
-                    state.valueWaiters.shift().resolve(value);
+                    const drained = state.valueWaiters.splice(0, state.valueWaiters.length);
+                    for (const waiter of drained) {
+                        waiter.resolve(value);
+                    }
                 }
                 break;
             case 'queue':
@@ -58,13 +88,8 @@ export class ChannelStore {
                     state.queue.push(value);
                 }
                 else {
-                    // At capacity
-                    console.warn(`[noetic] Channel '${channel.name}': queue at capacity (${state.capacity}), dropping message.`);
-                    if (isExternalChannel(channel)) {
-                        state.queue.shift();
-                        state.queue.push(value);
-                    }
-                    // For internal, drop the new value
+                    // At capacity — park the sender (back-pressure).
+                    result = this.parkSender(state, channel.name, value, opts);
                 }
                 break;
             case 'topic':
@@ -73,30 +98,128 @@ export class ChannelStore {
                 }
                 break;
         }
-        if (state.wakeSubscribers.size > 0) {
-            // Swap in a fresh set before firing so a callback that re-subscribes
-            // (typical for `every` re-arming on its next iteration) lands on the
-            // new set and survives until the next send.
-            const wakers = state.wakeSubscribers;
-            state.wakeSubscribers = new Set();
-            for (const wake of wakers) {
-                wake();
+        this.fireWakes(state);
+        return result;
+    }
+    /** Park an internal sender on a full queue until a slot frees (FIFO). */
+    parkSender(state, channelName, value, opts) {
+        const timeout = opts?.timeout ?? DEFAULT_SEND_TIMEOUT;
+        const signal = opts?.signal;
+        if (signal?.aborted) {
+            return Promise.reject(cancelledError(signal));
+        }
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            let removeAbortListener = null;
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                removeAbortListener?.();
+            };
+            const entry = {
+                value,
+                resolve: () => {
+                    cleanup();
+                    resolve();
+                },
+                reject: (e) => {
+                    cleanup();
+                    reject(e);
+                },
+            };
+            state.pendingSenders.push(entry);
+            const removeEntry = () => {
+                const idx = state.pendingSenders.indexOf(entry);
+                if (idx < 0) {
+                    return false;
+                }
+                state.pendingSenders.splice(idx, 1);
+                return true;
+            };
+            if (timeout > 0) {
+                timer = setTimeout(() => {
+                    if (removeEntry()) {
+                        entry.reject(new NoeticErrorImpl({
+                            kind: 'channel_timeout',
+                            channelName,
+                            timeout,
+                        }));
+                    }
+                }, timeout);
             }
+            if (signal) {
+                const onAbort = () => {
+                    if (removeEntry()) {
+                        entry.reject(cancelledError(signal));
+                    }
+                };
+                signal.addEventListener('abort', onAbort, {
+                    once: true,
+                });
+                removeAbortListener = () => {
+                    signal.removeEventListener('abort', onAbort);
+                };
+            }
+        });
+    }
+    /**
+     * A dequeue freed a queue slot — shift the oldest parked sender's value
+     * into it (FIFO) and resolve that sender's promise.
+     */
+    promotePendingSender(state) {
+        if (state.pendingSenders.length === 0) {
+            return;
+        }
+        if (state.queue.length >= state.capacity) {
+            return;
+        }
+        const sender = state.pendingSenders.shift();
+        state.queue.push(sender.value);
+        sender.resolve();
+    }
+    /** Fire-and-reset the one-shot wake subscribers for a channel state. */
+    fireWakes(state) {
+        if (state.wakeSubscribers.size === 0) {
+            return;
+        }
+        // Swap in a fresh set before firing so a callback that re-subscribes
+        // (typical for `every` re-arming on its next iteration) lands on the
+        // new set and survives until the next send.
+        const wakers = state.wakeSubscribers;
+        state.wakeSubscribers = new Set();
+        for (const wake of wakers) {
+            wake();
         }
     }
-    async recv(channel, timeout = 30_000) {
+    async recv(channel, timeout = 30_000, signal) {
+        // An already-aborted context must reject promptly rather than park a
+        // waiter that nothing will ever wake (spec 09, Cancellation item 2).
+        if (signal?.aborted) {
+            throw cancelledError(signal);
+        }
         const state = this.getOrCreate(channel);
         switch (state.mode) {
             case 'value':
                 if (state.hasValue) {
                     return state.currentValue;
                 }
-                return this.waitWithTimeout(state.valueWaiters, channel.name, timeout);
-            case 'queue':
+                return this.waitWithTimeout(state.valueWaiters, channel.name, timeout, signal);
+            case 'queue': {
                 if (state.queue.length > 0) {
-                    return state.queue.shift();
+                    const head = state.queue.shift();
+                    this.promotePendingSender(state);
+                    return head;
                 }
-                return this.waitWithTimeout(state.queueWaiters, channel.name, timeout);
+                // capacity-0 edge: senders can be parked while the queue is empty —
+                // hand the oldest parked value straight to this receiver.
+                if (state.pendingSenders.length > 0) {
+                    const sender = state.pendingSenders.shift();
+                    sender.resolve();
+                    return sender.value;
+                }
+                return this.waitWithTimeout(state.queueWaiters, channel.name, timeout, signal);
+            }
             case 'topic': {
                 // Clamp timeout to prevent indefinite subscriber leaks
                 let effectiveTimeout = timeout;
@@ -105,8 +228,10 @@ export class ChannelStore {
                     effectiveTimeout = MAX_TOPIC_TIMEOUT;
                 }
                 return new Promise((resolve, reject) => {
+                    let removeAbortListener = null;
                     const timer = setTimeout(() => {
                         state.topicSubscribers.delete(handler);
+                        removeAbortListener?.();
                         reject(new NoeticErrorImpl({
                             kind: 'channel_timeout',
                             channelName: channel.name,
@@ -116,9 +241,23 @@ export class ChannelStore {
                     const handler = (value) => {
                         clearTimeout(timer);
                         state.topicSubscribers.delete(handler);
+                        removeAbortListener?.();
                         resolve(value);
                     };
                     state.topicSubscribers.add(handler);
+                    if (signal) {
+                        const onAbort = () => {
+                            clearTimeout(timer);
+                            state.topicSubscribers.delete(handler);
+                            reject(cancelledError(signal));
+                        };
+                        signal.addEventListener('abort', onAbort, {
+                            once: true,
+                        });
+                        removeAbortListener = () => {
+                            signal.removeEventListener('abort', onAbort);
+                        };
+                    }
                 });
             }
         }
@@ -128,32 +267,55 @@ export class ChannelStore {
         switch (state.mode) {
             case 'value':
                 return state.hasValue ? state.currentValue : null;
-            case 'queue':
-                return state.queue.length > 0 ? state.queue.shift() : null;
+            case 'queue': {
+                if (state.queue.length > 0) {
+                    const head = state.queue.shift();
+                    this.promotePendingSender(state);
+                    return head;
+                }
+                return null;
+            }
             case 'topic':
                 return null;
         }
     }
-    waitWithTimeout(waiters, channelName, timeout) {
+    waitWithTimeout(waiters, channelName, timeout, signal) {
         return new Promise((resolve, reject) => {
             let timer = null;
-            const wrappedResolve = (v) => {
+            let removeAbortListener = null;
+            // Symmetric cleanup: whichever path settles the waiter (delivery,
+            // timeout, abort) must release both the timer and the abort listener.
+            const cleanup = () => {
                 if (timer) {
                     clearTimeout(timer);
                 }
+                removeAbortListener?.();
+            };
+            const wrappedResolve = (v) => {
+                cleanup();
                 resolve(v);
             };
+            const wrappedReject = (e) => {
+                cleanup();
+                reject(e);
+            };
             const entry = {
                 resolve: wrappedResolve,
-                reject,
+                reject: wrappedReject,
             };
             waiters.push(entry);
+            const removeEntry = () => {
+                const idx = waiters.indexOf(entry);
+                if (idx < 0) {
+                    return false;
+                }
+                waiters.splice(idx, 1);
+                return true;
+            };
             if (timeout > 0) {
                 timer = setTimeout(() => {
-                    const idx = waiters.indexOf(entry);
-                    if (idx >= 0) {
-                        waiters.splice(idx, 1);
-                        reject(new NoeticErrorImpl({
+                    if (removeEntry()) {
+                        wrappedReject(new NoeticErrorImpl({
                             kind: 'channel_timeout',
                             channelName,
                             timeout,
@@ -161,8 +323,42 @@ export class ChannelStore {
                     }
                 }, timeout);
             }
+            if (signal) {
+                const onAbort = () => {
+                    if (removeEntry()) {
+                        wrappedReject(cancelledError(signal));
+                    }
+                };
+                signal.addEventListener('abort', onAbort, {
+                    once: true,
+                });
+                removeAbortListener = () => {
+                    signal.removeEventListener('abort', onAbort);
+                };
+            }
         });
     }
+    /**
+     * External-sender write: synchronous, never back-pressured (spec 06,
+     * External Sender Back-Pressure). At capacity the OLDEST queued item is
+     * dropped (with a warning) so external callers never block.
+     */
+    sendExternal(channel, value) {
+        const state = this.getOrCreate(channel);
+        const isFullQueue = state.mode === 'queue' &&
+            state.queueWaiters.length === 0 &&
+            state.queue.length >= state.capacity;
+        if (isFullQueue) {
+            console.warn(`[noetic] Channel '${channel.name}': queue at capacity (${state.capacity}), dropping oldest message (external sender).`);
+            state.queue.shift();
+            state.queue.push(value);
+            this.fireWakes(state);
+            return;
+        }
+        // Below capacity (or non-queue mode) the internal path resolves
+        // synchronously — nothing can park here.
+        void this.send(channel, value);
+    }
     getHandle(channel, executionId) {
         const store = this;
         return {
@@ -177,7 +373,7 @@ export class ChannelStore {
                         channelName: channel.name,
                     });
                 }
-                store.send(channel, value);
+                store.sendExternal(channel, value);
             },
         };
     }

package/dist/runtime/context-deps.d.ts

@@ -1,4 +1,4 @@
-export { buildContextMemory } from '../memory/layer-api.js';
-export type { ItemSchemaRegistry } from '../schemas/item.js';
-export { defaultItemSchemaRegistry } from '../schemas/item.js';
+export { buildContextMemory } from '@noetic-tools/memory';
+export type { ItemSchemaRegistry } from '@noetic-tools/types';
+export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export type { AgentHarnessContract, Channel, ChannelStore, Context, ContextMemory, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, LastLayerUsage, MemoryLayer, Span, StepMeta, TokenUsage, Tool, } from './context-type-deps.js';

package/dist/runtime/context-deps.js

@@ -1,2 +1,2 @@
-export { buildContextMemory } from '../memory/layer-api.js';
-export { defaultItemSchemaRegistry } from '../schemas/item.js';
+export { buildContextMemory } from '@noetic-tools/memory';
+export { defaultItemSchemaRegistry } from '@noetic-tools/types';

package/dist/runtime/context-impl.d.ts

@@ -34,6 +34,15 @@ export declare class ContextImpl implements Context<ContextMemory> {
     private _completed;
     private _aborted;
     private _abortReason?;
+    /**
+     * Per-context abort fan-out. `abort()` fires it so operations blocked on
+     * this context (channel `recv` waiters, parked back-pressure senders)
+     * reject promptly with `{ kind: 'cancelled' }` instead of hanging until
+     * their timeout (spec 09, Cancellation item 2). Each fork/spawn child
+     * constructs its own ContextImpl and therefore its own controller —
+     * aborting a child never rejects the parent's waiters.
+     */
+    private readonly _abortController;
     private _memory?;
     /**
      * Stack of steps currently in flight on this context, most-recent last.
@@ -77,7 +86,7 @@ export declare class ContextImpl implements Context<ContextMemory> {
     recv<T>(ch: Channel<T>, opts?: {
         timeout?: number;
     }): Promise<T>;
-    send<T>(ch: Channel<T>, value: T): void;
+    send<T>(ch: Channel<T>, value: T): Promise<void>;
     tryRecv<T>(ch: Channel<T>): T | null;
     checkpoint(): Promise<void>;
     complete<T>(value: T): void;
@@ -85,6 +94,13 @@ export declare class ContextImpl implements Context<ContextMemory> {
     get completionValue(): unknown;
     get abortReason(): string | undefined;
     abort(reason?: string): void;
+    /**
+     * @internal
+     * Abort signal scoped to this context. Channel operations register on it
+     * so `abort()` rejects them promptly. Not part of the public Context
+     * interface.
+     */
+    get abortSignal(): AbortSignal;
     /**
      * @internal
      * Push a frame onto the execution frontier. Called by `execute()` at the

package/dist/runtime/context-impl.js

@@ -48,6 +48,15 @@ export class ContextImpl {
     _completed = false;
     _aborted = false;
     _abortReason;
+    /**
+     * Per-context abort fan-out. `abort()` fires it so operations blocked on
+     * this context (channel `recv` waiters, parked back-pressure senders)
+     * reject promptly with `{ kind: 'cancelled' }` instead of hanging until
+     * their timeout (spec 09, Cancellation item 2). Each fork/spawn child
+     * constructs its own ContextImpl and therefore its own controller —
+     * aborting a child never rejects the parent's waiters.
+     */
+    _abortController = new AbortController();
     _memory;
     /**
      * Stack of steps currently in flight on this context, most-recent last.
@@ -110,13 +119,18 @@ export class ContextImpl {
         if (!this.channelStore) {
             return Promise.reject(new Error('No channel store configured'));
         }
-        return this.channelStore.recv(ch, opts?.timeout);
+        return this.channelStore.recv(ch, opts?.timeout, this._abortController.signal);
     }
     send(ch, value) {
         if (!this.channelStore) {
-            throw new Error('No channel store configured');
+            return Promise.reject(new Error('No channel store configured'));
         }
-        this.channelStore.send(ch, value);
+        // Internal sender: back-pressured on full queue channels (default 30s →
+        // channel_timeout); aborting this context rejects a parked send with
+        // 'cancelled' via the shared abort signal.
+        return this.channelStore.send(ch, value, {
+            signal: this._abortController.signal,
+        });
     }
     tryRecv(ch) {
         if (!this.channelStore) {
@@ -145,6 +159,19 @@ export class ContextImpl {
     abort(reason) {
         this._aborted = true;
         this._abortReason = reason;
+        // Reject everything blocked on this context (channel recv waiters,
+        // parked back-pressure senders) with { kind: 'cancelled' }. Idempotent —
+        // a second abort() leaves the already-aborted signal untouched.
+        this._abortController.abort(reason ?? 'context aborted');
+    }
+    /**
+     * @internal
+     * Abort signal scoped to this context. Channel operations register on it
+     * so `abort()` rejects them promptly. Not part of the public Context
+     * interface.
+     */
+    get abortSignal() {
+        return this._abortController.signal;
     }
     /**
      * @internal

package/dist/runtime/context-type-deps.d.ts

@@ -1,14 +1,5 @@
-export type { Channel } from '../types/channel.js';
+export type { ContextMemory, MemoryLayer } from '@noetic-tools/memory';
+export type { AgentHarnessContract, Channel, Context, CwdState, FsAdapter, Item, ItemLog, LastLayerUsage, Span, StepMeta, TokenUsage, Tool, } from '@noetic-tools/types';
 export type { FrontierFrame } from '../types/checkpoint.js';
-export type { StepMeta, TokenUsage } from '../types/common.js';
-export type { Context, CwdState } from '../types/context.js';
-export type { ItemLog } from '../types/context-parts/item-log.js';
-export type { LastLayerUsage } from '../types/context-parts/layer-usage.js';
-export type { FsAdapter } from '../types/fs-adapter.js';
-export type { Item } from '../types/items.js';
-export type { ContextMemory, MemoryLayer } from '../types/memory.js';
-export type { Span } from '../types/observability.js';
-export type { AgentHarnessContract } from '../types/runtime.js';
-export type { Tool } from '../types/tool.js';
 export type { ChannelStore } from './channel-store.js';
 export type { EventBroadcaster } from './event-broadcaster.js';

package/dist/runtime/cwd-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { Context, CwdState } from '../types/context.js';
+import type { Context, CwdState } from '@noetic-tools/types';
 /**
  * @public Resolve the live cwd for a tool execution. Falls back to the
  * tool's factory-time cwd (then `process.cwd()`) so partial test contexts

package/dist/runtime/detached-handle.d.ts

@@ -1,6 +1,5 @@
-import type { DetachedHandle } from '../types/detached.js';
-import { DetachedStatus } from '../types/detached.js';
-import type { SubprocessAdapter, SubprocessHandle } from '../types/subprocess-adapter.js';
+import type { DetachedHandle, SubprocessAdapter, SubprocessHandle } from '@noetic-tools/types';
+import { DetachedStatus } from '@noetic-tools/types';
 interface DetachedHandleOpts {
     /** Id surfaced to callers — usually the execution id (childCtx.id in
      *  `detachedSpawn`) so consumers can correlate it with their own state. */

package/dist/runtime/detached-handle.js

@@ -1,6 +1,4 @@
-import { NoeticErrorImpl } from '../errors/noetic-error.js';
-import { DetachedStatus } from '../types/detached.js';
-import { frameworkCast } from '../util/framework-cast.js';
+import { DetachedStatus, frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
 //#endregion
 //#region Helpers
 const INITIAL_POLL_MS = 10;

package/dist/runtime/durable/checkpoint-store.d.ts

@@ -1,5 +1,5 @@
+import type { StorageAdapter } from '@noetic-tools/memory';
 import type { CheckpointSnapshot } from '../../types/checkpoint.js';
-import type { StorageAdapter } from '../../types/memory.js';
 export declare const CheckpointKeys: {
     readonly ExecPrefix: "execution:";
     readonly SnapshotSuffix: ":snapshot";

package/dist/runtime/durable/checkpoint-store.js

@@ -1,4 +1,4 @@
-import { NoeticConfigError } from '../../errors/noetic-config-error.js';
+import { NoeticConfigError } from '@noetic-tools/types';
 import { CheckpointSnapshotSchema } from '../../types/checkpoint.js';
 //#region Keys
 /**

package/dist/runtime/durable/harness-checkpoints.d.ts

@@ -1,8 +1,5 @@
-import type { LayerStateStore } from '../../memory/layer-lifecycle.js';
-import type { ItemSchemaRegistry } from '../../schemas/item.js';
-import type { Context } from '../../types/context.js';
-import type { Item } from '../../types/items.js';
-import type { MemoryLayer } from '../../types/memory.js';
+import type { LayerStateStore, MemoryLayer } from '@noetic-tools/memory';
+import type { Context, Item, ItemSchemaRegistry } from '@noetic-tools/types';
 import type { CheckpointStore } from './checkpoint-store.js';
 /**
  * Minimum harness surface `captureCheckpoint` / `restoreFromCheckpoint`

package/dist/runtime/durable/runnable-loop.d.ts

@@ -30,9 +30,7 @@
  * escalation) lives in the caller and composes via the `afterFirstTurn`
  * hook.
  */
-import type { HarnessResponse } from '../../types/harness-result.js';
-import type { ExecuteInput, Item } from '../../types/items.js';
-import type { ExecuteOptions, SessionScope } from '../../types/runtime.js';
+import type { ExecuteInput, ExecuteOptions, HarnessResponse, Item, SessionScope } from '@noetic-tools/types';
 import type { DetachedSignal } from './detached-signal.js';
 /**
  * Minimum harness surface the loop calls into. Defining this

package/dist/runtime/durable/session-seed.d.ts

@@ -10,7 +10,7 @@
  * restore a prior session) has one documented, named entrypoint rather
  * than reaching for the harness method inline.
  */
-import type { Item } from '../../types/items.js';
+import type { Item } from '@noetic-tools/types';
 /**
  * Minimum harness surface `seedFromItems` requires. Defined structurally
  * so tests (and out-of-process children) can pass a stub without casts;

package/dist/runtime/durable/stall-nudge.d.ts

@@ -5,11 +5,14 @@
  * and without the agent asking for external input — i.e. the agent
  * stopped without calling either a terminal tool or an ask-user-style
  * tool. That's a soft failure: rather than wait forever, we nudge the
- * agent once to remind it of its options. If the second turn also
- * ends in the same stalled shape we escalate: the caller-supplied
- * `onStall` callback records the escalation (task pause, metrics,
- * whatever the domain demands) and we settle the signal ourselves with
- * a canonical "stalled" outcome so the parent unwinds cleanly.
+ * agent once to remind it of its options and wait for the nudged turn
+ * to actually complete (`harness.execute` is enqueue-only, so the hook
+ * awaits `getAgentResponse` — raced against the signal — before
+ * re-checking). If the second turn also ends in the same stalled shape
+ * we escalate: the caller-supplied `onStall` callback records the
+ * escalation (task pause, metrics, whatever the domain demands) and we
+ * settle the signal ourselves with a canonical "stalled" outcome so
+ * the parent unwinds cleanly.
  *
  * The helper factors the state machine out of the loop so callers can
  * opt in per-runner. Task-specific concerns (how "pending external
@@ -17,7 +20,7 @@
  * represents a stalled failure) stay with the caller and flow in via
  * the config.
  */
-import type { InputMessageItem } from '../../types/items.js';
+import type { InputMessageItem } from '@noetic-tools/types';
 import type { DetachedSignal } from './detached-signal.js';
 import type { AfterFirstTurnContext, RunnableLoopHarness } from './runnable-loop.js';
 /**
@@ -74,9 +77,13 @@ export declare function createNudgeMessage(opts: CreateNudgeMessageOpts): InputM
  *   - the caller reports pending external input (`hasPendingExternal`
  *     returns true — e.g. an outstanding ask-user request).
  *
- * Otherwise it sends the nudge message via `harness.execute`, waits
- * for microtasks to flush, and re-checks the same two conditions. If
- * the agent still hasn't progressed, the hook fires `onStall` and
- * resolves the signal with `buildStalledOutcome()`.
+ * Otherwise it sends the nudge message via `harness.execute` and waits
+ * for the nudged turn to actually complete. `execute()` only enqueues
+ * the message — the turn runs asynchronously through the session
+ * runner — so the hook awaits `harness.getAgentResponse(threadId)`
+ * (raced against `signal.done` so a terminal tool that settles the
+ * signal mid-turn short-circuits the wait) before re-checking the same
+ * two conditions. If the agent still hasn't progressed, the hook fires
+ * `onStall` and resolves the signal with `buildStalledOutcome()`.
  */
 export declare function createStallNudgeHook<TOutcome>(opts: StallNudgeOpts<TOutcome>): (ctx: AfterFirstTurnContext) => Promise<void>;