@noetic-tools/core 3.0.0 → 3.2.0

package/dist/harness/agent-harness.d.ts

@@ -1,7 +1,7 @@
 import { ItemSchemaRegistry } from '@noetic-tools/types';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { LayerStateStore, RecallCache } from './deps/memory.js';
-import type { CheckpointStore, EventBroadcaster, StepLedgerStore } from './deps/runtime.js';
+import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
 import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
@@ -33,6 +33,14 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
      * to enable durable execution.
      */
     checkpointStore?: CheckpointStore;
+    /**
+     * Bounds on the step-completion ledger that backs step-level resume. Only meaningful
+     * alongside a `checkpointStore`. Defaults to `DEFAULT_STEP_LEDGER_RETENTION` — 128 KiB
+     * per entry, 1000 entries per execution — so an unbounded run cannot grow an unbounded
+     * ledger. Exceeding either cap costs resumability for the affected steps (they re-run),
+     * never correctness.
+     */
+    stepLedgerRetention?: StepLedgerRetention;
     llm?: LlmProviderConfig;
     /** Harness-wide item schema extensions. */
     itemSchemas?: ItemSchemaExtensions;
@@ -111,6 +119,12 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * @internal
      */
     readonly stepLedgerStore?: StepLedgerStore;
+    /**
+     * Resolved retention bounds for that ledger. Validated at construction so a bad cap
+     * is a loud config error rather than a run that silently records nothing.
+     * @internal
+     */
+    readonly stepLedgerRetention: Required<StepLedgerRetention>;
     private readonly initialStep?;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     private readonly harnessTools;
@@ -256,9 +270,60 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` when the snapshot's
      * schema version is unrecognised — the caller is expected to discard the
      * checkpoint via `CheckpointStore.clear()` and start a fresh execution.
+     *
+     * `opts` is the `createContext`-shaped wiring the host attached to the
+     * original context (broadcaster, parent, state, memory overrides). A
+     * snapshot recovers data, not live objects — pass the same wiring here or
+     * the resumed run gets an undecorated context and whatever depended on that
+     * wiring (event streaming, mid-turn injection) stops working without
+     * failing. Fields the snapshot owns — items, threadId, resourceId, cwd —
+     * are not accepted; they always come from the persisted record.
+     *
+     * Decoration applied *after* construction (`Object.assign`ed fields, abort
+     * registration) stays the host's job: apply it to the context this returns,
+     * whose `id` is already the original `executionId`.
+     */
+    restore(executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
+    /**
+     * Discard everything `restore(executionId)` would have used — the snapshot *and* the
+     * step-completion ledger — so the next run of that execution starts clean.
+     *
+     * Hosts must call this rather than resume when the workflow itself changed. A resumed
+     * run replays at the coarsest completed granularity: a parent step that finished
+     * replays wholesale, so an edit to one of its children is never noticed and the stale
+     * output wins. Divergence detection only catches a changed step *at* a recorded path.
+     *
+     * Also the right call after a terminal outcome (the execution finished, or the user
+     * abandoned it) — `CheckpointStore.clear` alone leaves the ledger's per-step keys
+     * behind, and nothing else enumerates them.
+     */
+    clearCheckpoint(executionId: string): Promise<void>;
+    /**
+     * Cancel an execution: abort `ctx` and every live descendant context, then
+     * run the memory-layer teardown for each (spec 09, Cancellation).
+     *
+     * The abort itself fans out top-down and synchronously — `ctx.abort()`
+     * cascades into every live fork path and spawn child, so no corner of the
+     * tree keeps working while cleanup is in progress. Cleanup then runs
+     * bottom-up: a child's `onComplete` / `dispose` fires before its parent's.
+     *
+     * Aborting a context rejects everything blocked on it (channel `recv`
+     * waiters, parked senders) with `{ kind: 'cancelled' }`, stops its in-flight
+     * model call and sub-harness turn, and makes the next step boundary throw
+     * `cancelled`.
+     *
+     * Cancellation is cooperative: a layer hook already in flight is allowed to
+     * settle, and step code that ignores `ctx.aborted` between `await`s runs to
+     * its next boundary. Calling `cancel()` on an already-cancelled context is a
+     * no-op.
+     */
+    cancel(ctx: Context, reason?: string): Promise<void>;
+    /**
+     * Run the layer lifecycle's abort path for one cancelled context:
+     * `onComplete` with `outcome: 'aborted'`, then `dispose`. Both always run
+     * under cancellation (spec 09, Cancellation item 5).
      */
-    restore(executionId: string): Promise<Context | null>;
-    cancel(_ctx: Context, _reason?: string): Promise<void>;
+    private teardownCancelledContext;
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;

package/dist/harness/agent-harness.js

@@ -3,8 +3,8 @@ import { SpanImpl } from '../observability/span-impl.js';
 import { NoopExporter } from '../observability/trace-exporter.js';
 import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, } from './deps/adapters.js';
 import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, } from './deps/interpreter.js';
-import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/memory.js';
-import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
+import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/memory.js';
+import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
 import { AgentHarnessModelCaller } from './model-call.js';
 export { createStreamIdleWatchdog } from './model-call.js';
@@ -130,6 +130,12 @@ export class AgentHarness {
      * @internal
      */
     stepLedgerStore;
+    /**
+     * Resolved retention bounds for that ledger. Validated at construction so a bad cap
+     * is a loud config error rather than a run that silently records nothing.
+     * @internal
+     */
+    stepLedgerRetention;
     initialStep;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     harnessTools;
@@ -192,6 +198,7 @@ export class AgentHarness {
                 storage: this.config.storage ?? createInMemoryStorage(),
             })
             : undefined;
+        this.stepLedgerRetention = resolveStepLedgerRetention(opts.stepLedgerRetention);
         this.initialStep = opts.initialStep;
         this.harnessTools = opts.tools ?? [];
         this._memory = opts.memory;
@@ -476,6 +483,7 @@ export class AgentHarness {
                 ? new StepLedger({
                     executionId,
                     store: this.stepLedgerStore,
+                    retention: this.stepLedgerRetention,
                 })
                 : undefined,
         });
@@ -669,12 +677,93 @@ export class AgentHarness {
      * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` when the snapshot's
      * schema version is unrecognised — the caller is expected to discard the
      * checkpoint via `CheckpointStore.clear()` and start a fresh execution.
