@llblab/pi-kit 0.15.0 → 0.16.0

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

@@ -7,6 +7,29 @@ import type { RehydrationPhase } from "./rehydration.ts";
 import { projectStateForModel, type MaterializedState } from "./state.ts";
 
 export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+const LAZY_HINT_PATH = "effective.lazy";
+const LAZY_HINT_MAX_KEYS = 32;
+const LAZY_HINT_MAX_JSON_CHARS = 1024;
+
+type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
+
+function lazyValueKind(value: Exclude<MaterializedState["lazy"], undefined>): LazyValueKind {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "object") return "object";
+	return typeof value as Exclude<LazyValueKind, "array" | "object">;
+}
+
+/** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
+export function lazyNavigationHint(state: MaterializedState): { available: boolean; path: string; keys?: Record<string, LazyValueKind> } {
+	const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
+	if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy)) return base;
+	const entries = Object.entries(state.lazy);
+	if (entries.length > LAZY_HINT_MAX_KEYS) return base;
+	const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
+	return JSON.stringify(keys).length <= LAZY_HINT_MAX_JSON_CHARS ? { ...base, keys } : base;
+}
+
 
 /** Bounded context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
@@ -85,6 +108,7 @@ export function runtimeContextMessage(
 	const context = {
 		specification: snapshot.meta.specification,
 		state: projectStateForModel(state),
+		lazy_navigation: lazyNavigationHint(state),
 		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
 		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
 		...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),

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

@@ -223,11 +223,12 @@ export function inspectStateFlowContinuationProvenance(
 	const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
 	try {
 		const config = readRegular(paths.config);
+		const runtimeSource = readRegular(paths.runtime);
 		const meta = readRegular(paths.meta);
-		if (config === undefined && meta === undefined) {
+		if (config === undefined && runtimeSource === undefined && meta === undefined) {
 			return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		}
-		const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
+		const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
 		if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
 		if (runtime.meta.publication === "files") {
@@ -238,7 +239,7 @@ export function inspectStateFlowContinuationProvenance(
 			validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
 			return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
 		}
-		const runtimePath = relative(resolve(repositoryRoot), paths.meta);
+		const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
 		if (runtimePath.startsWith("..")) throw new Error("runtime provenance escapes repository");
 		const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 		if (!owner) throw new Error("runtime owner commit is unavailable");

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

@@ -27,6 +27,7 @@ const STATE_FILE = "state.json";
 const CHECKPOINT_FILE = "checkpoint.json";
 const PATCHES_FILE = "patches.jsonl";
 const META_FILE = "meta.json";
+const RUNTIME_FILE = "runtime.json";
 
 /** Canonical semantic sources plus runtime-owned temporal metadata. */
 export interface ScopeStreamSources {
@@ -159,9 +160,9 @@ export function temporalScopePaths(cwd: string, sessionId: string, scope: StateS
 	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
 }
 
-export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; meta: string } {
+export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; runtime: string; meta: string } {
 	const directory = sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory;
-	return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
+	return { config: join(directory, "config.json"), runtime: join(directory, RUNTIME_FILE), meta: join(directory, META_FILE) };
 }
 
 /** Unsupported state.json presence never becomes an anchored checkpoint. */
@@ -178,7 +179,7 @@ export function captureTemporalFileBases(cwd: string, sessionId: string, reposit
 	const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
 		const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 		const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
-		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.meta])];
+		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
 	});
 	return captureOwnedFileBases(paths, repositoryRoot);
 }
@@ -218,6 +219,9 @@ export function serializeScopeMetadata(
 	cwdIdentity?: string, existingSource?: string,
 ): string {
 	const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
+	if (scope === "session") {
+		for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap", "remotePublication", "revision", "temporalRevision", "publication"]) delete existing[key];
+	}
 	const sources = serializeScopeStream(stream, scope, cwdIdentity);
 	const value = {
 		...existing,
@@ -359,7 +363,7 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
 		return cwdKey(segments[0]!)
 			&& sessionKey(segments[1]!)
 			&& (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
-				|| segments[2] === "config.json" || segments[2] === META_FILE);
+				|| segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
 	}
 	return false;
 }

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

