@llblab/pi-kit 0.25.0 → 0.27.0

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

@@ -3,18 +3,11 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
-import { ArtifactReadTracker } from "./acquisition.ts";
-import {
-  classifyArtifactCompilationNeed,
-  inspectRegisteredArtifactPaths,
-  ORDINARY_ARTIFACT_COMPILER,
-  sameArtifactSourceFingerprint,
-  type ArtifactInvalidationRequest,
-} from "./artifact.ts";
-import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
+import { ArtifactAcquisitionState, missingArtifactRemovals } from "./acquisition.ts";
+import { inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint } from "./artifact.ts";
+import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, StateFlowCompactionRequests } from "./compaction.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";
@@ -25,19 +18,20 @@ import {
   type SessionAddress,
 } from "./durable.ts";
 import { completeRun, deactivateEpisode, prepareRun, resumeEpisode, startEpisode } from "./episode.ts";
-import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.ts";
+import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, SettledTurnBackup, startStateFlowBackupPush } from "./git.ts";
 import { projectRecentTransitionsWithLimit } from "./history.ts";
-import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
+import { isObject, presentationJson, sameJson } from "./json.ts";
 import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
 import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.ts";
+import { OwnedOperationSlot, RenewableLifetime, type OwnedOperation } from "./operation.ts";
 import { readProjectedState, readStatePath } from "./query.ts";
 import { selectedBoundaryFailure, selectRetainedCheckpoint, waitForRecovery } from "./recovery.ts";
 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 { discoverSnapshotData, findAssistantToolBatch, findBranchPolicy, findPassiveStopBoundary, hasPendingFork, hasPriorConversation, hasUncheckpointedConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
 import { hasCompiledSkillArtifact, hashSkillSource, registeredSkillResolver, SkillReadTracker, type SuccessfulSkillRead } from "./skills.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 { HistoryBoundaryExpiredError, emptySnapshot, migrationFailure, preRuntimeCheckpoint, type InactiveMode, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
+import { emptyState, projectStateForModel, type AtomicScopePatches, type SemanticState, type ModelState, 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";
@@ -59,14 +53,14 @@ export const PATCH_STATE_TOOL_NAME = "patch_state";
 export const READ_STATE_TOOL_NAME = "read_state";
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 
-interface InferencePreparation {
+interface InferencePreparation extends OwnedOperation {
 	readonly controller: AbortController;
 	readonly prompt?: string;
 	accepted?: boolean;
 	operation?: Promise<void>;
 }
 
-interface BranchRestoration {
+interface BranchRestoration extends OwnedOperation {
 	readonly controller: AbortController;
 	/** Memory acceptance is independent of the requested session mode. */
 	awaitingAcceptance: boolean;
@@ -74,6 +68,15 @@ interface BranchRestoration {
 	operation?: Promise<void>;
 }
 
+interface ModeOperation extends OwnedOperation {
+	operation?: Promise<StateFlowTelegramControlResult>;
+}
+
+interface InactivePersistence extends ModeOperation {
+	/** The native mode marker is recorded; later inactive choices start a new persistence. */
+	published?: boolean;
+}
+
 type BranchSelection =
 	| { kind: "settled" }
 	| { kind: "current"; mode: InactiveMode }
@@ -93,47 +96,49 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let selectedHistoryExpired = false;
 	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;
+	const inactivePersistence = new OwnedOperationSlot<InactivePersistence>();
+	const startActivation = new OwnedOperationSlot<ModeOperation>();
 	let forkInitialization = false;
-	let branchRestoration: BranchRestoration | undefined;
-	const restorationOperations = new Set<Promise<void>>();
-	let responseReconciliation: AbortController | undefined;
-	let sharedInspectionLifetime = new AbortController();
+	const branchRestoration = new OwnedOperationSlot<BranchRestoration>();
+	let deferredBranch: { reason: unknown; owner: string; cwd: string } | undefined;
+	const responseReconciliation = new OwnedOperationSlot<OwnedOperation>();
+	const sharedInspectionLifetime = new RenewableLifetime();
+	const memoryToolLifetime = new RenewableLifetime();
 	let completedRunAccepted = false;
-	let turnAcceptedForBackup = false;
-	let compactionPlan: StateFlowCompactionPlan | undefined;
-	let compactionInFlight = false;
-	let compactionStopped = false;
-	const compactionMarker = `state-flow-boundary:${randomUUID()}`;
+	const compactionRequests = new StateFlowCompactionRequests();
 	let passiveContinuation: PassiveContinuation | undefined;
 	let bootstrapContinuation: PassiveContinuation | undefined;
 	const contextProjection = new ContextProjection();
-	let inferencePreparation: InferencePreparation | undefined;
+	const inferencePreparation = new OwnedOperationSlot<InferencePreparation>();
 	let runAnchorTimestamp: number | undefined;
 	let runtime: TemporalRuntime | undefined;
 	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) => notifyActiveContext(message));
-	let backupPending = false;
-	const backupLifetime = new AbortController();
-	const backupOperations = new Set<Promise<string | undefined>>();
+	const backup = new SettledTurnBackup();
 	let shuttingDown = false;
-	let pushFailureNotified = false;
 	const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
 		? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
 		: undefined);
-	const artifactReads = new ArtifactReadTracker();
-	let artifactInvalidations: ArtifactInvalidationRequest[] = [];
-	let artifactHints: Record<string, string> = {};
-	const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
+	const acquisition = new ArtifactAcquisitionState();
+	const artifactReads = acquisition.reads;
 	let telegramStartPending = false;
 
 	function sessionAddress(ctx: ExtensionContext): SessionAddress {
 		return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
 	}
 
+	/** Native session identity captured before an await; any change supersedes the waiting operation. */
+	function sessionIdentity(ctx: ExtensionContext): () => boolean {
+		const cwd = ctx.cwd;
+		const owner = ctx.sessionManager.getSessionId();
+		const file = ctx.sessionManager.getSessionFile();
+		const timestamp = ctx.sessionManager.getHeader()?.timestamp;
+		return () => ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
+			&& ctx.sessionManager.getHeader()?.timestamp === timestamp;
+	}
+
 	function notifyProblem(ctx: ExtensionContext, message: string, level: "warning" | "error"): void {
 		ctx.ui.notify(conciseDiagnostic(message), level);
 	}
@@ -151,7 +156,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	}
 
 	function projectModelState(state: SemanticState): SemanticState {
-		return projectStateForModel(state, artifactHints);
+		return projectStateForModel(state, acquisition.hints);
 	}
 
 	function assertSelectedBranchAvailable(): void {
@@ -199,109 +204,32 @@ 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 cancelInactivePersistence(): Promise<StateFlowTelegramControlResult> | undefined {
-		const pending = inactivePersistence;
-		pending?.controller.abort();
-		inactivePersistence = undefined;
-		return pending?.operation;
-	}
-
-	function cancelStartActivation(): Promise<StateFlowTelegramControlResult> | undefined {
-		const pending = startActivation;
-		pending?.controller.abort();
-		startActivation = undefined;
-		return pending?.operation;
-	}
-
-	function cancelBranchRestoration(): Promise<void> | undefined {
-		const pending = branchRestoration;
-		pending?.controller.abort();
-		branchRestoration = undefined;
-		return pending?.operation;
-	}
-
-	function cancelResponseReconciliation(): void {
-		responseReconciliation?.abort();
-		responseReconciliation = undefined;
-	}
-
 	function cancelSharedInspections(): void {
-		sharedInspectionLifetime.abort(new Error("State Flow inspection was cancelled; select the scope again"));
-		sharedInspectionLifetime = new AbortController();
-	}
-
-	function cancelInferencePreparation(): void {
-		inferencePreparation?.controller.abort();
-		inferencePreparation = undefined;
+		sharedInspectionLifetime.renew(new Error("State Flow inspection was cancelled; select the scope again"));
 	}
 
 	function clearRunTransient(): void {
-		cancelInferencePreparation();
-		cancelResponseReconciliation();
+		inferencePreparation.cancel();
+		responseReconciliation.cancel();
 		cancelSharedInspections();
 		completedRunAccepted = false;
-		turnAcceptedForBackup = false;
-		compactionPlan = undefined;
-		compactionInFlight = false;
+		backup.clearTurn();
+		compactionRequests.clear();
 		skillReads.clear();
 		artifactReads.clear();
 	}
 
 	function deferInferencePreparation(prompt?: string): void {
-		cancelInferencePreparation();
-		inferencePreparation = { controller: new AbortController(), prompt };
-		artifactInvalidations = [];
-		artifactReads.setCandidates([]);
+		inferencePreparation.cancel();
+		inferencePreparation.claim({ controller: new AbortController(), prompt });
+		acquisition.clearInvalidations();
 	}
 
 	function refreshArtifactHints(): void {
-		if (!runtime?.view) {
-			artifactHints = {};
-			artifactInvalidations = [];
-			artifactReads.setCandidates([]);
-			return;
-		}
-		const paths = new Set<string>();
-		for (const scope of ["global", "cwd", "session"] as const) for (const path of Object.keys(scopeStates[scope].artifacts)) paths.add(path);
-		const observations = new Map(inspectRegisteredArtifactPaths(paths).map((observation) => [observation.path, observation]));
-		const nextHints: Record<string, string> = {};
-		const nextInvalidations = new Map<string, ArtifactInvalidationRequest>();
-		for (const scope of ["global", "cwd", "session"] as const) {
-			const provenance = runtime.artifactProvenance(scope);
-			for (const [path, metadata] of Object.entries(scopeStates[scope].artifacts)) {
-				delete nextHints[path];
-				nextInvalidations.delete(path);
-				if (metadata.kind === "skill") continue;
-				const observed = observations.get(path);
-				if (observed?.kind !== "present") continue;
-				const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, provenance[path]);
-				if (need.kind !== "requires-compilation") continue;
-				if (need.reason === "source-changed") nextHints[path] = SOURCE_CHANGED_HINT;
-				nextInvalidations.set(path, { path, scope, reason: need.reason });
-			}
-		}
-		artifactHints = nextHints;
-		artifactInvalidations = [...nextInvalidations.values()].sort((left, right) => left.path.localeCompare(right.path));
-		artifactReads.setCandidates(artifactInvalidations);
+		if (runtime?.view) acquisition.refresh(scopeStates, (scope) => runtime!.artifactProvenance(scope));
+		else acquisition.reset();
 	}
 
-	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 ?? {})) {
-			owners.set(path, [...owners.get(path) ?? [], scope]);
-		}
-		const removals: AtomicScopePatches = {};
-		for (const observation of inspectRegisteredArtifactPaths(owners.keys())) {
-			if (observation.kind !== "missing") continue;
-			for (const scope of owners.get(observation.path) ?? []) {
-				const artifacts = (removals[scope]?.artifacts ?? {}) as JsonObject;
-				removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
-			}
-		}
-		return removals;
-	}
-
-
 	function installScopeStates(): void {
 		scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
 		effectiveState = runtime?.view ? runtime.readView() : {};
@@ -319,17 +247,28 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	async function inspectTelegramState(scope: StateFlowTelegramScope): Promise<StateFlowTelegramInspection> {
 		if (!activeContext || shuttingDown) throw new Error("State Flow is not attached to an active session yet");
-		if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
-		const selected = runtime ??= createRuntime(activeContext);
+		const ctx = activeContext;
+		const owner = sessionAddress(ctx).key;
+		const cwd = ctx.cwd;
+		const off = snapshot.config.mode === "off";
+		const privateScope = scope === "session" || scope === "effective";
+		if (!off && privateScope) assertSelectedBranchAvailable();
+		// Off operator reads are disposable: they confer no selected-branch/cache authority.
+		const selected = off ? createRuntime(ctx) : runtime ??= createRuntime(ctx);
 		const signal = sharedInspectionLifetime.signal;
-		if (!selected.view || (scope !== "session" && !modePersistenceError)) await selected.refreshShared(signal);
+		let privateAvailable = true;
+		if (off && privateScope) privateAvailable = await selected.refreshCurrentMemory(signal) !== undefined;
+		else 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 (activeContext !== ctx || ctx.cwd !== cwd || sessionAddress(ctx).key !== owner || (!off && runtime !== selected)) {
+			throw new Error("State Flow inspection selection changed; select the scope again");
+		}
+		if (!privateAvailable) throw new Error("Current State Flow session memory is unavailable");
+		if (!off && privateScope) assertSelectedBranchAvailable();
 		if (!selected.view) throw new Error("State Flow temporal runtime is unavailable");
-		installScopeStates();
-		const state = scope === "effective" ? effectiveState : selected.readView(0, scope);
-		return { state: { ...projectModelState(state), ...(state.lazy === undefined ? {} : { lazy: structuredClone(state.lazy) }) }, revisions: scopeRevisions(), signal };
+		if (!off) installScopeStates();
+		const state = selected.readView(0, scope === "effective" ? undefined : scope);
+		return { state: { ...projectModelState(state), ...(state.lazy === undefined ? {} : { lazy: structuredClone(state.lazy) }) }, revisions: temporalScopeRevisions(selected.view), signal };
 	}
 
 	function syncStateFlowTools(): void {
@@ -342,15 +281,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			: active.filter((name) => !owned.includes(name)));
 	}
 
