@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -11,6 +11,8 @@ export interface StateFlowConfig {
 	autoStart: boolean;
 	/** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
 	logging: boolean;
+	/** Show successful patch_state arguments in the interactive tool row. */
+	showSuccessfulPatches: boolean;
 	remotePublication?: "off" | "turn-end" | "transition";
 }
 
@@ -21,6 +23,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 		directory: getDurableRepositoryRoot(agentDir),
 		autoStart: false,
 		logging: false,
+		showSuccessfulPatches: true,
 	};
 	let value: unknown;
 	try {
@@ -29,12 +32,13 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 	} catch (error) {
 		throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
 	}
-	const allowed = new Set(["directory", "autoStart", "logging", "remotePublication"]);
+	const allowed = new Set(["directory", "autoStart", "logging", "showSuccessfulPatches", "remotePublication"]);
 	if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
 		throw new Error(`State Flow configuration contains unknown settings: ${path}`);
 	}
 	if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean") throw new Error(`State Flow autoStart must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "logging") && typeof value.logging !== "boolean") throw new Error(`State Flow logging must be a boolean: ${path}`);
+	if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean") throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
 		throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${path}`);
 	}
@@ -48,6 +52,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 		directory: expanded === undefined ? defaults.directory : resolve(dirname(path), expanded),
 		autoStart: value.autoStart === true,
 		logging: value.logging === true,
+		showSuccessfulPatches: value.showSuccessfulPatches !== false,
 		...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication as "off" | "turn-end" | "transition" }),
 	};
 }

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

@@ -18,22 +18,26 @@ import {
 	serializeArtifactProvenanceRegistry,
 	type ArtifactProvenanceRegistry,
 } from "./artifact.ts";
-import { canonicalJson, containsNull, isJsonValue, isObject } from "./json.ts";
+import { canonicalJson, isJsonValue, isObject } from "./json.ts";
 import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
-import { isMaterializedState, type MaterializedState, type StateScope } from "./state.ts";
+import type { StateScope } from "./state.ts";
 
-const LEGACY_MAX_SCOPE_SLUG_LENGTH = 80;
-const LEGACY_SCOPE_KEY_PATTERN = /^[A-Za-z0-9._-]{1,80}-[a-f0-9]{64}$/;
 const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
 const CHECKPOINT_FILE = "checkpoint.json";
 const PATCHES_FILE = "patches.jsonl";
 const META_FILE = "meta.json";
 
-/** Canonical replay sources; current state is deliberately not serialized beside the tail. */
+/** Canonical semantic sources plus runtime-owned temporal metadata. */
 export interface ScopeStreamSources {
 	checkpoint: string;
 	patches: string;
+	temporal: ScopeTemporalMetadata;
+}
+
+export interface ScopeTemporalMetadata {
+	checkpoint: ScopeStream["checkpoint"]["through"];
+	patches: ScopeStream["patches"][number]["transition"][];
 }
 
 export interface SessionAddress {
@@ -41,17 +45,18 @@ export interface SessionAddress {
 	readonly key: string;
 }
 
-/** CWD storage requires its canonical owner; legacy ownerless sources are read-only. */
+/** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
 export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwdIdentity?: string): ScopeStreamSources {
 	validateScopeStream(stream, scope);
 	if (scope === "cwd" && cwdIdentity === undefined) throw new Error("State Flow CWD scope serialization requires its canonical identity");
 	if (scope !== "cwd" && cwdIdentity !== undefined) throw new Error("Only State Flow CWD scope serialization accepts a CWD identity");
-	const checkpoint = scope === "cwd"
-		? { ...stream.checkpoint, owner: { cwd: resolve(cwdIdentity!) } }
-		: stream.checkpoint;
 	return {
-		checkpoint: `${canonicalJson(checkpoint)}\n`,
-		patches: stream.patches.map((record) => `${canonicalJson(record)}\n`).join(""),
+		checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
+		patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
+		temporal: {
+			checkpoint: structuredClone(stream.checkpoint.through),
+			patches: stream.patches.map((record) => structuredClone(record.transition)),
+		},
 	};
 }
 
@@ -65,6 +70,7 @@ export function classifyScopeStream(
 	patchesSource: string | undefined,
 	scope: StateScope,
 	expectedCwd?: string,
+	metaSource?: string,
 ): ScopeStreamPresence {
 	if (checkpointSource === undefined && patchesSource === undefined) return { kind: "absent" };
 	if (checkpointSource === undefined || patchesSource === undefined) {
@@ -76,16 +82,11 @@ export function classifyScopeStream(
 	} catch {
 		throw new Error(`State Flow ${scope} checkpoint contains invalid JSON`);
 	}
-	if (checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint) && Object.hasOwn(checkpoint, "owner")) {
-		const { owner, ...semantic } = checkpoint as Record<string, unknown>;
-		if (scope !== "cwd" || owner === null || typeof owner !== "object" || Array.isArray(owner)
-			|| Object.keys(owner).join(",") !== "cwd" || typeof (owner as { cwd?: unknown }).cwd !== "string") {
-			throw new Error("Invalid State Flow CWD scope identity");
-		}
-		if (expectedCwd !== undefined && (owner as { cwd: string }).cwd !== resolve(expectedCwd)) throw new Error("State Flow CWD scope identity mismatch");
-		checkpoint = semantic;
-	} else if (scope === "cwd" && expectedCwd !== undefined) {
-		throw new Error("State Flow CWD scope identity is missing");
+	let meta: Record<string, unknown> | undefined;
+	if (metaSource !== undefined) {
+		try { meta = JSON.parse(metaSource) as Record<string, unknown>; }
+		catch { throw new Error(`State Flow ${scope} metadata contains invalid JSON`); }
+		if (!isObject(meta)) throw new Error(`Invalid State Flow ${scope} metadata`);
 	}
 	const patches: unknown[] = [];
 	for (const [index, line] of patchesSource.split(/\r?\n/).entries()) {
@@ -96,7 +97,35 @@ export function classifyScopeStream(
 			throw new Error(`State Flow ${scope} tail contains invalid JSON at line ${index + 1}`);
 		}
 	}
-	const stream = { checkpoint, patches };
+	const temporal = meta?.temporal;
+	if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
+		const owner = meta?.owner;
+		if (scope === "cwd" && expectedCwd !== undefined
+			&& (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
+			throw new Error(owner === undefined ? "State Flow CWD scope identity is missing" : "State Flow CWD scope identity mismatch");
+		}
+		const boundaries = temporal.patches;
+		if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
+		const stream = {
+			checkpoint: { through: temporal.checkpoint, state: checkpoint },
+			patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+		};
+		validateScopeStream(stream, scope);
+		return { kind: "present", stream };
+	}
+	// Complete predecessor envelopes are the only no-meta form that may be unwrapped.
+	let legacyCheckpoint = checkpoint;
+	if (isObject(checkpoint) && Object.hasOwn(checkpoint, "owner")) {
+		const { owner, ...semantic } = checkpoint;
+		if (scope !== "cwd" || !isObject(owner) || Object.keys(owner).join(",") !== "cwd" || typeof owner.cwd !== "string") {
+			throw new Error("Invalid State Flow CWD scope identity");
+		}
+		if (expectedCwd !== undefined && owner.cwd !== resolve(expectedCwd)) throw new Error("State Flow CWD scope identity mismatch");
+		legacyCheckpoint = semantic;
+	} else if (scope === "cwd" && expectedCwd !== undefined) {
+		throw new Error("State Flow CWD scope identity is missing");
+	}
+	const stream = { checkpoint: legacyCheckpoint, patches };
 	validateScopeStream(stream, scope);
 	return { kind: "present", stream };
 }
@@ -107,8 +136,9 @@ export function parseScopeStream(
 	patchesSource: string | undefined,
 	scope: StateScope,
 	expectedCwd?: string,
+	metaSource?: string,
 ): ScopeStream | undefined {
-	const presence = classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd);
+	const presence = classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd, metaSource);
 	return presence.kind === "present" ? presence.stream : undefined;
 }
 
@@ -134,13 +164,13 @@ export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRo
 	return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
 }
 
-/** A temporal reader never treats a legacy current snapshot as an anchored checkpoint. */
+/** Unsupported state.json presence never becomes an anchored checkpoint. */
 export function loadScopeStream(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey = sessionId): ScopeStream | undefined {
 	const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 	if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
 		throw new Error(`Legacy State Flow storage requires explicit migration: ${paths.directory}`);
 	}
-	return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined);
+	return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
 }
 
 /** Include legacy names in the CAS basis solely to prevent format races during cutover. */
@@ -182,24 +212,43 @@ export interface DurablePaths {
 	globalPatches: string;
 }
 
-/** One scope-level provenance document; versioned for lenient forward evolution. */
+/** Merge authoritative owned leaves while preserving forward-compatible metadata siblings. */
+export function serializeScopeMetadata(
+	registry: Readonly<ArtifactProvenanceRegistry> | undefined, stream: ScopeStream, scope: StateScope,
+	cwdIdentity?: string, existingSource?: string,
+): string {
+	const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
+	const sources = serializeScopeStream(stream, scope, cwdIdentity);
+	const value = {
+		...existing,
+		version: 1,
+		...(registry === undefined ? {} : { artifacts: serializeArtifactProvenanceRegistry(registry) }),
+		temporal: sources.temporal,
+		...(scope === "cwd" ? { owner: { cwd: resolve(cwdIdentity!) } } : {}),
+	};
+	return `${canonicalJson(value)}\n`;
+}
+
+/** Compatibility serializer retained for metadata-only callers. */
 export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
 	return `${canonicalJson({ version: 1, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
 }
 
-/** Missing provenance is unavailable evidence, never corrupt state. */
-export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
+function parseMetadataDocument(source: string | undefined, label: string): Record<string, unknown> {
 	if (source === undefined) return {};
 	let value: unknown;
-	try {
-		value = JSON.parse(source);
-	} catch {
-		throw new Error(`State Flow provenance file contains invalid JSON: ${path}`);
-	}
-	if (!isObject(value) || value.version !== 1 || !Object.hasOwn(value, "artifacts")
-		|| Object.keys(value).some((key) => key !== "version" && key !== "artifacts")) {
-		throw new Error(`Invalid State Flow provenance document: ${path}`);
-	}
+	try { value = JSON.parse(source); }
+	catch { throw new Error(`${label} contains invalid JSON`); }
+	if (!isObject(value) || !isJsonValue(value)) throw new Error(`Invalid ${label}`);
+	return value;
+}
+
+/** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
+export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
+	const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
+	if (Object.keys(value).length === 0) return {};
+	if (value.version !== 1) throw new Error(`Invalid State Flow provenance document: ${path}`);
+	if (!Object.hasOwn(value, "artifacts")) return {};
 	return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
 }
 
@@ -232,12 +281,6 @@ export function durablePaths(repositoryRoot = getDurableRepositoryRoot()): Durab
 	};
 }
 
-function legacyReadableScopeKey(identity: string, readable: string): string {
-	if (identity.length === 0) throw new Error("State Flow scope identity must be non-empty");
-	const slug = readable.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, LEGACY_MAX_SCOPE_SLUG_LENGTH) || "scope";
-	return `${slug}-${createHash("sha256").update(identity).digest("hex")}`;
-}
-
 /** Match Pi's native project-session directory convention exactly. */
 export function cwdScopeKey(cwd: string): string {
 	const canonical = resolve(cwd);
@@ -266,16 +309,6 @@ export function resolveSessionAddress(sessionFile: string | undefined, sessionId
 	return Object.freeze({ id: sessionId, key: sessionStorageKey(sessionFile, sessionId, timestamp) });
 }
 
-/** Read-only migration input for the untagged hashed-layout draft. */
-export function legacyCwdScopeKey(cwd: string): string {
-	const canonical = resolve(cwd);
-	return legacyReadableScopeKey(canonical, `--${canonical.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`);
-}
-
-export function legacySessionScopeKey(sessionId: string): string {
-	return legacyReadableScopeKey(sessionScopeKey(sessionId), sessionId);
-}
-
 export function cwdScopePaths(cwd: string, repositoryRoot = getDurableRepositoryRoot()): ScopePaths {
 	const directory = join(resolve(repositoryRoot), cwdScopeKey(cwd));
 	return { directory, state: join(directory, STATE_FILE), patches: join(directory, PATCHES_FILE) };
@@ -299,28 +332,6 @@ export function cwdPatchesPath(cwd: string, repositoryRoot = getDurableRepositor
 	return cwdScopePaths(cwd, repositoryRoot).patches;
 }
 
-/** Historical paths from the pre-0.4 hashed-layout draft; never selected for new writes. */
-export function legacyTemporalScopePaths(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string): TemporalScopePaths {
-	const root = resolve(repositoryRoot);
-	const cwdDirectory = join(root, legacyCwdScopeKey(cwd));
-	const directory = scope === "global" ? root : scope === "cwd" ? cwdDirectory : join(cwdDirectory, legacySessionScopeKey(sessionId));
-	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
-}
-
-export function legacySessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string): { config: string; meta: string } {
-	const directory = legacyTemporalScopePaths(cwd, sessionId, "session", repositoryRoot).directory;
-	return { config: join(directory, "config.json"), meta: join(directory, "meta.json") };
-}
-
-export function captureLegacyTemporalFileBases(cwd: string, sessionId: string, repositoryRoot: string): DurableFileBase[] {
-	const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
-		const pair = legacyTemporalScopePaths(cwd, sessionId, scope, repositoryRoot);
-		const runtime = scope === "session" ? legacySessionRuntimePaths(cwd, sessionId, repositoryRoot) : undefined;
-		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [] : [runtime.config, runtime.meta])];
-	});
-	return captureOwnedFileBases(paths, repositoryRoot);
-}
-
 export function sessionStatePath(cwd: string, sessionId: string, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId): string {
 	return sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).state;
 }
