@llblab/pi-kit 0.25.0 → 0.26.0

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

@@ -34,9 +34,9 @@ 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 { 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 ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
 import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
 import { PublicationBusyError } from "./storage.ts";
@@ -97,15 +97,18 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let startActivation: { controller: AbortController; operation?: Promise<StateFlowTelegramControlResult> } | undefined;
 	let forkInitialization = false;
 	let branchRestoration: BranchRestoration | undefined;
+	let deferredBranch: { reason: unknown; owner: string; cwd: string } | undefined;
 	const restorationOperations = new Set<Promise<void>>();
 	let responseReconciliation: AbortController | undefined;
 	let sharedInspectionLifetime = new AbortController();
+	let memoryToolLifetime = new AbortController();
 	let completedRunAccepted = false;
 	let turnAcceptedForBackup = false;
 	let compactionPlan: StateFlowCompactionPlan | undefined;
 	let compactionInFlight = false;
 	let compactionStopped = false;
-	const compactionMarker = `state-flow-boundary:${randomUUID()}`;
+	const compactionPrefix = `state-flow-boundary:${randomUUID()}:`;
+	let compactionMarker: string | undefined;
 	let passiveContinuation: PassiveContinuation | undefined;
 	let bootstrapContinuation: PassiveContinuation | undefined;
 	const contextProjection = new ContextProjection();
@@ -117,7 +120,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	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();
+	let backupLifetime = new AbortController();
 	const backupOperations = new Set<Promise<string | undefined>>();
 	let shuttingDown = false;
 	let pushFailureNotified = false;
@@ -230,6 +233,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		sharedInspectionLifetime = new AbortController();
 	}
 
+	function cancelBackupWork(): void {
+		backupLifetime.abort();
+		backupLifetime = new AbortController();
+		backupPending = false;
+	}
+
 	function cancelInferencePreparation(): void {
 		inferencePreparation?.controller.abort();
 		inferencePreparation = undefined;
@@ -319,17 +328,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 {
@@ -473,8 +493,10 @@ 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();
+		memoryToolLifetime.abort();
+		memoryToolLifetime = new AbortController();
 		cancelBranchRestoration();
 		// Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
 		if (!startOwner) {
@@ -488,6 +510,51 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		artifactReads.setCandidates([]);
 		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") {
+				cancelBackupWork();
+				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();
+				artifactHints = {};
+				if (adoptDefault) appendCheckpoint();
+				syncStateFlowTools();
+				updateUi(ctx);
+				return Promise.resolve();
+			}
+			if (pendingFork) sessionStartReason = "fork";
+		}
+		deferredBranch = undefined;
 		runtime = createRuntime(ctx);
 		installScopeStates();
 		branchStartsWithoutRuntime = false;
@@ -548,9 +615,11 @@ 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);
@@ -687,25 +756,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");
@@ -784,6 +852,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();
@@ -850,7 +919,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,
@@ -891,7 +960,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			return { ok: false, message: "State Flow activation was superseded", signal: pending.signal };
 		};
 		try {
-			if (!activeContext) await waitForRecovery(restoreActiveBranch(ctx, undefined, false, pending), 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?.operation) await waitForRecovery(branchRestoration.operation, signal);
 			if (!isOwner()) return superseded();
 			if (isActive()) return { ok: true, message: "State Flow is already active", signal: sharedInspectionLifetime.signal };
@@ -922,7 +992,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const initiallyActive = isActive();
 		let accepted = false;
 		let receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
-		const isCurrent = () => startActivation?.controller === pending && runtime === selected && !shuttingDown
+		const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
+		const isCurrent = () => startActivation?.controller === pending && !signal.aborted && runtime === selected && !shuttingDown
 			&& ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
 			&& ctx.sessionManager.getHeader()?.timestamp === timestamp && isActive() === (accepted || initiallyActive);
 		const superseded = (): StateFlowTelegramControlResult => {
@@ -931,13 +1002,20 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		};
 		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);
@@ -949,6 +1027,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				selectedHistoryExpired = false;
 				modePersistenceError = undefined;
 				installScopeStates();
+				const continuation = passiveContinuation ?? bootstrapContinuation ?? (deferred ? selectedContinuation(ctx, deferred.reason) : undefined);
+				deferredBranch = undefined;
 				clearRunTransient();
 				contextProjection.reset();
 				passiveContinuation = undefined;
