@llblab/pi-kit 0.19.2 → 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/node_modules/@llblab/pi-telegram/AGENTS.md

@@ -72,22 +72,24 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Telegram transport ownership is not semantic queue ownership. Losing the exact transport lock must not erase accepted local queue work or stop valid local Pi dispatch; direct Bot API mutations fail closed until exact direct or follower authority exists.
 - `tmp/telegram/owners.json` is the sole transport-owner authority. Cross-process read/check/write operations serialize transactionally and acquisition, refresh, release, takeover, and irreversible leader work fence the exact owner/epoch. `state.json` and `logs.jsonl` are diagnostics, never routing authority.
 - Threaded Mode has exactly one live leader per bot profile. Followers are real operator-started Pi processes and must authenticate/register over local IPC; Telegram never spawns hidden Pi processes. A live but unreachable owner does not authorize split-brain polling.
-- Local IPC is a trust boundary, not merely a private socket. Unknown, stale, mismatched-generation, or unauthorized requests must not inject prompts, callbacks, API sends, artifacts, liveness, or bindings.
+- Local IPC is a trust boundary, not merely a private socket. Unknown, stale, mismatched-generation, or unauthorized requests must not inject prompts, callbacks, API sends, artifacts, liveness, or bindings. Follower registration identity may prepare a binding, but inbound generation authority is published only after successful preparation for the same generation and current context; pending or failed startup cannot append into a retained old journal. Readiness also binds the active Pi context and supplied session generation. Session refresh awaits binding preparation without re-registering; reusing a context object cannot carry readiness across a session-generation change. Registration requests capture session authority before asynchronous startup and fence every publication/finalization against the current attempt. Stop or supersession invalidates that attempt; obsolete cleanup cannot erase a newer registration or a refreshed context.
 - Protocol compatibility is independent from package version. Registration negotiates protocol version, runtime build, and canonical capabilities before target provisioning or live publication. `durable-follower-admission-v1` gates source forwarding; `queue-handoff-v1` independently gates semantic queue transfer for every participant and is advertised only with exact source/recipient journal-binding composition. `follower.register` and capability-gated restore-only `follower.restoreWorkspace` are bootstrap requests; other requests require exact live-registry generation authority, and `bus.ack` is response-only. `thread-display-mode-v1` gates follower display-setting requests; the leader owns their serialized profile preference and title application.
-- Long-lived timers, pollers, watchers, receivers, heartbeats, background delivery, and deferred dispatch are session-bound. Replacement stops stale activity and makes late work inert; same-process handoff may preserve exact profile/target identity but never stale Pi context or cross-profile authority. Aborting a durable update generation does not release that `update_id`: replacement replay waits for its actual handler settlement, and effectful handlers use the shared execution fence immediately before commit and after awaited delegation. Internal clones explicitly carry the hidden fence; reroute forwarding, thread-store mutation, cleanup, and Bot API boundaries retain the originating generation.
+- Long-lived timers, pollers, watchers, receivers, heartbeats, background delivery, and deferred dispatch are session-bound. Replacement stops stale activity and makes late work inert; teardown must recheck the captured session generation even when context identity is reused. Same-process handoff may preserve exact profile/target identity but never stale Pi context or cross-profile authority. Participating source observations must hold a reference for the actual read, including pending-mutation/count queries against a stopped worker's retained source; a scoped observation never restores receipt readiness or execution authority. A donor cancellation resumed after remote handoff awaits must also hold a source reference; only the existing exact journal CAS may cancel, never undo accepted recipient custody. Stable source keys do not certify captured callable lifetimes: snapshot prepared worker capabilities at construction and replace them on source-handle renewal without replaying unsettled input. Aborting a durable update generation does not release that `update_id`: replacement replay waits for its actual handler settlement, and effectful handlers use the shared execution fence immediately before commit and after awaited delegation. Admission also rechecks that fence after the default handler returns, before its outcome can settle custody; a stopped handler's ordinary return is not completion authority. Internal clones explicitly carry the hidden fence; reroute forwarding, thread-store mutation, cleanup, and Bot API boundaries retain the originating generation.
 - Runtime state is event-driven reconciliation of local assumptions against Telegram signals, not a complete bot read-model and not permission to query Telegram on every action. Destructive thread cleanup goes through `thread-reconciler` with current proof and leader fencing. Fresh Workspace Thread creation derives its initial Bot API title from the active display mode before issuance; the stable generated `threadName` remains separate from the acknowledged `displayTitle`.
 
 ### 4.3 Durable Admission And Settlement
 
 - Admission is journal-first: validate and persist the complete `getUpdates` response before one monotonic offset commit, then signal an independent worker without awaiting semantic execution. Missing cursor with a non-empty journal, malformed/foreign authority, or capacity exhaustion fails closed. “Durable” means process-crash recovery after atomic rename, not unflushed host/kernel/filesystem/device/power-loss survival.
+- Storage cutovers must reconcile actual consumer locations before correcting path adapters. Never normalize a relative historical reference into new authority or treat equal reference strings / empty canonical storage as source completeness. Exact-path preflight is lexical only; physical identity, historical coverage, writer closure and migration remain separate proofs.
 - Workspace mutations acquire cross-process admission before their shared process-local gate and hold it through asynchronous API work and durable settlement. Topic lifecycle, complete unbound/reroute target handling, manual disconnect, and session-restart cleanup use profile-wide scope; either retained retirement-fence phase rejects them before state access. Cleanup scope spans intent publication, target mutation, persistence, and transport release. Detached reconciliation that mutates Thread state must reacquire fresh profile admission through the same gate; it cannot inherit a caller lease that ended before its timer runs. A live operation ID has one process-local caller: concurrent reuse is rejected before lease acquisition, while retry after the caller exits may resume exact durable authority.
-- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Automatic retirement remains disconnected until separately authorized and operator-validated.
+- Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
 - Foreign forwarding settles as `accepted`, `retryable`, or `terminal-rejected`. Only an authenticated acknowledgement carrying the expected `deliveryId` and `sourceUpdateId` releases leader journal authority. Negative, missing, stale, mismatched, or capacity-failed settlement remains durable; callback error answers are side effects only.
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
-- A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
-- Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner cleanup groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS birth proof discards all session-owned sources without replay; a matching proof is `alive`, while Windows or inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
+- A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Cached presence is not current execution proof: prepared custody must revalidate the exact queued owner/group without recovery and refuse offers or uncertain reads. Completion requires an exact removal acknowledgement, never merely `!ready`; a retained acknowledgement permits local cleanup only, not replay. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
+- Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner cleanup groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS birth proof discards all session-owned sources without replay; a matching proof is `alive`, while Windows or inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. Under actual `A`–`Z` allocation pressure, retirement may invoke that journal-owned CAS only for a current inactive binding after complete strict source inspection, no local work/live owner/delivery authority, whole unoffered receipt groups, and a preflight proving every grouped owner dead. It must then recapture all protection before preparing deletion; partial progress never grants deletion authority. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
 - Execution failures persist bounded diagnostics and attempt state as `retry-wait`, except that an exact Telegram HTTP 400 stale/deleted-thread API failure with a proven `{chatId, threadId}` terminally settles the currently executing source after best-effort shared binding invalidation. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity. Missing snapshots left by the retired broad temp cleanup rebuild only from a complete provably empty segment chain, while revisionless snapshots may recover from a validated later segment predecessor; otherwise the snapshot and segments move atomically under `tmp/telegram/recovery/` before a fresh journal is published and startup continues with informational recovery evidence.
-- An unresolved reaction delays only the exact governed queue item identified by chat/message sources, not unrelated queue work. Queue receipt publication follows in-memory append and precedes dispatch request; receipt-bearing turns remain queued until every exact source commits.
+- Business connection chats are a separate namespace even when their chat/message IDs match bot-chat IDs. Default DM routing must never infer private-queue deletion intent from `deleted_business_messages`; raw companion handlers remain separate owners.
+- An unresolved reaction delays only the exact governed queue item identified by chat/message sources, not unrelated queue work. An explicit immutable `preApprovalExcluded: true` cannot govern accepted work, even after re-pairing; missing or false exclusion evidence must not bypass the dependency guard. Prepared v3 drain may dispose of excluded pending input only through journal-owned `removeExcluded`, never generic raw completion; mixed requests containing non-excluded input must fail atomically. Queue receipt publication follows in-memory append and precedes dispatch request; receipt-bearing turns remain queued until every exact source commits.
 - The detailed implementation and release gates live in [`docs/architecture.md`](./docs/architecture.md), [`docs/multi-instance-bus.md`](./docs/multi-instance-bus.md), and [`BACKLOG.md`](./BACKLOG.md).
 
 ### 4.4 Queue, Delivery, And User Surfaces
@@ -99,7 +101,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - `preview` owns streaming lifecycle only, not assistant rendering. Finalization waits for active preview flushes and must not issue pre/post-final draft-clear calls that create transient Telegram draft UI. Turns that already answer as one atomic reply (voice replies, Guest Mode queries) never stream previews.
 - Native `sendChatAction(typing)` is the automatic activity signal for unsettled agent and compaction work while Telegram transport is authorized. Extension-owned blocking UI prompts pause it and completion resumes it while either work owner remains active. Do not invent extra in-chat work indicators or emit activity for startup/connect/reload/recovery alone.
 - Public activity handlers and connected companion delivery are asynchronous, target-bound, generation-fenced surfaces. Connected companion projection has no independent opt-out: disconnect or authority loss is its boundary. Token deltas, hidden reasoning, unknown sources, and stale authority never enter public projection.
-- Thread display defaults to the profile-scoped Letters strategy, with Names, Directory Snake, and Directory Title as the other automatic choices; Names projects the generated dictionary name for the slot. Unsupported retained display keys resolve to Letters without rewriting persisted configuration. A durable manual Thread display name retained on its Workspace binding overrides any automatic projection until exact reset; keep generated/recovery identity separate from manual and acknowledged display fields. UI labels, emoji semantics, navigation, settings controls, callback namespaces, voice behavior, command templates, and assistant markup follow the linked `/docs` contracts. Generated human-readable prompt-button labels use `emoji + space + text`; emoji-free text is only a reasoned no-semantic-marker fallback. Non-spatial generated controls default to top-level vertical cells, with nested rows reserved for unmistakably compact peers. Do not restate other evolving UI details here.
+- Thread display defaults to the profile-scoped Letters strategy, with Names, Directory Snake, and Directory Title as the other automatic choices; Names projects the generated dictionary name for the slot. Unsupported retained display keys resolve to Letters without rewriting persisted configuration. A durable manual Thread display name retained on its Workspace binding overrides any automatic projection until exact reset; keep generated/recovery identity separate from manual and acknowledged display fields. After leader startup, automatic display contraction waits one follower-staleness window so election and follower re-registration cannot briefly remove and restore an acknowledged same-cwd suffix; stop/start generation cancels stale reconciliation. UI labels, emoji semantics, navigation, settings controls, callback namespaces, voice behavior, command templates, and assistant markup follow the linked `/docs` contracts. Generated human-readable prompt-button labels use `emoji + space + text`; emoji-free text is only a reasoned no-semantic-marker fallback. Non-spatial generated controls default to top-level vertical cells, with nested rows reserved for unmistakably compact peers. Do not restate other evolving UI details here.
 
 ## 5. Domain Ownership Index