@llblab/pi-kit 0.24.0 → 0.25.0

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

@@ -15,7 +15,7 @@ import {
   type ArtifactInvalidationRequest,
 } from "./artifact.ts";
 import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
-import { loadStateFlowConfig } from "./config.ts";
+import { inactiveModeFor, loadStateFlowConfig } from "./config.ts";
 import { ContextProjection, contextView, createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, projectSystemProtocol, runtimeContextHead, syntheticUser, type PassiveContinuation } from "./context.ts";
 import { readNativeSessionHeader } from "./continuation.ts";
 import {
@@ -24,7 +24,7 @@ import {
   sessionScopeKey,
   type SessionAddress,
 } from "./durable.ts";
-import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
+import { completeRun, deactivateEpisode, prepareRun, resumeEpisode, startEpisode } from "./episode.ts";
 import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.ts";
 import { projectRecentTransitionsWithLimit } from "./history.ts";
 import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
@@ -36,8 +36,8 @@ import type { RehydrationPhase } from "./rehydration.ts";
 import { TemporalRuntime, type RuntimePublication } from "./runtime.ts";
 import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, hasUncheckpointedConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
 import { hasCompiledSkillArtifact, hashSkillSource, registeredSkillResolver, SkillReadTracker, type SuccessfulSkillRead } from "./skills.ts";
-import { HistoryBoundaryExpiredError, emptySnapshot, migrationFailure, type RetainedBoundaryCheckpoint, type Snapshot } from "./snapshot.ts";
-import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type ScopedStates, type StateScope } from "./state.ts";
+import { HistoryBoundaryExpiredError, emptySnapshot, migrationFailure, preRuntimeCheckpoint, type InactiveMode, type RetainedBoundaryCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
+import { emptyState, projectStateForModel, type AtomicScopePatches, type SemanticState, type ModelState, type ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
 import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
 import { PublicationBusyError } from "./storage.ts";
 import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramInspection, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
@@ -49,8 +49,8 @@ export interface StateFlowExtensionOptions {
 	repositoryRoot?: string;
 	onRuntime?: (accessor: { read(offset?: number, scope?: StateScope): ModelState }) => void;
 	telegram?: { load?: StateFlowTelegramLoader };
-	/** Test/SDK capability override; repository config remains the Pi default. */
-	passive?: { bootstrap?: boolean; tools?: boolean };
+	/** Test/SDK override of the default mode for new sessions; repository config remains the Pi default. */
+	mode?: StateFlowMode;
 }
 
 export { formatPatchStateArguments };
@@ -68,15 +68,15 @@ interface InferencePreparation {
 
 interface BranchRestoration {
 	readonly controller: AbortController;
-	/** Memory acceptance is independent of the requested active/passive policy. */
+	/** Memory acceptance is independent of the requested session mode. */
 	awaitingAcceptance: boolean;
-	passiveRequested?: boolean;
+	requestedMode?: InactiveMode;
 	operation?: Promise<void>;
 }
 
 type BranchSelection =
 	| { kind: "settled" }
-	| { kind: "current" }
+	| { kind: "current"; mode: InactiveMode }
 	| { kind: "restore"; checkpoint: RetainedBoundaryCheckpoint }
 	| { kind: "fork"; checkpoint: RetainedBoundaryCheckpoint; source: SessionAddress }
 	| { kind: "auto-start" };
@@ -84,17 +84,16 @@ type BranchSelection =
 export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
 	const agentDir = options.agentDir ?? getAgentDir();
 	const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
-	const config = {
-		...loadedConfig,
-		passiveBootstrap: options.passive?.bootstrap ?? loadedConfig.passiveBootstrap,
-		passiveTools: options.passive?.tools ?? loadedConfig.passiveTools,
-	};
-	let snapshot: Snapshot = emptySnapshot();
+	const config = options.mode === undefined ? loadedConfig
+		: { ...loadedConfig, mode: options.mode, inactiveMode: inactiveModeFor(options.mode) };
+	let snapshot: Snapshot = emptySnapshot(config.inactiveMode);
 	let scopeStates: ScopedStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
+	let effectiveState: SemanticState = {};
 	let branchStartsWithoutRuntime = false;
 	let selectedHistoryExpired = false;
-	let stopPersistenceError: string | undefined;
-	let stopPersistence: { controller: AbortController; operation?: Promise<StateFlowTelegramControlResult> } | undefined;
+	let modePersistenceError: string | undefined;
+	/** One pending inactive-mode persistence; later inactive choices coalesce until it publishes. */
+	let inactivePersistence: { controller: AbortController; published?: boolean; operation?: Promise<StateFlowTelegramControlResult> } | undefined;
 	let startActivation: { controller: AbortController; operation?: Promise<StateFlowTelegramControlResult> } | undefined;
 	let forkInitialization = false;
 	let branchRestoration: BranchRestoration | undefined;
@@ -151,7 +150,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
 	}
 
-	function projectModelState(state: MaterializedState): ModelState {
+	function projectModelState(state: SemanticState): SemanticState {
 		return projectStateForModel(state, artifactHints);
 	}
 
@@ -164,19 +163,28 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	options.onRuntime?.({ read: (offset, scope) => {
 		if (scope === "session") assertSelectedBranchAvailable();
 		if (!runtime) throw new Error("State Flow temporal runtime is unavailable");
-		return projectModelState(runtime.read(offset, scope));
+		const { lazy: _lazy, ...defaults } = emptyState();
+		return { ...defaults, ...projectModelState(runtime.readView(offset, scope)) };
 	} });
 
 	function assertPublicationAvailable(): void {
 		assertSelectedBranchAvailable();
-		if (stopPersistenceError) throw new Error(`Memory writes paused after Stop: ${stopPersistenceError}; use /state-flow-start`);
+		if (modePersistenceError) throw new Error(`Memory writes paused after mode change: ${modePersistenceError}; use /state-flow-active`);
+	}
+
+	function isActive(): boolean {
+		return snapshot.config.mode === "active";
+	}
+
+	/** An unavailable or pending active selection keeps the configured inactive policy, never an invented one. */
+	function inactiveSelection(mode: StateFlowMode): InactiveMode {
+		return mode === "active" ? config.inactiveMode : mode;
 	}
 
 	function appendCheckpoint(): void {
-		const checkpoint = branchStartsWithoutRuntime ? { disabled: true } : runtime?.retainedCheckpoint(snapshot) ?? { disabled: true };
-		if ("disabled" in checkpoint && !branchStartsWithoutRuntime) {
-			throw new Error("State Flow cannot checkpoint an unproven branch as ordinary disabled; restore a valid checkpoint first");
-		}
+		const checkpoint = branchStartsWithoutRuntime ? preRuntimeCheckpoint(snapshot.config.mode)
+			: runtime?.view ? runtime.retainedCheckpoint(snapshot) : undefined;
+		if (!checkpoint) throw new Error("State Flow cannot checkpoint an unproven branch; restore a valid checkpoint first");
 		pi.appendEntry(SNAPSHOT_ENTRY_TYPE, checkpoint);
 		if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
 	}
@@ -191,10 +199,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
 	}
 
-	function cancelStopPersistence(): Promise<StateFlowTelegramControlResult> | undefined {
-		const pending = stopPersistence;
+	function cancelInactivePersistence(): Promise<StateFlowTelegramControlResult> | undefined {
+		const pending = inactivePersistence;
 		pending?.controller.abort();
-		stopPersistence = undefined;
+		inactivePersistence = undefined;
 		return pending?.operation;
 	}
 
@@ -277,9 +285,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		artifactReads.setCandidates(artifactInvalidations);
 	}
 
-	function missingArtifactRemovals(states: ScopedStates): AtomicScopePatches {
+	function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches {
 		const owners = new Map<string, StateScope[]>();
-		for (const scope of ["global", "cwd", "session"] as const) for (const path of Object.keys(states[scope].artifacts)) {
+		for (const scope of ["global", "cwd", "session"] as const) for (const path of Object.keys(states[scope].artifacts ?? {})) {
 			owners.set(path, [...owners.get(path) ?? [], scope]);
 		}
 		const removals: AtomicScopePatches = {};
@@ -296,10 +304,17 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function installScopeStates(): void {
 		scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
+		effectiveState = runtime?.view ? runtime.readView() : {};
+	}
+
+	/** Active and passive expose both memory tools; Off exposes neither. */
+	function memoryToolsAvailable(): boolean {
+		return snapshot.config.mode !== "off";
 	}
 
-	function passiveToolsAvailable(): boolean {
-		return snapshot.config.enabled || config.passiveTools;
+	/** Passive memory context needs a loaded view; Off and Active never inject it. */
+	function passiveMemoryAvailable(): boolean {
+		return snapshot.config.mode === "passive" && runtime?.view !== undefined;
 	}
 
 	async function inspectTelegramState(scope: StateFlowTelegramScope): Promise<StateFlowTelegramInspection> {
@@ -307,22 +322,20 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
 		const selected = runtime ??= createRuntime(activeContext);
 		const signal = sharedInspectionLifetime.signal;
-		if (!selected.view || (scope !== "session" && !stopPersistenceError)) await selected.refreshShared(signal);
+		if (!selected.view || (scope !== "session" && !modePersistenceError)) await selected.refreshShared(signal);
 		signal.throwIfAborted();
 		if (runtime !== selected) throw new Error("State Flow inspection selection changed; select the scope again");
 		if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
 		if (!selected.view) throw new Error("State Flow temporal runtime is unavailable");
 		installScopeStates();
-		const state = scope === "effective"
-			? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
-			: scopeStates[scope];
-		return { state: { ...projectModelState(state), lazy: structuredClone(state.lazy) }, revisions: scopeRevisions(), signal };
+		const state = scope === "effective" ? effectiveState : selected.readView(0, scope);
+		return { state: { ...projectModelState(state), ...(state.lazy === undefined ? {} : { lazy: structuredClone(state.lazy) }) }, revisions: scopeRevisions(), signal };
 	}
 
 	function syncStateFlowTools(): void {
 		const active = pi.getActiveTools();
 		const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
-		const available = passiveToolsAvailable();
+		const available = memoryToolsAvailable();
 		if (owned.every((name) => active.includes(name) === available)) return;
 		pi.setActiveTools(available
 			? [...new Set([...active, ...owned])]
@@ -374,7 +387,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			if (!selected?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
 			await selected.withPatchTransaction((transaction) => {
 				signal.throwIfAborted();
-				if (runtime !== selected || inferencePreparation !== pending || !snapshot.config.enabled || shuttingDown) {
+				if (runtime !== selected || inferencePreparation !== pending || !isActive() || shuttingDown) {
 					throw new Error("State Flow inference selection changed while awaiting publication");
 				}
 				assertPublicationAvailable();
@@ -436,6 +449,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			cwdScopeKey: cwdScopeKey(cwd),
 			sessionScopeKey: sessionScopeKey(session.key),
 			scopeStates: diagnosticStates,
+			effectiveState,
 			recent: diagnosticRecent,
 			historyLimit: config.historyLimit,
 			...(view === undefined ? {} : { temporal: {
@@ -446,7 +460,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			} }),
 			staleArtifacts,
 			...(durableStateError === undefined ? {} : { durableStateError }),
-			...(stopPersistenceError === undefined ? {} : { publicationError: stopPersistenceError }),
+			...(modePersistenceError === undefined ? {} : { publicationError: modePersistenceError }),
 		};
 	}
 
@@ -465,7 +479,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		// Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
 		if (!startOwner) {
 			cancelStartActivation();
-			cancelStopPersistence();
+			cancelInactivePersistence();
 		}
 		clearRunTransient();
 		passiveContinuation = undefined;
@@ -484,44 +498,56 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		try {
 			const branch = ctx.sessionManager.getBranch();
 			const fence = retainsPhysicalSessionProjection(sessionStartReason)
-				? findPassiveStopBoundary(branch, ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE)?.persistenceError
+				? findPassiveStopBoundary(branch, ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE)
 				: undefined;
-			stopPersistenceError = fence ?? (startOwner ? stopPersistenceError : undefined);
-			if (fence) {
-				// The native Stop owns policy only: read proven memory, never replay or publish a stale selection.
-				selection = { kind: "current" };
+			modePersistenceError = fence?.persistenceError ?? (startOwner ? modePersistenceError : undefined);
+			if (fence?.persistenceError) {
+				// The native marker owns policy only: read proven memory, never replay or publish a stale selection.
+				selection = { kind: "current", mode: fence.mode ?? config.inactiveMode };
 			} else {
 				const discovery = discoverSnapshotData(branch);
-				const selected = selectRetainedCheckpoint(discovery.candidates);
+				const selected = selectRetainedCheckpoint(discovery.candidates, config.inactiveMode);
 				skipped = discovery.errors.length + selected.skipped.length;
-				branchStartsWithoutRuntime = selected.kind === "disabled" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
+				branchStartsWithoutRuntime = selected.kind === "pre-runtime" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
 				if (discovery.candidates.length === 0 && discovery.errors.length > 0) {
-					snapshot = migrationFailure({}, `Snapshot restoration failed: ${discovery.errors[0]}`);
+					snapshot = migrationFailure({}, `Snapshot restoration failed: ${discovery.errors[0]}`, config.inactiveMode);
 				} else if (selected.kind === "boundary" && forkInitialization) {
 					try {
 						// Native parent acquisition stays outside canonical exclusion.
 						const source = forkSource(ctx);
-						const sourceStopped = findPassiveStopBoundary(branch, source.id, PASSIVE_STOP_ENTRY_TYPE)?.persistenceError !== undefined;
-						selection = { kind: "fork", source, checkpoint: sourceStopped ? { ...selected.checkpoint, enabled: false } : selected.checkpoint };
+						const sourceFence = findPassiveStopBoundary(branch, source.id, PASSIVE_STOP_ENTRY_TYPE);
+						selection = { kind: "fork", source, checkpoint: sourceFence?.persistenceError !== undefined
+							? { ...selected.checkpoint, mode: sourceFence.mode ?? config.inactiveMode } : selected.checkpoint };
 					} catch (error) {
-						snapshot = selectedBoundaryFailure(diagnosticText(error));
+						snapshot = selectedBoundaryFailure(diagnosticText(error), inactiveSelection(selected.checkpoint.mode));
 					}
 				} else if (selected.kind === "boundary") {
 					selection = { kind: "restore", checkpoint: selected.checkpoint };
+				} else if (selected.kind === "pre-runtime") {
+					snapshot = emptySnapshot(selected.mode);
 				} else if (discovery.candidates.length > 0) {
-					snapshot = selected.kind === "disabled" ? emptySnapshot() : selected.snapshot;
-				} else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
-					selection = { kind: "auto-start" };
+					snapshot = selected.snapshot;
+				} else if (isNewSession(sessionStartReason, branch)) {
+					// The repository mode is only a default for genuinely new sessions.
+					if (config.mode === "active") selection = { kind: "auto-start" };
+					else {
+						snapshot = emptySnapshot(config.mode);
+						// Adopt the default once without initializing semantic storage.
+						appendCheckpoint();
+					}
 				} else {
-					snapshot = emptySnapshot();
+					snapshot = emptySnapshot(config.inactiveMode);
 				}
 			}
 		} catch (error) {
 			selection = { kind: "settled" };
-			snapshot = selectedBoundaryFailure(diagnosticText(error));
+			snapshot = selectedBoundaryFailure(diagnosticText(error), config.inactiveMode);
 		}
 		// Pending selection grants neither private reads nor publication until its acceptance installs memory.
-		if (selection.kind !== "settled") snapshot = migrationFailure({}, "State Flow branch restoration is pending");
+		if (selection.kind !== "settled") {
+			snapshot = migrationFailure({}, "State Flow branch restoration is pending", selection.kind === "current" ? selection.mode
+				: selection.kind === "auto-start" ? config.inactiveMode : inactiveSelection(selection.checkpoint.mode));
+		}
 		const pending: BranchRestoration = {
 			controller: new AbortController(),
 			awaitingAcceptance: selection.kind !== "settled" && selection.kind !== "current",
@@ -578,22 +604,23 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 						const current = await candidate.refreshCurrentMemory(signal);
 						assertCurrent();
 						if (current) runtime = selected = candidate;
-						snapshot = current ?? migrationFailure({}, "Current State Flow session memory is unavailable");
+						snapshot = current ? deactivateEpisode(current, pending.requestedMode ?? selection.mode)
+							: migrationFailure({}, "Current State Flow session memory is unavailable", pending.requestedMode ?? selection.mode);
 						installScopeStates();
 					} else if (selection.kind === "restore") {
 						await candidate.withRestoreTransaction(selection.checkpoint, (restored, publish) => {
 							assertCurrent();
 							// Canceled preparation or boundary continuation may have no specification. Retain uncompiled native context.
-							if (restored.config.enabled && restored.meta.specification === undefined
+							if (restored.config.mode === "active" && restored.meta.specification === undefined
 								&& retainsPhysicalSessionProjection(reason) && hasUncheckpointedConversation(ctx.sessionManager.getBranch())) restored.meta.bootstrap = true;
-							const next = pending.passiveRequested ? stopEpisode(restored) : restored;
+							const next = pending.requestedMode ? deactivateEpisode(restored, pending.requestedMode) : restored;
 							accept(candidate, next, publish(next), appendCheckpoint);
 						}, signal);
 					} else if (selection.kind === "fork") {
 						await candidate.withForkTransaction(selection.source, selection.checkpoint, (child, publish) => {
 							assertCurrent();
 							// Mode is selected independently of creating the child's private memory.
-							const next = pending.passiveRequested ? stopEpisode(child) : child;
+							const next = pending.requestedMode ? deactivateEpisode(child, pending.requestedMode) : child;
 							const publication = publish(next);
 							forkInitialization = false;
 							accept(candidate, next, publication, () => {
@@ -609,7 +636,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 							const discovery = discoverSnapshotData(branch);
 							if (current || discovery.candidates.length > 0 || discovery.errors.length > 0) throw new Error("Existing session runtime requires retained-boundary restoration");
 							const activated = startEpisode(hasPriorConversation(branch));
-							const next = pending.passiveRequested ? stopEpisode(activated) : activated;
+							const next = pending.requestedMode ? deactivateEpisode(activated, pending.requestedMode) : activated;
 							accept(candidate, next, publish(next), appendCheckpoint);
 						}, signal, true);
 					}
@@ -620,7 +647,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					}
 					if (!isCurrent()) return;
 					if (error instanceof HistoryBoundaryExpiredError) selectedHistoryExpired = true;
-					snapshot = selectedBoundaryFailure(diagnosticText(error));
+					snapshot = selectedBoundaryFailure(diagnosticText(error), snapshot.config.mode === "active" ? config.inactiveMode : snapshot.config.mode);
 					installScopeStates();
 				} finally {
 					pending.awaitingAcceptance = false;
@@ -628,25 +655,19 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				if (accepted) return;
 			}
 			settleSelection(ctx, reason, notifyRecovery, skipped, selected !== placeholder);
-			if (snapshot.config.enabled || !(config.passiveBootstrap || config.passiveTools) || runtime?.view) return;
-			const passive = createRuntime(ctx);
-			const priorView = selected?.view;
-			try {
-				await passive.refreshShared(signal);
-			} catch (error) {
-				if (isCurrent() && !signal.aborted && notifyRecovery && !stopPersistenceError) notifyProblem(ctx, `State Flow passive memory is unavailable: ${diagnosticText(error)}`, "warning");
-				return;
-			}
+			if (snapshot.config.mode !== "passive" || runtime?.view) return;
+			const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery);
+			if (passive === undefined) return;
 			assertCurrent();
 			// An intervening passive patch or inspection owns its newer cache, even on the same physical branch.
-			if (selected?.view !== priorView) return;
+			if (runtime?.view) return;
 			runtime = selected = passive;
 			installScopeStates();
 			updateUi(ctx);
 		} catch (error) {
 			// Host failures before acceptance leave the selection unavailable, never invented empty memory.
 			if (accepted || !isCurrent()) return;
-			snapshot = selectedBoundaryFailure(diagnosticText(error));
+			snapshot = selectedBoundaryFailure(diagnosticText(error), snapshot.config.mode === "active" ? config.inactiveMode : snapshot.config.mode);
 			installScopeStates();
 		} finally {
 			pending.awaitingAcceptance = false;
@@ -654,29 +675,42 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}
 	}
 
+	/** Load current shared memory for passive projection without initializing or publishing it. */
+	async function loadPassiveView(ctx: ExtensionContext, signal: AbortSignal, isCurrent: () => boolean, notify: boolean): Promise<TemporalRuntime | undefined> {
+		const passive = createRuntime(ctx);
+		try {
+			await passive.refreshShared(signal);
+		} catch (error) {
+			if (isCurrent() && !signal.aborted && notify && !modePersistenceError) notifyProblem(ctx, `State Flow passive memory is unavailable: ${diagnosticText(error)}`, "warning");
+			return undefined;
+		}
+		return passive;
+	}
+
 	function settleSelection(ctx: ExtensionContext, reason: unknown, notifyRecovery: boolean, skipped: number, selectedMemory: boolean): void {
-		const failure = !snapshot.config.enabled && snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error : undefined;
-		if (failure !== undefined && notifyRecovery && !stopPersistenceError) {
-			if (selectedHistoryExpired) notifyProblem(ctx, "State Flow history is outside the retained temporal window; /state-flow-start can use current session memory.", "warning");
+		const failure = !isActive() && snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error : undefined;
+		if (failure !== undefined && notifyRecovery && !modePersistenceError) {
+			if (selectedHistoryExpired) notifyProblem(ctx, "State Flow history is outside the retained temporal window; /state-flow-active can use current session memory.", "warning");
 			else notifyProblem(ctx, `State Flow restore failed: ${failure}`, "error");
 		}
 		if (selectedMemory && retainsPhysicalSessionProjection(reason) && runtime?.view) {
 			const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
 			if (boundary !== undefined) {
 				const continuation = createPassiveContinuation(
-					projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
+					projectModelState(effectiveState),
 					boundary.at,
 					boundary.from,
 					boundary.preserveContext,
 				);
-				if (!snapshot.config.enabled) passiveContinuation = continuation;
+				// Off retains the handoff boundary for a later Passive or Active choice but never projects it.
+				if (!isActive()) passiveContinuation = continuation;
 				else if (snapshot.meta.bootstrap) bootstrapContinuation = continuation;
 			}
 		}
-		if (notifyRecovery && snapshot.config.enabled && skipped > 0) {
+		if (notifyRecovery && isActive() && skipped > 0) {
 			notifyProblem(ctx, `State Flow skipped ${skipped} malformed snapshot(s); restored the last valid one.`, "warning");
 		}
-		if (snapshot.config.enabled) deferInferencePreparation();
+		if (isActive()) deferInferencePreparation();
 		syncStateFlowTools();
 		updateUi(ctx);
 	}
@@ -698,7 +732,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		async execute(_toolCallId, params, signal) {
 			try {
 				type ReadDetails = { path?: string; paths?: string[]; projection?: string; transitionId?: string };
-				if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
+				if (!memoryToolsAvailable()) throw new Error("State Flow tools are off for this session");
 				if (signal?.aborted) throw new Error("State Flow read was aborted");
 				if (!runtime?.view) throw new Error("State Flow temporal runtime is unavailable");
 				if (params.path === undefined && params.paths === undefined) throw new Error("read_state requires path or paths");
@@ -751,7 +785,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			try {
-				if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
+				if (!memoryToolsAvailable()) throw new Error("State Flow tools are off for this session");
 				assertPublicationAvailable();
 				if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
 				if (!isObject(params)) throw new Error("patch_state requires an object");
@@ -773,10 +807,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				const selected = runtime ??= createRuntime(ctx);
 				const acquiredArtifacts = structuredClone([...artifactReads.successful.values()]);
 				const acquiredSkills = structuredClone([...skillReads.successful.values()]);
-				const previousEffective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
+				const previousEffective = effectiveState;
 				return await selected.withPatchTransaction((transaction) => {
 					if (runtime !== selected) throw new Error("State Flow session selection changed while awaiting publication");
-					if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
+					if (!memoryToolsAvailable()) throw new Error("State Flow tools are off for this session");
 					assertPublicationAvailable();
 					for (const acquired of acquiredArtifacts) {
 						const observation = inspectRegisteredArtifactPaths([acquired.path])[0];
@@ -803,7 +837,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					}
 					clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
 					updateUi(ctx);
-					const updates = contextProjection.acceptPatch(previousEffective, overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session), patches, artifactHints);
+					const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, artifactHints);
 					const acknowledgement = changed
 						? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
 						: "\nState already current.";
@@ -830,8 +864,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (shuttingDown) return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
 		if (startActivation?.operation) return startActivation.operation;
 		telegramStartPending = false;
-		if (activeContext && !branchRestoration && snapshot.config.enabled) {
-			return Promise.resolve({ ok: true, message: "State Flow is already enabled", signal: sharedInspectionLifetime.signal });
+		if (activeContext && !branchRestoration && isActive()) {
+			return Promise.resolve({ ok: true, message: "State Flow is already active", signal: sharedInspectionLifetime.signal });
 		}
 		const pending: NonNullable<typeof startActivation> = { controller: new AbortController() };
 		startActivation = pending;
@@ -854,16 +888,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			&& ctx.sessionManager.getHeader()?.timestamp === timestamp;
 		const superseded = (): StateFlowTelegramControlResult => {
 			pending.abort();
-			return { ok: false, message: "State Flow Start was superseded", signal: pending.signal };
+			return { ok: false, message: "State Flow activation was superseded", signal: pending.signal };
 		};
 		try {
 			if (!activeContext) await waitForRecovery(restoreActiveBranch(ctx, undefined, false, pending), signal);
 			else if (branchRestoration?.operation) await waitForRecovery(branchRestoration.operation, signal);
 			if (!isOwner()) return superseded();
-			if (snapshot.config.enabled) return { ok: true, message: "State Flow is already enabled", signal: sharedInspectionLifetime.signal };
+			if (isActive()) return { ok: true, message: "State Flow is already active", signal: sharedInspectionLifetime.signal };
 			if (forkInitialization) {
-				// Withdraw this join on cancellation without revoking the independently owned Stop.
-				const stopping = stopPersistence?.operation;
+				// Withdraw this join on cancellation without revoking the independently owned mode persistence.
+				const stopping = inactivePersistence?.operation;
 				if (stopping) await waitForRecovery(stopping, signal);
 				if (!isOwner()) return superseded();
 				await waitForRecovery(restoreActiveBranch(ctx, "fork", false, pending), signal);
@@ -873,7 +907,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			return activateCurrentState(ctx, pending);
 		} catch (error) {
 			if (!isOwner()) return superseded();
-			const message = conciseDiagnostic(`State Flow Start failed: ${diagnosticText(error)}`);
+			const message = conciseDiagnostic(`State Flow activation failed: ${diagnosticText(error)}`);
 			notifyProblem(ctx, message, "error");
 			return { ok: false, message, signal: AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]) };
 		}
@@ -885,22 +919,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const cwd = ctx.cwd;
 		const file = ctx.sessionManager.getSessionFile();
 		const timestamp = ctx.sessionManager.getHeader()?.timestamp;
-		const initiallyEnabled = snapshot.config.enabled;
+		const initiallyActive = isActive();
 		let accepted = false;
 		let receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
 		const isCurrent = () => startActivation?.controller === pending && runtime === selected && !shuttingDown
 			&& ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
-			&& ctx.sessionManager.getHeader()?.timestamp === timestamp && snapshot.config.enabled === (accepted || initiallyEnabled);
+			&& ctx.sessionManager.getHeader()?.timestamp === timestamp && isActive() === (accepted || initiallyActive);
 		const superseded = (): StateFlowTelegramControlResult => {
 			pending.abort();
-			return { ok: false, message: "State Flow Start was superseded", signal: pending.signal };
+			return { ok: false, message: "State Flow activation was superseded", signal: pending.signal };
 		};
 		try {
 			const activation = createRuntime(ctx);
 			const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
 			const result = await activation.withStartTransaction((current, publish) => {
 				signal.throwIfAborted();
-				if (!isCurrent()) throw new Error("State Flow Start selection changed while awaiting publication");
+				if (!isCurrent()) throw new Error("State Flow activation selection changed while awaiting publication");
 				if (!current && !branchStartsWithoutRuntime) throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
 				const continuation = passiveContinuation ?? bootstrapContinuation;
 				const bootstrap = hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined;
@@ -908,12 +942,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				const recoveredCurrent = selectedHistoryExpired;
 				const publication = publish(activated);
 				accepted = true;
-				cancelStopPersistence();
+				cancelInactivePersistence();
 				runtime = selected = activation;
 				snapshot = activated;
 				activeContext = ctx;
 				selectedHistoryExpired = false;
-				stopPersistenceError = undefined;
+				modePersistenceError = undefined;
 				installScopeStates();
 				clearRunTransient();
 				contextProjection.reset();
@@ -927,29 +961,42 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				appendCheckpoint();
 				ctx.ui.notify(
 					recoveredCurrent
-						? "State Flow enabled from current session memory; unavailable historical state was not restored."
+						? "State Flow active from current session memory; unavailable historical state was not restored."
 						: 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.",
+							? "State Flow active. The next complete agent run will migrate active context into state."
+							: "State Flow active. The next prompt starts a stateful agent run.",
 					"info",
 				);
-				return { ok: true, message: "State Flow enabled", signal: receipt };
+				return { ok: true, message: "State Flow active", signal: receipt };
 			}, signal, branchStartsWithoutRuntime);
 			return isCurrent() ? result : superseded();
 		} catch (error) {
 			if (!isCurrent()) return superseded();
-			const message = conciseDiagnostic(`${accepted ? "State Flow enabled; lifecycle update failed" : "State Flow Start failed"}: ${diagnosticText(error)}`);
+			const message = conciseDiagnostic(`${accepted ? "State Flow active; lifecycle update failed" : "State Flow activation failed"}: ${diagnosticText(error)}`);
 			notifyProblem(ctx, message, accepted ? "warning" : "error");
 			return { ok: accepted, message, signal: receipt };
 		}
 	}
 
-	pi.registerCommand("state-flow-start", {
-		description: "Start State Flow mode",
-		handler: async (_args, ctx) => {
-			await startStateFlow(ctx);
-		},
-	});
+	const MODE_COMMAND_DESCRIPTIONS: Record<StateFlowMode, string> = {
+		active: "Make State Flow active on the current session branch",
+		passive: "Use passive State Flow memory on the current session branch",
+		off: "Turn State Flow tools and context off on the current session branch",
+	};
+
+	/** Terminal commands and Telegram controls share these lifecycle owners. */
+	function selectMode(ctx: ExtensionContext, mode: StateFlowMode): Promise<StateFlowTelegramControlResult> {
+		return mode === "active" ? startStateFlow(ctx) : deactivateStateFlow(ctx, mode);
+	}
+
+	for (const mode of ["active", "passive", "off"] as const) {
+		pi.registerCommand(`state-flow-${mode}`, {
+			description: MODE_COMMAND_DESCRIPTIONS[mode],
+			handler: async (_args, ctx) => {
+				await selectMode(ctx, mode);
+			},
+		});
+	}
 
 	pi.registerCommand("state-flow-status", {
 		description: "Show State Flow runtime status",
@@ -958,97 +1005,135 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 	});
 
-	function stopStateFlow(ctx: ExtensionContext): Promise<StateFlowTelegramControlResult> {
+	/** Local policy, tools and UI change before any canonical wait. */
+	function applyInactiveMode(ctx: ExtensionContext, mode: InactiveMode): void {
+		snapshot = deactivateEpisode(snapshot, mode);
+		clearRunTransient();
+		syncStateFlowTools();
+		updateUi(ctx);
+	}
+
+	function deactivateStateFlow(ctx: ExtensionContext, mode: InactiveMode): Promise<StateFlowTelegramControlResult> {
 		cancelStartActivation();
 		if (shuttingDown) return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
-		if (stopPersistence?.operation) return stopPersistence.operation;
+		telegramStartPending = false;
+		const persisting = inactivePersistence;
+		if (persisting?.operation && !persisting.published) {
+			// Pending inactive choices coalesce: acceptance persists whichever inactive mode is current then.
+			if (snapshot.config.mode !== mode) applyInactiveMode(ctx, mode);
+			return persisting.operation;
+		}
 		if (!activeContext) void restoreActiveBranch(ctx, undefined, false);
 		const restoring = branchRestoration;
+		// Read-only recovery also retains the latest policy; its native write fence is updated below.
+		if (restoring) restoring.requestedMode = mode;
 		if (restoring?.awaitingAcceptance) {
-			// Stop changes policy without cancelling memory restoration or initialization.
-			restoring.passiveRequested = true;
-			snapshot = stopEpisode(snapshot);
-			clearRunTransient();
-			syncStateFlowTools();
-			updateUi(ctx);
-			return Promise.resolve({ ok: true, message: "State Flow disabled; memory restoration continues" });
+			// A mode change never cancels memory restoration or initialization.
+			applyInactiveMode(ctx, mode);
+			return Promise.resolve({ ok: true, message: `State Flow ${mode}; memory restoration continues` });
+		}
+		if (snapshot.config.mode === mode) {
+			const retained = selectRetainedCheckpoint(discoverSnapshotData(ctx.sessionManager.getBranch()).candidates, config.inactiveMode);
+			const recordedMode = retained.kind === "pre-runtime" ? retained.mode : retained.kind === "boundary" ? retained.checkpoint.mode : undefined;
+			if (modePersistenceError || recordedMode === mode) return Promise.resolve({ ok: true, message: `State Flow is already ${mode}` });
 		}
-		const pending: NonNullable<typeof stopPersistence> = { controller: new AbortController() };
-		stopPersistence = pending;
-		const operation = persistStoppedState(ctx, pending.controller);
+		cancelInactivePersistence();
+		const pending: NonNullable<typeof inactivePersistence> = { controller: new AbortController() };
+		inactivePersistence = pending;
+		const operation = persistInactiveMode(ctx, pending, mode);
 		pending.operation = operation;
-		const finished = () => { if (stopPersistence === pending) stopPersistence = undefined; };
+		const finished = () => { if (inactivePersistence === pending) inactivePersistence = undefined; };
 		void operation.then(finished, finished);
 		return operation;
 	}
 
-	async function persistStoppedState(ctx: ExtensionContext, pending: AbortController): Promise<StateFlowTelegramControlResult> {
-		telegramStartPending = false;
-		const selected = runtime;
+	async function persistInactiveMode(ctx: ExtensionContext, pending: NonNullable<typeof inactivePersistence>, mode: InactiveMode): Promise<StateFlowTelegramControlResult> {
+		let selected = runtime;
 		const owner = ctx.sessionManager.getSessionId();
 		const current = snapshot;
+		const wasActive = current.config.mode === "active";
 		let unfinished = current.meta.specification !== undefined
 			|| (inferencePreparation?.prompt !== undefined && !inferencePreparation.accepted);
-		snapshot = stopEpisode(current);
-		clearRunTransient();
-		syncStateFlowTools();
-		updateUi(ctx);
-		if (stopPersistenceError) return { ok: true, message: "State Flow disabled; memory writes remain paused" };
+		applyInactiveMode(ctx, mode);
 		const stoppedAt = Date.now();
+		if (modePersistenceError) {
+			// Writes stay paused; the native marker records only the newly selected inactive policy.
+			pending.published = true;
+			pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
+				at: passiveContinuation?.startedAt ?? stoppedAt,
+				...(passiveContinuation?.activeRunStartedAt === undefined ? {} : { from: passiveContinuation.activeRunStartedAt }),
+				preserveContext: true, owner, persistenceError: modePersistenceError, mode,
+			});
+			return { ok: true, message: `State Flow ${mode}; memory writes remain paused` };
+		}
 		const incomingBoundary = current.meta.bootstrap ? bootstrapContinuation : undefined;
 		const anchor = runAnchorTimestamp;
 		const idle = ctx.isIdle();
-		const isCurrent = () => stopPersistence?.controller === pending && runtime === selected
-			&& !shuttingDown && ctx.sessionManager.getSessionId() === owner && !snapshot.config.enabled;
-		const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow Stop was superseded" });
+		const isCurrent = () => inactivePersistence === pending && runtime === selected
+			&& !shuttingDown && ctx.sessionManager.getSessionId() === owner && !isActive();
+		const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow mode change was superseded" });
 		const freezeHandoff = (): PassiveContinuation | undefined => {
 			contextProjection.reset();
-			const handoff = (current.config.enabled || stopPersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
+			const handoff = (wasActive || modePersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
 				? createPassiveContinuation(
-					projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
+					projectModelState(effectiveState),
 					incomingBoundary?.startedAt ?? stoppedAt,
 					incomingBoundary ? incomingBoundary.activeRunStartedAt : !idle || unfinished ? anchor : undefined,
-					stopPersistenceError !== undefined || (incomingBoundary ? incomingBoundary.preserveContext : current.meta.bootstrap === true || (unfinished && anchor === undefined)),
+					modePersistenceError !== undefined || (incomingBoundary ? incomingBoundary.preserveContext : current.meta.bootstrap === true || (unfinished && anchor === undefined)),
 				)
 				: undefined;
-			passiveContinuation = handoff ?? (!current.config.enabled ? passiveContinuation : undefined);
+			// Off keeps the frozen boundary for a later Passive/Active choice but never projects it.
+			passiveContinuation = handoff ?? (!wasActive ? passiveContinuation : undefined);
 			return handoff;
 		};
 		const complete = (): StateFlowTelegramControlResult => {
+			pending.published = true;
 			const exitHandoff = freezeHandoff();
-			if (exitHandoff || stopPersistenceError) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
+			const selectedMode = snapshot.config.mode;
+			if (exitHandoff || modePersistenceError) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
 				at: exitHandoff?.startedAt ?? stoppedAt,
 				...(exitHandoff?.activeRunStartedAt === undefined ? {} : { from: exitHandoff.activeRunStartedAt }),
-				...(exitHandoff?.preserveContext || stopPersistenceError ? { preserveContext: true } : {}),
-				...(stopPersistenceError === undefined ? {} : { owner, persistenceError: stopPersistenceError }),
+				...(exitHandoff?.preserveContext || modePersistenceError ? { preserveContext: true } : {}),
+				...(modePersistenceError === undefined ? {} : { owner, persistenceError: modePersistenceError, mode: selectedMode }),
 			});
-			if (!stopPersistenceError) {
+			if (!modePersistenceError) {
 				appendCheckpoint();
-				return { ok: true, message: "State Flow disabled" };
+				return { ok: true, message: `State Flow ${selectedMode}` };
 			}
-			const message = conciseDiagnostic(`State Flow disabled; memory writes paused: ${stopPersistenceError}`);
+			const message = conciseDiagnostic(`State Flow ${selectedMode}; memory writes paused: ${modePersistenceError}`);
 			notifyProblem(ctx, message, "warning");
 			return { ok: true, message };
 		};
 		let accepted = false;
 		try {
-			unfinished ||= current.config.enabled && hasUncheckpointedConversation(ctx.sessionManager.getBranch());
+			unfinished ||= wasActive && hasUncheckpointedConversation(ctx.sessionManager.getBranch());
 			// Projection changes before any wait; capture the old run's boundary before later native input can replace it.
 			freezeHandoff();
 			bootstrapContinuation = undefined;
 			artifactInvalidations = [];
 			artifactReads.setCandidates([]);
 			assertPublicationAvailable();
-			if (branchStartsWithoutRuntime || !selected?.view) return complete();
-			const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
+			const signal = ctx.signal ? AbortSignal.any([pending.controller.signal, ctx.signal]) : pending.controller.signal;
+			if (branchStartsWithoutRuntime || !selected?.view) {
+				// A pre-runtime choice is native-only; Passive then loads shared memory without initializing storage.
+				const result = complete();
+				if (snapshot.config.mode !== "passive" || runtime?.view) return result;
+				const passive = await loadPassiveView(ctx, signal, isCurrent, true);
+				if (passive && isCurrent() && !signal.aborted && !runtime?.view) {
+					runtime = selected = passive;
+					installScopeStates();
+					updateUi(ctx);
+				}
+				return isCurrent() ? result : superseded();
+			}
 			const result = await selected.withLifecycleTransaction((publish) => {
 				signal.throwIfAborted();
-				if (!isCurrent()) throw new Error("State Flow Stop selection changed while awaiting publication");
+				if (!isCurrent()) throw new Error("State Flow mode selection changed while awaiting publication");
 				assertPublicationAvailable();
-				const stopped = stopEpisode(snapshot);
-				const publication = publish(stopped);
+				const next = structuredClone(snapshot);
+				const publication = publish(next);
 				accepted = true;
-				snapshot = stopped;
+				snapshot = next;
 				installScopeStates();
 				recordPolicyPublication(publication, ctx);
 				return complete();
@@ -1058,11 +1143,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			if (!isCurrent()) return superseded();
 			const cause = diagnosticText(error);
 			if (accepted) {
-				const message = conciseDiagnostic(`State Flow disabled; lifecycle update failed: ${cause}`);
+				const message = conciseDiagnostic(`State Flow ${snapshot.config.mode}; lifecycle update failed: ${cause}`);
 				notifyProblem(ctx, message, "warning");
 				return { ok: true, message };
 			}
-			stopPersistenceError = cause.trim() ? cause : "Canonical State Flow persistence failed";
+			modePersistenceError = cause.trim() ? cause : "Canonical State Flow persistence failed";
 			bootstrapContinuation = undefined;
 			artifactInvalidations = [];
 			artifactReads.setCandidates([]);
@@ -1070,18 +1155,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}
 	}
 
-	pi.registerCommand("state-flow-stop", {
-		description: "Stop State Flow on the current session branch",
-		handler: async (_args, ctx) => {
-			await stopStateFlow(ctx);
-		},
-	});
-
 	const telegram = createStateFlowTelegramAdapter({
 		...(options.telegram?.load === undefined ? {} : { load: options.telegram.load }),
 		port: {
 			snapshot: () => ({
-				enabled: snapshot.config.enabled,
+				mode: snapshot.config.mode,
 				step: snapshot.meta.step,
 				revisions: scopeRevisions(),
 				bootstrap: snapshot.meta.bootstrap === true,
@@ -1089,13 +1167,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			}),
 			inspect: inspectTelegramState,
 			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: async () => {
+			select: async (mode) => {
 				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
-				const operation = stopStateFlow(activeContext);
+				const operation = selectMode(activeContext, mode);
+				if (mode === "active") return operation;
+				// Inactive choices revoke older presentation at once; the receipt belongs to the new lifetime.
 				const signal = sharedInspectionLifetime.signal;
 				try {
 					return { ...await operation, signal };
@@ -1117,8 +1193,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.on("before_agent_start", (event) => {
 		// Native run identity is independent of semantic enablement and survives mode toggles.
 		runAnchorTimestamp = undefined;
-		if (!snapshot.config.enabled) {
-			if (!config.passiveBootstrap || !runtime?.view) return;
+		if (!isActive()) {
+			if (!passiveMemoryAvailable()) return;
 			(event.systemPromptOptions.sections ??= {}).state_flow = PASSIVE_MEMORY_PROTOCOL;
 			return;
 		}
@@ -1133,20 +1209,23 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 
 	pi.on("context_with_system", (event) => {
-		const protocol = snapshot.config.enabled ? stateFlowProtocol(snapshot.meta.bootstrap === true)
-			: config.passiveBootstrap && runtime?.view ? PASSIVE_MEMORY_PROTOCOL : undefined;
+		// Off removes the owned section, including one contributed before an in-flight mode change.
+		const protocol = isActive() ? stateFlowProtocol(snapshot.meta.bootstrap === true)
+			: passiveMemoryAvailable() ? PASSIVE_MEMORY_PROTOCOL : undefined;
 		return { messages: projectSystemProtocol(event.messages, protocol) };
 	});
 
 	function projectContext(messages: AgentMessage[]) {
+		// Off injects no State Flow context, including a retained passive handoff.
+		if (snapshot.config.mode === "off") return;
 		if (runtime?.view) refreshArtifactHints();
-		if (!snapshot.config.enabled && !passiveContinuation && (!config.passiveBootstrap || !runtime?.view)) return;
+		if (!isActive() && !passiveContinuation && !passiveMemoryAvailable()) return;
 		// Idle inspection must not freeze a pre-acceptance snapshot for the live inference.
-		const projection = snapshot.config.enabled && inferencePreparation && !inferencePreparation.accepted
+		const projection = isActive() && inferencePreparation && !inferencePreparation.accepted
 			? new ContextProjection() : contextProjection;
-		const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
+		const effective = effectiveState;
 		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
-		const phase = snapshot.config.enabled ? currentRehydrationPhase() : undefined;
+		const phase = isActive() ? currentRehydrationPhase() : undefined;
 		const view = contextView(effective, artifactHints, invalidations, phase);
 		if (passiveContinuation) {
 			const retained = passiveContinuationMessages(messages, passiveContinuation);
@@ -1154,7 +1233,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			return { messages: projection.project(retained.slice(1), view, () => passiveContinuation!.handoff,
 				{ state: passiveContinuation.state, lazy_navigation: view.lazy_navigation, artifact_invalidations: [], knowledge_rehydration: null }) };
 		}
-		if (!snapshot.config.enabled) {
+		if (!isActive()) {
 			return { messages: projection.project(messages, view, () => syntheticUser(
 				`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state: view.state, lazy_navigation: view.lazy_navigation })}`)) };
 		}
@@ -1171,19 +1250,19 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const selected = runtime;
 		const operationSignal = ctx.signal;
 		// Idle projections remain observational; only a live native operation may await preparation.
-		if (!snapshot.config.enabled || !pending || !operationSignal || shuttingDown) return projectContext(messages);
+		if (!isActive() || !pending || !operationSignal || shuttingDown) return projectContext(messages);
 		pending.operation ??= prepareInference(pending, selected, ctx, operationSignal).finally(() => {
 			// A late withdrawal must not clear newer work; accepted lifecycle is never replayed after an error.
 			if (!pending.accepted && inferencePreparation === pending) pending.operation = undefined;
 		});
 		return pending.operation.then(() => {
 			if (shuttingDown || operationSignal.aborted || runtime !== selected || ctx.signal !== operationSignal) return;
-			if (snapshot.config.enabled && inferencePreparation !== pending) {
+			if (isActive() && inferencePreparation !== pending) {
 				// Start may require same-run maintenance. A new captured user prompt instead owns a different context request.
 				if (inferencePreparation?.prompt === undefined) return prepareContext(messages, ctx);
 				return;
 			}
-			if (snapshot.config.enabled && !pending.accepted) return;
+			if (isActive() && !pending.accepted) return;
 			return projectContext(messages);
 		});
 	}
@@ -1191,7 +1270,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.on("context", (event, ctx) => prepareContext(event.messages as AgentMessage[], ctx));
 
 	pi.on("tool_execution_start", (event) => {
-		if (!snapshot.config.enabled) return;
+		if (!isActive()) return;
 		// Pi emits this before tool_call. Keep the argument object as a fallback;
 		// tool_call replaces it with the mutable, post-preflight input reference.
 		skillReads.recordStart(event.toolCallId, event.toolName, event.args);
@@ -1199,21 +1278,19 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 
 	pi.on("tool_call", (event, ctx) => {
-		if (!snapshot.config.enabled) return;
+		if (!isActive()) return;
 		const batch = findAssistantToolBatch(ctx.sessionManager, event.toolCallId);
 		const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
 		if (patchCalls > 0) {
 			if (patchCalls !== 1) {
-				return {
-					block: true,
-					reason: "A State Flow barrier response must contain exactly one patch_state call",
-				};
+				const reason = "A State Flow barrier response must contain exactly one patch_state call";
+				recordDiagnostic(reason, "barrier-block", ctx, { tool: event.toolName, toolCallId: event.toolCallId, batchToolNames: batch });
+				return { block: true, reason };
 			}
 			if (event.toolName !== PATCH_STATE_TOOL_NAME) {
-				return {
-					block: true,
-					reason: "Blocked by the patch_state barrier; reconsider this action after State Flow rematerializes context",
-				};
+				const reason = "Blocked by the patch_state barrier; reconsider this action after State Flow rematerializes context";
+				recordDiagnostic(reason, "barrier-block", ctx, { tool: event.toolName, toolCallId: event.toolCallId, batchToolNames: batch });
+				return { block: true, reason };
 			}
 		}
 		skillReads.recordCall(event.toolCallId, event.toolName, event.input);
@@ -1221,14 +1298,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 
 	pi.on("tool_execution_end", (event) => {
-		if (!snapshot.config.enabled) return;
+		if (!isActive()) return;
 		skillReads.recordEnd(event.toolCallId, event.toolName, event.isError);
 		dropCurrentSkillReads();
 		artifactReads.recordEnd(event.toolCallId, event.toolName, event.isError);
 	});
 
 	pi.on("tool_result", (event) => {
-		if (!snapshot.config.enabled) return;
+		if (!isActive()) return;
 		const read = skillReads.recordResult(event.toolName, event.input, event.isError);
 		if (!read) return;
 		dropCurrentSkillReads();
@@ -1240,7 +1317,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.on("message_end", (event, ctx): any => {
 		// Observe actual user events even while disabled; Start/Stop cannot invent or erase them.
 		if (event.message.role === "user" && runAnchorTimestamp === undefined) runAnchorTimestamp = event.message.timestamp;
-		if (shuttingDown || !snapshot.config.enabled) return;
+		if (shuttingDown || !isActive()) return;
 		if (event.message.role !== "assistant") return;
 		cancelResponseReconciliation();
 		const message = event.message as unknown as { role: "assistant"; stopReason?: string; content?: unknown };
@@ -1255,7 +1332,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.on("turn_end", async (event, ctx) => {
 		if (shuttingDown) return;
 		const pending = responseReconciliation;
-		if (!snapshot.config.enabled || !pending) {
+		if (!isActive() || !pending) {
 			updateUi(ctx);
 			return;
 		}
@@ -1267,7 +1344,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			if (!selected?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
 			await selected.withPatchTransaction((transaction) => {
 				signal.throwIfAborted();
-				if (runtime !== selected || responseReconciliation !== pending || !snapshot.config.enabled) {
+				if (runtime !== selected || responseReconciliation !== pending || !isActive()) {
 					throw new Error("State Flow response selection changed while awaiting publication");
 				}
 				assertPublicationAvailable();
@@ -1353,12 +1430,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {
-		if (telegramStartPending && !snapshot.config.enabled) {
+		if (telegramStartPending && !isActive()) {
 			telegramStartPending = false;
 			await startStateFlow(ctx);
 			return;
 		}
-		if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap
+		if (!completedRunAccepted || compactionStopped || !isActive() || snapshot.meta.bootstrap
 			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !runtime?.view
 			|| !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
 		completedRunAccepted = false;
@@ -1392,7 +1469,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		contextProjection.reset();
 		const restoring = cancelBranchRestoration();
 		const starting = cancelStartActivation();
-		const stopping = cancelStopPersistence();
+		const stopping = cancelInactivePersistence();
 		backupLifetime.abort();
 		cancelInferencePreparation();
 		cancelResponseReconciliation();