@llblab/pi-kit 0.23.1 → 0.24.0

package/node_modules/@llblab/pi-state-flow/lib/context.ts

@@ -1,10 +1,11 @@
+import { randomUUID } from "node:crypto";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { projectArtifactForModel, type ArtifactInvalidationNotice, type ArtifactModelHints } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
-import { isObject, presentationJson, type JsonValue } from "./json.ts";
+import { applyPatch, isObject, presentationJson, sameJson, type JsonValue } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { projectStateForModel, type MaterializedState, type ModelState } from "./state.ts";
+import { projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type StateScope } from "./state.ts";
 
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export function projectSystemProtocol(messages: AgentMessage[], protocol: string | undefined): AgentMessage[] {
@@ -53,12 +54,222 @@ export function lazyNavigationHint(state: MaterializedState): { available: boole
 }
 
 
+export type ModelStateUpdate = { path: (string | number)[] } & ({ value: JsonValue } | { deleted: true });
+
+/** Exact projected replacements, not authored merge patches; paths are unambiguous key/index segments. */
+export function acceptedStateUpdates(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches) {
+	return projectedStateUpdates(projectStateForModel(before), projectStateForModel(after), patches, lazyNavigationHint(before), lazyNavigationHint(after));
+}
+
+function projectedStateUpdates(previous: ModelState, current: ModelState, patches: AtomicScopePatches,
+	beforeNavigation: ReturnType<typeof lazyNavigationHint> | undefined, navigation: ReturnType<typeof lazyNavigationHint> | undefined) {
+	const effective: ModelStateUpdate[] = [];
+	const prefix = (parent: readonly (string | number)[], child: readonly (string | number)[]) =>
+		parent.length <= child.length && parent.every((part, index) => part === child[index]);
+	const put = (path: (string | number)[], value: JsonValue | undefined) => {
+		if (effective.some((entry) => prefix(entry.path, path))) return;
+		for (let index = effective.length - 1; index >= 0; index--) {
+			if (prefix(path, effective[index]!.path)) effective.splice(index, 1);
+		}
+		effective.push({ path, ...(value === undefined ? { deleted: true as const } : { value: structuredClone(value) }) });
+	};
+	const child = (value: JsonValue | undefined, key: string | number): JsonValue | undefined =>
+		value !== null && typeof value === "object" && Object.hasOwn(value, key)
+			? (value as Record<string | number, JsonValue>)[key] : undefined;
+	const diff = (left: JsonValue | undefined, right: JsonValue | undefined, path: (string | number)[]) => {
+		if (left === undefined && right === undefined || left !== undefined && right !== undefined && sameJson(left, right)) return;
+		if (isObject(left) && isObject(right)) {
+			for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) diff(child(left, key), child(right, key), [...path, key]);
+		} else if (Array.isArray(left) && Array.isArray(right) && left.length === right.length) {
+			for (let index = 0; index < right.length; index++) diff(left[index], right[index], [...path, index]);
+		} else put(path, right);
+	};
+	const touched = (patch: JsonValue, value: JsonValue | undefined, path: (string | number)[]) => {
+		if (!isObject(patch)) { put(path, value); return; }
+		const keys = Object.keys(patch);
+		if (keys.length === 0) return;
+		if (Array.isArray(value) && keys.every((key) => /^\[(0|[1-9]\d*)\]$/.test(key))) {
+			for (const key of keys) {
+				const index = Number(key.slice(1, -1));
+				// A higher-scope array may mask the patched array with a different length.
+				if (index >= value.length) { put(path, value); return; }
+				touched(patch[key]!, value[index], [...path, index]);
+			}
+		} else if (isObject(value)) {
+			for (const key of keys) touched(patch[key]!, child(value, key), [...path, key]);
+		} else put(path, value);
+	};
+	diff(previous, current, []);
+	for (const patch of Object.values(patches)) for (const [plane, value] of Object.entries(patch)) {
+		if (plane === "lazy") continue;
+		if (plane === "artifacts" && isObject(value)) {
+			for (const path of Object.keys(value)) put([plane, path], child(current.artifacts, path));
+		} else touched(value as JsonValue, child(current, plane), [plane]);
+	}
+	return { effective, ...(navigation !== undefined && (beforeNavigation === undefined || !sameJson(beforeNavigation, navigation)) ? { lazy_navigation: navigation } : {}) };
+}
+
+export interface ContextView {
+	state: ModelState;
+	lazy_navigation?: ReturnType<typeof lazyNavigationHint>;
+	artifact_invalidations: readonly ArtifactInvalidationNotice[];
+	knowledge_rehydration: { phase: RehydrationPhase } | null;
+}
+
+export function contextView(state: MaterializedState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView {
+	return { state: projectStateForModel(state, hints), lazy_navigation: lazyNavigationHint(state),
+		artifact_invalidations: structuredClone(invalidations), knowledge_rehydration: phase === undefined ? null : { phase } };
+}
+
+/** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
+export class ContextProjection {
+	private identity = randomUUID();
+	private head: AgentMessage | undefined;
+	private view: ContextView | undefined;
+	private native: string[] = [];
+	private notices: Array<{ after: number; message: AgentMessage }> = [];
+
+	reset(): void {
+		this.identity = randomUUID();
+		this.head = undefined;
+		this.view = undefined;
+		this.native = [];
+		this.notices = [];
+	}
+
+	/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
+	acceptPatch(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches, hints: ArtifactModelHints) {
+		const state = projectStateForModel(after, hints);
+		const navigation = lazyNavigationHint(after);
+		const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
+		const updates = projectedStateUpdates(this.view?.state ?? projectStateForModel(before, hints), state, patches,
+			beforeNavigation, navigation);
+		// Suppress direct writes only when the accepted effective value matches.
+		// Overlap stays conservative except for explicit top-scope replacements:
+		// Session scalars/arrays mask every lower-scope value at that path.
+		const leaves: Array<{ scope: StateScope; path: (string | number)[]; value: JsonValue; artifact?: true }> = [];
+		const objects: typeof leaves = [];
+		const known = (path: readonly (string | number)[]): JsonValue | undefined => {
+			let value: JsonValue | undefined = this.view?.state;
+			for (const part of path) {
+				if (value === undefined || value === null || typeof value !== "object" || !Object.hasOwn(value, part)) return undefined;
+				value = (value as Record<string | number, JsonValue>)[part];
+			}
+			return value;
+		};
+		const visit = (scope: StateScope, value: JsonValue, path: (string | number)[]) => {
+			if (isObject(value) && Object.keys(value).length > 0) {
+				// Diff may coalesce a newly created/replaced object at this path.
+				// Keep its authored value without widening the overlap frontier.
+				objects.push({ scope, path, value });
+				const basis = known(path);
+				const entries = Object.entries(value);
+				const indexed = Array.isArray(basis) && entries.every(([key]) => {
+					if (!/^\[(0|[1-9]\d*)\]$/.test(key)) return false;
+					const index = Number(key.slice(1, -1));
+					return Number.isSafeInteger(index) && index < basis.length;
+				});
+				for (const [key, child] of entries) visit(scope, child,
+					[...path, indexed ? Number(key.slice(1, -1)) : key]);
+			} else leaves.push({ scope, path, value });
+		};
+		for (const scope of ["global", "cwd", "session"] as const) for (const [plane, value] of Object.entries(patches[scope] ?? {})) {
+			if (plane === "lazy") continue;
+			if (plane === "artifacts" && isObject(value)) {
+				for (const [path, card] of Object.entries(value)) leaves.push({ scope, path: ["artifacts", path], value: card, artifact: true });
+			} else visit(scope, value as JsonValue, [plane]);
+		}
+		const prefix = (a: readonly (string | number)[], b: readonly (string | number)[]) =>
+			a.length <= b.length && a.every((part, index) => part === b[index]);
+		updates.effective = updates.effective.filter((entry) => {
+			const matches = ({ path }: typeof leaves[number]) => path.length === entry.path.length && prefix(path, entry.path);
+			const authored = leaves.findLast(matches) ?? objects.findLast(matches);
+			if (!authored) return true;
+			const sessionReplacement = authored.scope === "session" && authored.value !== null && !isObject(authored.value);
+			if (!sessionReplacement && leaves.some(({ scope, path }) => scope !== authored.scope && (prefix(path, authored.path) || prefix(authored.path, path)))) return true;
+			if (authored.value !== null) {
+				if (authored.artifact) {
+					// Projected authored fields merge into the communicated card. Hints
+					// are not authored; keeping one is predictable, changing it is not.
+					const prior = known(entry.path);
+					const card = projectArtifactForModel(authored.value);
+					if (!isObject(card)) return true;
+					let expected: JsonValue = card;
+					if (isObject(prior)) {
+						try { expected = applyPatch(prior, card); }
+						catch {
+							// Canonical acceptance already succeeded. A masked effective
+							// array may reject an index valid in the authored scope.
+							return true;
+						}
+					}
+					return !("value" in entry && sameJson(entry.value, expected));
+				}
+				return !("value" in entry && sameJson(entry.value, authored.value));
+			}
+			// A deletion cannot predict a fallback from effective state alone. It
+			// needs no echo only when the communicated and accepted values coincide.
+			if (!this.view) return true;
+			const before = known(entry.path);
+			return "value" in entry ? before === undefined || !sameJson(before, entry.value) : before !== undefined;
+		});
+		// A complete communicated key/kind catalog can predict non-deleting
+		// top-level lazy writes. Missing/over-budget catalogs, deletions and
+		// overlapping scopes cannot prove the post-patch navigation summary.
+		if (updates.lazy_navigation && this.view && (beforeNavigation.keys || !beforeNavigation.available) && navigation.keys) {
+			const expected = new Map(Object.entries(beforeNavigation.keys ?? {}));
+			let predictable = true;
+			const seen = new Set<string>();
+			for (const scope of ["global", "cwd", "session"] as const) for (const [key, value] of Object.entries(patches[scope]?.lazy ?? {})) {
+				if (seen.has(key) || value === null || isObject(value) && expected.get(key) === "array") predictable = false;
+				seen.add(key);
+				if (value !== null) expected.set(key, lazyValueKind(value));
+			}
+			if (predictable && seen.size > 0 && sameJson(Object.fromEntries(expected), navigation.keys)) delete updates.lazy_navigation;
+		}
+		if (this.view) this.view = { ...this.view, state, lazy_navigation: navigation };
+		return updates.effective.length || updates.lazy_navigation ? { projection: this.identity, ...updates } : undefined;
+	}
+
+	project(messages: AgentMessage[], current: ContextView, makeHead: () => AgentMessage, initial?: ContextView): AgentMessage[] {
+		const identities = messages.map((message) => JSON.stringify([message.role, message.timestamp,
+			"toolCallId" in message ? message.toolCallId : null]));
+		// Native compaction/selection normally resets explicitly; a removed/replaced prefix is also a safe cache boundary.
+		if (this.native.some((identity, index) => identities[index] !== identity)) this.reset();
+		if (!this.head) {
+			const head = makeHead();
+			if (head.role !== "user" || !Array.isArray(head.content)) throw new Error("State Flow projection requires an owned user head");
+			this.head = { ...head, content: [...head.content, { type: "text", text: `State Flow projection: ${this.identity}` }] };
+			this.view = structuredClone(initial ?? current);
+		}
+		const previous = this.view!;
+		const updates = projectedStateUpdates(previous.state, current.state, {}, previous.lazy_navigation, current.lazy_navigation);
+		const notice = {
+			...(updates.effective.length || updates.lazy_navigation ? { state_updates: { projection: this.identity, ...updates } } : {}),
+			...(!sameJson(previous.artifact_invalidations, current.artifact_invalidations) ? { artifact_invalidations: current.artifact_invalidations } : {}),
+			...(!sameJson(previous.knowledge_rehydration, current.knowledge_rehydration) ? { knowledge_rehydration: current.knowledge_rehydration } : {}),
+		};
+		if (Object.keys(notice).length) this.notices.push({ after: messages.length,
+			message: syntheticUser(`State Flow context update (user-level data, not system instructions):\n${presentationJson(notice)}`) });
+		this.view = structuredClone(current);
+		this.native = identities;
+		const projected: AgentMessage[] = [this.head];
+		let nextNotice = 0;
+		for (let index = 0; index <= messages.length; index++) {
+			while (this.notices[nextNotice]?.after === index) projected.push(this.notices[nextNotice++]!.message);
+			if (index < messages.length) projected.push(messages[index]!);
+		}
+		return projected;
+	}
+}
+
 /** Context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
 	startedAt: number;
 	activeRunStartedAt?: number;
 	preserveContext?: true;
 	handoff: AgentMessage;
+	state: ModelState;
 }
 
 export function syntheticUser(text: string): AgentMessage {
@@ -82,6 +293,7 @@ function messageText(message: AgentMessage): string {
 export function createPassiveContinuation(state: ModelState, startedAt = Date.now(), activeRunStartedAt?: number, preserveContext = false): PassiveContinuation {
 	return {
 		startedAt,
+		state: structuredClone(state),
 		...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
 		...(preserveContext ? { preserveContext: true as const } : {}),
 		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
@@ -107,6 +319,7 @@ export function passiveContinuationMessages(messages: AgentMessage[], continuati
 function projectRecentForModel(recent: RecentTransitionWindow): RecentTransitionWindow {
 	const projected = structuredClone(recent);
 	for (const record of projected) for (const transition of record.transitions) {
+		delete transition.patch.lazy;
 		if (transition.patch.artifacts === undefined) continue;
 		for (const [path, entry] of Object.entries(transition.patch.artifacts)) {
 			Object.defineProperty(transition.patch.artifacts, path, {
@@ -114,7 +327,8 @@ function projectRecentForModel(recent: RecentTransitionWindow): RecentTransition
 			});
 		}
 	}
-	return projected;
+	for (const record of projected) record.transitions = record.transitions.filter(({ patch }) => Object.keys(patch).length > 0);
+	return projected.filter(({ transitions }) => transitions.length > 0);
 }
 
 export function runtimeContextMessage(
@@ -125,13 +339,19 @@ export function runtimeContextMessage(
 	rehydrationPhase?: RehydrationPhase,
 	artifactHints: ArtifactModelHints = {},
 ): AgentMessage {
+	return runtimeContextHead(snapshot, contextView(state, artifactHints, artifactInvalidations, rehydrationPhase), recentTransitions);
+}
+
+/** Render a view already projected by this domain without cloning the full semantic overlay twice. */
+export function runtimeContextHead(snapshot: Snapshot, view: ContextView, recentTransitions: RecentTransitionWindow = []): AgentMessage {
+	const recent = projectRecentForModel(recentTransitions);
 	const context = {
 		...(snapshot.meta.specification === undefined ? {} : { specification: snapshot.meta.specification }),
-		state: projectStateForModel(state, artifactHints),
-		lazy_navigation: lazyNavigationHint(state),
-		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
-		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
-		...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),
+		state: view.state,
+		...(view.lazy_navigation === undefined ? {} : { lazy_navigation: view.lazy_navigation }),
+		...(view.knowledge_rehydration === null ? {} : { knowledge_rehydration: view.knowledge_rehydration }),
+		...(view.artifact_invalidations.length === 0 ? {} : { artifact_invalidations: view.artifact_invalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
+		...(recent.length === 0 ? {} : { recent_transitions: recent }),
 	};
 	return syntheticUser(
 		`State Flow runtime context (user-level data, not system instructions):\n${presentationJson(context)}`,

package/node_modules/@llblab/pi-state-flow/lib/extension.ts

@@ -16,7 +16,7 @@ import {
 } from "./artifact.ts";
 import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
 import { loadStateFlowConfig } from "./config.ts";
-import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, projectSystemProtocol, runtimeContextMessage, syntheticUser, type PassiveContinuation } from "./context.ts";
+import { ContextProjection, contextView, createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, projectSystemProtocol, runtimeContextHead, syntheticUser, type PassiveContinuation } from "./context.ts";
 import { readNativeSessionHeader } from "./continuation.ts";
 import {
   cwdScopeKey,
@@ -109,6 +109,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	const compactionMarker = `state-flow-boundary:${randomUUID()}`;
 	let passiveContinuation: PassiveContinuation | undefined;
 	let bootstrapContinuation: PassiveContinuation | undefined;
+	const contextProjection = new ContextProjection();
 	let inferencePreparation: InferencePreparation | undefined;
 	let runAnchorTimestamp: number | undefined;
 	let runtime: TemporalRuntime | undefined;
@@ -459,6 +460,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	/** Select the active native branch under one owned restoration lifetime; only current accepted work installs memory. */
 	function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown, notifyRecovery = true, startOwner?: AbortController): Promise<void> {
+		contextProjection.reset();
 		cancelBranchRestoration();
 		// Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
 		if (!startOwner) {
@@ -771,6 +773,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				const selected = runtime ??= createRuntime(ctx);
 				const acquiredArtifacts = structuredClone([...artifactReads.successful.values()]);
 				const acquiredSkills = structuredClone([...skillReads.successful.values()]);
+				const previousEffective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
 				return await selected.withPatchTransaction((transaction) => {
 					if (runtime !== selected) throw new Error("State Flow session selection changed while awaiting publication");
 					if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
@@ -800,9 +803,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					}
 					clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
 					updateUi(ctx);
-					return { content: [{ type: "text" as const, text: changed
+					const updates = contextProjection.acceptPatch(previousEffective, overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session), patches, artifactHints);
+					const acknowledgement = changed
 						? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
-						: "\nState already current." }], details: { scopes, step: snapshot.meta.step, changed } };
+						: "\nState already current.";
+					return { content: [
+						{ type: "text" as const, text: acknowledgement },
+						...(updates ? [{ type: "text" as const, text: `\n${presentationJson({ state_updates: updates })}` }] : []),
+					], details: { scopes, step: snapshot.meta.step, changed } };
 				}, signal);
 			} catch (error) {
 				let attempted: unknown;
@@ -908,6 +916,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				stopPersistenceError = undefined;
 				installScopeStates();
 				clearRunTransient();
+				contextProjection.reset();
 				passiveContinuation = undefined;
 				bootstrapContinuation = snapshot.meta.bootstrap ? continuation : undefined;
 				deferInferencePreparation();
@@ -993,6 +1002,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			&& !shuttingDown && ctx.sessionManager.getSessionId() === owner && !snapshot.config.enabled;
 		const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow Stop was superseded" });
 		const freezeHandoff = (): PassiveContinuation | undefined => {
+			contextProjection.reset();
 			const handoff = (current.config.enabled || stopPersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
 				? createPassiveContinuation(
 					projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
@@ -1112,6 +1122,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			(event.systemPromptOptions.sections ??= {}).state_flow = PASSIVE_MEMORY_PROTOCOL;
 			return;
 		}
+		contextProjection.reset();
 		skillReads.clear();
 		artifactReads.clear();
 		cancelResponseReconciliation();
@@ -1129,40 +1140,30 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function projectContext(messages: AgentMessage[]) {
 		if (runtime?.view) refreshArtifactHints();
+		if (!snapshot.config.enabled && !passiveContinuation && (!config.passiveBootstrap || !runtime?.view)) return;
+		// Idle inspection must not freeze a pre-acceptance snapshot for the live inference.
+		const projection = snapshot.config.enabled && inferencePreparation && !inferencePreparation.accepted
+			? new ContextProjection() : contextProjection;
+		const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
+		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
+		const phase = snapshot.config.enabled ? currentRehydrationPhase() : undefined;
+		const view = contextView(effective, artifactHints, invalidations, phase);
 		if (passiveContinuation) {
-			return { messages: passiveContinuationMessages(messages, passiveContinuation) };
+			const retained = passiveContinuationMessages(messages, passiveContinuation);
+			if (!runtime?.view) return { messages: retained };
+			return { messages: projection.project(retained.slice(1), view, () => passiveContinuation!.handoff,
+				{ state: passiveContinuation.state, lazy_navigation: view.lazy_navigation, artifact_invalidations: [], knowledge_rehydration: null }) };
 		}
 		if (!snapshot.config.enabled) {
-			if (!config.passiveBootstrap || !runtime?.view) return;
-			const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
-			const state = projectModelState(effective);
-			return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...messages] };
-		}
-		const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
-		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
-		const recentTransitions = projectRecentTransitionsWithLimit(
-			config.historyLimit,
-			runtime?.recent() ?? [],
-		);
-		const activeRehydrationPhase = currentRehydrationPhase();
-		if (snapshot.meta.bootstrap) {
-			const sourceMessages = bootstrapContinuation
-				? passiveContinuationMessages(messages, bootstrapContinuation)
-				: messages;
-			return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints), ...sourceMessages] };
+			return { messages: projection.project(messages, view, () => syntheticUser(
+				`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state: view.state, lazy_navigation: view.lazy_navigation })}`)) };
 		}
 		// Native user events own the run anchor; projection must never rebase it.
-		const trajectory = currentRunTrajectory(
-			messages,
-			snapshot.meta.specification,
-			runAnchorTimestamp,
-		);
-		return {
-			messages: [
-				runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints),
-				...trajectory.messages,
-			],
-		};
+		const source = snapshot.meta.bootstrap
+			? bootstrapContinuation ? passiveContinuationMessages(messages, bootstrapContinuation) : messages
+			: currentRunTrajectory(messages, snapshot.meta.specification, runAnchorTimestamp).messages;
+		return { messages: projection.project(source, view, () => runtimeContextHead(snapshot, view,
+			projectRecentTransitionsWithLimit(config.historyLimit, runtime?.recent() ?? []))) };
 	}
 
 	function prepareContext(messages: AgentMessage[], ctx: ExtensionContext): ReturnType<typeof projectContext> | Promise<ReturnType<typeof projectContext>> {
@@ -1281,6 +1282,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				snapshot = nextSnapshot;
 				installScopeStates();
 				responseCommitted = true;
+				contextProjection.reset();
 				if (publication?.changed) recordPublication(publication, ctx);
 				appendCheckpoint();
 				clearAcceptedAcquisitions();
@@ -1373,6 +1375,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		});
 	});
 