@@ -337,7 +348,7 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
 	if (absolute === global.globalState || absolute === global.globalPatches
 		|| absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, META_FILE)) return true;
 	const segments = relative(root, absolute).split(sep);
-	const cwdKey = (value: string) => (value.startsWith("--") && value.endsWith("--")) || LEGACY_SCOPE_KEY_PATTERN.test(value);
+	const cwdKey = (value: string) => value.startsWith("--") && value.endsWith("--");
 	const sessionKey = (value: string) => {
 		try { return sessionScopeKey(value) === value; } catch { return false; }
 	};
@@ -346,7 +357,7 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
 	}
 	if (segments.length === 3) {
 		return cwdKey(segments[0]!)
-			&& (sessionKey(segments[1]!) || LEGACY_SCOPE_KEY_PATTERN.test(segments[1]!))
+			&& sessionKey(segments[1]!)
 			&& (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
 				|| segments[2] === "config.json" || segments[2] === META_FILE);
 	}
@@ -446,25 +457,6 @@ export function captureOwnedFileBases(paths: readonly string[], repositoryRoot:
 	});
 }
 
-function validateState(value: unknown, path: string): asserts value is MaterializedState {
-	if (!isMaterializedState(value) || !isJsonValue(value) || containsNull(value)) {
-		throw new Error(`Durable State Flow file has invalid materialized state: ${path}`);
-	}
-}
-
-/** One-way legacy current-state interpretation; explanatory journals are not recovery input. */
-export function parseStateSource(source: string | undefined, path: string): MaterializedState | undefined {
-	if (source === undefined) return undefined;
-	let value: unknown;
-	try {
-		value = JSON.parse(source);
-	} catch {
-		throw new Error(`Durable State Flow file contains invalid JSON: ${path}`);
-	}
-	validateState(value, path);
-	return structuredClone(value);
-}
-
 interface PreparedFile {
 	path: string;
 	repositoryRoot: string;

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

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { StringEnum, Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 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 { ArtifactReadTracker } from "./acquisition.ts";
@@ -26,6 +27,7 @@ import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePa
 import { runPublicationWorker } from "./publication.ts";
 import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
 import { isObject, sameJson } from "./json.ts";
+import { readStatePath } from "./query.ts";
 import {
 	cwdScopeKey,
 	resolveSessionAddress,
@@ -40,7 +42,7 @@ import {
 	planArtifactInvalidation,
 	type ArtifactInvalidationRequest,
 } from "./artifact.ts";
-import { planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
+import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
 
 export interface StateFlowExtensionOptions {
 	agentDir?: string;
@@ -55,6 +57,34 @@ export const READ_STATE_TOOL_NAME = "read_state";
 export const MAX_FALLBACK_ATTEMPTS: number = 2;
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 const PUBLICATION_SHUTDOWN_WAIT_MS = 2_000;
+const PATCH_DISPLAY_SECTION_KEYS = new Set([
+	"global",
+	"cwd",
+	"session",
+	"artifacts",
+	"contract",
+	"working",
+	"response",
+	"final",
+]);
+
+/** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
+export function formatPatchStateArguments(args: unknown): string {
+	const seenAtIndent = new Set<number>();
+	return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
+		const indent = line.length - line.trimStart().length;
+		const match = /^(\s+)"([^"]+)":/.exec(line);
+		if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
+			for (const seenIndent of seenAtIndent) {
+				if (seenIndent > indent) seenAtIndent.delete(seenIndent);
+			}
+			return [line];
+		}
+		const separator = seenAtIndent.has(indent) ? [""] : [];
+		seenAtIndent.add(indent);
+		return [...separator, line];
+	}).join("\n");
+}
 
 /** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
 export function normalizePatchStateArguments(args: unknown): any {
@@ -70,10 +100,15 @@ export function normalizePatchStateArguments(args: unknown): any {
 	return { ...args, final };
 }
 
+/** Keep tool output visually separated from its heading with exactly one leading newline. */
+function separatedOutput(text: string): string {
+	return `\n${text.replace(/^\n+/, "")}`;
+}
+
 /** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
 function separatedFailure(error: unknown): Error {
 	const message = error instanceof Error ? error.message : String(error);
-	return new Error(`\n${message}`, error instanceof Error ? { cause: error } : undefined);
+	return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
 }
 
 export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
@@ -560,9 +595,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			const branch = ctx.sessionManager.getBranch();
 			const discovery = discoverSnapshotData(branch);
 			let restoreSelected: (() => Snapshot) | undefined;
-			const recovery = recoverSnapshot(discovery.candidates, (revision, legacy) => {
+			const recovery = recoverSnapshot(discovery.candidates, (revision) => {
 				try {
-					const prepared = prepareBranchRestore(ctx, revision, legacy);
+					const prepared = prepareBranchRestore(ctx, revision);
 					restoreSelected = prepared.restore;
 					return prepared.snapshot;
 				} catch (error) {
@@ -586,7 +621,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				} else if (branchHasSnapshot && snapshot.config.enabled) {
 					const publication = runtime.initialize(snapshot, true);
 					recordPolicyPublication(publication, ctx);
-					delete snapshot.legacySession;
 				}
 				installScopeStates();
 			} else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
@@ -762,23 +796,33 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.registerTool({
 		name: READ_STATE_TOOL_NAME,
 		label: "Read State",
-		description: "Read one effective or scoped State Flow materialization at offset 0–7 in the active causal lineage. Read-only and lazy; unavailable pre-origin history is an error. Use only for a concrete historical or scope-specific gap, not routine rereading of current context.",
-		promptSnippet: "Read one cached effective/global/CWD/session state at temporal offset 0–7",
+		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",
 		parameters: Type.Object({
-			offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 7, description: "Accepted transitions before current state; defaults to 0" })),
-			scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"] as const, { description: "Projection at that same boundary; defaults to effective" })),
+			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" })),
 		}, { 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");
 				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);
+					return {
+						content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
+						details: { path: params.path, transitionId: result.boundary.id } 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 },
+					details: { offset, scope, transitionId: boundary.id } as ReadDetails,
 				};
 			} catch (error) {
 				throw separatedFailure(error);
@@ -804,6 +848,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			final: Type.Optional(Type.Boolean({ description: "Set exactly true to permit this iteration to finish at a later turn_end" })),
 		}, { additionalProperties: false }),
 		prepareArguments: normalizePatchStateArguments,
+		renderResult(result, { isPartial }, theme, context) {
+			const text = result.content.find((block) => block.type === "text")?.text ?? "";
+			if (context.isError) return new Text(separatedOutput(text), 0, 0);
+			if (isPartial || !config.showSuccessfulPatches) return new Text(text, 0, 0);
+			return new Text(separatedOutput(theme.fg("dim", formatPatchStateArguments(context.args))), 0, 0);
+		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			try {
 				if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
@@ -874,6 +924,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			activeContext = ctx;
 			runtime ??= createRuntime(ctx);
 			if (branchStartsWithoutRuntime) runtime.prepare();
+			runtime.migrateLegacyStorage();
 			const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
 				&& (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
 			if (!runtime.view && snapshot.meta.durableBase) {
@@ -896,7 +947,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				: runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
 			recordPolicyPublication(publication, ctx);
 			installScopeStates();
-			delete snapshot.legacySession;
 			clearRunTransient();
 			passiveContinuation = undefined;
 			bootstrapContinuation = snapshot.meta.bootstrap
@@ -1195,7 +1245,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
 			|| !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
 		completedRunAccepted = false;
-		const plan = planStateFlowCompaction(ctx.sessionManager.buildContextEntries(), snapshot.meta.durableBase, snapshot.meta.step);
+		const entries = ctx.sessionManager.buildContextEntries();
+		if (!hasCompactionSizedTranscript(entries)) return;
+		const plan = planStateFlowCompaction(entries, snapshot.meta.durableBase, snapshot.meta.step);
 		if (!plan) return;
 		compactionPlan = plan;
 		compactionInFlight = true;