@@ -958,6 +1038,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				recordPolicyPublication(publication, ctx);
 				syncStateFlowTools();
 				updateUi(ctx);
+				if (forkInitialization) {
+					forkInitialization = false;
+					pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner });
+				}
 				appendCheckpoint();
 				ctx.ui.notify(
 					recoveredCurrent
@@ -1014,8 +1098,9 @@ 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);
+		cancelStartActivation();
 		telegramStartPending = false;
 		const persisting = inactivePersistence;
 		if (persisting?.operation && !persisting.published) {
@@ -1028,7 +1113,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		// 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` });
 		}
@@ -1040,13 +1125,96 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		cancelInactivePersistence();
 		const pending: NonNullable<typeof inactivePersistence> = { controller: new AbortController() };
 		inactivePersistence = pending;
-		const operation = persistInactiveMode(ctx, pending, mode);
+		const operation = deferredBranch && mode === "passive" && !branchStartsWithoutRuntime
+			? acquirePassiveMode(ctx, pending, deferredBranch.reason)
+			: persistInactiveMode(ctx, pending, mode);
 		pending.operation = operation;
 		const finished = () => { if (inactivePersistence === pending) inactivePersistence = undefined; };
 		void operation.then(finished, finished);
 		return operation;
 	}
 
+	/** 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?.prompt !== undefined && !inferencePreparation.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.
+		}
+		cancelStartActivation();
+		cancelBranchRestoration();
+		cancelInactivePersistence();
+		cancelBackupWork();
+		memoryToolLifetime.abort();
+		memoryToolLifetime = new AbortController();
+		clearRunTransient();
+		contextProjection.reset();
+		telegramStartPending = false;
+		bootstrapContinuation = undefined;
+		passiveContinuation = undefined;
+		artifactInvalidations = [];
+		artifactHints = {};
+		artifactReads.setCandidates([]);
+		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: NonNullable<typeof inactivePersistence>, reason: unknown): Promise<StateFlowTelegramControlResult> {
+		await restoreActiveBranch(ctx, reason, true, pending.controller, "passive");
+		if (inactivePersistence !== 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: NonNullable<typeof inactivePersistence>, mode: InactiveMode): Promise<StateFlowTelegramControlResult> {
 		let selected = runtime;
 		const owner = ctx.sessionManager.getSessionId();
@@ -1082,7 +1250,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;
 		};
@@ -1383,20 +1551,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 
 	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);
+		if (event.reason !== "manual" || !event.customInstructions?.startsWith("state-flow-boundary:")) return;
+		const marker = compactionMarker;
+		if (shuttingDown || compactionStopped || !isActive() || !compactionPlan || !marker || event.customInstructions !== marker) return { cancel: true };
+		const result = stateFlowCompactionResult(compactionPlan, marker, event);
 		if (result === undefined || "cancel" in result) return result;
 		return { compaction: result };
 	});
 
 	pi.on("agent_before_settle", async (_event, ctx) => {
-		if (shuttingDown || !turnAcceptedForBackup) return;
+		if (shuttingDown || !memoryToolsAvailable() || !turnAcceptedForBackup) return;
 		turnAcceptedForBackup = false;
 		if (!backupPending) return;
 		backupPending = false;
 		const operationSignal = ctx.signal;
-		const signal = operationSignal ? AbortSignal.any([backupLifetime.signal, operationSignal]) : backupLifetime.signal;
+		const lifetime = backupLifetime.signal;
+		const signal = operationSignal ? AbortSignal.any([lifetime, operationSignal]) : lifetime;
 		const selected = runtime;
 		try {
 			if (existsSync(join(repositoryRoot, ".git"))) {
@@ -1407,9 +1577,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				backupOperations.add(operation);
 				try { await operation; }
 				finally { backupOperations.delete(operation); }
-				if (signal.aborted) return;
+				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;
@@ -1417,7 +1587,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					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; });
+				}, () => { pushFailureNotified = false; }, lifetime);
 			}
 		} catch (error) {
 			if (signal.aborted || runtime !== selected) return;
@@ -1444,11 +1614,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const plan = planStateFlowCompaction(entries, runtime.causalBasis(), snapshot.meta.step, runAnchorTimestamp);
 		if (!plan) return;
 		compactionPlan = plan;
+		const marker = compactionMarker = `${compactionPrefix}${randomUUID()}`;
 		compactionInFlight = true;
 		// 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 = () => {
+				if (compactionMarker === marker) { compactionPlan = undefined; compactionInFlight = false; }
+				resolve();
+			};
+			ctx.compact({ customInstructions: marker, onComplete: finished, onError: finished });
 		});
 	});
 
@@ -1466,6 +1640,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 	pi.on("session_shutdown", async (_event, _ctx) => {
 		shuttingDown = true;
+		memoryToolLifetime.abort();
 		contextProjection.reset();
 		const restoring = cancelBranchRestoration();
 		const starting = cancelStartActivation();

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

@@ -206,14 +206,15 @@ export function backupCurrentStateFlowFiles(repositoryRoot: string, signal?: Abo
 }
 
 /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
-export function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean {
+export function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void, signal?: AbortSignal): boolean {
 	const root = resolve(repositoryRoot);
-	if (activePushes.has(root)) return false;
-	const push = pushCurrentStateFlowBackup(root).then(
+	if (signal?.aborted || activePushes.has(root)) return false;
+	const push = pushCurrentStateFlowBackup(root, signal).then(
 		(result) => {
-			if (result) { try { onSuccess?.(); } catch { /* Reporting cannot change push acceptance. */ } }
+			if (result && !signal?.aborted) { try { onSuccess?.(); } catch { /* Reporting cannot change push acceptance. */ } }
 		},
 		(error) => {
+			if (signal?.aborted) return;
 			try { onFailure(error); } catch { /* Reporting cannot revive a failed push. */ }
 		},
 	).finally(() => { activePushes.delete(root); });
