@llblab/pi-kit 0.20.0 → 0.21.0

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

@@ -25,7 +25,7 @@ import {
   type SessionAddress,
 } from "./durable.ts";
 import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
-import { backupCurrentStateFlowFiles } from "./git.ts";
+import { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./git.ts";
 import { projectRecentTransitionsWithLimit } from "./history.ts";
 import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
 import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
@@ -40,6 +40,7 @@ import { emptySnapshot, migrationFailure, type Snapshot } from "./snapshot.ts";
 import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type ScopedStates, type StateScope } from "./state.ts";
 import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
 import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
+import { temporalScopeRevisions, type ScopeRevisions } from "./temporal.ts";
 import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, type StagedScopedTransition } from "./transition.ts";
 
 export interface StateFlowExtensionOptions {
@@ -85,7 +86,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let activeContext: ExtensionContext | undefined;
 	let rehydrationPhase: RehydrationPhase | undefined;
 	const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
-	const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => activeContext?.ui.notify(message, "warning"));
+	const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
 	let backupPending = false;
 	const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
 		? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
@@ -100,6 +101,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
 	}
 
+	function notifyActiveContext(message: string): void {
+		try {
+			activeContext?.ui.notify(message, "warning");
+		} catch {
+			// An asynchronous push attempt can outlive the Pi context that launched it.
+		}
+	}
+
 	function createRuntime(ctx: ExtensionContext): TemporalRuntime {
 		return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
 	}
@@ -134,8 +143,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
 	}
 
+	function scopeRevisions(): ScopeRevisions {
+		return runtime?.view
+			? temporalScopeRevisions(runtime.view)
+			: { global: 0, cwd: 0, session: 0 };
+	}
+
 	function updateUi(ctx: ExtensionContext): void {
-		ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
+		ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
 	}
 
 	function clearRunTransient(): void {
@@ -202,6 +217,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (Object.keys(removals).length > 0) {
 			const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
 			commitStage(stage, ctx, false);
+			updateUi(ctx);
 		}
 		refreshArtifactHints();
 	}
@@ -217,10 +233,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function refreshTelegramStateView(scope: StateFlowTelegramScope): void {
 		if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
-		if (runtime?.view) return;
-		if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
-		runtime ??= createRuntime(activeContext);
-		runtime.loadPassive();
+		if (!runtime?.view) {
+			if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
+			runtime ??= createRuntime(activeContext);
+			runtime.loadPassive();
+		} else if (scope !== "session") {
+			runtime.refreshShared();
+		}
 		installScopeStates();
 	}
 
@@ -319,6 +338,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				head: structuredClone(view.lineage.at(-1)!),
 				historyDepth: view.lineage.length - 1,
 				tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
+				revisions: temporalScopeRevisions(view),
 			} }),
 			staleArtifacts,
 			...(durableStateError === undefined ? {} : { durableStateError }),
@@ -699,6 +719,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			snapshot: () => ({
 				enabled: snapshot.config.enabled,
 				step: snapshot.meta.step,
+				revisions: scopeRevisions(),
 				bootstrap: snapshot.meta.bootstrap === true,
 				startPending: telegramStartPending,
 			}),
@@ -709,6 +730,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					: scopeStates[scope];
 				return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
 			},
+			revisions: () => scopeRevisions(),
 			canStartNow: () => activeContext === undefined || activeContext.isIdle(),
 			start: () => {
 				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -909,7 +931,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (!backupPending) return;
 		backupPending = false;
 		try {
-			if (existsSync(join(repositoryRoot, ".git"))) backupCurrentStateFlowFiles(repositoryRoot);
+			if (existsSync(join(repositoryRoot, ".git"))) {
+				backupCurrentStateFlowFiles(repositoryRoot);
+				const pushSessionId = sessionAddress(ctx).id;
+				const pushCwd = ctx.cwd;
+				void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
+					const message = error instanceof Error ? error.message : String(error);
+					diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
+					notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
+				});
+			}
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			recordDiagnostic(message, "publication-conflict", ctx);
@@ -950,10 +981,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		runAnchorTimestamp = undefined;
 		restoreActiveBranch(ctx);
 	});