@@ -27,3 +27,8 @@ export function prepareRun(snapshot: Snapshot, prompt: string): boolean {
 	snapshot.meta.validation = undefined;
 	return true;
 }
+
+/** Retain the full prompt only while its run remains recoverable and unfinished. */
+export function completeRun(snapshot: Snapshot): void {
+	delete snapshot.meta.specification;
+}

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

@@ -5,7 +5,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.ts";
-import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
+import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
 import { ArtifactReadTracker } from "./acquisition.ts";
 import { loadStateFlowConfig } from "./config.ts";
 import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
@@ -18,7 +18,7 @@ import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatche
 import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
 import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
 import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
-import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
+import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
 import { recoverSnapshot } from "./recovery.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
 import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
@@ -26,8 +26,8 @@ import { coalescePublicationTarget, createPublicationQueue, type PublicationQueu
 import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
 import { runPublicationWorker } from "./publication.ts";
 import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
-import { isObject, sameJson } from "./json.ts";
-import { readStatePath } from "./query.ts";
+import { canonicalJson, isObject, sameJson } from "./json.ts";
+import { readProjectedState, readStatePath } from "./query.ts";
 import {
 	cwdScopeKey,
 	resolveSessionAddress,
@@ -50,6 +50,8 @@ export interface StateFlowExtensionOptions {
 	knowledgeRoot?: string;
 	onRuntime?: (accessor: { read(offset?: number, scope?: StateScope): MaterializedState }) => void;
 	telegram?: { load?: StateFlowTelegramLoader };
+	/** Test/SDK capability override; repository config remains the Pi default. */
+	passive?: { bootstrap?: boolean; tools?: boolean };
 }
 
 export const PATCH_STATE_TOOL_NAME = "patch_state";
@@ -113,7 +115,12 @@ function separatedFailure(error: unknown): Error {
 
 export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
 	const agentDir = options.agentDir ?? getAgentDir();
-	const config = loadStateFlowConfig(agentDir);
+	const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
+	const config = {
+		...loadedConfig,
+		passiveBootstrap: options.passive?.bootstrap ?? loadedConfig.passiveBootstrap,
+		passiveTools: options.passive?.tools ?? loadedConfig.passiveTools,
+	};
 	let snapshot: Snapshot = emptySnapshot();
 	let scopeStates: ScopedStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
 	let branchHasSnapshot = false;
@@ -268,11 +275,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
 	}
 
+	function passiveToolsAvailable(): boolean {
+		return snapshot.config.enabled || config.passiveTools;
+	}
+
 	function syncStateFlowTools(): void {
 		const active = pi.getActiveTools();
 		const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
-		if (owned.every((name) => active.includes(name) === snapshot.config.enabled)) return;
-		pi.setActiveTools(snapshot.config.enabled
+		const available = passiveToolsAvailable();
+		if (owned.every((name) => active.includes(name) === available)) return;
+		pi.setActiveTools(available
 			? [...new Set([...active, ...owned])]
 			: active.filter((name) => !owned.includes(name)));
 	}
@@ -680,6 +692,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				else if (snapshot.meta.bootstrap) bootstrapContinuation = continuation;
 			}
 		}
+		if (!snapshot.config.enabled && (config.passiveBootstrap || config.passiveTools) && !runtime?.view) {
+			try {
+				runtime?.loadPassive();
+				installScopeStates();
+			} catch (error) {
+				ctx.ui.notify(`State Flow passive memory is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			}
+		}
 		if (snapshot.config.enabled) deferArtifactRefresh();
 		syncStateFlowTools();
 		updateUi(ctx);
@@ -796,34 +816,38 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.registerTool({
 		name: READ_STATE_TOOL_NAME,
 		label: "Read State",
-		description: "Read State Flow through a unified path such as state, state[1], state.cwd[2], or state.global.patches[0]. The legacy offset/scope form remains accepted. Read-only and lazy; unavailable hot history is an error.",
-		promptSnippet: "Read cached state or accepted scope patches with a unified path",
+		description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary.",
+		promptSnippet: "Read exact state values, structures, or historical semantic patches",
 		parameters: Type.Object({
-			path: Type.Optional(Type.String({ description: "Unified query path; current aliases use index 0" })),
-			offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 7, description: "Legacy accepted-transition offset; defaults to 0" })),
-			scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"] as const, { description: "Legacy projection at the same boundary; defaults to effective" })),
+			path: Type.Optional(Type.String({ description: "One semantic path; unscoped paths use effective, explicit roots may use effective/global/cwd/session and historical [N], and arrays support half-open [start..end] ranges" })),
+			paths: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Ordered query paths evaluated as one all-or-error read" })),
+			projection: Type.Optional(StringEnum(["value", "keys", "patch"] as const, { description: "Value snapshot by default, structural keys with minimal meta, or the selected historical semantic patch" })),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, signal) {
 			try {
-				type ReadDetails = { path?: string; offset?: number; scope?: string; transitionId: string };
-				if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
+				type ReadDetails = { path?: string; paths?: string[]; projection?: string; transitionId?: string };
+				if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
 				if (signal?.aborted) throw new Error("State Flow read was aborted");
 				if (!runtime?.view) throw new Error("State Flow temporal runtime is unavailable");
-				if (params.path !== undefined) {
-					if (params.offset !== undefined || params.scope !== undefined) throw new Error("read_state path cannot be combined with legacy offset or scope");
-					const result = readStatePath(runtime.view, params.path);
+				if (params.path === undefined && params.paths === undefined) throw new Error("read_state requires path or paths");
+				if (params.path !== undefined && params.paths !== undefined) throw new Error("read_state accepts path or paths, not both");
+				{
+					const paths = params.paths ?? [params.path!];
+					if (paths.length === 1 && /^(?:global|cwd|session)\.patches(?:\[\d+\])?$/.test(paths[0]!)) {
+						if (params.projection !== undefined && params.projection !== "value") throw new Error("Scope patch paths support only the value projection");
+						const result = readStatePath(runtime.view, paths[0]!);
+						if (!("patch" in result)) throw new Error("Expected a scope patch path");
+						return {
+							content: [{ type: "text", text: `\n${JSON.stringify({ patch: result.patch })}` }],
+							details: { path: paths[0], transitionId: result.boundary.id } as ReadDetails,
+						};
+					}
+					const result = readProjectedState(runtime.view, paths, params.projection);
 					return {
 						content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
-						details: { path: params.path, transitionId: result.boundary.id } as ReadDetails,
+						details: { ...(params.path === undefined ? { paths } : { path: params.path }), projection: params.projection ?? "value" } as ReadDetails,
 					};
 				}
-				const { offset = 0, scope = "effective" } = params;
-				const state = runtime.read(offset, scope === "effective" ? undefined : scope);
-				const boundary = runtime.view.lineage.at(-1 - offset)!;
-				return {
-					content: [{ type: "text", text: `\n${JSON.stringify({ offset, scope, boundary, state: projectStateForModel(state) })}` }],
-					details: { offset, scope, transitionId: boundary.id } as ReadDetails,
-				};
 			} catch (error) {
 				throw separatedFailure(error);
 			}
@@ -856,7 +880,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			try {
-				if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
+				if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
 				if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
 				if (!isObject(params)) throw new Error("patch_state requires an object");
 				const allowed = new Set(["global", "cwd", "session", "final"]);
@@ -878,16 +902,27 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 						return { content: [{ type: "text", text: "\nState unchanged; iteration remains non-terminal." }], details: { final: false } };
 					}
 					if (params.final !== true) throw new Error('patch_state requires at least one scope patch or {"final":true}');
+					if (!snapshot.config.enabled) return { content: [{ type: "text", text: "\nState unchanged; passive turns have no terminal barrier." }], details: { final: false } };
 					validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
 					terminalEligible = true;
 					return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
 				}
-				const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
+				if (!runtime?.view) {
+					runtime ??= createRuntime(ctx);
+					runtime.prepare();
+					const publication = runtime.initialize(snapshot, true, undefined, true);
+					recordPolicyPublication(publication, ctx);
+					installScopeStates();
+					branchHasSnapshot = true;
+				}
+				runtime.migrateLegacyStorage();
+				installScopeStates();
+				const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
 				const semanticChange = (["global", "cwd", "session"] as const).some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
 				const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
 				if (!semanticChange && !provenanceChange) throw new Error('patch_state scope patches must materially update state or required provenance; omit them and use {"final":true} when unchanged');
 				commitStage(stage, ctx, false);
-				if (params.final === true) {
+				if (params.final === true && snapshot.config.enabled) {
 					terminalEligible = true;
 				}
 				updateUi(ctx);
@@ -1051,11 +1086,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				bootstrap: snapshot.meta.bootstrap === true,
 				startPending: telegramStartPending,
 			}),
-			state: (scope) => projectStateForModel(
-				scope === "effective"
+			state: (scope) => {
+				const selected = scope === "effective"
 					? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
-					: scopeStates[scope],
-			),
+					: scopeStates[scope];
+				return {
+					...projectStateForModel(selected),
+					...(Object.hasOwn(selected, "lazy") ? { lazy: structuredClone(selected.lazy) } : {}),
+				};
+			},
 			canStartNow: () => activeContext === undefined || activeContext.isIdle(),
 			start: () => {
 				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -1080,7 +1119,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	void telegram.ensure();
 
 	pi.on("before_agent_start", (event, ctx) => {
-		if (!snapshot.config.enabled) return;
+		if (!snapshot.config.enabled) {
+			if (!config.passiveBootstrap || !runtime?.view) return;
+			return {
+				systemPrompt: `${event.systemPrompt}\n\nState Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns do not require final:true and never trigger State Flow continuation or compaction.`,
+			};
+		}
 		skillReads.clear();
 		artifactReads.clear();
 		if (artifactRefreshPending) refreshArtifactInvalidations(ctx);
@@ -1105,7 +1149,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (passiveContinuation) {
 			return { messages: passiveContinuationMessages(event.messages as AgentMessage[], passiveContinuation) };
 		}
-		if (!snapshot.config.enabled || snapshot.meta.specification === undefined) return;
+		if (!snapshot.config.enabled) {
+			if (!config.passiveBootstrap || !runtime?.view) return;
+			const state = projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session));
+			return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${canonicalJson({ state, lazy_navigation: lazyNavigationHint(state) })}`), ...(event.messages as AgentMessage[])] };
+		}
+		if (snapshot.meta.specification === undefined) return;
 		const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
 		const invalidations = artifactInvalidations.map(({ path, reason }) => ({ path, reason }));
 		const recentTransitions = projectRecentTransitionsWithLimit(
@@ -1206,9 +1255,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			return;
 		}
 		let responseCommitted = false;