-	function recordPublication(_publication: RuntimePublication, _ctx: ExtensionContext): void {
+	/** Accepted canonical publication establishes runtime authority and makes the settled-turn Git backup due. */
+	function recordPublication(): void {
 		// A passive view is not runtime authority; only accepted canonical publication establishes it.
 		branchStartsWithoutRuntime = false;
-		backupPending = true;
-	}
-
-	/** Record accepted lifecycle persistence; Git backup is scheduled only after an accepted turn settles. */
-	function recordPolicyPublication(publication: RuntimePublication | undefined, ctx: ExtensionContext): void {
-		if (publication) recordPublication(publication, ctx);
+		backup.markPublished();
 	}
 
 	function skillReadIsCurrent(read: SuccessfulSkillRead): boolean {
@@ -374,11 +309,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		return `State Flow acquisition: this registered Skill belongs at ${target}. If durable compiled guidance is useful, include a non-empty description, kind:"skill", and compilation object there. Unrelated semantic patches do not need to include it.`;
 	}
 
-	function clearAcceptedAcquisitions(acquiredArtifactPaths = new Set(artifactReads.successful.keys())): void {
-		artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
-		artifactReads.setCandidates(artifactInvalidations);
+	function clearAcceptedAcquisitions(acquiredArtifactPaths?: ReadonlySet<string>): void {
+		acquisition.acceptAcquired(acquiredArtifactPaths);
 		dropCurrentSkillReads();
-		artifactReads.clear();
 	}
 
 	async function prepareInference(pending: InferencePreparation, selected: TemporalRuntime | undefined, ctx: ExtensionContext, operationSignal: AbortSignal): Promise<void> {
@@ -387,7 +320,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 || !isActive() || shuttingDown) {
+				if (runtime !== selected || !inferencePreparation.owns(pending) || !isActive() || shuttingDown) {
 					throw new Error("State Flow inference selection changed while awaiting publication");
 				}
 				assertPublicationAvailable();
@@ -410,13 +343,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				snapshot = nextSnapshot;
 				installScopeStates();
 				if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap") rehydrationPhase = "step";
-				if (publication?.changed) recordPublication(publication, ctx);
+				if (publication?.changed) recordPublication();
 				if (pending.prompt !== undefined || publication?.changed) appendCheckpoint();
 				if (Object.keys(removals).length > 0) clearAcceptedAcquisitions();
 				updateUi(ctx);
 			}, signal);
 		} catch (error) {
-			if (signal.aborted || runtime !== selected || inferencePreparation !== pending || shuttingDown) return;
+			if (signal.aborted || runtime !== selected || !inferencePreparation.owns(pending) || shuttingDown) return;
 			// Pi reports context-hook exceptions and continues. Abort through its public port rather than infer from stale preparation.
 			ctx.abort();
 			const cause = diagnosticText(error);
@@ -428,27 +361,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	}
 
 
-	function currentRehydrationPhase(): RehydrationPhase | undefined {
-		return rehydrationPhase;
-	}
-
 	function statusDiagnostics(ctx: ExtensionContext): StatusDiagnostics {
 		const cwd = ctx.cwd;
-		const diagnosticStates = scopeStates;
 		const view = runtime?.view;
 		const diagnosticRecent = runtime?.recent() ?? [];
 		const durableStateError = snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error
 			: view ? undefined : "no temporal runtime is selected on this branch";
 
 		const staleArtifacts: StatusDiagnostics["staleArtifacts"] = durableStateError === undefined
-			? artifactInvalidations.map(({ path, scope, reason }) => ({ scope: scope ?? "global", path, reason }))
+			? acquisition.invalidations.map(({ path, scope, reason }) => ({ scope: scope ?? "global", path, reason }))
 			: [];
 		const session = sessionAddress(ctx);
 		return {
 			repositoryRoot,
 			cwdScopeKey: cwdScopeKey(cwd),
 			sessionScopeKey: sessionScopeKey(session.key),
-			scopeStates: diagnosticStates,
+			scopeStates,
 			effectiveState,
 			recent: diagnosticRecent,
 			historyLimit: config.historyLimit,
@@ -473,21 +401,66 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	}
 
 	/** Select the active native branch under one owned restoration lifetime; only current accepted work installs memory. */
-	function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown, notifyRecovery = true, startOwner?: AbortController): Promise<void> {
+	function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown, notifyRecovery = true, startOwner?: AbortController, requestedMode?: InactiveMode): Promise<void> {
 		contextProjection.reset();
-		cancelBranchRestoration();
+		memoryToolLifetime.renew();
+		branchRestoration.cancel();
 		// Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
 		if (!startOwner) {
-			cancelStartActivation();
-			cancelInactivePersistence();
+			startActivation.cancel();
+			inactivePersistence.cancel();
 		}
 		clearRunTransient();
 		passiveContinuation = undefined;
 		bootstrapContinuation = undefined;
-		artifactInvalidations = [];
-		artifactReads.setCandidates([]);
+		acquisition.clearInvalidations();
 		telegramStartPending = false;
 		activeContext = ctx;
+		if (!startOwner) {
+			let mode: StateFlowMode = config.inactiveMode;
+			let adoptDefault = false;
+			let withoutRuntime = false;
+			let persistenceError: string | undefined;
+			let pendingFork = false;
+			try {
+				const branch = ctx.sessionManager.getBranch();
+				const discovery = discoverSnapshotData(branch);
+				withoutRuntime = discovery.candidates.length === 0 && discovery.errors.length === 0;
+				adoptDefault = withoutRuntime && isNewSession(sessionStartReason, branch);
+				pendingFork = hasPendingFork(branch, ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
+				const inherited = sessionStartReason === "fork" || pendingFork;
+				const policy = findBranchPolicy(branch, inherited ? undefined : ctx.sessionManager.getSessionId(),
+					inherited || retainsPhysicalSessionProjection(sessionStartReason) ? PASSIVE_STOP_ENTRY_TYPE : undefined, config.inactiveMode);
+				mode = policy?.mode ?? (adoptDefault ? config.mode : config.inactiveMode);
+				persistenceError = inherited
+					? findBranchPolicy(branch, ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE, config.inactiveMode)?.persistenceError
+					: policy?.persistenceError;
+			} catch {
+				// Off needs only policy; unavailable native evidence grants no memory authority.
+			}
+			if (mode === "off") {
+				backup.cancel();
+				const owner = sessionAddress(ctx).key;
+				const reason = pendingFork || (deferredBranch?.owner === owner && deferredBranch.cwd === ctx.cwd && deferredBranch.reason === "fork"
+					&& retainsPhysicalSessionProjection(sessionStartReason)) ? "fork" : sessionStartReason;
+				if (reason === "fork" && !pendingFork) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { owner: ctx.sessionManager.getSessionId(), forkPending: true });
+				deferredBranch = { reason, owner, cwd: ctx.cwd };
+				runtime = undefined;
+				snapshot = emptySnapshot("off");
+				branchStartsWithoutRuntime = withoutRuntime;
+				selectedHistoryExpired = false;
+				modePersistenceError = persistenceError;
+				forkInitialization = reason === "fork";
+				installScopeStates();
+				acquisition.reset();
+				if (adoptDefault) appendCheckpoint();
+				syncStateFlowTools();
+				updateUi(ctx);
+				return Promise.resolve();
+			}
+			if (pendingFork) sessionStartReason = "fork";
+		}
+		deferredBranch = undefined;
 		runtime = createRuntime(ctx);
 		installScopeStates();
 		branchStartsWithoutRuntime = false;
@@ -548,17 +521,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			snapshot = migrationFailure({}, "State Flow branch restoration is pending", selection.kind === "current" ? selection.mode
 				: selection.kind === "auto-start" ? config.inactiveMode : inactiveSelection(selection.checkpoint.mode));
 		}