@@ -228,15 +229,17 @@ export async function awaitInFlightBackupPushes(repositoryRoot: string): Promise
 }
 
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
-export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
+export function pushCurrentStateFlowBackup(repositoryRoot: string, signal?: AbortSignal): Promise<{ commit: string; remote: string; ref: string } | undefined> {
 	return new Promise((resolvePush, rejectPush) => {
 		let root: string;
 		let commit: string | undefined;
 		let destination: { remote: string; ref: string } | undefined;
 		try {
+			signal?.throwIfAborted();
 			root = assertRepositoryRoot(repositoryRoot);
 			commit = currentHead(root);
 			destination = configuredPushDestination(root);
+			signal?.throwIfAborted();
 		} catch (error) {
 			rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
 			return;
@@ -273,6 +276,7 @@ export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ co
 			if (settled) return;
 			settled = true;
 			clearTimeout(timeout);
+			signal?.removeEventListener("abort", cancelled);
 			if (error) rejectPush(error);
 			else resolvePush({ commit: commit!, ...destination! });
 		}
@@ -284,5 +288,10 @@ export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ co
 		child.once("exit", () => { if (failure) child.stderr?.destroy(); });
 		child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
 			: new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
+		function cancelled(): void {
+			terminate(signal?.reason instanceof Error ? signal.reason : new Error("Git backup push cancelled"));
+		}
+		signal?.addEventListener("abort", cancelled, { once: true });
+		if (signal?.aborted) cancelled();
 	});
 }

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

