@llblab/pi-kit 0.9.0 → 0.10.0

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

@@ -7,6 +7,7 @@ import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol }
 import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
 import { ArtifactReadTracker } from "./acquisition.ts";
 import { loadStateFlowConfig } from "./config.ts";
+import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { SkillReadTracker } from "./skills.ts";
 import { emptySnapshot, migrationFailure, persistableSnapshot, type Snapshot } from "./snapshot.ts";
@@ -44,11 +45,12 @@ export interface StateFlowExtensionOptions {
 	repositoryRoot?: string;
 	knowledgeRoot?: string;
 	onRuntime?: (accessor: { read(offset?: number, scope?: StateScope): MaterializedState }) => void;
+	telegram?: { load?: StateFlowTelegramLoader };
 }
 
 export const PATCH_STATE_TOOL_NAME = "patch_state";
 export const READ_STATE_TOOL_NAME = "read_state";
-export const MAX_RESOLUTION_ATTEMPTS = 3;
+export const MAX_FALLBACK_ATTEMPTS: number = 2;
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 
 /** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
@@ -65,9 +67,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let branchHasSnapshot = false;
 	let branchStartsWithoutRuntime = false;
 	let terminalEligible = false;
-	let terminalDraftIntercepted = false;
-	let resolutionAttempts = 0;
-	let resolutionFailureReported = false;
+	let resolutionPending = false;
+	let fallbackAttempts = 0;
+	let fallbackFailureReported = false;
 	let responseAwaitingReconciliation = false;
 	let passiveContinuation: PassiveContinuation | undefined;
 	let bootstrapContinuation: PassiveContinuation | undefined;
@@ -85,6 +87,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
 	let artifactInvalidations: ArtifactInvalidationRequest[] = [];
 	let loggingWarningReported = false;
+	let telegramStartPending = false;
 
 	function sessionAddress(ctx: ExtensionContext): SessionAddress {
 		return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
@@ -124,9 +127,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function clearRunTransient(): void {
 		terminalEligible = false;
-		terminalDraftIntercepted = false;
-		resolutionAttempts = 0;
-		resolutionFailureReported = false;
+		resolutionPending = false;
+		fallbackAttempts = 0;
+		fallbackFailureReported = false;
 		responseAwaitingReconciliation = false;
 		runAnchorTimestamp = undefined;
 		skillReads.clear();
@@ -273,10 +276,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}, runtime!.causalBasis(), { finalizeRun });
 		if (!committed) return false;
 		installScopeStates();
-		artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
-		artifactReads.setCandidates(artifactInvalidations);
-		skillReads.clear();
-		artifactReads.clear();
+		// A preserved primary response commits mid-run; pending acquisition obligations must
+		// still block final eligibility until the fallback turns resolve or expire.
+		if (!(finalizeRun && resolutionPending)) {
+			artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
+			artifactReads.setCandidates(artifactInvalidations);
+			skillReads.clear();
+			artifactReads.clear();
+		}
 		persist();
 		return true;
 	}
@@ -451,6 +458,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		artifactInvalidations = [];
 		artifactReads.setCandidates([]);
 		artifactRefreshPending = false;
+		telegramStartPending = false;
 		activeContext = ctx;
 		const session = sessionAddress(ctx);
 		runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot);
@@ -579,15 +587,77 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}
 	}
 
-	function continueForResolution(): void {
-		terminalDraftIntercepted = true;
+	function continueFallbackResolution(lastWarning: boolean): void {
+		resolutionPending = true;
 		pi.sendMessage({
 			customType: VALIDATION_MESSAGE_TYPE,
-			content: "Before completing this turn, make the State Flow iteration terminal-eligible. Call patch_state with any durable scope changes and final:true, or call patch_state with {\"final\":true} when no semantic update is needed. Then provide the final answer normally.",
+			content: lastWarning
+				? "This is the last State Flow fallback turn. The iteration's answer is preserved and will not change. Apply the final:true patch now: call patch_state with any remaining durable scope changes and final:true, or with {\"final\":true} when nothing remains. Do not restate the answer."
+				: "The iteration's answer is preserved as the final response; later turns cannot replace it. Apply the final:true patch: call patch_state with any durable scope changes from this iteration (including required artifact or Skill compilation) and final:true, or with {\"final\":true} when nothing remains to persist. Do not restate the answer.",
 			display: false,
 		}, { deliverAs: "steer", triggerTurn: true });
 	}
 
+	/** Preserve the primary answer as this iteration's response and steer bounded fallback turns whose only purpose is the final:true patch. */
+	function beginFallbackResolution(ctx: ExtensionContext, message: { content?: unknown }, reason: string): void {
+		responseAwaitingReconciliation = true;
+		fallbackAttempts = 0;
+		fallbackFailureReported = false;
+		recordDiagnostic(`Preserved the terminal draft as the iteration response; fallback resolution started: ${reason}`, "terminal-pending", ctx, {
+			content: message.content,
+			resolutionAttempt: 0,
+			terminalEligible,
+		});
+		continueFallbackResolution(MAX_FALLBACK_ATTEMPTS === 1);
+	}
+
+	/** Fallback turns never become the response; they exist only to supply the final:true patch. */
+	function resolveFallbackTurn(ctx: ExtensionContext, message: { content?: unknown }): any {
+		let resolved = terminalEligible;
+		if (resolved) {
+			try {
+				validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
+			} catch (error) {
+				resolved = false;
+				recordDiagnostic(error instanceof Error ? error.message : String(error), "terminal-pending", ctx, {
+					content: message.content,
+					resolutionAttempt: fallbackAttempts,
+					terminalEligible,
+				});
+			}
+		}
+		if (resolved) {
+			resolutionPending = false;
+			recordDiagnostic(`Fallback resolution obtained final:true after ${fallbackAttempts} fallback turn${fallbackAttempts === 1 ? "" : "s"}; the preserved answer stands`, "finalization", ctx, {
+				content: message.content,
+				resolutionAttempt: fallbackAttempts,
+				terminalEligible,
+			});
+			return { message: { ...message, role: "assistant" as const, content: [] } };
+		}
+		fallbackAttempts = Math.min(MAX_FALLBACK_ATTEMPTS, fallbackAttempts + 1);
+		if (fallbackAttempts < MAX_FALLBACK_ATTEMPTS) {
+			recordDiagnostic(`Fallback turn ended without final:true (${fallbackAttempts}/${MAX_FALLBACK_ATTEMPTS})`, "terminal-pending", ctx, {
+				content: message.content,
+				resolutionAttempt: fallbackAttempts,
+				terminalEligible,
+			});
+			continueFallbackResolution(fallbackAttempts + 1 >= MAX_FALLBACK_ATTEMPTS);
+			return { message: { ...message, role: "assistant" as const, content: [] } };
+		}
+		resolutionPending = false;
+		recordDiagnostic(`Fallback resolution exhausted without final:true (${fallbackAttempts}/${MAX_FALLBACK_ATTEMPTS}); the preserved response and current state remain`, "finalization", ctx, {
+			content: message.content,
+			resolutionAttempt: fallbackAttempts,
+			terminalEligible,
+		});
+		if (!fallbackFailureReported) {
+			fallbackFailureReported = true;
+			ctx.ui.notify(`State Flow kept the preserved answer; no final:true patch arrived after ${MAX_FALLBACK_ATTEMPTS} fallback turns, so the iteration closed with its current state.`, "warning");
+		}
+		return { message: { ...message, role: "assistant" as const, content: [] } };
+	}
+
 	pi.registerTool({
 		name: READ_STATE_TOOL_NAME,
 		label: "Read State",
@@ -654,7 +724,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					if (params.final !== true) throw new Error('patch_state requires at least one scope patch or {"final":true}');
 					validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
 					terminalEligible = true;
-					terminalDraftIntercepted = false;
 					return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
 				}
 				const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
@@ -664,7 +733,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				commitStage(stage, ctx, false);
 				if (params.final === true) {
 					terminalEligible = true;
-					terminalDraftIntercepted = false;
 				}
 				updateUi(ctx);
 				const publication = pendingPublication === undefined ? "" : "; durable publication pending";
@@ -676,7 +744,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					input: attempted,
 					tool: PATCH_STATE_TOOL_NAME,
 					toolCallId,
-					resolutionAttempt: resolutionAttempts,
+					resolutionAttempt: fallbackAttempts,
 					terminalEligible,
 				});
 				throw separatedFailure(error);
