@hunterzhu/pulse-runtime 0.5.1 → 0.7.0

package/dist/dsl/read-continuation.d.ts

@@ -0,0 +1,9 @@
+import type { JsonValue } from '../core/types.js';
+import type { StepContext } from './program.js';
+/** A bounded window must expose new bytes, rather than slide through already read text. */
+export declare function isUnreadFileWindow(ctx: Pick<StepContext<unknown>, 'results'>, call: {
+    toolName: JsonValue;
+    input: JsonValue;
+}, refs: readonly string[]): boolean;
+/** Count actual new windows/version changes, not arbitrary reads at positive offsets. */
+export declare function isReadProgress(ctx: Pick<StepContext<unknown>, 'results'>, ref: string, priorRefs: readonly string[]): boolean;

package/dist/dsl/read-continuation.js

@@ -0,0 +1,84 @@
+import { normalize } from 'node:path';
+const pathKey = (value) => typeof value === 'string' ? normalize(value).replaceAll('\\', '/') : undefined;
+const limitBytes = 3000;
+const row = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const integer = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/** A bounded window must expose new bytes, rather than slide through already read text. */
+export function isUnreadFileWindow(ctx, call, refs) {
+    if (call.toolName !== 'fs.read')
+        return false;
+    const { path, offset = 0, startLine, maxBytes = limitBytes } = row(call.input);
+    if (typeof path !== 'string' || !integer(offset) || !integer(maxBytes) || maxBytes === 0)
+        return false;
+    const size = Math.min(maxBytes, limitBytes);
+    const ordered = [...new Set(refs)].sort((a, b) => Number(a.match(/\d+$/)?.[0] ?? 0) - Number(b.match(/\d+$/)?.[0] ?? 0));
+    const observations = ordered.flatMap((ref, order) => {
+        const meta = ctx.results.meta(ref), body = row(ctx.results.read(ref)), args = row(meta?.toolArguments);
+        if (meta?.outcomeStatus !== 'succeeded' || !['fs.read', 'fs.write', 'fs.apply_patch', 'fs.apply_patches', 'fs.stage'].includes(meta.toolName ?? ''))
+            return [];
+        if (pathKey(body.path) !== pathKey(path) && pathKey(body.target) !== pathKey(path) && pathKey(args.path) !== pathKey(path))
+            return [];
+        if (meta.toolName === 'fs.stage' && body.committed !== true)
+            return [];
+        return [{ body, args, read: meta.toolName === 'fs.read', order }];
+    });
+    const latest = observations.at(-1);
+    if (latest && typeof latest.body.hash !== 'string')
+        return false;
+    const pages = observations.filter(o => o.read && o.body.hash === latest?.body.hash);
+    if (startLine !== undefined) {
+        if (!integer(startLine) || startLine < 1 || offset !== 0 || pages.some(p => integer(p.args.startLine) && startLine >= p.args.startLine && startLine <= p.args.startLine + (typeof p.body.content === 'string' ? p.body.content.split('\n').length - (p.body.content.endsWith('\n') ? 2 : 1) : 0)))
+            return false;
+        // Search anchors are exact observed locations, not model-invented line numbers.
+        // A later write invalidates older anchors, even when the read result was retained.
+        const lastWrite = observations.filter(o => !o.read && o.body.changed !== false).at(-1)?.order ?? -1;
+        return ordered.some((ref, order) => {
+            if (order <= lastWrite)
+                return false;
+            const meta = ctx.results.meta(ref), body = row(ctx.results.read(ref));
+            return meta?.toolName === 'fs.search' && meta.outcomeStatus === 'succeeded' && Array.isArray(body.matches) && body.matches.some(m => pathKey(row(m).path) === pathKey(path) && row(m).line === startLine);
+        });
+    }
+    if (!latest || pages.length === 0)
+        return offset === 0;
+    const ranges = pages.flatMap(({ body }) => {
+        const start = body.offset ?? 0;
+        const end = integer(body.nextOffset) ? body.nextOffset : typeof body.content === 'string' ? start + Buffer.byteLength(body.content) : undefined;
+        return integer(start) && integer(end) && end > start ? [[start, end]] : [];
+    }).sort((a, b) => a[0] - b[0]);
+    const merged = [];
+    for (const range of ranges) {
+        const last = merged.at(-1);
+        if (last && range[0] <= last[1])
+            last[1] = Math.max(last[1], range[1]);
+        else
+            merged.push([...range]);
+    }
+    const eof = pages.flatMap(({ body }) => body.nextOffset === null && typeof body.content === 'string' && integer(body.offset ?? 0) ? [(body.offset ?? 0) + Buffer.byteLength(body.content)] : []);
+    const end = Math.min(offset + size, ...eof);
+    if (!Number.isSafeInteger(end) || end <= offset)
+        return false;
+    const covered = merged.reduce((n, [start, stop]) => n + Math.max(0, Math.min(stop, end) - Math.max(start, offset)), 0);
+    if (covered >= end - offset)
+        return false;
+    if (pages.some(({ body }) => body.nextOffset === offset))
+        return true;
+    // A little context overlap is useful, but 1-byte shifts cannot defeat the gate.
+    return merged.some(([start, stop]) => offset >= start && offset < stop && end > stop) && covered <= Math.min(512, Math.floor((end - offset) / 4));
+}
+/** Count actual new windows/version changes, not arbitrary reads at positive offsets. */
+export function isReadProgress(ctx, ref, priorRefs) {
+    const meta = ctx.results.meta(ref), body = row(ctx.results.read(ref)), args = row(meta?.toolArguments);
+    if (meta?.toolName !== 'fs.read' || meta.outcomeStatus !== 'succeeded')
+        return false;
+    const path = body.path ?? args.path;
+    const priorFile = [...new Set(priorRefs)].sort((a, b) => Number(b.match(/\d+$/)?.[0] ?? 0) - Number(a.match(/\d+$/)?.[0] ?? 0)).find(prior => {
+        const m = ctx.results.meta(prior), b = row(ctx.results.read(prior)), a = row(m?.toolArguments);
+        return m?.outcomeStatus === 'succeeded' && ['fs.read', 'fs.write', 'fs.apply_patch', 'fs.apply_patches', 'fs.stage'].includes(m.toolName ?? '') && (m.toolName !== 'fs.stage' || b.committed === true) && pathKey(b.path ?? b.target ?? a.path) === pathKey(path);
+    });
+    if (priorFile && typeof body.hash === 'string' && typeof row(ctx.results.read(priorFile)).hash === 'string' && body.hash !== row(ctx.results.read(priorFile)).hash)
+        return true;
+    if (!priorFile && args.startLine === undefined)
+        return false;
+    return isUnreadFileWindow(ctx, { toolName: 'fs.read', input: { ...args, path, ...(args.startLine === undefined ? { offset: body.offset ?? args.offset ?? 0 } : {}) } }, priorRefs);
+}