+     *
+     * `opts` is the `createContext`-shaped wiring the host attached to the
+     * original context (broadcaster, parent, state, memory overrides). A
+     * snapshot recovers data, not live objects — pass the same wiring here or
+     * the resumed run gets an undecorated context and whatever depended on that
+     * wiring (event streaming, mid-turn injection) stops working without
+     * failing. Fields the snapshot owns — items, threadId, resourceId, cwd —
+     * are not accepted; they always come from the persisted record.
+     *
+     * Decoration applied *after* construction (`Object.assign`ed fields, abort
+     * registration) stays the host's job: apply it to the context this returns,
+     * whose `id` is already the original `executionId`.
      */
-    async restore(executionId) {
-        return restoreFromCheckpoint(this, executionId);
+    async restore(executionId, opts) {
+        return restoreFromCheckpoint(this, executionId, opts);
+    }
+    /**
+     * Discard everything `restore(executionId)` would have used — the snapshot *and* the
+     * step-completion ledger — so the next run of that execution starts clean.
+     *
+     * Hosts must call this rather than resume when the workflow itself changed. A resumed
+     * run replays at the coarsest completed granularity: a parent step that finished
+     * replays wholesale, so an edit to one of its children is never noticed and the stale
+     * output wins. Divergence detection only catches a changed step *at* a recorded path.
+     *
+     * Also the right call after a terminal outcome (the execution finished, or the user
+     * abandoned it) — `CheckpointStore.clear` alone leaves the ledger's per-step keys
+     * behind, and nothing else enumerates them.
+     */
+    async clearCheckpoint(executionId) {
+        return clearCheckpoint(this, executionId);
     }
     //#endregion
-    async cancel(_ctx, _reason) { }
+    /**
+     * Cancel an execution: abort `ctx` and every live descendant context, then
+     * run the memory-layer teardown for each (spec 09, Cancellation).
+     *
+     * The abort itself fans out top-down and synchronously — `ctx.abort()`
+     * cascades into every live fork path and spawn child, so no corner of the
+     * tree keeps working while cleanup is in progress. Cleanup then runs
+     * bottom-up: a child's `onComplete` / `dispose` fires before its parent's.
+     *
+     * Aborting a context rejects everything blocked on it (channel `recv`
+     * waiters, parked senders) with `{ kind: 'cancelled' }`, stops its in-flight
+     * model call and sub-harness turn, and makes the next step boundary throw
+     * `cancelled`.
+     *
+     * Cancellation is cooperative: a layer hook already in flight is allowed to
+     * settle, and step code that ignores `ctx.aborted` between `await`s runs to
+     * its next boundary. Calling `cancel()` on an already-cancelled context is a
+     * no-op.
+     */
+    async cancel(ctx, reason) {
+        if (ctx.aborted) {
+            return;
+        }
+        // Snapshot the tree first: `abort()` cascades and clears each context's
+        // child registry, so collecting afterwards would find nothing.
+        const tree = collectContextTree(ctx);
+        ctx.abort(reason);
+        for (const node of tree.reverse()) {
+            await this.teardownCancelledContext(node);
+        }
+    }
+    /**
+     * Run the layer lifecycle's abort path for one cancelled context:
+     * `onComplete` with `outcome: 'aborted'`, then `dispose`. Both always run
+     * under cancellation (spec 09, Cancellation item 5).
+     */
+    async teardownCancelledContext(ctx) {
+        const layers = ctx.layers ?? [];
+        if (layers.length === 0) {
+            return;
+        }
+        await completeLayers({
+            layers: [
+                ...layers,
+            ],
+            ctx: this.toExecCtx(ctx),
+            log: ctx.itemLog,
+            outcome: 'aborted',
+            store: this.layerStateStore,
+        });
+        await this.disposeLayers([
+            ...layers,
+        ], ctx);
+    }
     createSpan(name, parent) {
         return new SpanImpl(name, parent);
     }

package/dist/harness/deps/memory.d.ts

@@ -1,2 +1,2 @@
 export type { LayerStateStore, RecallCache } from '@noetic-tools/memory';
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/memory';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/memory';

package/dist/harness/deps/memory.js

@@ -1 +1 @@
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/memory';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/memory';

package/dist/harness/deps/runtime.d.ts

@@ -1,10 +1,11 @@
 export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl } from '../../runtime/context-impl.js';
+export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export type { CheckpointStore } from '../../runtime/durable/index.js';
-export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
-export type { StepLedgerEntry, StepLedgerStore } from '../../runtime/durable/step-ledger.js';
-export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
+export type { RestoreCheckpointOptions } from '../../runtime/durable/harness-checkpoints.js';
+export { captureCheckpoint, clearCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export type { StepLedgerEntry, StepLedgerRetention, StepLedgerStore, } from '../../runtime/durable/step-ledger.js';
+export { createStepLedgerStore, resolveStepLedgerRetention, StepLedger, } from '../../runtime/durable/step-ledger.js';
 export type { EventBroadcaster } from '../../runtime/event-broadcaster.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export type { QueuedMessage } from '../../runtime/message-queue.js';

package/dist/harness/deps/runtime.js

@@ -1,8 +1,8 @@
 export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl } from '../../runtime/context-impl.js';