@@ -684,74 +752,79 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 	});
 
-	pi.registerCommand("state-flow-start", {
-		description: "Start State Flow mode",
-		handler: async (_args, ctx) => {
-			if (!activeContext) restoreActiveBranch(ctx);
-			const previousSnapshot = structuredClone(snapshot);
-			const previousPassiveContinuation = passiveContinuation;
-			const previousBootstrapContinuation = bootstrapContinuation;
-			const previousArtifactRefreshPending = artifactRefreshPending;
-			const previousArtifactInvalidations = structuredClone(artifactInvalidations);
-			try {
-				if (!runtime?.view && !snapshot.meta.durableBase && !branchStartsWithoutRuntime) {
-					throw new Error("Selected branch revision is unavailable; restore its original Git history before starting State Flow");
-				}
-				const branch = ctx.sessionManager.getBranch();
-				activeContext = ctx;
-				runtime ??= createRuntime(ctx);
-				if (branchStartsWithoutRuntime) runtime.prepare();
-				const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
-					&& (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
-				if (!runtime.view && snapshot.meta.durableBase) {
-					snapshot = runtime.restore(snapshot.meta.durableBase, snapshot);
-					setPendingPublication(snapshot.meta.pendingPublication);
-					branchHasSnapshot = true;
-				}
-				const existingBranch = branchHasSnapshot;
-				snapshot = existingBranch
-					? resumeEpisode(snapshot, bootstrap)
-					: startEpisode(bootstrap);
-				if (snapshot.meta.remotePublication === undefined) {
-					snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
-						resolveRemotePublicationPolicy(existingBranch ? undefined : config.remotePublication, { legacyRuntime: existingBranch }),
-					);
-				}
+	function startStateFlow(ctx: ExtensionContext): StateFlowTelegramControlResult {
+		if (!activeContext) restoreActiveBranch(ctx);
+		telegramStartPending = false;
+		const previousSnapshot = structuredClone(snapshot);
+		const previousPassiveContinuation = passiveContinuation;
+		const previousBootstrapContinuation = bootstrapContinuation;
+		const previousArtifactRefreshPending = artifactRefreshPending;
+		const previousArtifactInvalidations = structuredClone(artifactInvalidations);
+		try {
+			if (!runtime?.view && !snapshot.meta.durableBase && !branchStartsWithoutRuntime) {
+				throw new Error("Selected branch revision is unavailable; restore its original Git history before starting State Flow");
+			}
+			const branch = ctx.sessionManager.getBranch();
+			activeContext = ctx;
+			runtime ??= createRuntime(ctx);
+			if (branchStartsWithoutRuntime) runtime.prepare();
+			const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
+				&& (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
+			if (!runtime.view && snapshot.meta.durableBase) {
+				snapshot = runtime.restore(snapshot.meta.durableBase, snapshot);
+				setPendingPublication(snapshot.meta.pendingPublication);
 				branchHasSnapshot = true;
-				const publication = runtime.view
-					? runtime.promote(snapshot) ?? runtime.publish(snapshot)
-					: runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
-				recordPolicyPublication(publication, ctx);
-				installScopeStates();
-				delete snapshot.legacySession;
-				clearRunTransient();
-				passiveContinuation = undefined;
-				bootstrapContinuation = snapshot.meta.bootstrap
-					? previousPassiveContinuation ?? previousBootstrapContinuation
-					: undefined;
-				deferArtifactRefresh();
-				syncStateFlowTools();
-				persist();
-				updateUi(ctx);
-				ctx.ui.notify(
-					snapshot.meta.bootstrap
-						? "State Flow enabled. The next complete agent run will migrate active context into state."
-						: "State Flow enabled. The next prompt starts a stateful agent run.",
-					"info",
-				);
-			} catch (error) {
-				snapshot = previousSnapshot;
-				passiveContinuation = previousPassiveContinuation;
-				bootstrapContinuation = previousBootstrapContinuation;
-				artifactRefreshPending = previousArtifactRefreshPending;
-				artifactInvalidations = previousArtifactInvalidations;
-				artifactReads.setCandidates(artifactInvalidations);
-				syncStateFlowTools();
-				ctx.ui.notify(
-					`State Flow could not initialize CWD state: ${error instanceof Error ? error.message : String(error)}`,
-					"error",
+			}
+			const existingBranch = branchHasSnapshot;
+			snapshot = existingBranch
+				? resumeEpisode(snapshot, bootstrap)
+				: startEpisode(bootstrap);
+			if (snapshot.meta.remotePublication === undefined) {
+				snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
+					resolveRemotePublicationPolicy(existingBranch ? undefined : config.remotePublication, { legacyRuntime: existingBranch }),
 				);
 			}
+			branchHasSnapshot = true;
+			const publication = runtime.view
+				? runtime.promote(snapshot) ?? runtime.publish(snapshot)
+				: runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
+			recordPolicyPublication(publication, ctx);
+			installScopeStates();
+			delete snapshot.legacySession;
+			clearRunTransient();
+			passiveContinuation = undefined;
+			bootstrapContinuation = snapshot.meta.bootstrap
+				? previousPassiveContinuation ?? previousBootstrapContinuation
+				: undefined;
+			deferArtifactRefresh();
+			syncStateFlowTools();
+			persist();
+			updateUi(ctx);
+			ctx.ui.notify(
+				snapshot.meta.bootstrap
+					? "State Flow enabled. The next complete agent run will migrate active context into state."
+					: "State Flow enabled. The next prompt starts a stateful agent run.",
+				"info",
+			);
+			return { ok: true, message: "State Flow enabled" };
+		} catch (error) {
+			snapshot = previousSnapshot;
+			passiveContinuation = previousPassiveContinuation;
+			bootstrapContinuation = previousBootstrapContinuation;
+			artifactRefreshPending = previousArtifactRefreshPending;
+			artifactInvalidations = previousArtifactInvalidations;
+			artifactReads.setCandidates(artifactInvalidations);
+			syncStateFlowTools();
+			const message = `State Flow could not initialize CWD state: ${error instanceof Error ? error.message : String(error)}`;
+			ctx.ui.notify(message, "error");
+			return { ok: false, message };
+		}
+	}
+
+	pi.registerCommand("state-flow-start", {
+		description: "Start State Flow mode",
+		handler: async (_args, ctx) => {
+			startStateFlow(ctx);
 		},
 	});
 
@@ -762,56 +835,94 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 	});
 
+	function stopStateFlow(ctx: ExtensionContext): StateFlowTelegramControlResult {
+		if (!activeContext) restoreActiveBranch(ctx);
+		telegramStartPending = false;
+		let selected = runtime;
+		let current = snapshot;
+		if (!selected?.view && snapshot.meta.durableBase) {
+			selected = createRuntime(ctx);
+			current = selected.restore(snapshot.meta.durableBase, snapshot);
+		}
+		const stoppedAt = Date.now();
+		const exitStates = selected?.view ? selected.states() : undefined;
+		const exitHandoff = current.config.enabled && exitStates
+			? createPassiveContinuation(
+				projectStateForModel(overlayStates(exitStates.global, exitStates.cwd, exitStates.session)),
+				stoppedAt,
+			)
+			: undefined;
+		const retainedHandoff = exitHandoff ?? (!current.config.enabled ? passiveContinuation : undefined);
+		const stopped = stopEpisode(current);
+		const publication = selected?.view ? selected.publish(stopped) : undefined;
+		if (selected !== runtime) {
+			runtime = selected;
+			installScopeStates();
+		}
+		snapshot = stopped;
+		recordPolicyPublication(publication, ctx);
+		branchHasSnapshot = true;
+		clearRunTransient();
+		passiveContinuation = retainedHandoff;
+		bootstrapContinuation = undefined;
+		artifactInvalidations = [];
+		artifactReads.setCandidates([]);
+		artifactRefreshPending = false;
+		if (exitHandoff) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { at: stoppedAt });
+		syncStateFlowTools();
+		persist();
+		updateUi(ctx);
+		return { ok: true, message: "State Flow disabled" };
+	}
+
 	pi.registerCommand("state-flow-stop", {
 		description: "Stop State Flow on the current session branch",
 		handler: async (_args, ctx) => {
-			if (!activeContext) restoreActiveBranch(ctx);
-			let selected = runtime;
-			let current = snapshot;
-			if (!selected?.view && snapshot.meta.durableBase) {
-				selected = createRuntime(ctx);
-				current = selected.restore(snapshot.meta.durableBase, snapshot);
-			}
-			const stoppedAt = Date.now();
-			const exitStates = selected?.view ? selected.states() : undefined;
-			const exitHandoff = current.config.enabled && exitStates
-				? createPassiveContinuation(
-					projectStateForModel(overlayStates(exitStates.global, exitStates.cwd, exitStates.session)),
-					stoppedAt,
-				)
-				: undefined;
-			const retainedHandoff = exitHandoff ?? (!current.config.enabled ? passiveContinuation : undefined);
-			const stopped = stopEpisode(current);
-			const publication = selected?.view ? selected.publish(stopped) : undefined;
-			if (selected !== runtime) {
-				runtime = selected;
-				installScopeStates();
-			}
-			snapshot = stopped;
-			recordPolicyPublication(publication, ctx);
-			branchHasSnapshot = true;
-			clearRunTransient();
-			passiveContinuation = retainedHandoff;
-			bootstrapContinuation = undefined;
-			artifactInvalidations = [];
-			artifactReads.setCandidates([]);
-			artifactRefreshPending = false;
-			if (exitHandoff) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { at: stoppedAt });
-			syncStateFlowTools();
-			persist();
-			updateUi(ctx);
+			stopStateFlow(ctx);
 		},
 	});
 
+	const telegram = createStateFlowTelegramAdapter({
+		...(options.telegram?.load === undefined ? {} : { load: options.telegram.load }),
+		port: {
+			snapshot: () => ({
+				enabled: snapshot.config.enabled,
+				step: snapshot.meta.step,
+				bootstrap: snapshot.meta.bootstrap === true,
+				startPending: telegramStartPending,
+			}),
+			canStartNow: () => activeContext === undefined || activeContext.isIdle(),
+			start: () => {
+				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
+				return startStateFlow(activeContext);
+			},
+			stop: () => {
+				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
+				try {
+					return stopStateFlow(activeContext);
+				} catch (error) {
+					return { ok: false, message: error instanceof Error ? error.message : String(error) };
+				}
+			},
+			deferStart: () => {
+				telegramStartPending = true;
+			},
+			cancelStart: () => {
+				telegramStartPending = false;
+			},
+		},
+	});
+	void telegram.ensure();
+
 	pi.on("before_agent_start", (event, ctx) => {
 		if (!snapshot.config.enabled) return;
 		skillReads.clear();
 		artifactReads.clear();
 		if (artifactRefreshPending) refreshArtifactInvalidations(ctx);
 		terminalEligible = false;
-		terminalDraftIntercepted = false;
-		resolutionAttempts = 0;
-		resolutionFailureReported = false;
+		resolutionPending = false;
+		fallbackAttempts = 0;
+		fallbackFailureReported = false;
 		responseAwaitingReconciliation = false;
 		const rotatesRun = snapshot.meta.specification !== undefined;
 		if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap") rehydrationPhase = "step";
@@ -841,7 +952,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				? passiveContinuationMessages(event.messages as AgentMessage[], bootstrapContinuation)
 				: event.messages as AgentMessage[];
 			const messages = withoutPrivateValidation(sourceMessages);
-			return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, terminalDraftIntercepted), ...messages] };
+			return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, resolutionPending), ...messages] };
 		}
 		const trajectory = currentRunTrajectory(
 			event.messages as AgentMessage[],
@@ -851,7 +962,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		runAnchorTimestamp = trajectory.anchorTimestamp;
 		return {
 			messages: [
-				runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, terminalDraftIntercepted),
+				runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, resolutionPending),
 				...trajectory.messages,
 			],
 		};