-	pi.on("session_shutdown", (_event, ctx) => {
+	pi.on("session_shutdown", (_event, _ctx) => {
 		telegramStartPending = false;
 		compactionStopped = true;
 		completedRunAccepted = false;
+		activeContext = undefined;
 		telegram.dispose();
 	});
 }

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

@@ -2,13 +2,19 @@
 import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.ts";
 import { acquirePublicationLock, withStoragePublicationLock } from "./storage.ts";
 
 const GIT_TIMEOUT_MS = 15_000;
 const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
 
+function redactGitDiagnostic(value: string): string {
+	return value
+		.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
+		.replace(/([?&](?:access_token|auth|password|token)=)[^&\s]+/gi, "$1***");
+}
+
 interface GitResult {
 	status: number;
 	stdout: string;
@@ -134,6 +140,22 @@ function currentBranchRef(repositoryRoot: string): string {
 	return result.stdout.trim();
 }
 
+function configuredPushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
+	const branchRef = currentBranchRef(repositoryRoot);
+	const branch = branchRef.slice("refs/heads/".length);
+	const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
+	if (configuredRemote.status > 1) throw new Error(configuredRemote.stderr || "Cannot inspect State Flow backup remote configuration");
+	if (configuredRemote.status !== 0 || configuredRemote.stdout.trim().length === 0) return undefined;
+	const remote = configuredRemote.stdout.trim();
+	if (remote === ".") throw new Error("State Flow backup replication requires a non-local Git remote");
+	const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
+	if (configuredMerge.status > 1) throw new Error(configuredMerge.stderr || "Cannot inspect State Flow backup branch configuration");
+	const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
+		? configuredMerge.stdout.trim()
+		: branchRef;
+	return { remote, ref };
+}
+
 function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string | undefined): string | undefined {
 	const branchRef = currentBranchRef(repositoryRoot);
 	if (currentHead(repositoryRoot) !== expectedHead) throw new Error("State Flow backup Git base changed concurrently");
@@ -183,3 +205,63 @@ function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string |
 export function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined {
 	return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
 }
+
+/** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
+export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
+	return new Promise((resolvePush, rejectPush) => {
+		let root: string;
+		let commit: string | undefined;
+		let destination: { remote: string; ref: string } | undefined;
+		try {
+			root = assertRepositoryRoot(repositoryRoot);
+			commit = currentHead(root);
+			destination = configuredPushDestination(root);
+		} catch (error) {
+			rejectPush(error);
+			return;
+		}
+		if (commit === undefined || destination === undefined) {
+			resolvePush(undefined);
+			return;
+		}
+		const child = spawn("git", ["-C", root, "push", "--porcelain", "--", destination.remote, `${commit}:${destination.ref}`], {
+			detached: process.platform !== "win32",
+			stdio: ["ignore", "ignore", "pipe"],
+			windowsHide: true,
+			env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
+		});
+		let stderr = "";
+		let failure: Error | undefined;
+		let settled = false;
+		function terminate(error: Error): void {
+			failure ??= error;
+			if (child.exitCode !== null || child.signalCode !== null) {
+				child.stderr?.destroy();
+				return;
+			}
+			if (!child.pid) return;
+			try {
+				if (process.platform === "win32") child.kill("SIGKILL");
+				else process.kill(-child.pid, "SIGKILL");
+			} catch {
+				// Keep waiting for close: signalling failure is not proof that the process ended.
+			}
+		}
+		const timeout = setTimeout(() => terminate(new Error(`Git backup push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
+		function finish(error?: Error): void {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (error) rejectPush(error);
+			else resolvePush({ commit: commit!, ...destination! });
+		}
+		child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
+		child.on("error", (error) => {
+			failure ??= error;
+			if (!child.pid) finish(error);
+		});
+		child.once("exit", () => { if (failure) child.stderr?.destroy(); });
+		child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
+			: new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
+	});
+}

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

@@ -56,7 +56,7 @@ READ: Use read_state for concrete scope/history gaps. lazy_navigation lists boun
 
 WRITE: patch_state is the sole model-authored semantic mutation mechanism. Supply global/cwd/session patches in any combination; all supplied scopes are validated and durably accepted as one atomic transition. Call it alone in an assistant response, then continue only after its acknowledgement.
 
-RESPONSE: Ordinary assistant completion needs no finalization patch. Runtime reconciles the accepted non-empty answer into response at turn_end without another inference.
+RESPONSE: Ordinary assistant completion needs no finalization patch. At turn_end, runtime stores the exact accepted answer; empty becomes response "".
 
 INTENTS: Keep chosen actions; detail may stay lazy. State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
 
@@ -88,10 +88,8 @@ export function finalizedAssistantResponse(message: AgentMessage): string {
 	if (message.content.some((block) => block.type === "toolCall")) {
 		throw new Error("Accepted State Flow response cannot contain a tool call");
 	}
-	const response = message.content
+	return message.content
 		.filter((block) => block.type === "text")
 		.map((block) => block.text)
 		.join("");
-	if (response.trim().length === 0) throw new Error("Finalized State Flow response must contain non-empty text");
-	return response;
 }

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

@@ -415,6 +415,17 @@ export class TemporalRuntime {
 		return { view: reconciledView(), base: captured, provenance };
 	}
 
+	/** Refresh live shared scopes in memory without publishing or advancing private semantic history. */
+	refreshShared(): boolean {
+		if (!this.view || !this.base) throw new Error("State Flow shared refresh requires a selected temporal runtime");
+		const before = this.view;
+		const reconciled = this.reconcileSharedDrift(new Set());
+		this.view = reconciled.view;
+		this.base = reconciled.base;
+		this.provenanceByScope = reconciled.provenance;
+		return before !== this.view;
+	}
+
 	/** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
 	acceptRestoredOrigin(snapshot: Snapshot): RuntimePublication {
 		if (!this.restoredOriginPending) throw new Error("State Flow has no prepared restored origin to accept");

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

@@ -3,7 +3,7 @@ import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "
 import { retainedMemoryScopes } from "./memory.ts";
 import type { Snapshot } from "./snapshot.ts";
 import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
-import type { TransitionBoundary } from "./temporal.ts";
+import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 
 export const STATUS_KEY = "state-flow";
 
@@ -24,13 +24,18 @@ export interface StatusDiagnostics {
 	scopeStates: ScopedStates;
 	recent: RecentTransitionWindow;
 	historyLimit: number;
-	temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number> };
+	temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number>; revisions: ScopeRevisions };
 	staleArtifacts: readonly StaleArtifactDiagnostic[];
 	durableStateError?: string;
 }
 
-export function compactStatus(snapshot: Snapshot, colorize: Colorize): string {
-	return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.meta.step}`)}`;
+export function formatScopeRevisionVector(revisions: ScopeRevisions): string {
+	return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
+}
+
+export function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined {
+	if (!snapshot.config.enabled) return undefined;
+	return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
 }
 
 function countArtifacts(states: ScopedStates, scope: StateScope): number {
@@ -62,6 +67,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
 			`Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
 			"Retained patch tails: unavailable"]
 		: [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
+			`Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
 			`Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
 			`Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
 	const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";

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

@@ -3,6 +3,9 @@
 // This is a leaf adapter. Core semantics, storage, and inference never depend on it; when
 // pi-telegram is absent or its registry is not ready, registration fails open and retries.
 
+import { formatScopeRevisionVector } from "./status.ts";
+import type { ScopeRevisions } from "./temporal.ts";
+
 export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
@@ -15,7 +18,9 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url):
 
 export interface StateFlowTelegramSnapshot {
 	enabled: boolean;
+	/** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
 	step: number;
+	revisions?: ScopeRevisions;
 	bootstrap: boolean;
 	startPending: boolean;
 }
@@ -93,6 +98,8 @@ export interface StateFlowTelegramControlResult {
 export interface StateFlowTelegramPort {
 	snapshot(): StateFlowTelegramSnapshot;
 	state(scope: StateFlowTelegramScope): StateFlowTelegramState;
+	/** Optional additive capability; absent legacy ports retain their branch-step presentation. */
+	revisions?(): ScopeRevisions;
 	canStartNow(): boolean;
 	start(): StateFlowTelegramControlResult;
 	stop(): StateFlowTelegramControlResult;
@@ -107,12 +114,14 @@ export interface StateFlowTelegramAdapter {
 
 /** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
 export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
-	return `🌀 State Flow: ${stateFlowLabelValue(snapshot)}`;
+	if (!snapshot.enabled) return "🌀 State Flow: off";
+	return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
 }
 
 /** Shared live value: plain in the button label, monospaced in the submenu state line. */
 function stateFlowLabelValue(snapshot: StateFlowTelegramSnapshot): string {
-	return `#${snapshot.step}`;
+	if (!snapshot.enabled) return "off";
+	return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
 }
 
 /** Submenu state line: the same identity as the button label, with the live value in monospace. */
@@ -191,13 +200,18 @@ function renderStateFlowTelegramField(value: unknown): string {
 	return rendered;
 }
 
-export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
-	const fields = ["intents", "contract", "working", "artifacts", "response", "lazy"] as const;
+export function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
+	const fields: Array<keyof StateFlowTelegramState> = scope === "global" || scope === "cwd"
+		? ["intents", "contract", "working", "artifacts", "lazy"]
+		: ["intents", "contract", "working", "artifacts", "response", "lazy"];
+	const revision = scope === "effective"
+		? formatScopeRevisionVector(revisions)
+		: `#${revisions[scope]}`;
 	return {
 		blocks: [
 			{
 				type: "heading",
-				text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
+				text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
 				size: 3,
 			},
 			...fields.map((field) => ({
@@ -233,7 +247,10 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 				}
 				if (ctx.action === "inspect") {
 					if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
-					await ctx.openRich(renderStateFlowRichState(ctx.payload, port.snapshot().step, port.state(ctx.payload)));
+					const state = port.state(ctx.payload);
+					const live = port.snapshot();
+					const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
+					await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
 					await ctx.answerCallback();
 					return "handled" as const;
 				}

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

@@ -21,6 +21,8 @@ export interface TemporalPatch {
 }
 
 export interface ScopeStream {
+	/** Monotonic semantic revision owned by this scope; independent of branch-local boundary positions. */
+	revision: number;
 	checkpoint: ScopeCheckpoint;
 	patches: TemporalPatch[];
 }
@@ -32,6 +34,7 @@ export interface TemporalState {
 }
 
 const SCOPES: StateScope[] = ["global", "cwd", "session"];
+export type ScopeRevisions = Record<StateScope, number>;
 
 function validateHistoryLimit(limit: number): void {
 	if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_HISTORY_LIMIT) {
@@ -69,7 +72,8 @@ function sameBoundary(left: TransitionBoundary, right: TransitionBoundary): bool
 export function validateScopeStream(value: unknown, scope: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): asserts value is ScopeStream {
 	validateHistoryLimit(historyLimit);
 	if (!SCOPES.includes(scope)) throw new Error("Unknown temporal scope");
-	if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches"
+	if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches,revision"
+		|| !Number.isSafeInteger(value.revision) || (value.revision as number) < 0
 		|| !isObject(value.checkpoint) || Object.keys(value.checkpoint).sort().join(",") !== "state,through"
 		|| !Array.isArray(value.patches)) {
 		throw new Error("Invalid temporal checkpoint/tail envelope");
@@ -78,6 +82,7 @@ export function validateScopeStream(value: unknown, scope: StateScope, historyLi
 	validateBoundary(stream.checkpoint.through);
 	validateState(stream.checkpoint.state);
 	if (stream.patches.length > historyLimit) throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
+	if (stream.revision < stream.patches.length) throw new Error("Temporal scope revision predates its retained patch tail");
 	let previous = stream.checkpoint.through;
 	let state = stream.checkpoint.state;
 	const identities = new Set([previous.id]);
@@ -191,6 +196,7 @@ export function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id
 export function createTemporalState(states: ScopedStates, id: string, historyLimit = DEFAULT_HISTORY_LIMIT): TemporalState {
 	const through: TransitionBoundary = { id, position: 0, parent: null };
 	const stream = (scope: StateScope): ScopeStream => ({
+		revision: 0,
 		checkpoint: { through: structuredClone(through), state: structuredClone(states[scope]) },
 		patches: [],
 	});
@@ -234,7 +240,9 @@ export function selectScopeStreamAtBoundary(stream: ScopeStream, scope: StateSco
 		throw new Error("Selected State Flow history boundary predates the retained scope checkpoint");
 	}
 	const selected = structuredClone(stream);
-	selected.patches = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
+	const retained = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
+	selected.revision -= selected.patches.length - retained.length;
+	selected.patches = retained;
 	validateScopeStream(selected, scope, historyLimit);
 	return selected;
 }
@@ -250,12 +258,28 @@ export function selectTemporalStateBoundary(view: TemporalState, boundaryId: str
 	const selected = structuredClone(view);
 	selected.lineage = selected.lineage.slice(0, index + 1);
 	for (const scope of SCOPES) {
-		selected.scopes[scope].patches = selected.scopes[scope].patches.filter(({ transition }) => transition.position <= target.position);
+		const stream = selected.scopes[scope];
+		const retained = stream.patches.filter(({ transition }) => transition.position <= target.position);
+		stream.revision -= stream.patches.length - retained.length;
+		stream.patches = retained;
 	}
 	validateTemporalState(selected, historyLimit);
 	return selected;
 }
 
+/** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
+export function temporalScopeRevisions(view: TemporalState): ScopeRevisions {
+	const revisions = {
+		global: view.scopes.global.revision,
+		cwd: view.scopes.cwd.revision,
+		session: view.scopes.session.revision,
+	};
+	if (Object.values(revisions).some((revision) => !Number.isSafeInteger(revision) || revision < 0)) {
+		throw new Error("Invalid State Flow scope revision vector");
+	}
+	return revisions;
+}
+
 /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
 export function readTemporalState(view: TemporalState, offset = 0, scope?: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): MaterializedState {
 	validateHistoryLimit(historyLimit);
@@ -298,6 +322,8 @@ export function advanceTemporalState(
 	const next = structuredClone(view);
 	for (const { scope, patch } of changes) {
 		const stream = next.scopes[scope];
+		if (stream.revision >= Number.MAX_SAFE_INTEGER) throw new Error(`State Flow ${scope} scope revision is exhausted`);
+		stream.revision += 1;
 		if (historyLimit === 0) {
 			stream.checkpoint = { through: structuredClone(boundary), state: apply(scopeAt(stream, head), patch) };
 			stream.patches = [];

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

@@ -257,8 +257,8 @@ export function stageScopedTransition(
 	causalBasis: string,
 	successfulArtifactReads: Iterable<SuccessfulArtifactRead> = [],
 ): StagedScopedTransition {
-	if (typeof transition.response !== "string" || transition.response.trim().length === 0) {
-		throw new Error("Accepted State Flow response body must be non-empty");
+	if (typeof transition.response !== "string") {
+		throw new Error("Accepted State Flow response body must be a string");
 	}
 	return stageScopedSemanticTransition(
 		currentStates,

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.17.4",
+    "@llblab/pi-state-flow": "0.18.0",
     "@llblab/pi-telegram": "0.51.0",
     "@llblab/skills": "1.15.0"
   },