+export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
-export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
-export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
+export { captureCheckpoint, clearCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export { createStepLedgerStore, resolveStepLedgerRetention, StepLedger, } from '../../runtime/durable/step-ledger.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export { SessionRunner } from '../../runtime/session-runner.js';
 export { buildItemStream, filterReasoningStream, filterTextStream, } from '../../runtime/session-streams.js';

package/dist/index.d.ts

@@ -100,9 +100,9 @@ export { react } from './patterns/react.js';
 /** @public */
 export { AgentHarness } from './harness/agent-harness.js';
 /** @public */
-export type { AfterFirstTurnContext, CheckpointStore, CreateCheckpointStoreOptions, CreateNudgeMessageOpts, DetachedSignal, RunnableLoopHarness, RunnableLoopOpts, SessionSeedHarness, StallNudgeOpts, } from './runtime/durable/index.js';
+export type { AfterFirstTurnContext, CheckpointStore, CreateCheckpointStoreOptions, CreateNudgeMessageOpts, DetachedSignal, RunnableLoopHarness, RunnableLoopOpts, SessionSeedHarness, StallNudgeOpts, StepLedgerRetention, StepLedgerStats, } from './runtime/durable/index.js';
 /** @public */
-export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
+export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, DEFAULT_STEP_LEDGER_RETENTION, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
 /** @public */
 export { getRegistry, lookupStep, registerStep } from './runtime/step-registry.js';
 /** @public */
@@ -121,7 +121,7 @@ export { isServerToolSpec } from '@noetic-tools/types';
 /** @public */
 /** @public */
 /** @public */
-export type { Context, ContextHarness, CwdState, ItemLog, LastLayerUsage, LayerUsageEntry, } from '@noetic-tools/types';
+export type { Context, ContextHarness, CwdState, ItemLog, LastLayerUsage, LayerUsageEntry, RestoreContextOptions, } from '@noetic-tools/types';
 /** @public */
 export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers.js';
 /** @public */

package/dist/index.js

@@ -88,7 +88,7 @@ export { react } from './patterns/react.js';
 /** @public */
 export { AgentHarness } from './harness/agent-harness.js';
 /** @public */
-export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
+export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, DEFAULT_STEP_LEDGER_RETENTION, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
 /** @public */
 export { getRegistry, lookupStep, registerStep } from './runtime/step-registry.js';
 //#endregion

package/dist/interpreter/execute-action.js

@@ -9,7 +9,7 @@ import { isServerToolSpec, SteeringAction } from './action-types.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
 import { trackUsage } from './message-helpers.js';
-import { getContextChannelStore, isFunctionCall, isMutableContext } from './typeguards.js';
+import { getContextChannelStore, isContextImpl, isFunctionCall, isMutableContext, } from './typeguards.js';
 //#region run
 export async function executeRun(step, input, ctx) {
     const retry = step.retry;
@@ -400,6 +400,11 @@ export async function executeLLM(step, input, ctx, layers) {
                     ];
         }
         const _serverTools = serverToolSpecs.length > 0 ? serverToolSpecs : undefined;
+        // Cancellation reaches INSIDE the model call, not just the step boundary:
+        // the caller's abort signal stops the stream and the tool-round loop mid
+        // flight, so `ctx.abort()` / `harness.cancel()` don't wait out a long
+        // generation before taking effect (spec 09, Cancellation item 2).
+        const signal = isContextImpl(baseCtx) ? baseCtx.abortSignal : undefined;
         const request = resolvedTools
             ? {
                 model: resolvedModel,
@@ -415,6 +420,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 allowedToolNames,
                 nodeId: step.id,
                 parentSpan: baseCtx.span,
+                signal,
             }
             : {
                 model: resolvedModel,
@@ -426,6 +432,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 _serverTools,
                 nodeId: step.id,
                 parentSpan: baseCtx.span,
+                signal,
             };
         const response = await baseCtx.harness.callModel(request);
         // Track tokens/cost for EVERY model call, including responses steering
@@ -433,6 +440,15 @@ export async function executeLLM(step, input, ctx, layers) {
         // real, and until.maxCost / HarnessResponse.usage must see it (spec 07:
         // tokens accumulate across all LLM calls).
         trackUsage(baseCtx, response);
+        // An abort that landed mid-call returns whatever rounds completed before
+        // the signal fired. The spend is charged above, but a truncated generation
+        // is not this step's output — surface cancellation instead.
+        if (baseCtx.aborted) {
+            throw new NoeticErrorImpl({
+                kind: 'cancelled',
+                reason: baseCtx.abortReason ?? 'context aborted',
+            });
+        }
         if (hasLayers) {
             const decision = await baseCtx.harness.afterModelCall(layers, response, baseCtx);
             if (decision.action === SteeringAction.Deny) {
@@ -624,6 +640,9 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
         if (hasLayers) {
             layerStore.cleanup(childExecutionCtx.executionId);
         }
+        // The child is settled: leave the parent's abort cascade so a parent that
+        // outlives many spawns does not retain every finished child.
+        childCtx.detachFromParent();
     }
 }
 //#endregion

package/dist/interpreter/execute-control.js

@@ -143,21 +143,30 @@ export async function executeFork(step, input, ctx, rawExecuteStep, opts) {
         childContexts,
         opts,
     }));