@@ -1,4 +1,4 @@
-import { parseRetainedPiCheckpoint, type InactiveMode } from "./snapshot.ts";
+import { parseRetainedPiCheckpoint, readCheckpointMode, type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 
@@ -22,6 +22,8 @@ export interface PassiveStopBoundary {
 	persistenceError?: string;
 	/** The inactive mode selected by that failed change; legacy markers omit it. */
 	mode?: InactiveMode;
+	/** Native-only Off choice; canonical runtime mode is deliberately not updated. */
+	memoryDeferred?: true;
 }
 
 export interface SnapshotDiscovery {
@@ -44,6 +46,55 @@ export function discoverSnapshotData(branch: readonly BranchEntry[]): SnapshotDi
 	return { candidates, errors };
 }
 
+/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
+export function findBranchPolicy(
+	branch: readonly BranchEntry[], sessionId: string | undefined, stopEntryType: string | undefined, inactiveMode: InactiveMode,
+): { mode: StateFlowMode; persistenceError?: string } | undefined {
+	let stopReset = false;
+	for (let index = branch.length - 1; index >= 0; index--) {
+		try {
+			const entry = branch[index];
+			if (entry?.type !== "custom") continue;
+			if (entry.customType === SNAPSHOT_ENTRY_TYPE) {
+				const mode = readCheckpointMode(entry.data, inactiveMode);
+				if (mode !== undefined) return { mode };
+				const data = entry.data as { disabled?: unknown; mode?: unknown; enabled?: unknown } | undefined;
+				if (data?.disabled === true && !Object.hasOwn(data, "mode") && !Object.hasOwn(data, "enabled")) return { mode: inactiveMode };
+			} else if (stopEntryType !== undefined && entry.customType === stopEntryType) {
+				const data = entry.data as PassiveStopBoundary & { owner?: unknown; reset?: unknown } | undefined;
+				if (!data || stopReset || (sessionId === undefined ? typeof data.owner !== "string" || !data.owner.trim() : data.owner !== sessionId)) continue;
+				if (data.reset === true) { stopReset = true; continue; }
+				if (Number.isSafeInteger(data.at) && data.at >= 0 && data.memoryDeferred === true && data.mode === "off") {
+					return { mode: "off", ...(typeof data.persistenceError === "string" && data.persistenceError.trim() ? { persistenceError: data.persistenceError } : {}) };
+				}
+				if (Number.isSafeInteger(data.at) && data.at >= 0 && typeof data.persistenceError === "string" && data.persistenceError.trim()) {
+					return { mode: data.mode === "off" || data.mode === "passive" ? data.mode : inactiveMode, persistenceError: data.persistenceError };
+				}
+			}
+		} catch {
+			// Malformed native policy cannot prevent another explicit retained choice from being read.
+		}
+	}
+	return undefined;
+}
+
+/** Native policy bookkeeping retains an unacquired fork across extension reloads. */
+export function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean {
+	for (let index = branch.length - 1; index >= 0; index--) {
+		try {
+			const entry = branch[index];
+			if (entry?.type !== "custom" || entry.customType !== entryType) continue;
+			const data = entry.data as { owner?: unknown; reset?: unknown; forkPending?: unknown } | undefined;
+			if (data?.owner !== sessionId) continue;
+			if (data.reset === true) return false;
+			if (data.forkPending === true) return true;
+		} catch {
+			// Unrelated native entries grant no fork authority.
+		}
+	}
+	return false;
+}
+
 export function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[] {
 	return discoverSnapshotData(branch).candidates;
 }

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

@@ -26,10 +26,12 @@ export interface SnapshotConfig {
 }
 
 /**
- * Read-only compatibility for session config and native checkpoints written before `mode`:
- * `enabled:true` stays active; `enabled:false` stays the caller's inactive policy.
+ * Read only mode policy, without validating or accessing semantic checkpoint metadata.
+ * Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
+ * Legacy `enabled:false` follows the caller's inactive policy.
  */
-function decodeLegacyMode(value: JsonObject, inactiveMode: InactiveMode): StateFlowMode | undefined {
+export function readCheckpointMode(value: unknown, inactiveMode: InactiveMode = "passive"): StateFlowMode | undefined {
+	if (!isObject(value)) return undefined;
 	if (Object.hasOwn(value, "mode")) return Object.hasOwn(value, "enabled") || !isStateFlowMode(value.mode) ? undefined : value.mode;
 	return typeof value.enabled === "boolean" ? value.enabled ? "active" : inactiveMode : undefined;
 }
@@ -134,7 +136,7 @@ export function parseSessionRuntime(
 	let runtime: unknown;
 	try {
 		const settings: unknown = JSON.parse(config);
-		const mode = isObject(settings) && Object.keys(settings).length === 1 ? decodeLegacyMode(settings, "passive") : undefined;
+		const mode = isObject(settings) && Object.keys(settings).length === 1 ? readCheckpointMode(settings, "passive") : undefined;
 		if (mode === undefined) throw new Error("Invalid State Flow runtime configuration or counters");
 		runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
 	} catch (error) {
@@ -230,7 +232,7 @@ export function parseRetainedPiCheckpoint(value: unknown, inactiveMode: Inactive
 	if (keys.length === 1 && value.disabled === true) return { mode: inactiveMode };
 	if (keys.length === 1 && (value.mode === "passive" || value.mode === "off")) return { mode: value.mode };
 	const allowed = new Set(["boundary", "mode", "enabled", "step", "bootstrap", "specification"]);
-	const mode = decodeLegacyMode(value, inactiveMode);
+	const mode = readCheckpointMode(value, inactiveMode);
 	if (keys.some((key) => !allowed.has(key))
 		|| typeof value.boundary !== "string" || value.boundary.trim().length === 0
 		|| mode === undefined