@llblab/pi-kit 0.20.0 → 0.21.1

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

@@ -74,7 +74,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - 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. 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; 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.
+- 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. Follower heartbeat response deadlines align with the eight-second leader stale-liveness window rather than the generic one-second local-RPC default; an ordinary multi-second Pi/TUI event-loop stall is not registration loss. 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
@@ -95,7 +95,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 ### 4.4 Queue, Delivery, And User Surfaces
 
 - Queue lane/kind admission is explicit. Dispatch waits for active-turn, pending-dispatch, control, compaction, `ctx.isIdle()`, and Pi pending-message guards; a dispatched prompt stays queued until `agent_start` consumes it. The terminal `+N` suffix is a yellow count of executable prompts still waiting, excludes the dispatched head immediately, and never counts current agent work from any source. Each prompt is one object with one active lane and no reserved return slot. Normal and Priority are separate FIFO lanes: crossing lanes removes it from the source and appends it at the destination tail, while Keep/Skip and same-category emoji changes preserve lane position. Complete reaction sets independently derive Priority from recognized positive emoji and Skip from recognized negative emoji; both may coexist, suppressed turns retain durable receipts while waiting, and Skip settles them only when the prompt reaches dispatch before dropping it without inference. Suppressed turns remain visible at a struck-through physical ordinal without contributing to executable queue counters, while graceful session shutdown discards all remaining queue authority before clearing memory.
-- `/stop`, `/abort`, `/next`, and `/continue` respectively reset+abort, abort while preserving queue, force the next turn, and enqueue a control-lane continuation. Abort-history folding applies only to Telegram-owned active turns.
+- `/stop`, `/abort`, `/next`, and `/continue` respectively reset+abort, abort while preserving queue, force the next turn, and enqueue a control-lane continuation. Abort-history folding applies only to Telegram-owned active turns. A busy `/next` marks only its exact active Telegram turn: terminal abort settlement attempts one explicit abort notice before the exact selected queued prompt receives its dispatch notice. Notice failure is diagnostic and cannot block dispatch; a later `/abort` or `/stop` cancels both pending transition notices before taking ownership. Target command adapters must forward these transition ports. A successful dispatch notice keeps the queued prompt's one reply-header claim across agent start, so later messages in that turn never repeat it.
 - Telegram extension side effects must not hold Pi's core lifecycle hostage after semantic completion. Preserve ordering in extension-owned background work, record failures, and fence target/profile/transport/session authority.
 - Complete assistant/guest model answers use Telegram-native Rich Markdown. Harness-owned menus, status, diagnostics, thinking, and tool evidence remain explicit HTML/plain or their documented native surface. Before Telegram preview or final delivery, strip every assistant-authored HTML comment regardless of Markdown position while keeping action activation top-level-only; a comment-only result sends no text message. Preserve literal code outside comments and structurally safe chunking; never split invalid markup.
 - `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.

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

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 0.51.1: Queue transitions and follower heartbeat stability
+
+- `/next lifecycle notices`: Target command composition now forwards request, exact-turn marker, and cancellation ports. Busy `/next` orders abort then selected-prompt dispatch notices; failures cannot block dispatch, and `/abort`/`/stop` cancel stale notices. A successful dispatch notice keeps first-reply ownership through agent start, so later answer messages do not repeat the queued-prompt reply. Rapid ordinary messages remain distinct turns.
+- `Follower heartbeat stability`: Follower heartbeats now use a dedicated eight-second response deadline aligned with leader stale-liveness policy instead of the generic one-second local-RPC default. Ordinary multi-second TUI/event-loop stalls therefore retain registration and stable `follower` status rather than destroying the socket, producing leader EPIPE noise, and entering repeated reconnect cycles.
+
 ## 0.51.0: Safe Workspace rotation and follower readiness
 
 - `Workspace slot rotation`: Fresh allocation reclaims the oldest proven inactive slot only at full A–Z pressure. Exact grouped receipts may be journal-CAS discarded only after complete source inspection proves every process-birth owner dead. Live/unknown owners, partial groups, handoffs and unrelated work stay protected. Fresh protection precedes Thread/history deletion and slot reuse. Pi sessions/files/memory/journals remain; restore-only never evicts; ambiguous deletion never replays.

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

@@ -34,6 +34,7 @@ export interface TelegramQueueBindingRuntime<TContext> {
     mutation: Queue.TelegramQueueMutationController<TContext>;
     dispatchNext: (ctx: TContext) => void;
     requestNextDispatchAnnouncement: () => void;
+    cancelNextDispatchAnnouncement: () => void;
     watchdog: Queue.TelegramQueueDispatchWatchdogRuntime<TContext>;
 }
 export declare function createTelegramQueueBindingRuntime<TContext>(deps: {
@@ -58,6 +59,7 @@ export declare function createTelegramQueueBindingRuntime<TContext>(deps: {
     updateStatus: (ctx: TContext, error?: string) => void;
     sendTextReply: Queue.TelegramQueueDispatchRuntimeDeps<TContext>["sendTextReply"];
     sendUserMessage: Queue.TelegramQueueDispatchRuntimeDeps<TContext>["sendUserMessage"];
+    reconcileNextDispatchAnnouncementReplyOwnership?: (item: Queue.PendingTelegramTurn) => void;
     recordRuntimeEvent?: TelegramRuntimeEventRecorder;
 }): TelegramQueueBindingRuntime<TContext>;
 export interface TelegramGenerativeAppLiveSurfaceBinding {

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

@@ -79,6 +79,7 @@ export function createTelegramQueueBindingRuntime(deps) {
         },
         updateStatus: deps.updateStatus,
         sendTextReply: deps.sendTextReply,
+        reconcileNextDispatchAnnouncementReplyOwnership: deps.reconcileNextDispatchAnnouncementReplyOwnership,
         recordRuntimeEvent: deps.recordRuntimeEvent,
         ...deps.promptDispatch,
         sendUserMessage: deps.sendUserMessage,
@@ -87,6 +88,7 @@ export function createTelegramQueueBindingRuntime(deps) {
         mutation,
         dispatchNext: dispatch.dispatchNext,
         requestNextDispatchAnnouncement: dispatch.requestNextDispatchAnnouncement,
+        cancelNextDispatchAnnouncement: dispatch.cancelNextDispatchAnnouncement,
         watchdog: Queue.createTelegramQueueDispatchWatchdogRuntime({
             hasQueuedItems: deps.store.hasQueuedItems,
             dispatchNextQueuedTelegramTurn: dispatch.dispatchNext,

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

@@ -8,7 +8,7 @@
 import * as Sync from "./sync.ts";
 import * as Threads from "./threads.ts";
 import { type TelegramUpdateJournalStoreOptions } from "./journal.ts";
-import type { TelegramLockEntry, TelegramLockState } from "./locks.ts";
+import { type TelegramLockEntry, type TelegramLockState } from "./locks.ts";
 import type { TelegramQueueHandoffPayload, TelegramQueueHandoffStageResult } from "./queue.ts";
 import type { TelegramTarget } from "./target.ts";
 import { type TelegramBusAgentMessage, type TelegramBusAgentTargetSelector, type TelegramBusEnvelope, type TelegramBusForwardOwnership, type TelegramBusProtocolIdentity, type TelegramBusSocketPathSource } from "./bus.ts";
@@ -18,6 +18,7 @@ export declare const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2500;
 export declare const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30000;
 export declare const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30000;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30000;
+export declare const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = 8000;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS: number;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS: number;
 export interface TelegramFollowerSessionHandoff {
@@ -170,6 +171,7 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<TContext extends {
     registrationRetryAttempts?: number;
     registrationRetryDelayMs?: number;
     heartbeatMs?: number;
+    heartbeatTimeoutMs?: number;
     recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
     onHeartbeatFailure?: (error: unknown, ctx: TContext) => Promise<void> | void;
     onRegistered?: (ctx: TContext) => Promise<void> | void;