@llblab/pi-kit 0.23.2 → 0.24.1

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
@@ -127,13 +339,18 @@ 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 })) }),
+		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(

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

@@ -5,7 +5,9 @@ export type { StateDocument } from "./state.ts";
 
 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.";
 
-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}`;
+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"]);
 
@@ -98,7 +100,7 @@ SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd
 
 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.
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.19.1",
+  "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:
 

package/node_modules/@llblab/pi-telegram/AGENTS.md

@@ -125,7 +125,7 @@ The detailed map is canonical in [`docs/architecture.md`](./docs/architecture.md
 - Command templates remain compact and shell-free. Use string leaves or ordered `template` arrays; shell operators are not an execution contract. Examples use portable executable placeholders, never machine-local paths.
 - `telegram_attach` is the canonical file path and `telegram_message` the direct Markdown text/buttons path. Both require current direct or registered-follower authority and must not replace the normal active-turn reply.
 - Inbound handlers transform text/media before queueing; outbound handlers precede programmatic/provider fallbacks. Public contracts and ordering live in `docs/inbound.md`, `docs/outbound.md`, and `docs/public-api.md`.
-- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through the single `/telegram-internal` Pi gateway via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; only a runtime-armed typed action may execute, manual invocation reports that the command cannot be run manually, and the handler receives the real `ExtensionCommandContext` before calling `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
+- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through the single `/telegram-internal` Pi gateway via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; only a runtime-armed typed action may execute, manual invocation reports that the command cannot be run manually, and the handler receives the real `ExtensionCommandContext` before calling `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. A registered follower cannot persist leader-owned state: its Workspace Thread intent is published and claimed by the leader over capability-gated exact-generation bus RPC after leader-side binding validation, and records its source runtime instance so only that follower lineage may re-key or claim it. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
 
 ## 7. Engineering Conventions
 

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 0.51.5: Follower Thread new-session hotfix
+
+- `Follower Thread /new`: Telegram `/new` now starts a new session in a follower's Pi process and preserves its Thread binding. The leader publishes and later claims the durable replacement intent through capability-gated, generation-fenced bus requests, validating its own live registration and Workspace binding before accepting the follower's request. Incompatible or stale leaders fail closed rather than silently switching sessions.
+- `Follower restore diagnostics`: Session startup now records when automatic follower restore lacks a session binding, Threaded Mode, or leader-side Workspace authority, or finishes without connecting. Restore-only refusal still cannot create a new Thread; `/telegram-connect` remains the explicit recovery path.
+
 ## 0.51.4: Resolver-owned Skills and drift-safe Git installs
 
 - `Resolver-owned Skills`: Auto-discovered user/project checkouts now contribute source Skills even when Pi selects their compiled entrypoint, while manifest-loaded npm, Git, and Pi Kit packages retain `pi.skills` filters and package provenance. Resolver regressions cover checkout and filtered-package behavior; unsupported source manifest aliases are removed.

package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.d.ts

@@ -54,6 +54,8 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
         threadId: number;
     }) => Promise<string>;
     setThreadDisplayMode?: (mode: TelegramThreadDisplayMode) => Promise<void>;
+    /** Leader-mediated durable publication or successor claim; true only after exact commit. */
+    requestSessionReplacement?: (operation: "publish" | "settle", intent: Threads.TelegramSessionReplacementIntent) => Promise<boolean>;
     stop: () => void;
 }
 export interface TelegramBusFollowerSessionReplacementSuspenderDeps {

package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.js

@@ -11,7 +11,7 @@ import * as Threads from "./threads.js";
 import { parseTelegramUpdateJournalQueueOwner } from "./journal.js";
 import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, } from "./locks.js";
 import { isTelegramApiMethodRetrySafe, TelegramApiCommitUnknownError, TelegramApiStaleTargetError, } from "./telegram-api.js";
-import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, } from "./bus.js";
+import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, } from "./bus.js";
 import { getTelegramBusTransportRetryPolicy, TELEGRAM_BUS_REGISTRATION_RETRY, } from "./bus-transport.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
 export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
@@ -1214,8 +1214,13 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
                 deps.setActiveAuthSecret?.(undefined);
                 await deps.stopReceiving?.();
                 if (registrationOptions?.restoreWorkspace &&
-                    response.error?.code === "workspace-binding-unavailable")
+                    response.error?.code === "workspace-binding-unavailable") {
+                    deps.recordRuntimeEvent?.("bus", "Telegram follower auto-connect refused by leader: Workspace binding unavailable.", {
+                        phase: "follower-auto-connect-skip",
+                        reason: "leader-binding-unavailable",
+                    });
                     return false;
+                }
                 throw new Error(response.message ??
                     "Telegram bus follower registration was rejected.");
             }
@@ -1426,6 +1431,54 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
             }
             return resetName;
         },
+        async requestSessionReplacement(operation, intent) {
+            if (!activeLeaderSocketPath || !activeRegistrationGeneration) {
+                throw new Error("Telegram follower is not registered with the leader.");
+            }
+            if (!hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT) ||
+                !hasTelegramBusCapability(deps.registrationState?.getLeaderProtocol(), TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT)) {
+                throw new Error("The active Telegram leader does not support follower session replacement. Update or restart that Pi instance.");
+            }
+            const expectedLeaderSocketPath = activeLeaderSocketPath;
+            const expectedRegistrationGeneration = activeRegistrationGeneration;
+            const expectedAuthSecret = activeAuthSecret;
+            const requestId = deps.createRequestId();
+            const response = await sendTelegramBusLocalEnvelope({
+                socketPath: expectedLeaderSocketPath,
+                timeoutMs: registrationTimeoutMs,
+                retry: getTelegramBusTransportRetryPolicy({
+                    endpoint: expectedLeaderSocketPath,
+                    operation: "operation",
+                }),
+                envelope: {
+                    kind: operation === "publish"
+                        ? "follower.publishSessionReplacement"
+                        : "follower.settleSessionReplacement",
+                    requestId,
+                    auth: expectedAuthSecret,
+                    instanceId: deps.instanceId,
+                    registrationGeneration: expectedRegistrationGeneration,
+                    intent,
+                    sentAtMs: getNowMs(),
+                },
+            });
+            if (response?.kind !== "bus.ack" || !response.ok ||
+                response.requestId !== requestId ||
+                !isRecord(response.result) || response.result.committed !== true) {
+                throw new Error(response?.kind === "bus.ack"
+                    ? (response.message ?? "Telegram session replacement was rejected.")
+                    : "Telegram session replacement was not acknowledged.");
+            }
+            if (activeLeaderSocketPath !== expectedLeaderSocketPath ||
+                activeRegistrationGeneration !== expectedRegistrationGeneration ||
+                activeAuthSecret !== expectedAuthSecret ||
+                (deps.registrationState &&
+                    deps.registrationState.getGeneration() !==
+                        expectedRegistrationGeneration)) {
+                throw new Error("Telegram session replacement completed for a stale follower registration.");
+            }
+            return true;
+        },
         async disconnectFromLeader() {
             if (!activeLeaderSocketPath || !activeRegistrationGeneration) {
                 return false;

package/node_modules/@llblab/pi-telegram/dist/lib/bus-leader.d.ts

@@ -135,6 +135,23 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
     runWorkspaceOperation?: TelegramBusWorkspaceAdmissionRunner;
     workspaceRotation?: TelegramWorkspaceSlotRotationPorts;
 }
+export type TelegramBusFollowerSessionReplacementOperation = (follower: TelegramBusFollowerView, intent: Threads.TelegramSessionReplacementIntent, isCurrent: () => boolean) => Promise<boolean>;
+/**
+ * Leader-owned durable session-replacement authority for registered followers.
+ * Followers cannot persist `state.json`; the leader validates the request
+ * against its live registry entry and authoritative Workspace binding before
+ * one CAS publication or claim. Follower memory is never accepted as binding
+ * evidence.
+ */
+export declare function createTelegramBusFollowerSessionReplacementAuthority(deps: {
+    store: Pick<Threads.TelegramTopicTargetStore, "load" | "getWorkspaceBindingByTarget" | "getSessionReplacementIntent" | "commitSessionReplacementIntent" | "removeSessionReplacementIntent">;
+    getTelegramProfile?: () => string | undefined;
+    getNowMs?: () => number;
+    ttlMs?: number;
+}): {
+    publish: TelegramBusFollowerSessionReplacementOperation;
+    settle: TelegramBusFollowerSessionReplacementOperation;
+};
 export declare function createTelegramBusLeaderRuntimeAssembly<TContext>(deps: TelegramBusLeaderRuntimeAssemblyDeps<TContext>): TelegramBusLeaderRuntime<TContext> & {
     renameLeaderThreadAdmitted: (threadName: string, expectedTarget?: Threads.TelegramTopicTargetRecord["target"]) => Promise<Threads.TelegramTopicTargetRecord>;
     resetLeaderThreadName: (expectedTarget: Threads.TelegramTopicTargetRecord["target"]) => Promise<{
@@ -188,6 +205,8 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     }> | {
         threadName: string;
     };
+    publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+    settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
     getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
     onFollowerRegistered?: () => void;
     applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
@@ -273,6 +292,8 @@ export declare function createTelegramBusLeaderEnvelopeHandler(deps: {
     }> | {
         threadName: string;
     };
+    publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+    settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
     getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
     onFollowerRegistered?: () => void;
     applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;