package/dist/dsl/templates.d.ts

@@ -20,13 +20,20 @@ export interface ReActLaneConfig {
     maxTurns?: number;
     maxTruncationRetries?: number;
     maxToolsPerTurn?: number;
+    prepareQuestion?: (toolName: string, input: JsonValue, ctx: StepContext<JsonValue>) => JsonValue;
+    validateQuestion?: (toolName: string, input: JsonValue, ctx: StepContext<JsonValue>) => string | undefined;
+    onHumanReply?: (question: JsonValue, answer: JsonValue, ctx: StepContext<JsonValue>) => NextStepTarget<JsonValue> | undefined;
+    /** Bound investigation-only rounds for an implementation run; pagination is exempt. */
+    maxReadOnlyRounds?: number | ((ctx: StepContext<JsonValue>) => number | undefined);
     serialTools?: string[];
     stopAfterFirstSerialTool?: boolean;
     /** Return a durable token when a new attempt should get a fresh turn budget. */
     resetTurnsOnEntry?: (ctx: StepContext<JsonValue>) => string | number | undefined;
     outputSchema?: ZodTypeAny;
     requirements?: Record<string, JsonValue>;
+    manualApprovalFallback?: boolean;
     toolApproval?: {
+        requiresApproval?: (calls: JsonValue) => boolean;
         prompt: string | ((calls: JsonValue, ctx: StepContext<JsonValue>) => string);
         onDenied?: (reason: string, ctx: StepContext<JsonValue>) => NextStepTarget<JsonValue>;
     };

package/dist/dsl/templates.js

@@ -4,7 +4,7 @@ export function defineReActLane(config) {
         const onFinish = config.onFinish ?? (config.outputSchema === undefined
             ? { text: (resultRef) => ({ complete: { value: { textRef: resultRef } } }) }
             : { text: (resultRef) => ({ complete: { value: { textRef: resultRef } } }), structured: { schema: config.outputSchema, onParsed: (value) => ({ complete: { value: value } }) } });
-        builder.addReActLoopStep('react', { ...(config.task === undefined ? {} : { task: config.task }), instruction: config.instruction, ...(config.inputs === undefined ? {} : { inputs: config.inputs }), ...(config.toolAllow === undefined ? {} : { toolAllow: config.toolAllow }), ...(config.maxToolsPerTurn === undefined ? {} : { maxToolsPerTurn: config.maxToolsPerTurn }), ...(config.serialTools === undefined ? {} : { serialTools: config.serialTools }), ...(config.stopAfterFirstSerialTool === undefined ? {} : { stopAfterFirstSerialTool: config.stopAfterFirstSerialTool }), ...(config.maxTruncationRetries === undefined ? {} : { maxTruncationRetries: config.maxTruncationRetries }), ...(config.maxTurns === undefined ? {} : { maxTurns: config.maxTurns }), ...(config.resetTurnsOnEntry === undefined ? {} : { resetTurnsOnEntry: config.resetTurnsOnEntry }), ...(config.outputSchema === undefined ? {} : { outputSchema: config.outputSchema }), ...(config.requirements === undefined ? {} : { requirements: config.requirements }), ...(config.toolApproval === undefined ? {} : { toolApproval: config.toolApproval }), onFinish });
+        builder.addReActLoopStep('react', { ...(config.task === undefined ? {} : { task: config.task }), instruction: config.instruction, ...(config.manualApprovalFallback ? { manualApprovalFallback: true } : {}), ...(config.prepareQuestion === undefined ? {} : { prepareQuestion: config.prepareQuestion }), ...(config.validateQuestion === undefined ? {} : { validateQuestion: config.validateQuestion }), ...(config.onHumanReply === undefined ? {} : { onHumanReply: config.onHumanReply }), ...(config.inputs === undefined ? {} : { inputs: config.inputs }), ...(config.toolAllow === undefined ? {} : { toolAllow: config.toolAllow }), ...(config.maxToolsPerTurn === undefined ? {} : { maxToolsPerTurn: config.maxToolsPerTurn }), ...(config.maxReadOnlyRounds === undefined ? {} : { maxReadOnlyRounds: config.maxReadOnlyRounds }), ...(config.serialTools === undefined ? {} : { serialTools: config.serialTools }), ...(config.stopAfterFirstSerialTool === undefined ? {} : { stopAfterFirstSerialTool: config.stopAfterFirstSerialTool }), ...(config.maxTruncationRetries === undefined ? {} : { maxTruncationRetries: config.maxTruncationRetries }), ...(config.maxTurns === undefined ? {} : { maxTurns: config.maxTurns }), ...(config.resetTurnsOnEntry === undefined ? {} : { resetTurnsOnEntry: config.resetTurnsOnEntry }), ...(config.outputSchema === undefined ? {} : { outputSchema: config.outputSchema }), ...(config.requirements === undefined ? {} : { requirements: config.requirements }), ...(config.toolApproval === undefined ? {} : { toolApproval: config.toolApproval }), onFinish });
         config.extend?.(builder);
     });
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './core/types.js';
+export * from './core/tool-image.js';
 export * from './core/errors.js';
 export * from './core/mutations.js';
 export * from './core/inbox.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './core/types.js';