+		if (requestedMode) snapshot = deactivateEpisode(snapshot, requestedMode);
 		const pending: BranchRestoration = {
 			controller: new AbortController(),
 			awaitingAcceptance: selection.kind !== "settled" && selection.kind !== "current",
+			...(requestedMode === undefined ? {} : { requestedMode }),
 		};
-		branchRestoration = pending;
-		const operation = attachBranch(ctx, pending, selection, sessionStartReason, notifyRecovery, skipped);
-		pending.operation = operation;
-		restorationOperations.add(operation);
-		const finished = () => { restorationOperations.delete(operation); };
-		void operation.then(finished, finished);
-		return operation;
+		branchRestoration.claim(pending);
+		// attachBranch releases its own ownership; settlement only drains it for shutdown.
+		return branchRestoration.track(pending, attachBranch(ctx, pending, selection, sessionStartReason, notifyRecovery, skipped), false);
 	}
 
 	async function attachBranch(
@@ -568,26 +539,23 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const placeholder = runtime;
 		let selected = runtime;
 		const owner = ctx.sessionManager.getSessionId();
-		const cwd = ctx.cwd;
-		const file = ctx.sessionManager.getSessionFile();
-		const timestamp = ctx.sessionManager.getHeader()?.timestamp;
+		const sameSession = sessionIdentity(ctx);
 		const signal = AbortSignal.any([pending.controller.signal, ...(ctx.signal ? [ctx.signal] : [])]);
-		const isCurrent = () => branchRestoration === pending && !pending.controller.signal.aborted && !shuttingDown && runtime === selected
-			&& ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
-			&& ctx.sessionManager.getHeader()?.timestamp === timestamp;
+		const isCurrent = () => branchRestoration.owns(pending) && !pending.controller.signal.aborted && !shuttingDown && runtime === selected
+			&& sameSession();
 		const assertCurrent = () => {
 			signal.throwIfAborted();
 			if (!isCurrent()) throw new Error("State Flow branch selection changed while awaiting publication");
 		};
 		let accepted = false;
 		// Install accepted memory before native writes; later ancillary failures cannot revert or replay it.
-		const accept = (candidate: TemporalRuntime, next: Snapshot, publication: RuntimePublication, nativeWrites: () => void): void => {
+		const accept = (candidate: TemporalRuntime, next: Snapshot, nativeWrites: () => void): void => {
 			accepted = true;
 			pending.awaitingAcceptance = false;
 			runtime = selected = candidate;
 			snapshot = next;
 			installScopeStates();
-			recordPolicyPublication(publication, ctx);
+			recordPublication();
 			let failure: unknown;
 			try { nativeWrites(); } catch (error) { failure = error; }
 			settleSelection(ctx, reason, notifyRecovery, skipped, true);
@@ -614,16 +582,17 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 							if (restored.config.mode === "active" && restored.meta.specification === undefined
 								&& retainsPhysicalSessionProjection(reason) && hasUncheckpointedConversation(ctx.sessionManager.getBranch())) restored.meta.bootstrap = true;
 							const next = pending.requestedMode ? deactivateEpisode(restored, pending.requestedMode) : restored;
-							accept(candidate, next, publish(next), appendCheckpoint);
+							publish(next);
+							accept(candidate, 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.requestedMode ? deactivateEpisode(child, pending.requestedMode) : child;
-							const publication = publish(next);
+							publish(next);
 							forkInitialization = false;
-							accept(candidate, next, publication, () => {
+							accept(candidate, next, () => {
 								pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner });
 								appendCheckpoint();
 							});
@@ -637,7 +606,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 							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.requestedMode ? deactivateEpisode(activated, pending.requestedMode) : activated;
-							accept(candidate, next, publish(next), appendCheckpoint);
+							publish(next);
+							accept(candidate, next, appendCheckpoint);
 						}, signal, true);
 					}
 				} catch (error) {
@@ -671,7 +641,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			installScopeStates();
 		} finally {
 			pending.awaitingAcceptance = false;
-			if (branchRestoration === pending) branchRestoration = undefined;
+			branchRestoration.release(pending);
 		}
 	}
 