-    switch (step.mode) {
-        case 'all':
-            return executeAll(step, paths, input, ctx, childContexts, executeStep, concurrency);
-        case 'race':
-            return executeRace(step, paths, input, ctx, childContexts, executeStep, concurrency);
-        case 'settle':
-            return executeSettle(step, paths, input, ctx, childContexts, executeStep, concurrency);
-        default: {
-            const _exhaustive = step;
-            throw new NoeticErrorImpl({
-                kind: 'step_failed',
-                stepId: 'unknown',
-                cause: new Error('Unknown fork mode'),
-                retriesExhausted: false,
-            });
+    try {
+        switch (step.mode) {
+            case 'all':
+                return await executeAll(step, paths, input, ctx, childContexts, executeStep, concurrency);
+            case 'race':
+                return await executeRace(step, paths, input, ctx, childContexts, executeStep, concurrency);
+            case 'settle':
+                return await executeSettle(step, paths, input, ctx, childContexts, executeStep, concurrency);
+            default: {
+                const _exhaustive = step;
+                throw new NoeticErrorImpl({
+                    kind: 'step_failed',
+                    stepId: 'unknown',
+                    cause: new Error('Unknown fork mode'),
+                    retriesExhausted: false,
+                });
+            }
+        }
+    }
+    finally {
+        // Every path has settled (or been abandoned in `race`): leave the parent's
+        // abort cascade so it retains only children that are still cancellable.
+        for (const child of childContexts) {
+            child.detachFromParent();
         }
     }
 }

package/dist/interpreter/execute-sub-harness.js

@@ -9,7 +9,7 @@ import { ZodError } from 'zod';
 import { resolveLazy } from './execute-action.js';
 import { trackUsage } from './message-helpers.js';
 import { SubHarnessEventBridge } from './sub-harness-events.js';
-import { isFunctionCall, isMutableContext } from './typeguards.js';
+import { isContextImpl, isFunctionCall, isMutableContext } from './typeguards.js';
 //#endregion
 //#region Helpers
 function sessionStore(ctx) {
@@ -39,6 +39,14 @@ function resolveTurnText(resolvedPrompt, input) {
     }
     return typeof input === 'string' ? input : '';
 }
+/**
+ * Abort signal of the executing context, when it is a framework context. Handed
+ * to the adapter so `ctx.abort()` / `harness.cancel()` stops the coding agent's
+ * in-flight turn instead of leaving a sub-process running until it finishes.
+ */
+function abortSignalOf(ctx) {
+    return isContextImpl(ctx) ? ctx.abortSignal : undefined;
+}
 function buildRunContext(ctx) {
     return {
         cwd: ctx.cwdState.cwd,
@@ -46,6 +54,7 @@ function buildRunContext(ctx) {
         shell: ctx.shell,
         subprocess: ctx.subprocess,
         threadId: ctx.threadId,
+        signal: abortSignalOf(ctx),
     };
 }
 function toLlmResponse(result) {
@@ -108,6 +117,7 @@ async function startOrReuseSession(step, harness, ctx, baseCtx, history) {
         instructions: await resolveLazy(step.instructions, ctx),
         history,
         ctx: buildRunContext(baseCtx),
+        signal: abortSignalOf(baseCtx),
     });
     if (reuseKey) {
         store.set(reuseKey, session);
@@ -167,6 +177,9 @@ export async function executeSubHarness(step, input, ctx) {
         result = await resolution.session.doPromptTurn({
             prompt: turnText,
             emit: (part) => bridge.forward(part),
+            // Per-turn signal, so a session reused across turns is cancelled by the
+            // context running the CURRENT turn rather than the one that started it.
+            signal: abortSignalOf(baseCtx),
         });
     }
     catch (e) {
@@ -178,6 +191,14 @@ export async function executeSubHarness(step, input, ctx) {
         if (e instanceof NoeticErrorImpl) {
             throw e;
         }
+        // An adapter interrupted by the abort signal rejects with whatever its SDK
+        // throws; the context is the authority on why the turn ended.
+        if (baseCtx.aborted) {
+            throw new NoeticErrorImpl({
+                kind: 'cancelled',
+                reason: baseCtx.abortReason ?? 'context aborted',
+            });
+        }
         throw new NoeticErrorImpl({
             kind: 'step_failed',
             stepId: step.id,

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

@@ -1,5 +1,12 @@
 import type { AgentHarnessContract, Channel, ChannelStore, Context, ContextMemory, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, ItemSchemaRegistry, LastLayerUsage, MemoryLayer, Span, StepMeta, TokenUsage, Tool } from './context-deps.js';
 import type { StepLedger } from './durable/step-ledger.js';
+/**
+ * @internal
+ * The cancellation tree rooted at `ctx`, in pre-order (a parent before its
+ * children). Reverse it to walk deepest-first. Only framework contexts track
+ * children, so a foreign `Context` implementation yields just itself.
+ */
+export declare function collectContextTree(ctx: Context): Context[];
 export declare class ContextImpl implements Context<ContextMemory> {
     readonly id: string;
     stepCount: number;
@@ -41,9 +48,18 @@ export declare class ContextImpl implements Context<ContextMemory> {
      * 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.
+     * aborting a child never rejects the parent's waiters, while aborting a
+     * parent DOES cascade down to every live child (see `_children`).
      */
     private readonly _abortController;
+    /**
+     * Live child contexts (fork paths, spawn children) registered for the abort
+     * cascade. A child adds itself at construction and removes itself via
+     * `detachFromParent()` when its execution settles, so a long-lived parent
+     * driving a loop of spawns does not accumulate finished children.
+     * @internal
+     */
+    private readonly _children;
     private _memory?;
     /**
      * Stack of steps currently in flight on this context, most-recent last.
@@ -107,6 +123,27 @@ export declare class ContextImpl implements Context<ContextMemory> {
          */
         id?: string;
     });
+    /**
+     * @internal
+     * Register `child` for the abort cascade. A child constructed under an
+     * already-aborted parent is aborted immediately — otherwise a spawn issued
+     * in the window between `abort()` and the interpreter noticing would run a
+     * whole sub-agent that nothing can stop.
+     */
+    private adoptChild;
+    /**
+     * @internal
+     * Leave the parent's abort cascade. Called by the interpreter when a spawn
+     * child or fork path settles — a finished child has nothing left to cancel,
+     * and holding it would leak for the remaining life of the parent.
+     */
+    detachFromParent(): void;
+    /**
+     * @internal
+     * Live child contexts, in registration order. Consumed by
+     * `AgentHarness.cancel` to walk the execution tree depth-first.
+     */
+    get children(): ReadonlyArray<ContextImpl>;
     get elapsed(): number;
     get aborted(): boolean;
     get fs(): FsAdapter;

package/dist/runtime/context-impl.js

@@ -9,6 +9,24 @@ class NoopSpan {
     addEvent(_name, _attributes) { }
     end() { }
 }
+/**
+ * @internal
+ * The cancellation tree rooted at `ctx`, in pre-order (a parent before its
+ * children). Reverse it to walk deepest-first. Only framework contexts track
+ * children, so a foreign `Context` implementation yields just itself.
+ */
+export function collectContextTree(ctx) {
+    const tree = [
+        ctx,
+    ];
+    if (!(ctx instanceof ContextImpl)) {
+        return tree;
+    }
+    for (const child of ctx.children) {
+        tree.push(...collectContextTree(child));
+    }
+    return tree;
+}
 export class ContextImpl {
     id;
     stepCount = 0;
@@ -54,9 +72,18 @@ export class ContextImpl {
      * 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.
+     * aborting a child never rejects the parent's waiters, while aborting a
+     * parent DOES cascade down to every live child (see `_children`).
      */
     _abortController = new AbortController();
+    /**
+     * Live child contexts (fork paths, spawn children) registered for the abort
+     * cascade. A child adds itself at construction and removes itself via
+     * `detachFromParent()` when its execution settles, so a long-lived parent
+     * driving a loop of spawns does not accumulate finished children.
+     * @internal
+     */
+    _children = new Set();
     _memory;
     /**
      * Stack of steps currently in flight on this context, most-recent last.
@@ -120,6 +147,46 @@ export class ContextImpl {
             }
         }
         this.itemLog = log;
+        // Join the parent's abort cascade last, so the child is fully constructed
+        // before an already-aborted parent aborts it.
+        if (this.parent instanceof ContextImpl) {
+            this.parent.adoptChild(this);
+        }
+    }
+    /**
+     * @internal
+     * Register `child` for the abort cascade. A child constructed under an
+     * already-aborted parent is aborted immediately — otherwise a spawn issued
+     * in the window between `abort()` and the interpreter noticing would run a
+     * whole sub-agent that nothing can stop.
+     */
+    adoptChild(child) {
+        if (this._aborted) {
+            child.abort(this._abortReason ?? 'parent context aborted');
+            return;
+        }
+        this._children.add(child);
+    }
+    /**
+     * @internal
+     * Leave the parent's abort cascade. Called by the interpreter when a spawn
+     * child or fork path settles — a finished child has nothing left to cancel,
+     * and holding it would leak for the remaining life of the parent.
+     */
+    detachFromParent() {
+        if (this.parent instanceof ContextImpl) {
+            this.parent._children.delete(this);
+        }
+    }
+    /**
+     * @internal
+     * Live child contexts, in registration order. Consumed by
+     * `AgentHarness.cancel` to walk the execution tree depth-first.
+     */
+    get children() {
+        return [
+            ...this._children,
+        ];
     }
     get elapsed() {
         return Date.now() - this._createdAt;
@@ -184,12 +251,26 @@ export class ContextImpl {
         return this._abortReason;
     }
     abort(reason) {
+        if (this._aborted) {
+            // Idempotent (spec 09): the first abort owns the reason, and the signal
+            // has already fired — re-firing it would be a no-op anyway.
+            return;
+        }
         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.
+        // parked back-pressure senders) with { kind: 'cancelled' }.
         this._abortController.abort(reason ?? 'context aborted');
+        // Cascade to live children (fork paths, spawn children). The registry is
+        // cleared first so a child's own `detachFromParent()` during its unwind
+        // cannot mutate the set we are iterating.
+        const children = [
+            ...this._children,
+        ];
+        this._children.clear();
+        for (const child of children) {
+            child.abort(reason ?? 'parent context aborted');
+        }
     }
     /**
      * @internal

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

@@ -1,7 +1,20 @@
 import type { LayerStateStore, MemoryLayer } from '@noetic-tools/memory';
-import type { Context, Item, ItemSchemaRegistry } from '@noetic-tools/types';
+import type { Context, Item, ItemSchemaRegistry, RestoreContextOptions } from '@noetic-tools/types';
+import type { EventBroadcaster } from '../event-broadcaster.js';
 import type { CheckpointStore } from './checkpoint-store.js';
-import type { StepLedgerStore } from './step-ledger.js';
+import type { StepLedgerRetention, StepLedgerStore } from './step-ledger.js';
+/**
+ * Host wiring forwarded into the context `restoreFromCheckpoint` builds.
+ * `RestoreContextOptions` covers the portable fields; core widens it with the
+ * internal `_broadcaster` seam so a resumed turn keeps streaming framework UI
+ * events.
+ *
+ * @internal
+ */
+export type RestoreCheckpointOptions = RestoreContextOptions & {
+    /** @internal Event broadcaster the host attached to the original context. */
+    _broadcaster?: EventBroadcaster;
+};
 /**
  * Minimum harness surface `captureCheckpoint` / `restoreFromCheckpoint`
  * require. `AgentHarness` already satisfies this shape via its
@@ -13,15 +26,15 @@ import type { StepLedgerStore } from './step-ledger.js';
 export interface CheckpointHarnessHandle {
     readonly checkpointStore?: CheckpointStore;
     readonly stepLedgerStore?: StepLedgerStore;
+    readonly stepLedgerRetention?: StepLedgerRetention;
     readonly layerStateStore: LayerStateStore;
     readonly itemSchemas: ItemSchemaRegistry;
     readonly _memory?: MemoryLayer[];
-    createContext(opts?: {
+    createContext(opts?: RestoreCheckpointOptions & {
         items?: Item[];
         threadId?: string;
         resourceId?: string;
         cwdInit?: string;
-        memory?: MemoryLayer[];
     }): Context;
 }
 /**
@@ -41,10 +54,31 @@ export declare function captureCheckpoint(h: CheckpointHarnessHandle, ctx: Conte
  * the restored context observes the pre-crash state through
  * `readLayerState` and the memory projectors.
  *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state,
+ * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
+ * objects, so a host that decorated the original context has to hand the same
+ * decoration back here — otherwise the resumed run gets a bare context and
+ * whatever depended on that wiring stops working silently. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted
+ * record, never from `opts`.
+ *
  * Preserves the original executionId on the returned context via
  * `Object.defineProperty` — adapter correlation across crash/restart
  * requires a stable id.
  *
  * @internal
  */
-export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string): Promise<Context | null>;
+export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
+/**
+ * Discard every recovery record for one execution: the snapshot and the completion
+ * ledger. Clearing the snapshot alone would strand the ledger's shards under
+ * `execution:<id>:ledger:*` forever, since nothing else enumerates them.
+ *
+ * This is the operation a host performs when resume is no longer valid — most often
+ * because the workflow changed. Replay happens at the coarsest completed granularity,
+ * so a step edited *beneath* a recorded parent is invisible to divergence detection and
+ * the old output would be replayed over the new tree. Clear, then start fresh.
+ *
+ * @internal
+ */
+export declare function clearCheckpoint(h: CheckpointHarnessHandle, executionId: string): Promise<void>;

package/dist/runtime/durable/harness-checkpoints.js

@@ -65,13 +65,21 @@ export async function captureCheckpoint(h, ctx) {
  * the restored context observes the pre-crash state through
  * `readLayerState` and the memory projectors.
  *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state,
+ * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
+ * objects, so a host that decorated the original context has to hand the same
+ * decoration back here — otherwise the resumed run gets a bare context and
+ * whatever depended on that wiring stops working silently. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted
+ * record, never from `opts`.
+ *
  * Preserves the original executionId on the returned context via
  * `Object.defineProperty` — adapter correlation across crash/restart
  * requires a stable id.
  *
  * @internal
  */
-export async function restoreFromCheckpoint(h, executionId) {
+export async function restoreFromCheckpoint(h, executionId, opts) {
     const store = h.checkpointStore;
     if (!store) {
         return null;
@@ -85,12 +93,16 @@ export async function restoreFromCheckpoint(h, executionId) {
     }
     const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
     const cwdInit = snapshot.cwd?.current ?? undefined;
+    /* Caller wiring first, snapshot second: a host may legitimately swap the memory
+     * layers or hang the restored execution under a new parent, but it must never be
+     * able to override the identity/history the snapshot is the record of. */
     const ctx = h.createContext({
+        ...opts,
         items,
         threadId: snapshot.threadId,
         resourceId: snapshot.resourceId,
         cwdInit,
-        memory: h._memory,
+        memory: opts?.memory ?? h._memory,
     });
     if (ctx instanceof ContextImpl) {
         Object.defineProperty(ctx, 'id', {
@@ -111,6 +123,7 @@ export async function restoreFromCheckpoint(h, executionId) {
                     executionId,
                     store: h.stepLedgerStore,
                     recovered,
+                    retention: h.stepLedgerRetention,
                 }),
                 configurable: false,
                 writable: false,
@@ -121,3 +134,21 @@ export async function restoreFromCheckpoint(h, executionId) {
     return ctx;
 }
 //#endregion
+//#region clearCheckpoint
+/**
+ * Discard every recovery record for one execution: the snapshot and the completion
+ * ledger. Clearing the snapshot alone would strand the ledger's shards under
+ * `execution:<id>:ledger:*` forever, since nothing else enumerates them.
+ *
+ * This is the operation a host performs when resume is no longer valid — most often
+ * because the workflow changed. Replay happens at the coarsest completed granularity,
+ * so a step edited *beneath* a recorded parent is invisible to divergence detection and
+ * the old output would be replayed over the new tree. Clear, then start fresh.
+ *
+ * @internal
+ */
+export async function clearCheckpoint(h, executionId) {
+    await h.checkpointStore?.clear(executionId);
+    await h.stepLedgerStore?.clear(executionId);
+}
+//#endregion

package/dist/runtime/durable/index.d.ts

@@ -8,3 +8,5 @@ export type { SessionSeedHarness } from './session-seed.js';
 export { seedFromItems } from './session-seed.js';
 export type { CreateNudgeMessageOpts, StallNudgeOpts } from './stall-nudge.js';
 export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge.js';
+export type { StepLedgerRetention, StepLedgerStats } from './step-ledger.js';
+export { DEFAULT_STEP_LEDGER_RETENTION } from './step-ledger.js';

package/dist/runtime/durable/index.js

@@ -3,3 +3,4 @@ export { createDetachedSignal } from './detached-signal.js';
 export { runnableLoop } from './runnable-loop.js';
 export { seedFromItems } from './session-seed.js';
 export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge.js';
+export { DEFAULT_STEP_LEDGER_RETENTION } from './step-ledger.js';

package/dist/runtime/durable/step-ledger.d.ts

@@ -10,6 +10,12 @@
  * Entries are stored one key per step so appends are O(1). Folding the whole ledger
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
+ *
+ * Sharding bounds the cost of one append but not the total, so retention is bounded on
+ * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
+ * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
+ * construction — a missing entry re-runs its step, which costs work rather than
+ * correctness.
  */
 import type { StorageAdapter } from '@noetic-tools/memory';
 import { z } from 'zod';
@@ -23,46 +29,128 @@ export declare const StepLedgerEntrySchema: z.ZodObject<{
 }, z.core.$strip>;
 /** @public A completed step recorded for replay. */
 export type StepLedgerEntry = z.infer<typeof StepLedgerEntrySchema>;
+/**
+ * @public
+ * Bounds on what one execution's ledger retains. Both caps degrade resume rather than
+ * break it: a step with no entry simply runs again, so the worst case is repeated work
+ * (and repeated side effects — see `specs/23a-step-level-resume` § "The side-effect
+ * boundary"), never a replayed value that disagrees with the recorded run.
+ */
+export interface StepLedgerRetention {
+    /**
+     * Largest output, in UTF-8 bytes of its JSON encoding, that will be recorded. A step
+     * whose output exceeds this is not recorded at all and re-runs on resume. Keeps one
+     * entry inside the per-value limit real storage backends impose (128 KiB on several)
+     * instead of failing the write. Pass `Infinity` to record any size.
+     *
+     * Defaults to `DEFAULT_STEP_LEDGER_RETENTION.maxEntryBytes` (128 KiB).
+     */
+    maxEntryBytes?: number;
+    /**
+     * Most entries retained for one execution. Recording past the cap evicts the oldest
+     * entry, so resume is best-effort over a bounded *suffix* of the run: the tail of the
+     * work is skipped, the head runs again. Pass `Infinity` to retain every entry.
+     *
+     * Defaults to `DEFAULT_STEP_LEDGER_RETENTION.maxEntries` (1000).
+     */
+    maxEntries?: number;
+}
+/** @public Retention applied when a harness does not configure `stepLedgerRetention`. */
+export declare const DEFAULT_STEP_LEDGER_RETENTION: {
+    readonly maxEntryBytes: number;
+    readonly maxEntries: 1000;
+};
+/**
+ * @public
+ * Fill in defaults and reject nonsense. Validating loudly matters because every
+ * misconfiguration here fails *silently* at runtime — a negative cap would drop every
+ * entry and the run would look fine while resuming nothing.
+ *
+ * @throws NoeticConfigError `code: 'STEP_LEDGER_RETENTION_INVALID'`
+ */
+export declare function resolveStepLedgerRetention(retention?: StepLedgerRetention): Required<StepLedgerRetention>;
 /** Storage key prefix owning every ledger entry for one execution. */
 export declare function stepLedgerPrefix(executionId: string): string;
+/**
+ * @public
+ * Everything one execution's ledger recovered from storage: the entries available for
+ * replay plus the sequence bookkeeping a further append needs. `nextSeq` cannot be
+ * derived from `entries.size` — retention leaves gaps, and reusing a live sequence
+ * number would overwrite an entry the resumed run still has to replay.
+ */
+export interface StepLedgerWindow {
+    /** Recovered entries, keyed by execution path. Corrupt rows are skipped. */
+    entries: Map<string, StepLedgerEntry>;
+    /** Sequence number the next append takes: highest recorded, plus one. */
+    nextSeq: number;
+    /** Lowest sequence number still in storage — where eviction resumes. */
+    oldestSeq: number;
+}
 /**
  * @public
  * Durable append-only ledger for one harness's executions. Backed by the same
  * `StorageAdapter` as the checkpoint store; it reserves the `:ledger:` suffix that
  * `CheckpointKeys` already sets aside.
+ *
+ * The store owns the key layout only. Retention policy lives in `StepLedger`, which
+ * holds the per-execution sequence cursor that eviction needs.
  */
 export interface StepLedgerStore {
     /** Record a completed step. Sequence numbers order entries within an execution. */
     append: (executionId: string, seq: number, entry: StepLedgerEntry) => Promise<void>;
-    /** Every recorded entry for an execution, keyed by path. Corrupt rows are skipped. */
-    load: (executionId: string) => Promise<Map<string, StepLedgerEntry>>;
+    /** Drop one entry by sequence number. No-op when the key is absent. */
+    delete: (executionId: string, seq: number) => Promise<void>;
+    /** Everything recorded for an execution, plus its sequence bounds. */
+    load: (executionId: string) => Promise<StepLedgerWindow>;
     /** Drop an execution's ledger (paired with `CheckpointStore.clear`). */
     clear: (executionId: string) => Promise<void>;
 }
 export declare function createStepLedgerStore(opts: {
     storage: StorageAdapter;
 }): StepLedgerStore;
+/** @public What retention did to one execution's ledger. Observable for host logging. */
+export interface StepLedgerStats {
+    /** Entries written. */
+    recorded: number;
+    /** Entries not written because their output exceeded `maxEntryBytes`. */
+    droppedOversize: number;
+    /** Entries not written because their output does not survive JSON encoding. */
+    droppedUnserialisable: number;
+    /** Entries deleted to stay within `maxEntries`. */
+    evicted: number;
+}
 /**
  * @public
  * The in-memory ledger a single execution carries: entries recovered from a previous
  * run (available for replay) plus the sequence counter for newly recorded ones.
  *
  * Shared by reference across fork/spawn children so one execution has one ledger —
- * path keys are globally unique across the step tree, so a flat map is correct.
+ * path keys are globally unique across the step tree, so a flat map is correct. That
+ * sharing is also why retention lives here rather than in the store: the sequence
+ * cursor eviction walks belongs to the execution, not to the harness.
  */
 export declare class StepLedger {
     /** Recovered entries, by path. Consumed as replay proceeds. */
     private readonly replayable;
+    /** Sequence number the next recorded entry takes. */
     private seq;
+    /** Lowest sequence number still in storage — advances as eviction proceeds. */
+    private oldestSeq;
     private readonly store?;
     private readonly executionId;
+    private readonly retention;
+    private readonly counts;
     constructor(opts: {
         executionId: string;
         store?: StepLedgerStore;
-        recovered?: Map<string, StepLedgerEntry>;
+        /** What `StepLedgerStore.load` recovered. Absent on a fresh execution. */
+        recovered?: StepLedgerWindow;
+        retention?: StepLedgerRetention;
     });
     /** True when this execution has nothing recovered to replay (the common, fresh case). */
     get isEmpty(): boolean;
+    /** What retention has done so far. A snapshot — safe to hold. */
+    get stats(): StepLedgerStats;
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
      * A divergence (different step id or kind at this path) discards the entry and every
@@ -77,4 +165,18 @@ export declare class StepLedger {
     private discardSubtree;
     /** Record a completed step. Best-effort: a failed write costs resumability, not the run. */
     record(entry: StepLedgerEntry): Promise<void>;
+    /**
+     * Whether this entry is small enough — and encodable at all — to be worth a write.
+     * An output no adapter could serialise is treated exactly like an oversized one:
+     * not recorded, so the step re-runs.
+     */
+    private retainable;
+    /**
+     * Delete oldest-first until the execution is back inside `maxEntries`. The bound is on
+     * the sequence *window* rather than an exact row count, which is what keeps this
+     * correct without a `list()` per append.
+     */
+    private evictOverflow;
+    /** One warning per reason per execution — a long run would otherwise flood the log. */
+    private warnOnFirstDrop;
 }

package/dist/runtime/durable/step-ledger.js

@@ -10,9 +10,17 @@
  * Entries are stored one key per step so appends are O(1). Folding the whole ledger
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
+ *
+ * Sharding bounds the cost of one append but not the total, so retention is bounded on
+ * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
+ * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
+ * construction — a missing entry re-runs its step, which costs work rather than
+ * correctness.
  */
 import { storageGetMany } from '@noetic-tools/memory';
+import { NoeticConfigError } from '@noetic-tools/types';
 import { z } from 'zod';
+//#region Entry
 /** @public One completed step, keyed by its execution path. */
 export const StepLedgerEntrySchema = z.object({
     /** Execution path key — see `ContextImpl.currentPath()`. Unique per dispatch. */
@@ -23,6 +31,55 @@ export const StepLedgerEntrySchema = z.object({
     output: z.unknown(),
     completedAt: z.string(),
 });
+/** @public Retention applied when a harness does not configure `stepLedgerRetention`. */
+export const DEFAULT_STEP_LEDGER_RETENTION = {
+    maxEntryBytes: 128 * 1024,
+    maxEntries: 1e3,
+};
+/**
+ * @public
+ * Fill in defaults and reject nonsense. Validating loudly matters because every
+ * misconfiguration here fails *silently* at runtime — a negative cap would drop every
+ * entry and the run would look fine while resuming nothing.
+ *
+ * @throws NoeticConfigError `code: 'STEP_LEDGER_RETENTION_INVALID'`
+ */
+export function resolveStepLedgerRetention(retention) {
+    const resolved = {
+        maxEntryBytes: retention?.maxEntryBytes ?? DEFAULT_STEP_LEDGER_RETENTION.maxEntryBytes,
+        maxEntries: retention?.maxEntries ?? DEFAULT_STEP_LEDGER_RETENTION.maxEntries,
+    };
+    for (const [field, value] of Object.entries(resolved)) {
+        if (value === Number.POSITIVE_INFINITY) {
+            continue;
+        }
+        if (!Number.isFinite(value) || value < 1) {
+            throw new NoeticConfigError({
+                code: 'STEP_LEDGER_RETENTION_INVALID',
+                message: `stepLedgerRetention.${field} must be a positive number or Infinity (received ${String(value)}).`,
+                hint: 'Omit the field to accept the default, or pass Infinity to disable the cap.',
+            });
+        }
+    }
+    return resolved;
+}
+/**
+ * Whether `json` fits `cap` UTF-8 bytes. A UTF-16 code unit encodes to between 1 and 3
+ * UTF-8 bytes (a surrogate pair is 2 units → 4 bytes, i.e. 2 per unit), so string
+ * length brackets the byte count and decides most calls without encoding a megabyte
+ * of output just to measure it.
+ */
+function fitsByteCap(json, cap) {
+    if (json.length > cap) {
+        return false;
+    }
+    if (json.length * 3 <= cap) {
+        return true;
+    }
+    return new TextEncoder().encode(json).length <= cap;
+}
+//#endregion
+//#region Store
 /** Storage key prefix owning every ledger entry for one execution. */
 export function stepLedgerPrefix(executionId) {
     return `execution:${executionId}:ledger:`;
@@ -31,22 +88,43 @@ export function stepLedgerPrefix(executionId) {
 function seqKey(executionId, seq) {
     return `${stepLedgerPrefix(executionId)}${String(seq).padStart(8, '0')}`;
 }
+/** The sequence number a ledger key carries, or null when the suffix is not one. */
+function seqFromKey(executionId, key) {
+    const prefix = stepLedgerPrefix(executionId);
+    if (!key.startsWith(prefix)) {
+        return null;
+    }
+    const seq = Number(key.slice(prefix.length));
+    return Number.isInteger(seq) && seq >= 0 ? seq : null;
+}
 export function createStepLedgerStore(opts) {
     const { storage } = opts;
     return {
         append: async (executionId, seq, entry) => {
             await storage.set(seqKey(executionId, seq), entry);
         },
+        delete: async (executionId, seq) => {
+            await storage.delete(seqKey(executionId, seq));
+        },
         load: async (executionId) => {
             const keys = await storage.list(stepLedgerPrefix(executionId));
             /* One batch read, not one round trip per completed step. Recovery is the
              * moment a network-backed adapter can least afford an N+1. */
-            const entries = await storageGetMany(storage, keys);
-            const byPath = new Map();
+            const raws = await storageGetMany(storage, keys);
+            const entries = new Map();
+            /* Sequence bounds come from the KEYS, not the parsed rows: a row that fails to
+             * parse still occupies its key, so it must not be handed back out as reusable. */
+            let highestSeq = -1;
+            let oldestSeq = -1;
             // Walk `keys`, not the map: `seqKey`'s zero-padding makes `list()` order
             // dispatch order, and a later entry at a path must win over an earlier one.
             for (const key of keys) {
-                const raw = entries.get(key);
+                const seq = seqFromKey(executionId, key);
+                if (seq !== null) {
+                    highestSeq = Math.max(highestSeq, seq);
+                    oldestSeq = oldestSeq === -1 ? seq : Math.min(oldestSeq, seq);
+                }
+                const raw = raws.get(key);
                 if (raw === undefined) {
                     continue;
                 }
@@ -57,9 +135,13 @@ export function createStepLedgerStore(opts) {
                     console.warn(`StepLedger: discarding unreadable entry "${key}": ${parsed.error.message}`);
                     continue;
                 }
-                byPath.set(parsed.data.path, parsed.data);
+                entries.set(parsed.data.path, parsed.data);
             }
-            return byPath;
+            return {
+                entries,
+                nextSeq: highestSeq + 1,
+                oldestSeq: oldestSeq === -1 ? 0 : oldestSeq,
+            };
         },
         clear: async (executionId) => {
             const keys = await storage.list(stepLedgerPrefix(executionId));
@@ -75,24 +157,44 @@ export function createStepLedgerStore(opts) {
  * run (available for replay) plus the sequence counter for newly recorded ones.
  *
  * Shared by reference across fork/spawn children so one execution has one ledger —
- * path keys are globally unique across the step tree, so a flat map is correct.
+ * path keys are globally unique across the step tree, so a flat map is correct. That
+ * sharing is also why retention lives here rather than in the store: the sequence
+ * cursor eviction walks belongs to the execution, not to the harness.
  */
 export class StepLedger {
     /** Recovered entries, by path. Consumed as replay proceeds. */
     replayable;
+    /** Sequence number the next recorded entry takes. */
     seq;
+    /** Lowest sequence number still in storage — advances as eviction proceeds. */
+    oldestSeq;
     store;
     executionId;
+    retention;
+    counts = {
+        recorded: 0,
+        droppedOversize: 0,
+        droppedUnserialisable: 0,
+        evicted: 0,
+    };
     constructor(opts) {
         this.executionId = opts.executionId;
         this.store = opts.store;
-        this.replayable = opts.recovered ?? new Map();
-        this.seq = this.replayable.size;
+        this.retention = resolveStepLedgerRetention(opts.retention);
+        this.replayable = opts.recovered?.entries ?? new Map();
+        this.seq = opts.recovered?.nextSeq ?? 0;
+        this.oldestSeq = opts.recovered?.oldestSeq ?? 0;
     }
     /** True when this execution has nothing recovered to replay (the common, fresh case). */
     get isEmpty() {
         return this.replayable.size === 0;
     }
+    /** What retention has done so far. A snapshot — safe to hold. */
+    get stats() {
+        return {
+            ...this.counts,
+        };
+    }
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
      * A divergence (different step id or kind at this path) discards the entry and every
@@ -125,13 +227,80 @@ export class StepLedger {
         if (!this.store) {
             return;
         }
+        if (!this.retainable(entry)) {
+            return;
+        }
+        /* Reserve the sequence number BEFORE awaiting: concurrent fork legs record through
+         * the one shared ledger, and two of them reading the same counter would write the
+         * same key, silently overwriting a sibling's entry. A write that then fails leaves a
+         * gap, which only makes the window below a slight over-estimate of the live count —
+         * eviction runs marginally early, never late. */
         const seq = this.seq;
-        this.seq += 1;
+        this.seq = seq + 1;
         try {
             await this.store.append(this.executionId, seq, entry);
         }
         catch (error) {
             console.warn(`StepLedger: failed to record "${entry.path}":`, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        this.counts.recorded += 1;
+        await this.evictOverflow();
+    }
+    /**
+     * Whether this entry is small enough — and encodable at all — to be worth a write.
+     * An output no adapter could serialise is treated exactly like an oversized one:
+     * not recorded, so the step re-runs.
+     */
+    retainable(entry) {
+        let json;
+        try {
+            json = JSON.stringify(entry.output);
+        }
+        catch {
+            this.counts.droppedUnserialisable += 1;
+            this.warnOnFirstDrop(this.counts.droppedUnserialisable, `StepLedger: not recording "${entry.path}" — its output does not survive JSON encoding.`);
+            return false;
+        }
+        // `undefined` stringifies to nothing; there is no size to bound.
+        if (json !== undefined && !fitsByteCap(json, this.retention.maxEntryBytes)) {
+            this.counts.droppedOversize += 1;
+            this.warnOnFirstDrop(this.counts.droppedOversize, `StepLedger: not recording "${entry.path}" — output exceeds maxEntryBytes (${this.retention.maxEntryBytes}).`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete oldest-first until the execution is back inside `maxEntries`. The bound is on
+     * the sequence *window* rather than an exact row count, which is what keeps this
+     * correct without a `list()` per append.
+     */
+    async evictOverflow() {
+        const store = this.store;
+        if (!store) {
+            return;
+        }
+        while (this.seq - this.oldestSeq > this.retention.maxEntries) {
+            const victim = this.oldestSeq;
+            try {
+                await store.delete(this.executionId, victim);
+            }
+            catch (error) {
+                /* Leave the cursor where it is and stop: the next append retries this victim
+                 * rather than spinning on a store that is currently refusing deletes. */
+                console.warn(`StepLedger: failed to evict entry ${victim} of "${this.executionId}":`, error instanceof Error ? error.message : String(error));
+                return;
+            }
+            this.oldestSeq = victim + 1;
+            this.counts.evicted += 1;
+        }
+    }
+    /** One warning per reason per execution — a long run would otherwise flood the log. */
+    warnOnFirstDrop(count, message) {
+        if (count > 1) {
+            return;
         }
+        console.warn(`${message} The step will re-run on resume; further drops are silent.`);
     }
 }
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@noetic-tools/memory": "^2.0.0",
-    "@noetic-tools/types": "^2.0.0",
+    "@noetic-tools/types": "^2.1.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },