@llblab/pi-kit 0.28.0 → 0.29.1

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

@@ -30,7 +30,7 @@ import type { RehydrationPhase } from "./rehydration.ts";
 import { TemporalRuntime, type RuntimePublication } from "./runtime.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 RetainedPiCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
+import { emptySnapshot, isActiveRestorationBlocked, 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";
@@ -80,7 +80,7 @@ interface InactivePersistence extends ModeOperation {
 type BranchSelection =
 	| { kind: "settled" }
 	| { kind: "current"; mode: InactiveMode }
-	| { kind: "restore"; checkpoint: RetainedBoundaryCheckpoint }
+	| { kind: "attach"; checkpoint: RetainedBoundaryCheckpoint }
 	| { kind: "fork"; checkpoint: RetainedBoundaryCheckpoint; source: SessionAddress }
 	| { kind: "auto-start" };
 
@@ -93,7 +93,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let scopeStates: ScopedStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
 	let effectiveState: SemanticState = {};
 	let branchStartsWithoutRuntime = false;
-	let selectedBoundaryError: { expired: boolean; blockInference: boolean } | undefined;
 	let modePersistenceError: string | undefined;
 	/** One pending inactive-mode persistence; later inactive choices coalesce until it publishes. */
 	const inactivePersistence = new OwnedOperationSlot<InactivePersistence>();
@@ -177,11 +176,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (modePersistenceError) throw new Error(`Memory writes paused after mode change: ${modePersistenceError}; use /state-flow-active`);
 	}
 
+	/** Active lifecycle work requires validated memory, not merely a selected Active policy. */
 	function isActive(): boolean {
-		return snapshot.config.mode === "active";
+		return snapshot.config.mode === "active" && !isActiveRestorationBlocked(snapshot);
 	}
 
-	/** An unavailable or pending active selection keeps the configured inactive policy, never an invented one. */
+	/** Pending acquisition has no accepted Active memory yet. */
 	function inactiveSelection(mode: StateFlowMode): InactiveMode {
 		return mode === "active" ? config.inactiveMode : mode;
 	}
@@ -448,7 +448,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				runtime = undefined;
 				snapshot = emptySnapshot("off");
 				branchStartsWithoutRuntime = withoutRuntime;
-				selectedBoundaryError = undefined;
 				modePersistenceError = persistenceError;
 				forkInitialization = reason === "fork";
 				installScopeStates();
@@ -464,7 +463,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		runtime = createRuntime(ctx);
 		installScopeStates();
 		branchStartsWithoutRuntime = false;
-		selectedBoundaryError = undefined;
 		forkInitialization = sessionStartReason === "fork";
 		let selection: BranchSelection = { kind: "settled" };
 		let skipped = 0;
@@ -492,12 +490,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 						selection = { kind: "fork", source, checkpoint: sourceFence?.persistenceError !== undefined
 							? { ...selected.checkpoint, mode: sourceFence.mode ?? config.inactiveMode } : selected.checkpoint };
 					} catch (error) {
-						selectedBoundaryError = { expired: error instanceof HistoryBoundaryExpiredError,
-							blockInference: selected.checkpoint.mode === "active" && requestedMode === undefined };
-						snapshot = selectedBoundaryFailure(diagnosticText(error), inactiveSelection(selected.checkpoint.mode));
+						snapshot = selectedBoundaryFailure(diagnosticText(error), requestedMode ?? selected.checkpoint.mode);
 					}
 				} else if (selected.kind === "boundary") {
-					selection = { kind: "restore", checkpoint: selected.checkpoint };
+					selection = { kind: "attach", checkpoint: selected.checkpoint };
 				} else if (selected.kind === "pre-runtime") {
 					snapshot = emptySnapshot(selected.mode);
 				} else if (discovery.candidates.length > 0) {
@@ -551,10 +547,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		};
 		let accepted = false;
 		const failSelection = (error: unknown): void => {
-			selectedBoundaryError = { expired: error instanceof HistoryBoundaryExpiredError,
-				blockInference: pending.requestedMode === undefined && (selection.kind === "auto-start"
-					|| ((selection.kind === "restore" || selection.kind === "fork") && selection.checkpoint.mode === "active")) };
-			snapshot = selectedBoundaryFailure(diagnosticText(error), inactiveSelection(snapshot.config.mode));
+			const mode = pending.requestedMode ?? (selection.kind === "auto-start" ? "active"
+				: selection.kind === "attach" || selection.kind === "fork" ? selection.checkpoint.mode : snapshot.config.mode);
+			snapshot = selectedBoundaryFailure(diagnosticText(error), mode);
 			installScopeStates();
 		};
 		// Install accepted memory before native writes; later ancillary failures cannot revert or replay it.
@@ -584,9 +579,17 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 						snapshot = current ? deactivateEpisode(current, pending.requestedMode ?? selection.mode)
 							: migrationFailure({}, "Current State Flow session memory is unavailable", pending.requestedMode ?? selection.mode);
 						installScopeStates();
-					} else if (selection.kind === "restore") {
-						await candidate.withRestoreTransaction(selection.checkpoint, (restored, publish) => {
+					} else if (selection.kind === "attach") {
+						// Memory is the current same-session files; the Pi checkpoint supplies only mode and run lifecycle.
+						await candidate.withStartTransaction((current, publish) => {
 							assertCurrent();
+							if (!current) throw new Error("Current State Flow session memory is unavailable");
+							const { checkpoint } = selection;
+							const restored: Snapshot = { config: { mode: checkpoint.mode }, meta: {
+								step: current.meta.step,
+								...(checkpoint.bootstrap ? { bootstrap: true } : {}),
+								...(checkpoint.specification === undefined ? {} : { specification: checkpoint.specification }),
+							} };
 							// Canceled preparation or boundary continuation may have no specification. Retain uncompiled native context.
 							if (restored.config.mode === "active" && restored.meta.specification === undefined
 								&& retainsPhysicalSessionProjection(reason) && hasUncheckpointedConversation(ctx.sessionManager.getBranch())) restored.meta.bootstrap = true;
@@ -595,6 +598,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 							accept(candidate, next, appendCheckpoint);
 						}, signal);
 					} else if (selection.kind === "fork") {
+						// The runtime copies the parent's current memory; the checkpoint supplies only child mode/bootstrap.
 						await candidate.withForkTransaction(selection.source, selection.checkpoint, (child, publish) => {
 							assertCurrent();
 							// Mode is selected independently of creating the child's private memory.
@@ -632,7 +636,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				if (accepted) return;
 			}
 			settleSelection(ctx, reason, notifyRecovery, skipped, selected !== placeholder);
-			if (snapshot.config.mode !== "passive" || runtime?.view) return;
+			if (snapshot.config.mode === "off" || isActive() || runtime?.view) return;
+			// Unavailable Active memory may expose shared reads, never substitute private memory or model context.
 			const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery);
 			if (passive === undefined) return;
 			assertCurrent();
@@ -674,8 +679,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	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 (selectedBoundaryError?.expired) 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");
+			notifyProblem(ctx, `State Flow restore failed: ${failure}`, "error");
 		}
 		const continuation = selectedMemory ? selectedContinuation(ctx, reason) : undefined;
 		if (continuation !== undefined) {
@@ -884,19 +888,26 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}
 	}
 
-	async function activateCurrentState(ctx: ExtensionContext, pending: AbortController): Promise<StateFlowTelegramControlResult> {
+	/** Explicit Active or Passive accepts validated current same-session memory without claiming unavailable history. */
+	async function activateCurrentState(
+		ctx: ExtensionContext, pending: AbortController, mode: "active" | "passive" = "active",
+		owns = () => startActivation.current?.controller === pending,
+	): Promise<StateFlowTelegramControlResult> {
 		let selected = runtime;
 		const owner = ctx.sessionManager.getSessionId();
 		const sameSession = sessionIdentity(ctx);
-		const initiallyActive = isActive();
+		const policy = () => `${snapshot.config.mode}:${isActive()}`;
+		const initialPolicy = policy();
+		const acceptedPolicy = `${mode}:${mode === "active"}`;
+		const active = mode === "active";
 		let accepted = false;
 		let receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
 		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 isCurrent = () => owns() && !signal.aborted && runtime === selected && !shuttingDown
+			&& sameSession() && policy() === (accepted ? acceptedPolicy : initialPolicy);
 		const superseded = (): StateFlowTelegramControlResult => {
 			pending.abort();
-			return { ok: false, message: "State Flow activation was superseded", signal: pending.signal };
+			return { ok: false, message: active ? "State Flow activation was superseded" : "State Flow mode change was superseded", signal: pending.signal };
 		};
 		try {
 			const activation = createRuntime(ctx);
@@ -910,28 +921,29 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			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");
+				if (!current && (!active || !branchStartsWithoutRuntime)) throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
 				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 = selectedBoundaryError?.expired;
+				const activated = !active ? deactivateEpisode(current!, "passive")
+					: current ? resumeEpisode(current, bootstrap) : startEpisode(bootstrap);
+				const resumedWrites = modePersistenceError !== undefined;
 				publish(activated);
 				accepted = true;
-				inactivePersistence.cancel();
+				// Passive acceptance runs inside its own inactive-persistence owner.
+				if (active) inactivePersistence.cancel();
 				runtime = selected = activation;
 				snapshot = activated;
 				activeContext = ctx;
-				selectedBoundaryError = undefined;
 				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();
+				passiveContinuation = active ? undefined : continuation;
+				bootstrapContinuation = active && snapshot.meta.bootstrap ? continuation : undefined;
+				if (active) deferInferencePreparation();
 				receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
 				recordPublication();
 				syncStateFlowTools();
@@ -941,21 +953,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner });
 				}
 				appendCheckpoint();
-				ctx.ui.notify(
-					recoveredCurrent
-						? "State Flow active from current session memory; unavailable historical state was not restored."
-						: snapshot.meta.bootstrap
-							? "State Flow active. The next complete agent run will migrate active context into state."
-							: "State Flow active. The next prompt starts a stateful agent run.",
-					"info",
-				);
+				if (!active) {
+					if (resumedWrites) ctx.ui.notify("State Flow passive; memory writes resumed from current session memory.", "info");
+					return { ok: true, message: "State Flow passive", signal: receipt };
+				}
+				ctx.ui.notify(snapshot.meta.bootstrap
+					? "State Flow active. The next complete agent run will migrate active context into state."
+					: "State Flow active. The next prompt starts a stateful agent run.", "info");
 				return { ok: true, message: "State Flow active", signal: receipt };
-			}, signal, branchStartsWithoutRuntime);
+			}, signal, active && branchStartsWithoutRuntime);
 			return isCurrent() ? result : superseded();
 		} catch (error) {
 			if (!isCurrent()) return superseded();
-			const message = conciseDiagnostic(`${accepted ? "State Flow active; lifecycle update failed" : "State Flow activation failed"}: ${diagnosticText(error)}`);
-			notifyProblem(ctx, message, accepted ? "warning" : "error");
+			const message = conciseDiagnostic(`${accepted ? `State Flow ${mode}; lifecycle update failed` : active ? "State Flow activation failed" : "State Flow passive acceptance failed"}: ${diagnosticText(error)}`);
+			// Failed Passive acceptance falls back to its caller's write-fence report.
+			if (active || accepted) notifyProblem(ctx, message, accepted ? "warning" : "error");
 			return { ok: accepted, message, signal: receipt };
 		}
 	}
@@ -987,10 +999,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		},
 	});
 
+	/** Unavailable selection or failed persistence needs current-memory acceptance, not a sticky Passive write fence. */
+	function passiveRecoveryNeeded(mode: InactiveMode): boolean {
+		return mode === "passive" && (modePersistenceError !== undefined || snapshot.meta.validation?.attempt === 0);
+	}
+
 	/** Local policy, tools and UI change before any canonical wait. */
 	function applyInactiveMode(ctx: ExtensionContext, mode: InactiveMode): void {
 		snapshot = deactivateEpisode(snapshot, mode);
-		if (selectedBoundaryError) selectedBoundaryError.blockInference = false;
 		clearRunTransient();
 		syncStateFlowTools();
 		updateUi(ctx);
@@ -1019,7 +1035,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (snapshot.config.mode === mode) {
 			const retained = selectRetainedCheckpoint(discoverSnapshotData(ctx.sessionManager.getBranch()).candidates, config.inactiveMode);
 			const recordedMode = retained.kind === "pre-runtime" ? retained.mode : retained.kind === "boundary" ? retained.checkpoint.mode : undefined;
-			if (modePersistenceError || recordedMode === mode) return Promise.resolve({ ok: true, message: `State Flow is already ${mode}` });
+			if (!passiveRecoveryNeeded(mode) && (modePersistenceError || recordedMode === mode)) return Promise.resolve({ ok: true, message: `State Flow is already ${mode}` });
 		}
 		inactivePersistence.cancel();
 		const pending = inactivePersistence.claim({ controller: new AbortController() });
@@ -1071,7 +1087,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		acquisition.reset();
 		runtime = undefined;
 		snapshot = emptySnapshot("off");
-		selectedBoundaryError = undefined;
 		branchStartsWithoutRuntime = preRuntime;
 		forkInitialization = pendingFork;
 		deferredBranch = { owner: address.key, cwd: ctx.cwd, reason: pendingFork ? "fork" : undefined };
@@ -1113,8 +1128,33 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		const wasActive = current.config.mode === "active";
 		let unfinished = current.meta.specification !== undefined
 			|| (inferencePreparation.current?.prompt !== undefined && !inferencePreparation.current.accepted);
+		const recoverPassive = passiveRecoveryNeeded(mode);
 		applyInactiveMode(ctx, mode);
 		const stoppedAt = Date.now();
+		if (recoverPassive) {
+			const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow mode change was superseded" });
+			const owns = () => inactivePersistence.owns(pending) && !pending.controller.signal.aborted && !shuttingDown;
+			try {
+				// Join pending read-only recovery so its installation cannot supersede this acceptance.
+				const restoring = branchRestoration.current?.operation;
+				if (restoring) await waitForRecovery(restoring, pending.controller.signal);
+			} catch {
+				return superseded();
+			}
+			if (!owns()) return superseded();
+			// Passive is a stable mode: explicit selection accepts validated current memory instead of keeping a write fence.
+			const recovered = await activateCurrentState(ctx, pending.controller, "passive", () => inactivePersistence.owns(pending));
+			if (recovered.ok) pending.published = true;
+			if (recovered.ok || !owns()) return recovered;
+			if (current.config.mode === mode && modePersistenceError) {
+				// The existing native fence already records this policy; report why acceptance still failed.
+				pending.published = true;
+				const message = conciseDiagnostic(`State Flow passive; memory writes remain paused: ${recovered.message}`);
+				notifyProblem(ctx, message, "warning");
+				return { ok: true, message };
+			}
+			selected = runtime;
+		}
 		if (modePersistenceError) {
 			// Writes stay paused; the native marker records only the newly selected inactive policy.
 			pending.published = true;
@@ -1217,6 +1257,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		port: {
 			snapshot: () => ({
 				mode: snapshot.config.mode,
+				inferenceBlocked: isActiveRestorationBlocked(snapshot),
 				step: snapshot.meta.step,
 				revisions: scopeRevisions(),
 				bootstrap: snapshot.meta.bootstrap === true,
@@ -1304,7 +1345,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function prepareContext(messages: AgentMessage[], ctx: ExtensionContext): ReturnType<typeof projectContext> | Promise<ReturnType<typeof projectContext>> {
 		// Pi continues after hook errors; public Abort fences inference instead of exposing the native history fallback.
-		if (selectedBoundaryError?.blockInference && ctx.signal && !shuttingDown) {
+		if (isActiveRestorationBlocked(snapshot) && ctx.signal && !shuttingDown) {
 			ctx.abort();
 			notifyProblem(ctx, "State Flow inference blocked: Active memory restoration failed. Select a valid branch or use /state-flow-active for current memory; /state-flow-passive or /state-flow-off explicitly permits native context.", "error");
 			return;

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

@@ -38,7 +38,7 @@ export function projectDiagnosticContent(content: unknown): StateFlowDiagnosticB
 
 /** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
 export function stateFlowLogPath(agentDir: string): string {
-	return join(agentDir, "tmp", "state-flow", "logs.jsonl");
+	return join(agentDir, "tmp", "pi-state-flow", "logs.jsonl");
 }
 
 function ensureDiagnosticDirectory(path: string): void {

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

@@ -1,4 +1,4 @@
-import { parseRetainedPiCheckpoint, migrationFailure, type InactiveMode, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
+import { parseRetainedPiCheckpoint, migrationFailure, type InactiveMode, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
 
 export type RetainedCheckpointSelection =
 	| { kind: "boundary"; checkpoint: RetainedBoundaryCheckpoint; skipped: string[] }
@@ -45,6 +45,6 @@ export function waitForRecovery<T>(operation: Promise<T>, signal: AbortSignal):
 }
 
 /** A selected boundary that cannot be resolved stays unavailable; callers never fall through to older evidence. */
-export function selectedBoundaryFailure(cause: string, mode: InactiveMode = "passive"): Snapshot {
+export function selectedBoundaryFailure(cause: string, mode: StateFlowMode = "passive"): Snapshot {
 	return migrationFailure({}, `Snapshot restoration failed: ${cause}`, mode);
 }

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

@@ -6,9 +6,9 @@ import { pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenan
 import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction, type StorageTransaction, type TemporalFileBase } from "./storage.ts";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { hashJson, sameJson } from "./json.ts";
-import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
+import { RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
 import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
-import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, selectScopeStreamAtBoundary, validateScopeLineage, type ScopeStream, type TemporalState } from "./temporal.ts";
+import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, validateScopeLineage, type ScopeStream, type TemporalState } from "./temporal.ts";
 
 const SCOPES = ["global", "cwd", "session"] as const;
 const SHARED_SCOPES = ["global", "cwd"] as const;
@@ -24,8 +24,13 @@ export interface RuntimePatchTransaction {
 type PublicationSelection =
 	| { kind: "patch" | "lifecycle" }
 	| { kind: "start"; allowCreateOrigin: boolean }
-	| { kind: "restore"; checkpoint: RetainedBoundaryCheckpoint }
-	| { kind: "fork"; source: SessionAddress; checkpoint: RetainedBoundaryCheckpoint };
+	| { kind: "fork"; source: SessionAddress; lifecycle: ForkLifecycle };
+
+/** Child policy recorded by the native fork; memory always comes from the parent's current files. */
+export interface ForkLifecycle {
+	mode: StateFlowMode;
+	bootstrap?: true;
+}
 
 interface SessionCopy {
 	stream: ScopeStream;
@@ -78,7 +83,6 @@ export class TemporalRuntime {
 	private semanticRevision: string | undefined;
 	private savedRuntime: string | undefined;
 	private transaction: StorageTransaction | undefined;
-	private restoredOriginPending = false;
 	private provenanceByScope: Record<StateScope, ArtifactProvenanceRegistry> = emptyProvenance();
 	/** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
 	private readonly absentSharedScopes = new Set<StateScope>();
@@ -130,7 +134,6 @@ export class TemporalRuntime {
 		this.provenanceByScope = provenance;
 		this.semanticRevision = undefined;
 		this.savedRuntime = undefined;
-		this.restoredOriginPending = false;
 		this.absentSharedScopes.clear();
 		return true;
 	}
@@ -187,80 +190,6 @@ export class TemporalRuntime {
 		return result;
 	}
 
-	/** Prepare a retained session boundary from current canonical files; shared scopes remain live. */
-	prepareBoundaryRestore(checkpoint: RetainedBoundaryCheckpoint): { snapshot: Snapshot; restore: () => Snapshot } {
-		if (!lstatSync(this.root, { throwIfNoEntry: false })) throw new RevisionUnavailableError("Selected State Flow boundary storage is unavailable");
-		return this.prepareBoundaryRestoreBase(checkpoint, captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey));
-	}
-
-	private prepareBoundaryRestoreBase(checkpoint: RetainedBoundaryCheckpoint, base: TemporalFileBase): { snapshot: Snapshot; restore: () => Snapshot } {
-		const files = new Map(base.files.map((file) => [file.path, file.content]));
-		const scopes = Object.fromEntries(SCOPES.map((scope) => {
-			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-			const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope,
-				scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
-			if (!stream) throw new RevisionUnavailableError(`State Flow ${scopeLabel(scope)} scope is unavailable for retained-boundary restoration`);
-			return [scope, stream];
-		})) as Record<StateScope, ScopeStream>;
-		const runtimePaths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
-		const document = parseSessionRuntime(files.get(runtimePaths.config), files.get(runtimePaths.runtime), this.cwd, this.sessionId);
-		if (!document) throw new RevisionUnavailableError("State Flow session runtime is unavailable for retained-boundary restoration");
-		// The codecs validate persisted retention against the format maximum, not the new operator limit.
-		validateScopeLineage(scopes.session, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
-		const boundary = document.meta.lineage.slice(-(this.historyLimit + 1)).find(({ id }) => id === checkpoint.boundary);
-		if (!boundary) throw new HistoryBoundaryExpiredError("Selected State Flow history boundary is outside the retained temporal window");
-		const selectedSession = selectScopeStreamAtBoundary(scopes.session, "session", boundary, MAX_HISTORY_LIMIT);
-		const view = adoptTemporalStreams({
-			global: scopes.global,
-			cwd: scopes.cwd,
-			session: selectedSession,
-		}, `restore:${checkpoint.boundary}:${randomUUID()}`, this.historyLimit);
-		const snapshot: Snapshot = {
-			config: { mode: checkpoint.mode },
-			meta: {
-				step: checkpoint.step,
-				...(checkpoint.bootstrap === true ? { bootstrap: true } : {}),
-				...(checkpoint.specification === undefined ? {} : { specification: checkpoint.specification }),
-			},
-		};
-		const provenance = Object.fromEntries(SCOPES.map((scope) => {
-			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-			const parsed = parseScopeProvenance(files.get(paths.meta), paths.meta);
-			const retained = pruneArtifactProvenance(parsed, readTemporalState(view, 0, scope, this.historyLimit).artifacts);
-			if (scope === "session") {
-				// Live evidence cannot prove an earlier artifact version, even after a change-away-and-back.
-				for (const record of scopes.session.patches) {
-					if (record.transition.position <= boundary.position) continue;
-					for (const path of Object.keys(record.patch.artifacts === null ? retained : record.patch.artifacts ?? {})) delete retained[path];
-				}
-			}
-			return [scope, retained];
-		})) as Record<StateScope, ArtifactProvenanceRegistry>;
-		let consumed = false;
-		return {
-			snapshot: structuredClone(snapshot),
-			restore: () => {
-				if (consumed) throw new Error("Prepared State Flow restore was already consumed");
-				consumed = true;
-				this.view = view;
-				this.base = base;
-				this.provenanceByScope = provenance;
-				this.semanticRevision = undefined;
-				this.savedRuntime = hashJson(createSessionRuntime(snapshot, this.cwd, this.sessionId, view.lineage, provenance.session));
-				this.restoredOriginPending = true;
-				this.absentSharedScopes.clear();
-				return structuredClone(snapshot);
-			},
-		};
-	}
-
-	/** Restore and canonically accept one retained boundary as a single lifecycle operation. */
-	restoreBoundary(checkpoint: RetainedBoundaryCheckpoint): { snapshot: Snapshot; publication: RuntimePublication } {
-		const prepared = this.prepareBoundaryRestore(checkpoint);
-		const snapshot = prepared.restore();
-		return { snapshot, publication: this.acceptRestoredOrigin(snapshot) };
-	}
-
 	/** Await a coherent read-only recovery view; this neither activates policy nor accepts publication authority. */
 	async refreshCurrentMemory(signal?: AbortSignal): Promise<Snapshot | undefined> {
 		signal?.throwIfAborted();
@@ -309,42 +238,10 @@ export class TemporalRuntime {
 		this.provenanceByScope = provenance;
 		this.semanticRevision = undefined;
 		this.savedRuntime = undefined;
-		this.restoredOriginPending = false;
 		this.absentSharedScopes.clear();
 		return snapshot;
 	}
 
-	/** Copy one retained source-session boundary over the child's current shared scopes. */
-	prepareBoundaryFork(source: SessionAddress, checkpoint: RetainedBoundaryCheckpoint): { snapshot: Snapshot; fork: () => { snapshot: Snapshot; publication: RuntimePublication } } {
-		const parent = Object.freeze({ ...source });
-		if (parent.id === this.sessionId || parent.key === this.sessionKey) throw new Error("State Flow fork requires a distinct session identity and key");
-		const sourceRuntime = new TemporalRuntime(this.cwd, parent, this.root, undefined, this.historyLimit);
-		const prepared = sourceRuntime.prepareBoundaryRestore(checkpoint);
-		prepared.restore();
-		const snapshot: Snapshot = {
-			config: structuredClone(prepared.snapshot.config),
-			meta: {
-				step: 0,
-				...(prepared.snapshot.meta.bootstrap === undefined ? {} : { bootstrap: prepared.snapshot.meta.bootstrap }),
-			},
-		};
-		let consumed = false;
-		return {
-			snapshot: structuredClone(snapshot),
-			fork: () => {
-				if (consumed) throw new Error("Prepared State Flow fork was already consumed");
-				consumed = true;
-				if (this.view) throw new Error("State Flow fork target already has session storage");
-				const publication = this.initializeOrigin(snapshot, { allowCreateCwd: false, copy: {
-					stream: sourceRuntime.view!.scopes.session,
-					provenance: sourceRuntime.artifactProvenance("session"),
-				} });
-				if (!publication?.revision) throw new Error("State Flow fork requires existing shared scope storage");
-				return { snapshot: structuredClone(snapshot), publication };
-			},
-		};
-	}
-
 	initialize(snapshot: Snapshot, allowCreateCwd: boolean, expectedShared?: Pick<ScopedStates, "global" | "cwd">, newSessionOrigin = false): RuntimePublication | undefined {
 		return this.initializeOrigin(snapshot, { allowCreateCwd, expectedShared, newSessionOrigin });
 	}
@@ -518,7 +415,6 @@ export class TemporalRuntime {
 
 	/** Prepare current shared state while retaining the exact accepted private publication basis. */
 	private publicationCandidate(storage: StorageTransaction, current?: TemporalFileBase): TemporalRuntime {
-		if (this.restoredOriginPending) throw new RevisionUnavailableError("State Flow restored origin must be accepted before patching memory");
 		current ??= storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
 		candidate.transaction = storage;
@@ -573,26 +469,19 @@ export class TemporalRuntime {
 		return this.withPublicationTransaction((_candidate, publish, current) => action(current, (snapshot) => publish(snapshot)), { kind: "start", allowCreateOrigin }, signal);
 	}
 
-	/** Select one retained private boundary beside current shared streams, then accept only after caller policy is rechecked. */
-	async withRestoreTransaction<T>(checkpoint: RetainedBoundaryCheckpoint, action: (selected: Snapshot, publish: (snapshot: Snapshot) => RuntimePublication) => T, signal?: AbortSignal): Promise<T> {
-		signal?.throwIfAborted();
-		return this.withPublicationTransaction((_candidate, publish, selected) => action(selected!, (snapshot) => publish(snapshot)),
-			{ kind: "restore", checkpoint: structuredClone(checkpoint) }, signal);
-	}
-
-	/** Copy exact retained parent authority into an unoccupied child; the caller rechecks native selection after waiting. */
-	async withForkTransaction<T>(source: SessionAddress, checkpoint: RetainedBoundaryCheckpoint, action: (selected: Snapshot, publish: (snapshot: Snapshot) => RuntimePublication) => T, signal?: AbortSignal): Promise<T> {
+	/** Copy the parent's current session memory into an unoccupied child; the caller rechecks native selection after waiting. */
+	async withForkTransaction<T>(source: SessionAddress, lifecycle: ForkLifecycle, action: (selected: Snapshot, publish: (snapshot: Snapshot) => RuntimePublication) => T, signal?: AbortSignal): Promise<T> {
 		signal?.throwIfAborted();
 		return this.withPublicationTransaction((_candidate, publish, selected) => action(selected!, (snapshot) => publish(snapshot)),
-			{ kind: "fork", source: { ...source }, checkpoint: structuredClone(checkpoint) }, signal);
+			{ kind: "fork", source: { ...source }, lifecycle: { mode: lifecycle.mode, ...(lifecycle.bootstrap ? { bootstrap: true as const } : {}) } }, signal);
 	}
 
-	private prepareForkCandidate(storage: StorageTransaction, source: SessionAddress, checkpoint: RetainedBoundaryCheckpoint): {
+	private prepareForkCandidate(storage: StorageTransaction, source: SessionAddress, lifecycle: ForkLifecycle): {
 		candidate: TemporalRuntime; current: Snapshot; assertSource: () => void;
 	} {
 		const sourceBase = storage.capture(this.cwd, source.id, this.root, source.key);
 		const parent = new TemporalRuntime(this.cwd, source, this.root, undefined, this.historyLimit);
-		const selected = parent.prepareBoundaryRestoreBase(checkpoint, sourceBase).restore();
+		if (!parent.loadCurrentMemoryBase(sourceBase)) throw new RevisionUnavailableError("State Flow fork parent memory is unavailable");
 		const base = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const files = new Map(base.files.map((file) => [file.path, file.content]));
 		const paths = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
@@ -613,7 +502,7 @@ export class TemporalRuntime {
 		}
 		return {
 			candidate,
-			current: { config: selected.config, meta: { step: 0, ...(selected.meta.bootstrap === undefined ? {} : { bootstrap: selected.meta.bootstrap }) } },
+			current: { config: { mode: lifecycle.mode }, meta: { step: 0, ...(lifecycle.bootstrap ? { bootstrap: true } : {}) } },
 			assertSource: () => assertTemporalFileBase(sourceBase, storage.capture(this.cwd, source.id, this.root, source.key)),
 		};
 	}
@@ -635,15 +524,15 @@ export class TemporalRuntime {
 				if (selection.source.id === this.sessionId || selection.source.key === this.sessionKey) throw new Error("State Flow fork requires a distinct session identity and key");
 				if (this.view) throw new Error("State Flow fork target already has session storage");
 			}
-			if (!semantic && (!this.semanticRevision || !this.view || !this.base || this.restoredOriginPending)) {
+			if (!semantic && (!this.semanticRevision || !this.view || !this.base)) {
 				throw new Error("State Flow lifecycle transaction requires an accepted runtime");
 			}
 		};
 		signal?.throwIfAborted();
 		assertAuthority();
 		if (kind === "patch" || allowCreateOrigin) initializeFileStore(this.root);
-		if ((kind === "start" || kind === "restore" || kind === "fork") && !lstatSync(this.root, { throwIfNoEntry: false })) {
-			throw new RevisionUnavailableError(kind !== "start" ? "Selected State Flow boundary storage is unavailable" : "Current State Flow session storage is unavailable");
+		if ((kind === "start" || kind === "fork") && !lstatSync(this.root, { throwIfNoEntry: false })) {
+			throw new RevisionUnavailableError(kind === "fork" ? "State Flow fork parent storage is unavailable" : "Current State Flow session storage is unavailable");
 		}
 		return withStorageTransaction(this.root, (storage) => {
 			assertAuthority();
@@ -651,14 +540,12 @@ export class TemporalRuntime {
 			let candidate: TemporalRuntime;
 			let assertSource: (() => void) | undefined;
 			if (selection.kind === "fork") {
-				({ candidate, current, assertSource } = this.prepareForkCandidate(storage, selection.source, selection.checkpoint));
-			} else if (selection.kind === "restore" || selection.kind === "start") {
+				({ candidate, current, assertSource } = this.prepareForkCandidate(storage, selection.source, selection.lifecycle));
+			} else if (selection.kind === "start") {
 				candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
 				candidate.transaction = storage;
 				const base = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
-				current = selection.kind === "restore"
-					? candidate.prepareBoundaryRestoreBase(selection.checkpoint, base).restore()
-					: candidate.loadCurrentMemoryBase(base);
+				current = candidate.loadCurrentMemoryBase(base);
 				if (!current) {
 					if (!allowCreateOrigin) throw new RevisionUnavailableError("Current State Flow session memory is unavailable");
 					if (SCOPES.some((scope) => lstatSync(join(temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).directory, "state.json"), { throwIfNoEntry: false }))) {
@@ -676,7 +563,7 @@ export class TemporalRuntime {
 				assertSource?.();
 				// Patch preparation without semantic work preserves complete accepted cohorts; selection accepts origins with configured folding.
 				// New authority or wholly absent shared pairs still need normal atomic initialization; partial evidence already failed.
-				const writeSemantic = semantic && (kind === "start" || kind === "restore" || kind === "fork" || accepted !== undefined || !this.semanticRevision
+				const writeSemantic = semantic && (kind === "start" || kind === "fork" || accepted !== undefined || !this.semanticRevision
 					|| SCOPES.some((scope) => Object.keys(provenance?.[scope] ?? {}).length > 0)
 					|| candidate.base!.files.some((file) => file.content === undefined));
 				// Every capability acceptance validates its captured cohort, including semantic no-ops.
@@ -687,7 +574,6 @@ export class TemporalRuntime {
 				this.provenanceByScope = candidate.provenanceByScope;
 				this.semanticRevision = candidate.semanticRevision;
 				this.savedRuntime = candidate.savedRuntime;
-				this.restoredOriginPending = false;
 				this.absentSharedScopes.clear();
 				published = true;
 				return publication;
@@ -697,15 +583,6 @@ export class TemporalRuntime {
 		}, signal);
 	}
 
-	/** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
-	acceptRestoredOrigin(snapshot: Snapshot): RuntimePublication {
-		if (!this.restoredOriginPending) throw new Error("State Flow has no prepared restored origin to accept");
-		const publication = this.publish(snapshot, true);
-		if (!publication) throw new Error("State Flow restored origin produced no canonical publication");
-		this.restoredOriginPending = false;
-		return publication;
-	}
-
 	publish(
 		snapshot: Snapshot,
 		semantic = false,
@@ -713,7 +590,6 @@ export class TemporalRuntime {
 		options: { provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>> } = {},
 	): RuntimePublication | undefined {
 		if (!this.view || !this.base) throw new Error("State Flow temporal publication is unavailable; restore or initialize before accepting a transition");
-		if (this.restoredOriginPending && !semantic) throw new Error("State Flow restored origin must be accepted before runtime-only persistence");
 		// Explicit evidence updates still own a scope CAS, even if they equal the stale cache.
 		const provenanceScopes = SCOPES.filter((scope) => Object.keys(options.provenance?.[scope] ?? {}).length > 0);
 		const runtimeOnly = !semantic && accepted === undefined && provenanceScopes.length === 0;