+export * from './core/tool-image.js';
 export * from './core/errors.js';
 export * from './core/mutations.js';
 export * from './core/inbox.js';

package/dist/models/router.d.ts

@@ -1,6 +1,7 @@
 import type { JsonValue, LLMRequestProjection, PrivacyLabel, ProvenanceRef } from '../core/types.js';
 export type ReasoningLevel = 'low' | 'medium' | 'high';
 export interface ModelCapabilities {
+    imageInput?: boolean;
     toolCalling?: boolean;
     structuredOutput?: boolean;
     reasoning?: ReasoningLevel;
@@ -33,6 +34,7 @@ export interface ModelAdapter {
         request: LLMRequestProjection;
         signal: AbortSignal;
         onObservation?: (chunk: string) => void;
+        onReasoning?: (chunk: string) => void;
         model?: string;
         outputSchema?: JsonValue;
         maxOutputTokens?: number;

package/dist/models/router.js

@@ -6,7 +6,7 @@ function isModelCandidate(value) {
     if (!capabilities || typeof capabilities !== 'object' || Array.isArray(capabilities))
         return false;
     const modelCapabilities = capabilities;
-    return typeof candidate.id === 'string' && candidate.id.length > 0 && typeof candidate.providerId === 'string' && candidate.providerId.length > 0 && Array.isArray(candidate.tasks) && candidate.tasks.length > 0 && candidate.tasks.every((task) => typeof task === 'string' && task.length > 0) && typeof candidate.priority === 'number' && Number.isFinite(candidate.priority) && Number.isInteger(modelCapabilities.maxContextTokens) && modelCapabilities.maxContextTokens > 0 && (modelCapabilities.maxOutputTokens === undefined || (Number.isInteger(modelCapabilities.maxOutputTokens) && modelCapabilities.maxOutputTokens > 0)) && (modelCapabilities.local === undefined || typeof modelCapabilities.local === 'boolean') && (modelCapabilities.toolCalling === undefined || typeof modelCapabilities.toolCalling === 'boolean') && (modelCapabilities.structuredOutput === undefined || typeof modelCapabilities.structuredOutput === 'boolean') && (modelCapabilities.reasoning === undefined || ['low', 'medium', 'high'].includes(String(modelCapabilities.reasoning))) && (candidate.adapter === undefined || (typeof candidate.adapter === 'object' && candidate.adapter !== null && typeof candidate.adapter.executeAttempt === 'function'));
+    return typeof candidate.id === 'string' && candidate.id.length > 0 && typeof candidate.providerId === 'string' && candidate.providerId.length > 0 && Array.isArray(candidate.tasks) && candidate.tasks.length > 0 && candidate.tasks.every((task) => typeof task === 'string' && task.length > 0) && typeof candidate.priority === 'number' && Number.isFinite(candidate.priority) && Number.isInteger(modelCapabilities.maxContextTokens) && modelCapabilities.maxContextTokens > 0 && (modelCapabilities.maxOutputTokens === undefined || (Number.isInteger(modelCapabilities.maxOutputTokens) && modelCapabilities.maxOutputTokens > 0)) && (modelCapabilities.imageInput === undefined || typeof modelCapabilities.imageInput === 'boolean') && (modelCapabilities.local === undefined || typeof modelCapabilities.local === 'boolean') && (modelCapabilities.toolCalling === undefined || typeof modelCapabilities.toolCalling === 'boolean') && (modelCapabilities.structuredOutput === undefined || typeof modelCapabilities.structuredOutput === 'boolean') && (modelCapabilities.reasoning === undefined || ['low', 'medium', 'high'].includes(String(modelCapabilities.reasoning))) && (candidate.adapter === undefined || (typeof candidate.adapter === 'object' && candidate.adapter !== null && typeof candidate.adapter.executeAttempt === 'function'));
 }
 export class InMemoryModelRegistry {
     candidates = [];
@@ -21,7 +21,7 @@ export class InMemoryModelRegistry {
 }
 /** Conservative admission estimate used before a provider attempt is started. */
 export function estimateProjectionTokens(projection) {
-    return Math.ceil(Buffer.byteLength(JSON.stringify(projection.blocks), 'utf8') / 4);
+    return Math.ceil(Buffer.byteLength(JSON.stringify(projection.blocks), 'utf8') / 4) + (projection.images?.length ?? 0) * 4096;
 }
 export class ModelRouter {
     registry;

package/dist/scheduler/runtime.d.ts

@@ -6,7 +6,7 @@ import { PulseSession } from '../dsl/session.js';
 import type { ProgramRef } from '../dsl/templates.js';
 import { FactInbox, ObservationInbox, type FactInboxDedupeArchive, type FactInboxDedupeArchiveBatch } from '../core/inbox.js';
 import { EffectOutbox } from '../storage/outbox.js';
-import { type RuntimePersistenceBackend, type RuntimePersistenceSnapshot } from '../storage/persistence.js';
+import { type RuntimePersistenceBackend, type RuntimePersistenceCompatibility, type RuntimePersistenceSnapshot } from '../storage/persistence.js';
 import { type RuntimeLogSink, type RuntimeSessionStore, type SessionLogExport, type SessionLogExportOptions } from '../storage/session.js';
 import { ResourceLockManager } from './locks.js';
 import { type Mutation } from '../core/mutations.js';
@@ -186,6 +186,11 @@ export interface RuntimeConfig {
     hostPolicy?: ModelHostPolicy;
     modelRouter?: ModelRouter;
     tools?: RuntimeToolRegistry;
+    recoveryBuildMigration?: {
+        from: string;
+        to: string;
+    };
+    recoveryFingerprints?: RuntimePersistenceCompatibility['fingerprints'];
     toolVersions?: Record<string, string>;
     policyVersion?: string;
     routerVersion?: string;
@@ -298,6 +303,8 @@ export declare class PulseRuntime {
     private readonly enforcingRecoveryPrograms;
     private readonly toolVersions;
     private readonly recoveryCompatibility;
+    private readonly recoveryBuildMigration;
+    private readonly recoveryFingerprints;
     private readonly policyVersion;
     private readonly routerVersion;
     private readonly budget;
@@ -381,6 +388,13 @@ export declare class PulseRuntime {
     private wakeError;
     private tickBudget;
     static restore(backend: RuntimePersistenceBackend, config?: Omit<RuntimeConfig, 'persistence'>): Promise<PulseRuntime>;
+    private lazyResultCache;
+    private lazyResultSizes;
+    private lazyResultBytes;
+    private lazyResultRefs;
+    private installLazyResults;
+    /** Only the active step's referenced bodies enter its pure snapshot. Older refs remain available through Host inspection. */
+    private stepState;
     constructor(config?: RuntimeConfig);
     register(program: LaneProgram): void;
     /** Register the program used for urgent, concurrent human interactions. */
@@ -416,6 +430,7 @@ export declare class PulseRuntime {
     private assertRecoveryPrograms;
     private persistenceCompatibility;
     private assertRecoveryCompatibility;
+    private assertRecoveryFingerprints;
     private currentToolVersions;
     private tryEmit;
     private rejectHostCommand;

package/dist/scheduler/runtime.js

@@ -12,6 +12,7 @@ import { EffectOutbox } from '../storage/outbox.js';
 import { exportRuntimeCheckpoint, exportRuntimePersistence, externalizeRuntimeResultBodies, externalizeRuntimeSnapshotBodies, hydrateRuntimeResultBodies, hydrateRuntimeSnapshotBodies, importRuntimePersistence, validateRuntimePersistenceSnapshot, withRuntimePersistenceIntegrity } from '../storage/persistence.js';
 import { exportRuntimeLog, exportRuntimeLogTo, exportWarmStartSession } from '../storage/session.js';
 import { ResourceLockManager } from './locks.js';
+import { extractToolImage } from '../core/tool-image.js';
 import { appendRuntimeEvent, normalizeRuntimeEvent } from '../core/events.js';
 import { apply, forkRuntimeStateForAdmission } from '../core/mutations.js';
 import { ContextMerger } from '../context/merger.js';
@@ -25,6 +26,12 @@ import { runtimeErrorFromCause } from '../core/errors.js';
 import { RuntimeToolRegistry } from '../tools/registry.js';
 import { SchedulerDecisionCoordinator, schedulerDecisionCandidateFromLane } from './decision.js';
 import { HumanArbitrationCoordinator, ruleHumanArbitration } from './human-arbitration.js';
+function repeatedControlFailure(error, count) {
+    const details = { lastError: error, consecutiveControlErrors: count };
+    if (error.code === 'CONTEXT_TOO_LARGE')
+        return { code: error.code, message: `${error.message} Configure historyCompaction with an Effect-backed summary, or restore a checkpoint with a smaller history before continuing.`, details };
+    return { code: 'CONTROL_ERROR_LOOP', message: 'Lane exceeded the consecutive control error limit.', details };
+}
 function encodeEffectExecution(execution) {
     const encoded = structuredClone(execution);
     const artifact = execution.artifact;
@@ -461,7 +468,7 @@ export class PulseRuntime {
     results = {
         get: (resultRef) => {
             const result = this.state.results.get(resultRef);
-            return result === undefined ? undefined : structuredClone(result);
+            return result === undefined ? undefined : { ...structuredClone(result), ...(result.value === undefined ? {} : { value: structuredClone(result.value) }) };
         },
     };
     shuttingDown = false;
@@ -480,6 +487,8 @@ export class PulseRuntime {
     enforcingRecoveryPrograms;
     toolVersions;
     recoveryCompatibility;
+    recoveryBuildMigration;
+    recoveryFingerprints;
     policyVersion;
     routerVersion;
     budget;
@@ -567,15 +576,97 @@ export class PulseRuntime {
         if (loaded?.snapshotBodies === 'external' && backend.snapshotStore === undefined)
             throw new Error('RUNTIME_SNAPSHOT_STORE_REQUIRED');
         const withSnapshots = loaded === undefined || backend.snapshotStore === undefined ? loaded : await hydrateRuntimeSnapshotBodies(loaded, backend.snapshotStore);
-        const snapshot = withSnapshots === undefined || backend.resultStore === undefined ? withSnapshots : await hydrateRuntimeResultBodies(withSnapshots, backend.resultStore);
+        const snapshot = withSnapshots === undefined || backend.resultStore === undefined || backend.lazyResultBodies && backend.resultStore.loadSync ? withSnapshots : await hydrateRuntimeResultBodies(withSnapshots, backend.resultStore);
         if (snapshot?.resultBodies === 'external' && backend.resultStore === undefined)
             throw new Error('RUNTIME_RESULT_STORE_REQUIRED');
         const restoredConfig = snapshot === undefined ? config : { ...config, persistence: snapshot, ...(config.persistenceBackend === undefined || loaded?.integrity?.digest === undefined ? {} : { persistenceExpectedDigest: loaded.integrity.digest }) };
-        return new PulseRuntime({
+        const runtime = new PulseRuntime({
             ...restoredConfig,
             ...(restoredConfig.factInboxDedupeArchive === undefined && backend.factInboxDedupeArchive !== undefined ? { factInboxDedupeArchive: backend.factInboxDedupeArchive } : {}),
             ...(restoredConfig.sessionStore === undefined && backend.sessionStore !== undefined ? { sessionStore: backend.sessionStore } : {}),
         });
+        if (snapshot?.compatibility?.fingerprints)
+            runtime.assertRecoveryFingerprints(snapshot.compatibility);
+        if (backend.lazyResultBodies && backend.resultStore?.loadSync)
+            runtime.installLazyResults(backend, snapshot?.externalResultRefs ?? []);
+        return runtime;
+    }
+    lazyResultCache = new Map();
+    lazyResultSizes = new Map();
+    lazyResultBytes = 0;
+    lazyResultRefs = new Set();
+    installLazyResults(backend, persistedRefs) {
+        const store = backend.resultStore;
+        if (!store?.loadSync)
+            return;
+        for (const [ref, result] of this.state.results) {
+            if (this.lazyResultRefs.has(ref) || !persistedRefs.includes(ref))
+                continue;
+            this.lazyResultRefs.add(ref);
+            delete result.value;
+            Object.defineProperty(result, 'value', { configurable: true, enumerable: false, get: () => {
+                    let value = this.lazyResultCache.get(ref);
+                    if (value === undefined) {
+                        value = store.loadSync(ref);
+                        if (value === undefined)
+                            throw new Error(`RUNTIME_RESULT_NOT_FOUND:${ref}`);
+                        if (result.contentHash && contentHash(value) !== result.contentHash)
+                            throw new Error(`RUNTIME_RESULT_INTEGRITY_MISMATCH:${ref}`);
+                        this.lazyResultCache.set(ref, value);
+                        const bytes = Buffer.byteLength(stableSerialize(value));
+                        this.lazyResultSizes.set(ref, bytes);
+                        this.lazyResultBytes += bytes;
+                    }
+                    while ((this.lazyResultBytes > 4_000_000 || this.lazyResultCache.size > 128) && this.lazyResultCache.size > 1) {
+                        const oldest = this.lazyResultCache.keys().next().value;
+                        this.lazyResultBytes -= this.lazyResultSizes.get(oldest) ?? 0;
+                        this.lazyResultCache.delete(oldest);
+                        this.lazyResultSizes.delete(oldest);
+                    }
+                    return value;
+                } });
+        }
+    }
+    /** Only the active step's referenced bodies enter its pure snapshot. Older refs remain available through Host inspection. */
+    stepState(lane) {
+        const copy = structuredClone(this.state);
+        if (!this.lazyResultRefs.size)
+            return copy;
+        const refs = new Set();
+        const collect = (value) => {
+            if (typeof value === 'string') {
+                if (this.state.results.has(value))
+                    refs.add(value);
+                return;
+            }
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    collect(item);
+                return;
+            }
+            if (value && typeof value === 'object')
+                for (const item of Object.values(value))
+                    collect(item);
+        };
+        collect(lane.resume.locals);
+        collect(lane.context.state);
+        collect(lane.pendingResumeInput);
+        collect(lane.pendingHumanInputs);
+        collect([...(lane.visibleResultRefs ?? [])].slice(-64));
+        collect(lane.context.history.slice(-64));
+        const agent = this.state.agents.get(lane.agentId);
+        if (agent) {
+            collect(agent.globalVersions.get(agent.latestGlobalVersion));
+            collect(agent.globalVersions.get(lane.contextSnapshotVersion));
+        }
+        for (const ref of refs) {
+            const source = this.state.results.get(ref), target = copy.results.get(ref);
+            if (source && target && source.value !== undefined) {
+                target.value = structuredClone(source.value);
+                collect(target.value);
+            }
+        }
+        return copy;
     }
     constructor(config = {}) {
         validateRuntimeConfig(config);
@@ -588,6 +679,8 @@ export class PulseRuntime {
         this.modelRouter = config.modelRouter ?? new ModelRouter(this.models, config.hostPolicy);
         this.tools = config.tools ?? new RuntimeToolRegistry();
         this.toolVersions = { ...(config.toolVersions ?? {}) };
+        this.recoveryBuildMigration = config.recoveryBuildMigration;
+        this.recoveryFingerprints = config.recoveryFingerprints;
         this.policyVersion = config.policyVersion;
         this.routerVersion = config.routerVersion;
         this.state = restored?.state ?? createRuntimeState(config.maxTotalLanes ?? 64, { ...(config.maxQueuedEffects === undefined ? {} : { maxQueuedEffects: config.maxQueuedEffects }), ...(config.maxRunning === undefined ? {} : { maxRunning: config.maxRunning }), ...(config.forkAffinity === undefined ? {} : { forkAffinity: config.forkAffinity }), ...(config.historySoftTokens === undefined ? {} : { historySoftTokens: config.historySoftTokens }), ...(config.historyHardTokens === undefined ? {} : { historyHardTokens: config.historyHardTokens }), ...(config.maxResultSummaryBytes === undefined ? {} : { maxResultSummaryBytes: config.maxResultSummaryBytes }), ...(config.trustedSanitizerIds === undefined ? {} : { trustedSanitizerIds: config.trustedSanitizerIds }) });
@@ -1101,6 +1194,10 @@ export class PulseRuntime {
         return compacted;
     }
     async persist(backend) {
+        if (backend.eventArchive && backend.checkpointEventInterval && this.state.events.length >= backend.checkpointEventInterval) {
+            await this.checkpoint(backend);
+            return;
+        }
         const persistedPolicy = this.storagePolicy.clone();
         persistedPolicy.markPersisted();
         // The saved state is already authoritative: restore does not replay the
@@ -1122,6 +1219,8 @@ export class PulseRuntime {
             if (journalWatermark !== undefined && journalWatermark > this.mutationLog.watermark && journalWatermark <= this.mutationLog.lastSequence)
                 this.mutationLog.truncateThrough(journalWatermark);
         }
+        if (backend.lazyResultBodies && backend.resultStore?.loadSync)
+            this.installLazyResults(backend, snapshot.externalResultRefs ?? []);
         this.storagePolicy.markPersisted();
         this.markArtifactsPersisted();
         this.syncStoragePolicy();
@@ -1169,11 +1268,14 @@ export class PulseRuntime {
             }
         }
         const eventWatermark = options.compactEventsThrough ?? this.state.events.at(-1)?.seq;
+        let archivedEventIds = [];
         if (backend.eventArchive !== undefined && eventWatermark !== undefined) {
             const fromSeq = (this.state.eventsCompactedThrough ?? 0) + 1;
             const events = this.state.events.filter((event) => event.seq >= fromSeq && event.seq <= eventWatermark);
             if (events.length)
                 await backend.eventArchive.append(events);
+            archivedEventIds = events.map(event => event.id);
+            persistedPolicy.forgetArchivedEvents(archivedEventIds);
         }
         const exported = exportRuntimeCheckpoint(this.persistenceState(), this.mutationLog, this.outbox, this.quarantine, persistedPolicy, eventWatermark === undefined ? {} : { compactEventsThrough: eventWatermark }, this.factInbox.snapshot(), this.persistenceCompatibility());
         const archived = backend.eventArchive === undefined || eventWatermark === undefined ? exported : withRuntimePersistenceIntegrity({ ...exported, eventArchive: { through: eventWatermark } });
@@ -1185,7 +1287,6 @@ export class PulseRuntime {
             this.persistenceDigest = snapshot.integrity?.digest;
         this.storagePolicy.markPersisted();
         this.markArtifactsPersisted();
-        this.syncStoragePolicy();
         const watermark = snapshot.checkpoint?.logWatermark ?? 0;
         if (watermark > 0 && this.mutationLog.lastSequence >= watermark)
             this.mutationLog.truncateThrough(watermark);
@@ -1193,6 +1294,10 @@ export class PulseRuntime {
             this.state.events = this.state.events.filter((event) => event.seq > eventWatermark);
             this.state.eventsCompactedThrough = Math.max(this.state.eventsCompactedThrough ?? 0, eventWatermark);
         }
+        this.storagePolicy.forgetArchivedEvents(archivedEventIds);
+        this.syncStoragePolicy();
+        if (backend.lazyResultBodies && backend.resultStore?.loadSync)
+            this.installLazyResults(backend, snapshot.externalResultRefs ?? []);
         this.schedulePersistence();
         return snapshot;
     }
@@ -1242,6 +1347,7 @@ export class PulseRuntime {
             schemaVersion: 1,
             programVersions: Object.fromEntries([...this.programs.entries()].map(([key, program]) => [key, program.version])),
             toolVersions,
+            ...(this.recoveryFingerprints ? { fingerprints: this.recoveryFingerprints } : {}),
             ...(this.policyVersion === undefined ? {} : { policyVersion: this.policyVersion }),
             ...(this.routerVersion === undefined ? {} : { routerVersion: this.routerVersion }),
         };
@@ -1252,6 +1358,7 @@ export class PulseRuntime {
             if (!program || program.version !== version)
                 throw new Error(`PROGRAM_VERSION_UNAVAILABLE:${key}`);
         }
+        this.assertRecoveryFingerprints(expected);
         const toolVersions = this.currentToolVersions();
         for (const [name, version] of Object.entries(expected.toolVersions))
             if (toolVersions[name] !== version)
@@ -1261,6 +1368,19 @@ export class PulseRuntime {
         if (expected.routerVersion !== undefined && this.routerVersion !== expected.routerVersion)
             throw new Error(`ROUTER_VERSION_UNAVAILABLE:${expected.routerVersion}`);
     }
+    assertRecoveryFingerprints(expected) {
+        if (expected.fingerprints) {
+            if (!this.recoveryFingerprints)
+                throw new Error('RECOVERY_FINGERPRINT_REQUIRED');
+            if (expected.fingerprints.build !== this.recoveryFingerprints.build && (this.recoveryBuildMigration?.from !== expected.fingerprints.build || this.recoveryBuildMigration?.to !== this.recoveryFingerprints.build))
+                throw new Error(`RECOVERY_BUILD_MIGRATION_REQUIRED:from=${expected.fingerprints.build}:to=${this.recoveryFingerprints.build}`);
+            for (const [name, hash] of Object.entries(expected.fingerprints.tools))
+                if (this.recoveryFingerprints.tools[name] !== hash)
+                    throw new Error(`TOOL_SCHEMA_INCOMPATIBLE:${name}`);
+            if (expected.fingerprints.policy !== this.recoveryFingerprints.policy)
+                throw new Error('RECOVERY_POLICY_INCOMPATIBLE');
+        }
+    }
     currentToolVersions() {
         return { ...this.toolVersions, ...Object.fromEntries(this.tools.list().map((manifest) => [manifest.name, manifest.version])) };
     }
@@ -1355,7 +1475,10 @@ export class PulseRuntime {
                     value = null;
                     artifact = artifactOutput(detailed.output);
                 }
-                return { value, ...(artifact === undefined ? {} : { artifact }), ...(detailed.normalized === undefined ? {} : { normalized: strictJsonValue(detailed.normalized) }), ...(detailed.summary === undefined ? {} : { summary: strictJsonValue(detailed.summary) }), sideEffectState: isSideEffectful(definition.manifest.sideEffectPolicy) ? 'applied' : 'none', executionState: 'succeeded', status: 'succeeded', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: detailed.manifest.version, retrySafety: detailed.manifest.retrySafety, defaultTimeoutMs: detailed.manifest.defaultTimeoutMs, observationCount: observations.length, ...(artifact === undefined ? {} : { artifactMediaType: artifact.mediaType }) }, ...(observations.length ? { observations } : {}) };
+                const image = extractToolImage(value);
+                value = image.value;
+                artifact = image.artifact ?? artifact;
+                return { value, ...(artifact === undefined ? {} : { artifact }), ...(detailed.normalized === undefined ? {} : { normalized: image.artifact ? value : strictJsonValue(detailed.normalized) }), ...(detailed.summary === undefined ? {} : { summary: strictJsonValue(detailed.summary) }), sideEffectState: isSideEffectful(definition.manifest.sideEffectPolicy) ? 'applied' : 'none', executionState: 'succeeded', status: 'succeeded', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: detailed.manifest.version, retrySafety: detailed.manifest.retrySafety, defaultTimeoutMs: detailed.manifest.defaultTimeoutMs, observationCount: observations.length, ...(artifact === undefined ? {} : { artifactMediaType: artifact.mediaType }) }, ...(observations.length ? { observations } : {}) };
             }
             catch (cause) {
                 if (signal.aborted && isSideEffectful(definition.manifest.sideEffectPolicy))
@@ -1443,7 +1566,7 @@ export class PulseRuntime {
         this.mutationLog.append(transactionId, mutations, this.state.now);
     }
     enqueueFact(fact, eventId, urgent = false) {
-        const candidateInbox = FactInbox.fromSnapshot(this.factInbox.snapshot());
+        const candidateInbox = FactInbox.fromSnapshot(this.factInbox.snapshot(), this.factInboxDedupeArchive ? { dedupeArchive: this.factInboxDedupeArchive } : {});
         if (!(urgent ? candidateInbox.enqueueUrgent(fact, eventId) : candidateInbox.enqueue(fact, eventId)))
             return false;
         const candidatePolicy = this.storagePolicy.clone();
@@ -1908,7 +2031,7 @@ export class PulseRuntime {
                 continue;
             }
             let output;
-            const stepContext = { lane: stepLane, state: structuredClone(this.state), ...(lane.pendingResumeInput ? { resumeInput: structuredClone(lane.pendingResumeInput) } : {}), ...(lane.pendingHumanInputs?.length ? { humanInputs: structuredClone(lane.pendingHumanInputs) } : {}), now: this.state.now, observe: (event) => { this.observationInbox.enqueue({ ...event, agentId: lane.agentId, laneId: lane.id, timestamp: this.state.now }); this.notifyActivity(); } };
+            const stepContext = { lane: stepLane, state: this.stepState(lane), ...(lane.pendingResumeInput ? { resumeInput: structuredClone(lane.pendingResumeInput) } : {}), ...(lane.pendingHumanInputs?.length ? { humanInputs: structuredClone(lane.pendingHumanInputs) } : {}), now: this.state.now, observe: (event) => { this.observationInbox.enqueue({ ...event, agentId: lane.agentId, laneId: lane.id, timestamp: this.state.now }); this.notifyActivity(); } };
             try {
                 output = withPureStepGuard(() => lane.series || program.seriesMember ? this.seriesStep(program, stepContext, lane.series) : program.step(stepContext));
             }
@@ -1942,7 +2065,7 @@ export class PulseRuntime {
                 const consecutive = (lane.consecutiveControlErrors ?? 0) + 1;
                 const controlInput = { type: 'control_error', error: rejection, ...(lane.pendingResumeInput ? { original: lane.pendingResumeInput } : {}) };
                 if (consecutive >= this.maxConsecutiveControlErrors)
-                    this.failLane(lane, { code: 'CONTROL_ERROR_LOOP', message: 'Lane exceeded the consecutive control error limit.', details: { lastError: rejection } });
+                    this.failLane(lane, repeatedControlFailure(rejection, consecutive));
                 else
                     this.commitLaneControlInput(lane, controlInput, { type: 'step.rejected', laneId: lane.id, data: rejection }, { consecutiveControlErrors: consecutive });
                 progressed++;
@@ -1957,7 +2080,7 @@ export class PulseRuntime {
                 }
                 else {
                     if (consecutive >= this.maxConsecutiveControlErrors)
-                        this.failLane(lane, { code: 'CONTROL_ERROR_LOOP', message: 'Lane exceeded the consecutive control error limit.', details: { lastError: result.rejection } });
+                        this.failLane(lane, repeatedControlFailure(result.rejection, consecutive));
                     else
                         this.commitLaneControlInput(lane, controlInput, { type: 'step.rejected', laneId: lane.id, data: result.rejection }, { consecutiveControlErrors: consecutive });
                 }
@@ -2493,6 +2616,12 @@ export class PulseRuntime {
         }
         let effectiveExecution = execution;
         let outputError = error ?? execution.error;
+        // A timeout remains a failure even when an aborted executor returns a generic cancellation.
+        const timeoutReason = effect.cancelRequested?.reason;
+        if (timeoutReason === 'ATTEMPT_TIMEOUT' || timeoutReason === 'TIMEOUT') {
+            outputError = { code: timeoutReason, message: `Effect exceeded its execution time limit (${timeoutReason}).`, retryable: false };
+            effectiveExecution = { ...execution, status: 'failed', executionState: 'failed', error: outputError };
+        }
         let resultDerivedFrom = [...(effect.derivedFrom ?? [])];
         let publishedArtifact;
         const rawInput = effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input) ? effect.input : {};
@@ -2501,7 +2630,7 @@ export class PulseRuntime {
                 const artifact = prepareArtifactPublication(this.state, { ...execution.artifact, laneId: effect.ownerLaneId, derivedFrom: [...(effect.derivedFrom ?? []), ...(execution.artifact.derivedFrom ?? [])] });
                 publishedArtifact = artifact;
                 resultDerivedFrom = [...resultDerivedFrom, { kind: 'artifact', ref: artifact.ref }];
-                effectiveExecution = { ...effectiveExecution, value: { artifactRef: artifact.ref }, privacy: artifact.privacy, ...(artifact.privacyTaints === undefined ? {} : { privacyTaints: artifact.privacyTaints }) };
+                effectiveExecution = { ...effectiveExecution, value: { ...(effectiveExecution.value && typeof effectiveExecution.value === 'object' && !Array.isArray(effectiveExecution.value) ? effectiveExecution.value : {}), artifactRef: artifact.ref }, privacy: artifact.privacy, ...(artifact.privacyTaints === undefined ? {} : { privacyTaints: artifact.privacyTaints }) };
             }
             catch (cause) {
                 effectiveExecution = { ...effectiveExecution, status: 'failed', executionState: 'failed', error: runtimeErrorFromCause(cause, 'ARTIFACT_PUBLICATION_FAILED') };
@@ -2543,6 +2672,8 @@ export class PulseRuntime {
             effect.retryPolicy = { maxAttempts: Math.max(1, eligible), initialBackoffMs: 0, maxBackoffMs: 0, jitter: false };
         }
         const attemptMetadata = execution.metadata && typeof execution.metadata === 'object' && !Array.isArray(execution.metadata) ? execution.metadata : undefined;
+        if (attempt && typeof attemptMetadata?.providerAttempts === 'number')
+            attempt.providerAttempts = attemptMetadata.providerAttempts;
         const selectedModel = attemptMetadata?.selected && typeof attemptMetadata.selected === 'object' && !Array.isArray(attemptMetadata.selected) ? attemptMetadata.selected : undefined;
         if (attempt && typeof selectedModel?.id === 'string')
             attempt.modelId = selectedModel.id;
@@ -3621,6 +3752,20 @@ export class PulseRuntime {
                         ...(observation.outcome?.resultRef === undefined ? [] : [observation.outcome.resultRef]),
                         ...(observation.outcome?.rejectedOutputRefs ?? []),
                     ]);
+                    // A failed/cancelled child may have durable tool effects without a
+                    // completion ResultRef. Expose only direct same-agent child receipts.
+                    for (const observation of Object.values(observations)) {
+                        if (observation.state === 'pending' || observation.target.kind !== 'lane')
+                            continue;
+                        const child = this.state.lanes.get(observation.target.id);
+                        if (!child || child.ownerLaneId !== nextLane.id || child.agentId !== nextLane.agentId)
+                            continue;
+                        for (const effectId of child.ownedEffectIds) {
+                            const effect = this.state.effects.get(effectId);
+                            if (effect?.kind === 'tool' && effect.outcome?.resultRef)
+                                refs.push(effect.outcome.resultRef);
+                        }
+                    }
                     if (!refs.length)
                         return;
                     if (nextLane.visibleResultRefs)

package/dist/storage/persistence.d.ts

@@ -38,10 +38,16 @@ export interface RuntimePersistenceCompatibility {
     toolVersions: Record<string, string>;
     policyVersion?: string;
     routerVersion?: string;
+    fingerprints?: {
+        build: string;
+        tools: Record<string, string>;
+        policy: string;
+    };
 }
 export interface RuntimeResultStore {
     save(ref: string, value: JsonValue): Promise<void>;
     load(ref: string): Promise<JsonValue | undefined>;
+    loadSync?(ref: string): JsonValue | undefined;
 }
 export interface RuntimeSnapshotStore {
     save(ref: string, value: JsonValue): Promise<void>;
@@ -57,6 +63,7 @@ export declare class FileRuntimeContentStore implements RuntimeResultStore, Runt
     constructor(directory: string);
     save(ref: string, value: JsonValue): Promise<void>;
     load(ref: string): Promise<JsonValue | undefined>;
+    loadSync(ref: string): JsonValue | undefined;
     private pathFor;
     private readEnvelope;
     private withLock;
@@ -70,6 +77,7 @@ export declare class SqliteRuntimeContentStore implements RuntimeResultStore, Ru
     constructor(filePath: string, namespace: 'result' | 'snapshot');
     save(ref: string, value: JsonValue): Promise<void>;
     load(ref: string): Promise<JsonValue | undefined>;
+    loadSync(ref: string): JsonValue | undefined;
     close(): Promise<void>;
     private open;
     private enqueue;
@@ -127,10 +135,13 @@ export declare class SqliteRuntimeFactInboxDedupeArchive implements FactInboxDed
     private enqueue;
 }
 export interface RuntimePersistenceBackend {
+    close?(): Promise<void>;
     load(): Promise<RuntimePersistenceSnapshot | undefined>;
     save(snapshot: RuntimePersistenceSnapshot, expectedDigest?: string): Promise<void>;
     sessionStore?: RuntimeSessionStore;
     resultStore?: RuntimeResultStore;
+    lazyResultBodies?: boolean;
+    checkpointEventInterval?: number;
     snapshotStore?: RuntimeSnapshotStore;
     eventArchive?: RuntimeEventArchive;
     factInboxDedupeArchive?: FactInboxDedupeArchiveWriter;