@@ -687,25 +657,24 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		return passive;
 	}
 
+	function selectedContinuation(ctx: ExtensionContext, reason: unknown): PassiveContinuation | undefined {
+		if (!retainsPhysicalSessionProjection(reason) || !runtime?.view) return undefined;
+		const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
+		return boundary === undefined ? undefined : createPassiveContinuation(
+			projectModelState(effectiveState), boundary.at, boundary.from, boundary.preserveContext,
+		);
+	}
+
 	function settleSelection(ctx: ExtensionContext, reason: unknown, notifyRecovery: boolean, skipped: number, selectedMemory: boolean): void {
 		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(effectiveState),
-					boundary.at,
-					boundary.from,
-					boundary.preserveContext,
-				);
-				// 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;
-			}
+		const continuation = selectedMemory ? selectedContinuation(ctx, reason) : undefined;
+		if (continuation !== undefined) {
+			if (!isActive()) passiveContinuation = continuation;
+			else if (snapshot.meta.bootstrap) bootstrapContinuation = continuation;
 		}
 		if (notifyRecovery && isActive() && skipped > 0) {
 			notifyProblem(ctx, `State Flow skipped ${skipped} malformed snapshot(s); restored the last valid one.`, "warning");
@@ -722,7 +691,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.registerTool({
 		name: READ_STATE_TOOL_NAME,
 		label: "Read State",
-		description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary.",
+		description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary. Path object keys must be ASCII identifiers ([A-Za-z_$][A-Za-z0-9_$-]*); non-ASCII keys cannot be addressed.",
 		promptSnippet: "Read exact state values, structures, or historical semantic patches",
 		parameters: Type.Object({
 			path: Type.Optional(Type.String({ description: "One semantic path; unscoped paths use effective, explicit roots may use effective/global/cwd/session and historical [N], and arrays support half-open [start..end] ranges" })),
@@ -764,7 +733,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	pi.registerTool({
 		name: PATCH_STATE_TOOL_NAME,
 		label: "Patch State",
-		description: "The sole State Flow semantic mutation protocol. Supply one or more global, cwd, or session patches; all supplied scopes commit atomically. This call must be the only State Flow barrier in its assistant response.",
+		description: "The sole State Flow semantic mutation protocol. Supply one or more global, cwd, or session patches; all supplied scopes commit atomically. This call must be the only State Flow barrier in its assistant response. Deleting an intent also deletes same-scope working/lazy keys its {\"$ref\"} values own unless another intent refs them. Name keys in ASCII ([A-Za-z_$][A-Za-z0-9_$-]*) so read paths and refs resolve; values may use any language.",
 		promptSnippet: "Atomically patch one or more global/cwd/session scopes",
 		promptGuidelines: [
 			"Use patch_state only for material durable semantic changes; ordinary answers need no finalization call.",
@@ -784,6 +753,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			return new Text(separatedOutput(theme.fg("dim", formatPatchStateArguments(context.args))), 0, 0);
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			signal = signal ? AbortSignal.any([signal, memoryToolLifetime.signal]) : memoryToolLifetime.signal;
 			try {
 				if (!memoryToolsAvailable()) throw new Error("State Flow tools are off for this session");
 				assertPublicationAvailable();
@@ -832,12 +802,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					snapshot = nextSnapshot;
 					installScopeStates();
 					if (publication?.changed) {
-						recordPublication(publication, ctx);
+						recordPublication();
 						appendCheckpoint();
 					}
 					clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
 					updateUi(ctx);
-					const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, artifactHints);
+					const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, acquisition.hints);
 					const acknowledgement = changed
 						? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
 						: "\nState already current.";
@@ -850,7 +820,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				let attempted: unknown;
 				try { attempted = structuredClone(params); } catch { attempted = undefined; }
 				const cause = diagnosticText(error);
-				recordDiagnostic(cause, /concurrently|advanced/.test(cause) ? "publication-conflict" : "invalid-patch", ctx, {
+				if (!signal.aborted && memoryToolsAvailable()) recordDiagnostic(cause, /concurrently|advanced/.test(cause) ? "publication-conflict" : "invalid-patch", ctx, {
 					input: attempted,
 					tool: PATCH_STATE_TOOL_NAME,
 					toolCallId,
@@ -862,42 +832,33 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function startStateFlow(ctx: ExtensionContext): Promise<StateFlowTelegramControlResult> {
 		if (shuttingDown) return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
-		if (startActivation?.operation) return startActivation.operation;
+		if (startActivation.current?.operation) return startActivation.current.operation;
 		telegramStartPending = false;
-		if (activeContext && !branchRestoration && isActive()) {
+		if (activeContext && !branchRestoration.current && 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;
-		const operation = runStart(ctx, pending.controller);
-		pending.operation = operation;
-		const finished = () => { if (startActivation === pending) startActivation = undefined; };
-		void operation.then(finished, finished);
-		return operation;
+		const pending = startActivation.claim({ controller: new AbortController() });
+		return startActivation.track(pending, runStart(ctx, pending.controller));
 	}
 
 	/** Await restoration-owned attachment and exact-source fork recovery before current-head activation. */
 	async function runStart(ctx: ExtensionContext, pending: AbortController): Promise<StateFlowTelegramControlResult> {
-		const owner = ctx.sessionManager.getSessionId();
-		const cwd = ctx.cwd;
-		const file = ctx.sessionManager.getSessionFile();
-		const timestamp = ctx.sessionManager.getHeader()?.timestamp;
+		const sameSession = sessionIdentity(ctx);
 		const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
-		const isOwner = () => startActivation?.controller === pending && !signal.aborted && !shuttingDown
-			&& ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
-			&& ctx.sessionManager.getHeader()?.timestamp === timestamp;
+		const isOwner = () => startActivation.current?.controller === pending && !signal.aborted && !shuttingDown && sameSession();
 		const superseded = (): StateFlowTelegramControlResult => {
 			pending.abort();
 			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 (deferredBranch?.reason === "fork") await waitForRecovery(restoreActiveBranch(ctx, "fork", false, pending), signal);
+			else if (!activeContext) await waitForRecovery(restoreActiveBranch(ctx, undefined, false, pending), signal);
+			else if (branchRestoration.current?.operation) await waitForRecovery(branchRestoration.current.operation, signal);
 			if (!isOwner()) return superseded();
 			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 mode persistence.
-				const stopping = inactivePersistence?.operation;
+				const stopping = inactivePersistence.current?.operation;
 				if (stopping) await waitForRecovery(stopping, signal);
 				if (!isOwner()) return superseded();
 				await waitForRecovery(restoreActiveBranch(ctx, "fork", false, pending), signal);
@@ -916,48 +877,59 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	async function activateCurrentState(ctx: ExtensionContext, pending: AbortController): Promise<StateFlowTelegramControlResult> {
 		let selected = runtime;
 		const owner = ctx.sessionManager.getSessionId();
-		const cwd = ctx.cwd;
-		const file = ctx.sessionManager.getSessionFile();
-		const timestamp = ctx.sessionManager.getHeader()?.timestamp;
+		const sameSession = sessionIdentity(ctx);
 		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 && isActive() === (accepted || initiallyActive);
+		const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
+		const isCurrent = () => startActivation.current?.controller === pending && !signal.aborted && runtime === selected && !shuttingDown
+			&& sameSession() && isActive() === (accepted || initiallyActive);
 		const superseded = (): StateFlowTelegramControlResult => {
 			pending.abort();
 			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 deferred = deferredBranch;
+			if (deferred) {
+				const discovery = discoverSnapshotData(ctx.sessionManager.getBranch());
+				const retained = selectRetainedCheckpoint(discovery.candidates, config.inactiveMode);
+				branchStartsWithoutRuntime = retained.kind === "pre-runtime" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
+			}
+			// Off activation owns one cancellable current-head publication, not an independent read-only restore.
 			const result = await activation.withStartTransaction((current, publish) => {
 				signal.throwIfAborted();
 				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;
+				const boundary = deferred && retainsPhysicalSessionProjection(deferred.reason)
+					? findPassiveStopBoundary(ctx.sessionManager.getBranch(), owner, PASSIVE_STOP_ENTRY_TYPE) : undefined;
+				const bootstrap = hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined || boundary !== undefined;
 				const activated = current ? resumeEpisode(current, bootstrap) : startEpisode(bootstrap);
 				const recoveredCurrent = selectedHistoryExpired;
-				const publication = publish(activated);
+				publish(activated);
 				accepted = true;
-				cancelInactivePersistence();
+				inactivePersistence.cancel();
 				runtime = selected = activation;
 				snapshot = activated;
 				activeContext = ctx;
 				selectedHistoryExpired = false;
 				modePersistenceError = undefined;
 				installScopeStates();
+				const continuation = passiveContinuation ?? bootstrapContinuation ?? (deferred ? selectedContinuation(ctx, deferred.reason) : undefined);
+				deferredBranch = undefined;
 				clearRunTransient();
 				contextProjection.reset();
 				passiveContinuation = undefined;
 				bootstrapContinuation = snapshot.meta.bootstrap ? continuation : undefined;
 				deferInferencePreparation();
 				receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
-				recordPolicyPublication(publication, ctx);
+				recordPublication();
 				syncStateFlowTools();
 				updateUi(ctx);
+				if (forkInitialization) {
+					forkInitialization = false;
+					pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner });
+				}
 				appendCheckpoint();
 				ctx.ui.notify(
 					recoveredCurrent
@@ -1014,21 +986,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	}
 
 	function deactivateStateFlow(ctx: ExtensionContext, mode: InactiveMode): Promise<StateFlowTelegramControlResult> {
-		cancelStartActivation();
 		if (shuttingDown) return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
+		if (mode === "off") return selectOff(ctx);
+		startActivation.cancel();
 		telegramStartPending = false;
-		const persisting = inactivePersistence;
+		const persisting = inactivePersistence.current;
 		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;
+		const restoring = branchRestoration.current;
 		// Read-only recovery also retains the latest policy; its native write fence is updated below.
 		if (restoring) restoring.requestedMode = mode;
 		if (restoring?.awaitingAcceptance) {
-			// A mode change never cancels memory restoration or initialization.
+			// Passive keeps independently owned restoration; Off withdraws it through selectOff.
 			applyInactiveMode(ctx, mode);
 			return Promise.resolve({ ok: true, message: `State Flow ${mode}; memory restoration continues` });
 		}
@@ -1037,23 +1010,98 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			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}` });
 		}
-		cancelInactivePersistence();
-		const pending: NonNullable<typeof inactivePersistence> = { controller: new AbortController() };
-		inactivePersistence = pending;
-		const operation = persistInactiveMode(ctx, pending, mode);
-		pending.operation = operation;
-		const finished = () => { if (inactivePersistence === pending) inactivePersistence = undefined; };
-		void operation.then(finished, finished);
-		return operation;
+		inactivePersistence.cancel();
+		const pending = inactivePersistence.claim({ controller: new AbortController() });
+		return inactivePersistence.track(pending, deferredBranch && mode === "passive" && !branchStartsWithoutRuntime
+			? acquirePassiveMode(ctx, pending, deferredBranch.reason)
+			: persistInactiveMode(ctx, pending, mode));
 	}
 
-	async function persistInactiveMode(ctx: ExtensionContext, pending: NonNullable<typeof inactivePersistence>, mode: InactiveMode): Promise<StateFlowTelegramControlResult> {
+	/** Off owns cancellation and native policy only; no canonical transaction or semantic handoff. */
+	function selectOff(ctx: ExtensionContext): Promise<StateFlowTelegramControlResult> {
+		const address = sessionAddress(ctx);
+		const owner = ctx.sessionManager.getSessionId();
+		const branch = ctx.sessionManager.getBranch();
+		const selected = runtime;
+		const sameOwner = selected?.sessionKey === address.key && selected.cwd === ctx.cwd;
+		const forkRecorded = hasPendingFork(branch, owner, PASSIVE_STOP_ENTRY_TYPE);
+		const pendingFork = forkRecorded || (sameOwner && forkInitialization) || (deferredBranch?.owner === address.key && deferredBranch.cwd === ctx.cwd && deferredBranch.reason === "fork");
+		const policy = findBranchPolicy(branch, owner, PASSIVE_STOP_ENTRY_TYPE, config.inactiveMode);
+		const sameDeferred = deferredBranch?.owner === address.key && deferredBranch.cwd === ctx.cwd;
+		const current = sameOwner || sameDeferred ? snapshot : emptySnapshot("off");
+		if (!sameOwner && !sameDeferred) modePersistenceError = policy?.persistenceError;
+		const alreadyOff = current.config.mode === "off" && policy?.mode === "off";
+		const incoming = sameOwner || sameDeferred ? current.meta.bootstrap ? bootstrapContinuation : passiveContinuation : undefined;
+		const unfinished = current.meta.specification !== undefined || (inferencePreparation.current?.prompt !== undefined && !inferencePreparation.current.accepted)
+			|| (isActive() && hasUncheckpointedConversation(branch));
+		const at = incoming?.startedAt ?? Date.now();
+		const from = incoming ? incoming.activeRunStartedAt : (sameOwner || sameDeferred) && (!ctx.isIdle() || unfinished) ? runAnchorTimestamp : undefined;
+		const preserveContext = modePersistenceError !== undefined || (incoming ? incoming.preserveContext : current.meta.bootstrap === true || (unfinished && from === undefined));
+		const discovery = discoverSnapshotData(branch);
+		const preRuntime = (sameOwner && branchStartsWithoutRuntime) || (discovery.candidates.length === 0 && discovery.errors.length === 0);
+		let checkpoint: RetainedPiCheckpoint | undefined;
+		try {
+			checkpoint = !modePersistenceError && current.meta.validation?.attempt !== 0
+				? preRuntime ? preRuntimeCheckpoint("off") : sameOwner && selected?.view ? selected.retainedCheckpoint(deactivateEpisode(current, "off")) : undefined
+				: undefined;
+		} catch {
+			// An unusable cached bookmark cannot prevent native Off policy or authorize replacement memory.
+		}
+		startActivation.cancel();
+		branchRestoration.cancel();
+		inactivePersistence.cancel();
+		backup.cancel();
+		memoryToolLifetime.renew();
+		clearRunTransient();
+		contextProjection.reset();
+		telegramStartPending = false;
+		bootstrapContinuation = undefined;
+		passiveContinuation = undefined;
+		acquisition.reset();
+		runtime = undefined;
+		snapshot = emptySnapshot("off");
+		selectedHistoryExpired = false;
+		branchStartsWithoutRuntime = preRuntime;
+		forkInitialization = pendingFork;
+		deferredBranch = { owner: address.key, cwd: ctx.cwd, reason: pendingFork ? "fork" : undefined };
+		activeContext = ctx;
+		installScopeStates();
+		syncStateFlowTools();
+		updateUi(ctx);
+		try {
+			if (!alreadyOff || (pendingFork && !forkRecorded)) {
+				if (!checkpoint || !preRuntime || pendingFork || preserveContext || from !== undefined || modePersistenceError) pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
+					owner, at, mode: "off", memoryDeferred: true,
+					...(from === undefined ? {} : { from }),
+					...(preserveContext ? { preserveContext: true } : {}),
+					...(pendingFork ? { forkPending: true } : {}),
+					...(modePersistenceError === undefined ? {} : { persistenceError: modePersistenceError }),
+				});
+				if (checkpoint) pi.appendEntry(SNAPSHOT_ENTRY_TYPE, checkpoint);
+			}
+			return Promise.resolve({ ok: true, message: alreadyOff ? "State Flow is already off" : "State Flow off" });
+		} catch (error) {
+			const message = conciseDiagnostic(`State Flow off; native mode recording failed: ${diagnosticText(error)}`);
+			notifyProblem(ctx, message, "error");
+			return Promise.resolve({ ok: false, message });
+		}
+	}
+
+	async function acquirePassiveMode(ctx: ExtensionContext, pending: InactivePersistence, reason: unknown): Promise<StateFlowTelegramControlResult> {
+		await restoreActiveBranch(ctx, reason, true, pending.controller, "passive");
+		if (!inactivePersistence.owns(pending) || pending.controller.signal.aborted || shuttingDown) {
+			return { ok: false, message: "State Flow mode change was superseded" };
+		}
+		return persistInactiveMode(ctx, pending, "passive");
+	}
+
+	async function persistInactiveMode(ctx: ExtensionContext, pending: 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);
+			|| (inferencePreparation.current?.prompt !== undefined && !inferencePreparation.current.accepted);
 		applyInactiveMode(ctx, mode);
 		const stoppedAt = Date.now();
 		if (modePersistenceError) {
@@ -1069,7 +1117,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const incomingBoundary = current.meta.bootstrap ? bootstrapContinuation : undefined;
 		const anchor = runAnchorTimestamp;
 		const idle = ctx.isIdle();
-		const isCurrent = () => inactivePersistence === pending && runtime === selected
+		const isCurrent = () => inactivePersistence.owns(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 => {
@@ -1082,7 +1130,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					modePersistenceError !== undefined || (incomingBoundary ? incomingBoundary.preserveContext : current.meta.bootstrap === true || (unfinished && anchor === undefined)),
 				)
 				: undefined;
-			// Off keeps the frozen boundary for a later Passive/Active choice but never projects it.
+			// Repeated Passive choices keep the already selected continuation boundary.
 			passiveContinuation = handoff ?? (!wasActive ? passiveContinuation : undefined);
 			return handoff;
 		};
@@ -1110,8 +1158,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			// Projection changes before any wait; capture the old run's boundary before later native input can replace it.
 			freezeHandoff();
 			bootstrapContinuation = undefined;
-			artifactInvalidations = [];
-			artifactReads.setCandidates([]);
+			acquisition.clearInvalidations();
 			assertPublicationAvailable();
 			const signal = ctx.signal ? AbortSignal.any([pending.controller.signal, ctx.signal]) : pending.controller.signal;
 			if (branchStartsWithoutRuntime || !selected?.view) {
@@ -1131,11 +1178,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				if (!isCurrent()) throw new Error("State Flow mode selection changed while awaiting publication");
 				assertPublicationAvailable();
 				const next = structuredClone(snapshot);
-				const publication = publish(next);
+				publish(next);
 				accepted = true;
 				snapshot = next;
 				installScopeStates();
-				recordPolicyPublication(publication, ctx);
+				recordPublication();
 				return complete();
 			}, signal);
 			return isCurrent() ? result : superseded();
@@ -1149,8 +1196,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			}
 			modePersistenceError = cause.trim() ? cause : "Canonical State Flow persistence failed";
 			bootstrapContinuation = undefined;
-			artifactInvalidations = [];
-			artifactReads.setCandidates([]);
+			acquisition.clearInvalidations();
 			return complete();
 		}
 	}
@@ -1184,7 +1230,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			},
 			cancelStart: () => {
 				telegramStartPending = false;
-				cancelStartActivation();
+				startActivation.cancel();
 			},
 		},
 	});
@@ -1201,7 +1247,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		contextProjection.reset();
 		skillReads.clear();
 		artifactReads.clear();
-		cancelResponseReconciliation();
+		responseReconciliation.cancel();
 		completedRunAccepted = false;
 		// This native hook has no operation signal. Capture only; the first active context owns acceptance.
 		deferInferencePreparation(event.prompt);
@@ -1221,12 +1267,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (runtime?.view) refreshArtifactHints();
 		if (!isActive() && !passiveContinuation && !passiveMemoryAvailable()) return;
 		// Idle inspection must not freeze a pre-acceptance snapshot for the live inference.
-		const projection = isActive() && inferencePreparation && !inferencePreparation.accepted
+		const projection = isActive() && inferencePreparation.current && !inferencePreparation.current.accepted
 			? new ContextProjection() : contextProjection;
 		const effective = effectiveState;
-		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
-		const phase = isActive() ? currentRehydrationPhase() : undefined;
-		const view = contextView(effective, artifactHints, invalidations, phase);
+		const invalidations = acquisition.invalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
+		const phase = isActive() ? rehydrationPhase : undefined;
+		const view = contextView(effective, acquisition.hints, invalidations, phase);
 		if (passiveContinuation) {
 			const retained = passiveContinuationMessages(messages, passiveContinuation);
 			if (!runtime?.view) return { messages: retained };
@@ -1246,20 +1292,20 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	}
 
 	function prepareContext(messages: AgentMessage[], ctx: ExtensionContext): ReturnType<typeof projectContext> | Promise<ReturnType<typeof projectContext>> {
-		const pending = inferencePreparation;
+		const pending = inferencePreparation.current;
 		const selected = runtime;
 		const operationSignal = ctx.signal;
 		// Idle projections remain observational; only a live native operation may await preparation.
 		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;
+			if (!pending.accepted && inferencePreparation.owns(pending)) pending.operation = undefined;
 		});
 		return pending.operation.then(() => {
 			if (shuttingDown || operationSignal.aborted || runtime !== selected || ctx.signal !== operationSignal) return;
-			if (isActive() && inferencePreparation !== pending) {
+			if (isActive() && !inferencePreparation.owns(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);
+				if (inferencePreparation.current?.prompt === undefined) return prepareContext(messages, ctx);
 				return;
 			}
 			if (isActive() && !pending.accepted) return;
@@ -1319,32 +1365,32 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (event.message.role === "user" && runAnchorTimestamp === undefined) runAnchorTimestamp = event.message.timestamp;
 		if (shuttingDown || !isActive()) return;
 		if (event.message.role !== "assistant") return;
-		cancelResponseReconciliation();
+		responseReconciliation.cancel();
 		const message = event.message as unknown as { role: "assistant"; stopReason?: string; content?: unknown };
 		if (message.stopReason === "aborted" || assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse") return;
 		if (message.stopReason === "length" || message.stopReason === "error") {
 			recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content });
 			return;
 		}
-		responseReconciliation = new AbortController();
+		responseReconciliation.claim({ controller: new AbortController() });
 	});
 
 	pi.on("turn_end", async (event, ctx) => {
 		if (shuttingDown) return;
-		const pending = responseReconciliation;
+		const pending = responseReconciliation.current;
 		if (!isActive() || !pending) {
 			updateUi(ctx);
 			return;
 		}
 		const selected = runtime;
-		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;
 		let responseCommitted = false;
 		try {
 			const response = finalizedAssistantResponse(event.message);
 			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 || !isActive()) {
+				if (runtime !== selected || !responseReconciliation.owns(pending) || !isActive()) {
 					throw new Error("State Flow response selection changed while awaiting publication");
 				}
 				assertPublicationAvailable();
@@ -1360,64 +1406,56 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				installScopeStates();
 				responseCommitted = true;
 				contextProjection.reset();
-				if (publication?.changed) recordPublication(publication, ctx);
+				if (publication?.changed) recordPublication();
 				appendCheckpoint();
 				clearAcceptedAcquisitions();
 				bootstrapContinuation = undefined;
 				rehydrationPhase = "step";
 				completedRunAccepted = !wasBootstrap;
-				turnAcceptedForBackup = true;
+				backup.markTurnAccepted();
 				updateUi(ctx);
 			}, signal);
 		} catch (error) {
 			// Superseded completion owns neither the new lifecycle nor its diagnostics/UI.
-			if (signal.aborted || runtime !== selected || responseReconciliation !== pending) return;
+			if (signal.aborted || runtime !== selected || !responseReconciliation.owns(pending)) return;
 			const cause = diagnosticText(error);
 			recordDiagnostic(cause, "finalization", ctx);
 			notifyProblem(ctx, responseCommitted
 				? `State Flow response saved; lifecycle update failed: ${cause}`
 				: `State Flow response reconciliation failed: ${cause}`, "error");
 		} finally {
-			if (responseReconciliation === pending) responseReconciliation = undefined;
+			responseReconciliation.release(pending);
 		}
 	});
 
 	pi.on("session_before_compact", (event) => {
-		if (!compactionPlan) return;
-		if (compactionStopped && event.reason === "manual" && event.customInstructions === compactionMarker) return { cancel: true };
-		const result = stateFlowCompactionResult(compactionPlan, compactionMarker, event);
+		const result = compactionRequests.resolve(event, !shuttingDown && isActive());
 		if (result === undefined || "cancel" in result) return result;
 		return { compaction: result };
 	});
 
 	pi.on("agent_before_settle", async (_event, ctx) => {
-		if (shuttingDown || !turnAcceptedForBackup) return;
-		turnAcceptedForBackup = false;
-		if (!backupPending) return;
-		backupPending = false;
+		if (shuttingDown || !memoryToolsAvailable() || !backup.takeSettledTurn()) return;
 		const operationSignal = ctx.signal;
-		const signal = operationSignal ? AbortSignal.any([backupLifetime.signal, operationSignal]) : backupLifetime.signal;
+		const lifetime = backup.lifetime;
+		const signal = operationSignal ? AbortSignal.any([lifetime, operationSignal]) : lifetime;
 		const selected = runtime;
 		try {
 			if (existsSync(join(repositoryRoot, ".git"))) {
 				const pushSessionId = sessionAddress(ctx).id;
 				const pushCwd = ctx.cwd;
 				// Pi 0.87 settles after its agent signal ends; waiting there would strand native Abort.
-				const operation = backupCurrentStateFlowFiles(repositoryRoot, signal, operationSignal !== undefined);
-				backupOperations.add(operation);
-				try { await operation; }
-				finally { backupOperations.delete(operation); }
-				if (signal.aborted) return;
+				await backup.track(backupCurrentStateFlowFiles(repositoryRoot, signal, operationSignal !== undefined));
+				if (signal.aborted || snapshot.config.mode === "off") return;
 				startStateFlowBackupPush(repositoryRoot, (error) => {
-					if (shuttingDown) return;
+					if (shuttingDown || lifetime.aborted || snapshot.config.mode === "off") return;
 					const message = diagnosticText(error);
 					const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
-					if (pushFailureNotified) return;
-					pushFailureNotified = true;
+					if (!backup.claimPushFailureNotice()) return;
 					notifyActiveContext(recorded
 						? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
 						: `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
-				}, () => { pushFailureNotified = false; });
+				}, () => backup.resetPushFailureNotice(), lifetime);
 			}
 		} catch (error) {
 			if (signal.aborted || runtime !== selected) return;
@@ -1435,20 +1473,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			await startStateFlow(ctx);
 			return;
 		}
-		if (!completedRunAccepted || compactionStopped || !isActive() || snapshot.meta.bootstrap
-			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !runtime?.view
+		if (!completedRunAccepted || compactionRequests.stopped || !isActive() || snapshot.meta.bootstrap
+			|| compactionRequests.inFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !runtime?.view
 			|| !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
 		completedRunAccepted = false;
 		const entries = ctx.sessionManager.buildContextEntries();
 		if (!hasCompactionSizedTranscript(entries)) return;
 		const plan = planStateFlowCompaction(entries, runtime.causalBasis(), snapshot.meta.step, runAnchorTimestamp);
 		if (!plan) return;
-		compactionPlan = plan;
-		compactionInFlight = true;
+		const marker = compactionRequests.begin(plan);
 		// Pi dispatches deferred companion prompts after all settled handlers return.
 		await new Promise<void>((resolve) => {
-			const finished = () => { compactionPlan = undefined; compactionInFlight = false; resolve(); };
-			ctx.compact({ customInstructions: compactionMarker, onComplete: finished, onError: finished });
+			const finished = () => {
+				compactionRequests.finish(marker);
+				resolve();
+			};
+			ctx.compact({ customInstructions: marker, onComplete: finished, onError: finished });
 		});
 	});
 
@@ -1466,20 +1506,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 	pi.on("session_shutdown", async (_event, _ctx) => {
 		shuttingDown = true;
+		memoryToolLifetime.end();
 		contextProjection.reset();
-		const restoring = cancelBranchRestoration();
-		const starting = cancelStartActivation();
-		const stopping = cancelInactivePersistence();
-		backupLifetime.abort();
-		cancelInferencePreparation();
-		cancelResponseReconciliation();
+		const restoring = branchRestoration.cancel();
+		const starting = startActivation.cancel();
+		const stopping = inactivePersistence.cancel();
+		backup.abort();
+		inferencePreparation.cancel();
+		responseReconciliation.cancel();
 		cancelSharedInspections();
 		telegramStartPending = false;
-		compactionStopped = true;
+		compactionRequests.stop();
 		completedRunAccepted = false;
 		activeContext = undefined;
 		telegram.dispose();
-		await Promise.allSettled([...backupOperations, ...restorationOperations, ...[restoring, stopping, starting].filter((operation) => operation !== undefined)]);
+		await Promise.allSettled([...backup.operations, ...branchRestoration.inflight, ...[restoring, stopping, starting].filter((operation) => operation !== undefined)]);
 		await awaitInFlightBackupPushes(repositoryRoot);
 	});
 }