@@ -905,31 +1016,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content, terminalEligible });
 			return;
 		}
+		if (resolutionPending) return resolveFallbackTurn(ctx, message);
 		if (!terminalEligible) {
-			responseAwaitingReconciliation = false;
-			terminalDraftIntercepted = true;
-			resolutionAttempts = Math.min(MAX_RESOLUTION_ATTEMPTS, resolutionAttempts + 1);
-			recordDiagnostic(`Terminal draft intercepted before State Flow eligibility (attempt ${resolutionAttempts}/${MAX_RESOLUTION_ATTEMPTS})`, "terminal-pending", ctx, {
-				content: message.content,
-				resolutionAttempt: resolutionAttempts,
-				terminalEligible,
-			});
-			if (resolutionAttempts < MAX_RESOLUTION_ATTEMPTS) {
-				continueForResolution();
-			} else if (!resolutionFailureReported) {
-				resolutionFailureReported = true;
-				ctx.ui.notify(`State Flow could not obtain final:true after ${MAX_RESOLUTION_ATTEMPTS} terminal attempts; committed state was preserved and no draft was accepted.`, "error");
-			}
-			return { message: { ...message, role: "assistant" as const, content: [] } };
+			beginFallbackResolution(ctx, message, "the terminal draft ended without State Flow eligibility");
+			return;
 		}
 		try {
 			validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
 		} catch (error) {
-			responseAwaitingReconciliation = false;
-			terminalDraftIntercepted = true;
-			recordDiagnostic(error instanceof Error ? error.message : String(error), "terminal-pending", ctx, { content: message.content, terminalEligible });
-			continueForResolution();
-			return { message: { ...message, role: "assistant" as const, content: [] } };
+			beginFallbackResolution(ctx, message, error instanceof Error ? error.message : String(error));
+			return;
 		}
 		responseAwaitingReconciliation = true;
 	});
@@ -952,12 +1048,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			ctx.ui.notify(`State Flow could not reconcile the final response: ${error instanceof Error ? error.message : String(error)}`, "error");
 		} finally {
 			responseAwaitingReconciliation = false;
-			terminalDraftIntercepted = false;
 		}
 		updateUi(ctx);
 	});
 
-	pi.on("agent_settled", (_event, _ctx) => {
+	pi.on("agent_settled", (_event, ctx) => {
+		if (telegramStartPending && !snapshot.config.enabled) {
+			telegramStartPending = false;
+			startStateFlow(ctx);
+		}
 		if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
 	});
 
@@ -967,8 +1066,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		retryPendingPush(ctx);
 		if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
 		updateUi(ctx);
+		void telegram.ensure();
 	});
 	pi.on("session_tree", (_event, ctx) => {
 		restoreActiveBranch(ctx);
 	});
+	pi.on("session_shutdown", () => {
+		telegramStartPending = false;
+		telegram.dispose();
+	});
 }