+		const specification = snapshot.meta.specification;
 		try {
 			const response = finalizedAssistantResponse(event.message);
 			const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime!.causalBasis());
+			completeRun(snapshot);
 			commitStage(stage, ctx, true);
 			responseCommitted = true;
 			bootstrapContinuation = undefined;
@@ -1217,6 +1268,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
 			completedRunAccepted = !wasBootstrap;
 		} catch (error) {
+			if (!responseCommitted && specification !== undefined) snapshot.meta.specification = specification;
 			recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
 			ctx.ui.notify(responseCommitted
 				? `State Flow committed the final response; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`

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

@@ -1,6 +1,6 @@
 // Domain: durable Git revision reads, compare-and-swap publication, and exact-commit push retry.
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, relative, resolve, sep } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -25,7 +25,7 @@ import { planLegacyStorageMigration } from "./migration.ts";
 import { canonicalJson, sameJson } from "./json.ts";
 import { validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
 import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime, type SessionRuntime, type Snapshot } from "./snapshot.ts";
-import { assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.ts";
+import { acquirePublicationLock, assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.ts";
 import type { MaterializedState, StateScope } from "./state.ts";
 
 const GIT_TIMEOUT_MS = 15_000;
@@ -108,12 +108,9 @@ function withPublicationLock<T>(repositoryRoot: string, action: (root: string) =
 		const root = assertRepositoryRoot(lockedRoot);
 		const common = resolve(root, git(root, ["rev-parse", "--git-common-dir"]).stdout.trim());
 		const path = resolve(common, "state-flow-publication.lock");
-		let descriptor: number;
-		try {
-			descriptor = openSync(path, "wx", 0o600);
-		} catch (error) {
-			throw new Error(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
-		}
+		const descriptor = acquirePublicationLock(path, (cause) => new Error(
+			`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause },
+		));
 		try {
 			writeFileSync(descriptor, `${process.pid}\n`);
 			return action(root);
@@ -229,15 +226,15 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 	const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
 	const readFile = revisionFileReader(root, revision, [
 		...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
-		canonicalRuntime.config, canonicalRuntime.meta,
+		canonicalRuntime.config, canonicalRuntime.runtime,
 	]);
 	const files: DurableFileBase[] = [];
 	const scopes = {} as Record<StateScope, ScopeStream | undefined>;
 	const provenance: Record<StateScope, ArtifactProvenanceRegistry> = { global: {}, cwd: {}, session: {} };
 	for (const { scope, paths } of scopePaths) {
 		const selected = revisionScopeFiles(readFile, paths);
-		files.push(selected.checkpoint, selected.patches, ...(scope === "session" ? [] : [selected.meta]));
-		if (scope !== "session") provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
+		files.push(selected.checkpoint, selected.patches, selected.meta);
+		provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
 		try {
 			scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope,
 				scope === "cwd" ? cwd : undefined, selected.meta.content);
@@ -246,15 +243,18 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 		}
 	}
 	const readRuntime = (paths: ReturnType<typeof sessionRuntimePaths>) => ({
-		paths, config: readFile(paths.config), meta: readFile(paths.meta),
+		paths, config: readFile(paths.config), runtime: readFile(paths.runtime), meta: readFile(paths.meta),
 	});
-	const { paths: runtimePaths, config, meta } = readRuntime(canonicalRuntime);
-	files.push(config, meta);
-	const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
+	const { paths: runtimePaths, config, runtime, meta } = readRuntime(canonicalRuntime);
+	files.push(config, runtime);
+	const document = parseSessionRuntime(config.content, runtime.content, cwd, sessionId, meta.content);
 	if (document === undefined) return { base: { head: revision, files }, scopes, provenance };
-	provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
+	if (Object.keys(provenance.session).length === 0 && document.meta.artifacts !== undefined) {
+		provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
+	}
+	const runtimeOwnerPath = runtime.content === undefined ? runtimePaths.meta : runtimePaths.runtime;
 	const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
-		relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
+		relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimeOwnerPath, root),
 	]).stdout.trim();
 	assertReadableRevision(root, owner);
 	let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
@@ -410,8 +410,7 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
 	if (snapshot.meta.step !== selected.runtime.meta.step) throw new Error("Git adoption must preserve the semantic step");
 	const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
 	runtime.meta.temporalRevision = "self";
-	const sources = serializeSessionRuntime(runtime, cwd, sessionId, selected.view.scopes.session,
-		selected.base.files.find(({ path }) => path === sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey).meta)?.content);
+	const sources = serializeSessionRuntime(runtime, cwd, sessionId);
 	initializeGitRepository(repositoryRoot);
 	return withPublicationLock(repositoryRoot, (root) => {
 		const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -420,13 +419,14 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
 		const provenancePaths = new Set([
 			temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
 			temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
+			temporalScopePaths(cwd, sessionId, "session", root, sessionKey).meta,
 		]);
 		// Preserve exact valid scope bytes; only runtime provenance changes representation.
 		const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
 			|| path.endsWith("patches.jsonl")
 			|| (provenancePaths.has(path) && identity !== "missing"))
 			.map(({ path, content }) => ({ path, content: content! }));
-		updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
+		updates.push({ path: paths.config, content: sources.config }, { path: paths.runtime, content: sources.runtime });
 		const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head!, path).content === content)
 			? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
 		if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
@@ -450,7 +450,7 @@ function includeUncommittedCohort(cwd: string, sessionId: string, root: string,
 		return { scope, pair: desired([paths.checkpoint, paths.patches]) };
 	});
 	const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
-	const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.meta]) : [];
+	const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.runtime]) : [];
 	const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head,
 		[...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
 	const absentFromHead = (files: OwnedFileUpdate[]) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
@@ -483,7 +483,8 @@ export function publishTemporalStateToGit(
 		if (runtime?.meta.publication === "files") throw new Error("Git publication requires explicit Git provenance");
 		const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
 		const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content,
-			current.files.find(({ path }) => path === runtimePaths.meta)?.content, cwd, sessionId);
+			current.files.find(({ path }) => path === runtimePaths.runtime)?.content, cwd, sessionId,
+			current.files.find(({ path }) => path === runtimePaths.meta)?.content);
 		if (previousRuntime?.meta.publication === "files") throw new Error("File-only storage requires explicit full-cohort Git adoption");
 		const runtimeOnly = runtime?.meta.temporalRevision !== undefined && runtime.meta.temporalRevision !== "self";
 		if (runtimeOnly) {

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

@@ -22,7 +22,7 @@ export interface RecentTransition extends AcceptedTransition {
 
 export type RecentTransitionWindow = RecentTransition[];
 const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response", "lazy"]);
 
 /** Normalize accepted replacements into recursive-merge replay, including removals. */
 function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
@@ -49,9 +49,13 @@ function validateScopedPatch(value: unknown): asserts value is RecentScopePatch
 	}
 	validatePatch(value.patch);
 	for (const [key, field] of Object.entries(value.patch)) {
-		if (!PATCH_KEYS.has(key) || (key === "response"
-			? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
-			throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
+		const valid = key === "response"
+			? value.scope === "session" && typeof field === "string"
+			: key === "lazy"
+				? field !== null
+				: PATCH_KEYS.has(key) && isObject(field);
+		if (!PATCH_KEYS.has(key) || !valid) {
+			throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
 		}
 	}
 }

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

@@ -3,6 +3,32 @@ import { createHash } from "node:crypto";
 export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
 export interface JsonObject { [key: string]: JsonValue }
 
+const ARRAY_INDEX_SELECTOR = /^\[(0|[1-9]\d*)\]$/;
+
+function isIndexedArrayPatch(value: JsonObject): boolean {
+	const keys = Object.keys(value);
+	return keys.length > 0 && keys.every((key) => ARRAY_INDEX_SELECTOR.test(key));
+}
+
+function applyArrayPatch(state: JsonValue[], patch: JsonObject): JsonValue[] {
+	const next = structuredClone(state);
+	for (const [selector, value] of Object.entries(patch)) {
+		const match = ARRAY_INDEX_SELECTOR.exec(selector)!;
+		const index = Number(match[1]);
+		if (!Number.isSafeInteger(index) || index >= next.length) {
+			throw new Error(`State patch array index ${selector} is out of bounds for length ${next.length}`);
+		}
+		if (value === null) throw new Error(`State patch array index ${selector} cannot be deleted; replace the whole array instead`);
+		const current = next[index]!;
+		next[index] = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
+			? applyArrayPatch(current, value)
+			: isObject(current) && isObject(value)
+				? applyPatch(current, value)
+				: structuredClone(value);
+	}
+	return next;
+}
+
 export function applyPatch(state: JsonObject, patch: JsonObject): JsonObject {
 	const next: JsonObject = structuredClone(state);
 	for (const [key, value] of Object.entries(patch)) {
@@ -11,9 +37,11 @@ export function applyPatch(state: JsonObject, patch: JsonObject): JsonObject {
 			continue;
 		}
 		const current = next[key];
-		const materialized = isObject(current) && isObject(value)
-			? applyPatch(current, value)
-			: structuredClone(value);
+		const materialized = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
+			? applyArrayPatch(current, value)
+			: isObject(current) && isObject(value)
+				? applyPatch(current, value)
+				: structuredClone(value);
 		Object.defineProperty(next, key, {
 			value: materialized,
 			enumerable: true,