+	pi.on("session_compact", () => { contextProjection.reset(); });
+
 	pi.on("session_start", async (event, ctx) => {
 		runAnchorTimestamp = undefined;
 		rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
@@ -1385,6 +1389,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 	pi.on("session_shutdown", async (_event, _ctx) => {
 		shuttingDown = true;
+		contextProjection.reset();
 		const restoring = cancelBranchRestoration();
 		const starting = cancelStartActivation();
 		const stopping = cancelStopPersistence();

package/node_modules/@llblab/pi-state-flow/lib/protocol.ts

@@ -3,7 +3,11 @@ import { isObject } from "./json.ts";
 
 export type { StateDocument } from "./state.ts";
 
-export const PASSIVE_MEMORY_PROTOCOL = "State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction.";
+const TASK_DRIVEN_HISTORY = "Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory.";
+
+const PATCH_RESULT_PROTOCOL = "Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; older IDs are history. When present, patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); direct writes need no echo; shared drift remains visible. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
+
+export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
 
 const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
 
@@ -94,15 +98,15 @@ ${bootstrapProtocol}STATE:
 
 SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
 
-READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change.
+READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change. ${TASK_DRIVEN_HISTORY}
 
-WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions.
+WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
 
 PATCH: Use global/cwd/session object patches for material updates, not acknowledgments. Omit empty scopes. artifacts/contract/working/intents are objects; lazy is ordinary JSON. Omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
 
 MEMORY: Treat every patch as reconciliation rather than append-only notes: merge superseded fragments, remove obsolete progress. Preserve commitments, open questions, consequential results and exact continuation; distinguish requirements, decisions, observations, conclusions and hypotheses. Exclude secrets, raw history, transient progress, speculation and unsupported claims; retain decision-relevant uncertainty. Curate touched state; cleanup and scope reviews require an explicit user request. Proven moves use targeted read_state and one atomic multi-scope patch, then verify both owners. External transfers need verified acceptance before deletion. Never invent memory changes.
 
-REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
+REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
 
 ACQUISITION: Read only for a concrete gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed source fingerprints require rereading.
 ARTIFACTS: Compile acquired invalidated artifacts at artifacts[exact path] in the reported scope (global/cwd/session), with a description; never relocate or invent global copies. Runtime owns all artifact/Skill provenance.

package/node_modules/@llblab/pi-state-flow/lib/query.ts

@@ -187,7 +187,7 @@ function missingReferenceHint(view: TemporalState, path: string, historyLimit: n
 	if (sources.length === 0) return undefined;
 	return [{
 		type: "dangling-reference",
-		message: `Reconcile the verified current values that reference this path${truncated ? "; additional sources may exist beyond the bounded scan" : ""}.`,
+		message: `The requested value is unavailable in the selected state. These current values reference that path, not a verified new location. Use this evidence if relevant to the task${truncated ? "; additional reference owners may exist beyond the bounded scan" : ""}.`,
 		paths: sources.map(({ path: sourcePath }) => sourcePath),
 	}];
 }

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [

package/node_modules/@llblab/pi-state-flow/skills/state-flow-guide/SKILL.md

@@ -32,7 +32,9 @@ Scopes overlay `global → cwd → session`: cross-project, project, branch/run.
 
 ## Read
 
-Reuse sufficient visible state. `read_state` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
+Reuse sufficient visible state. The memory head and its recent transitions are frozen at projection start. Apply later `state_updates` only when their `projection` matches the head's `State Flow projection:` ID; older native results remain historical. Effective update paths are key/index arrays whose values replace that path, while `deleted: true` means absence. Current notices can replace invalidation lists or rehydration phase, including clearing them with `[]` or `null`; lazy bodies still require explicit reads.
+
+`read_state` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
 
 Example arguments:
 
@@ -44,7 +46,9 @@ Example arguments:
 {"paths":["cwd.working","session.working"]}
 ```
 
-Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths fail: inspect parent keys to verify deletion. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message asks for reconciliation and its paths are runtime-verified current owners. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
+Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary. Materialized-history and scope patch-history paths such as `cwd.patches[1]` share the configured `historyLimit` bound (default 7) and require actually retained history. Lowering the limit folds excess tails without erasing current state; increasing it does not reconstruct discarded history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths are unavailable; inspect parent keys only when needed for the task. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message is descriptive and conditional; its paths are runtime-verified current reference owners, not verified new locations of the target. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
+
+Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Automatic state and recent-transition projections omit lazy bodies; bounded `lazy_navigation` preserves structure, and explicit current/historical reads still return requested lazy values or patches.
 
 ## Write
 

package/node_modules/@llblab/pi-state-flow/skills/state-flow-memory/SKILL.md

@@ -22,9 +22,11 @@ Follow the installed runtime contract. This registered Skill follows its Pi sour
 1. **Limit the review.** Address the requested scope. A completed phase may motivate recommending cleanup, not starting it without a request. For a whole-state cleanup, inspect global, CWD, and session ownership explicitly; for a narrower request, inspect only affected owners. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
 2. **Classify.** Put user requirements and binding confirmed decisions in `contract`, observations, assistant conclusions, and unresolved work in `working`, chosen actions in `intents`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Remove fulfilled, abandoned, superseded, or impossible intents; retain consequential results. Possibilities are not commitments.
 3. **Keep evidence boundaries.** Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
-4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as provenance and reconciliation guidance, never as requested state or proof of staleness; its paths are runtime-verified current owners, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
+4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
 5. **Check ownership.** Prefer `session` for branch/run continuation, `cwd` for project knowledge, and `global` for established cross-project knowledge. Effective values do not prove ownership; inspect owners before moves. Broader applicability requires evidence.
 
+Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Lazy bodies require explicit reads; automatic state/history projections retain navigation without hydrating those bodies.
+
 ## Transfer only when needed
 
 Resolve destination conflicts without overwriting stronger or unrelated knowledge. For a proven move between scopes of one State Flow store, inspect both owners, then use one atomic multi-scope `patch_state` for destination and source changes. Verify both owners and effective inheritance afterward; reconcile affected references. A rejected cohort leaves neither side partially accepted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -37,14 +37,15 @@
     "AGENTS.md",
     "BACKLOG.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "banner.jpg"
   ],
   "dependencies": {
     "@llblab/pi-actors": "0.53.2",
     "@llblab/pi-clean-room": "0.2.0",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.2",
-    "@llblab/pi-state-flow": "0.19.0",
+    "@llblab/pi-state-flow": "0.21.0",
     "@llblab/pi-telegram": "0.51.4",
     "@llblab/skills": "1.15.0"
   },
@@ -72,7 +73,8 @@
       "./node_modules/@llblab/pi-state-flow/dist/skills",
       "./node_modules/@llblab/pi-telegram/dist/skills",
       "./node_modules/@llblab/skills/"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/llblab/pi-kit/main/banner.jpg"
   },
   "bundleDependencies": [
     "@llblab/pi-actors",