@llblab/pi-kit 0.24.1 → 0.26.0

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

@@ -1,11 +1,11 @@
 /** Await a coherent capture; hosts without cancellation may refuse contention instead of hanging Abort. */
 export declare function backupCurrentStateFlowFiles(repositoryRoot: string, signal?: AbortSignal, waitForLock?: boolean): Promise<string | undefined>;
 /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
-export declare function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean;
+export declare function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void, signal?: AbortSignal): boolean;
 /** Resolve only after the push process has closed (including timeout termination). */
 export declare function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void>;
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
-export declare function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{
+export declare function pushCurrentStateFlowBackup(repositoryRoot: string, signal?: AbortSignal): Promise<{
     commit: string;
     remote: string;
     ref: string;

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

@@ -204,18 +204,20 @@ export function backupCurrentStateFlowFiles(repositoryRoot, signal, waitForLock
     return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root), signal, waitForLock), signal, waitForLock);
 }
 /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
-export function startStateFlowBackupPush(repositoryRoot, onFailure, onSuccess) {
+export function startStateFlowBackupPush(repositoryRoot, onFailure, onSuccess, signal) {
     const root = resolve(repositoryRoot);
-    if (activePushes.has(root))
+    if (signal?.aborted || activePushes.has(root))
         return false;
-    const push = pushCurrentStateFlowBackup(root).then((result) => {
-        if (result) {
+    const push = pushCurrentStateFlowBackup(root, signal).then((result) => {
+        if (result && !signal?.aborted) {
             try {
                 onSuccess?.();
             }
             catch { /* Reporting cannot change push acceptance. */ }
         }
     }, (error) => {
+        if (signal?.aborted)
+            return;
         try {
             onFailure(error);
         }
@@ -231,15 +233,17 @@ export async function awaitInFlightBackupPushes(repositoryRoot) {
         await push;
 }
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
-export function pushCurrentStateFlowBackup(repositoryRoot) {
+export function pushCurrentStateFlowBackup(repositoryRoot, signal) {
     return new Promise((resolvePush, rejectPush) => {
         let root;
         let commit;
         let destination;
         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))));
@@ -282,6 +286,7 @@ export function pushCurrentStateFlowBackup(repositoryRoot) {
                 return;
             settled = true;
             clearTimeout(timeout);
+            signal?.removeEventListener("abort", cancelled);
             if (error)
                 rejectPush(error);
             else
@@ -297,5 +302,11 @@ export function pushCurrentStateFlowBackup(repositoryRoot) {
             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() {
+            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/dist/lib/history.d.ts

@@ -1,10 +1,17 @@
-import type { ScopePatch, ScopedStates, StateScope } from "./state.ts";
+import { type JsonObject, type JsonValue } from "./json.ts";
+import type { ScopedSemanticStates, StateScope } from "./state.ts";
 export declare const DEFAULT_HISTORY_LIMIT = 7;
 export declare const MAX_HISTORY_LIMIT = 100;
 export interface RecentScopePatch {
     scope: StateScope;
-    patch: ScopePatch & {
-        response?: string;
+    patch: {
+        [key: string]: JsonValue | undefined;
+        intents?: JsonObject | null;
+        contract?: JsonObject | null;
+        working?: JsonObject | null;
+        artifacts?: JsonObject | null;
+        lazy?: JsonObject | null;
+        response?: string | null;
     };
 }
 /** Exact accepted replay cohort; temporal runtime owns its causal boundary. */
@@ -18,6 +25,6 @@ export interface RecentTransition extends AcceptedTransition {
 }
 export type RecentTransitionWindow = RecentTransition[];
 export declare function validateRecentTransition(value: unknown): asserts value is RecentTransition;
-export declare function createAcceptedTransition(currentStates: ScopedStates, nextStates: ScopedStates, id?: string): AcceptedTransition | undefined;
+export declare function createAcceptedTransition(currentStates: ScopedSemanticStates, nextStates: ScopedSemanticStates, id?: string): AcceptedTransition | undefined;
 /** Preserve the configured per-scope budget, filtering in selected-lineage order. */
 export declare function projectRecentTransitionsWithLimit(limit: number, lineage: readonly RecentTransition[]): RecentTransitionWindow;

package/node_modules/@llblab/pi-state-flow/dist/lib/history.js

@@ -30,13 +30,10 @@ function validateScopedPatch(value) {
     validatePatch(value.patch);
     for (const [key, field] of Object.entries(value.patch)) {
         const valid = key === "response"
-            ? value.scope === "session" && typeof field === "string"
-            : key === "lazy"
-                ? field !== null
-                : PATCH_KEYS.has(key) && isObject(field);
-        if (!PATCH_KEYS.has(key) || !valid) {
-            throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
-        }
+            ? value.scope === "session" && (field === null || typeof field === "string")
+            : !PATCH_KEYS.has(key) || field === null || isObject(field);
+        if (!valid)
+            throw new Error("Recent State Flow patches require object planes or deletion, and a session response string or deletion");
     }
 }
 export function validateRecentTransition(value) {
@@ -60,6 +57,8 @@ export function createAcceptedTransition(currentStates, nextStates, id) {
     const transitions = [];
     for (const scope of SCOPES) {
         const patch = replayPatch(currentStates[scope], nextStates[scope]);
+        if ((currentStates[scope].response ?? "") === (nextStates[scope].response ?? ""))
+            delete patch.response;
         if (Object.keys(patch).length > 0)
             transitions.push({ scope, patch });
     }

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

@@ -1,4 +1,4 @@
-export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization";
+export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block";
 /** Minimal structural block; only ordinary text keeps its exact content. */
 export interface StateFlowDiagnosticBlock {
     type: string;
@@ -15,6 +15,8 @@ export interface StateFlowDiagnosticRecord {
     input?: unknown;
     tool?: string;
     toolCallId?: string;
+    /** Names only, in native assistant-batch order; never sibling arguments. */
+    batchToolNames?: string[];
 }
 /** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
 export declare function projectDiagnosticContent(content: unknown): StateFlowDiagnosticBlock[];
@@ -26,6 +28,7 @@ export interface DiagnosticExtras {
     input?: unknown;
     tool?: string;
     toolCallId?: string;
+    batchToolNames?: readonly string[];
 }
 /** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
 export declare class StateFlowDiagnosticWriter {

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

@@ -77,6 +77,7 @@ export class StateFlowDiagnosticWriter {
                 ...(extras.input === undefined ? {} : { input: extras.input }),
                 ...(extras.tool === undefined ? {} : { tool: extras.tool }),
                 ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
+                ...(extras.batchToolNames === undefined ? {} : { batchToolNames: [...extras.batchToolNames] }),
             });
             return true;
         }

package/node_modules/@llblab/pi-state-flow/dist/lib/query.d.ts

@@ -1,5 +1,6 @@
+import { type RecentScopePatch } from "./history.ts";
 import { type JsonValue } from "./json.ts";
-import { type ModelState, type ScopePatch, type StateScope } from "./state.ts";
+import { type SemanticState, type StateScope } from "./state.ts";
 import { type TemporalState, type TransitionBoundary } from "./temporal.ts";
 export type StateReadQuery = {
     kind: "state";
@@ -15,13 +16,11 @@ export type StateReadQuery = {
 export type StateReadResult = {
     path: string;
     boundary: TransitionBoundary;
-    state: ModelState;
+    state: SemanticState;
 } | {
     path: string;
     boundary: TransitionBoundary;
-    patch: ScopePatch & {
-        response?: string;
-    };
+    patch: RecentScopePatch["patch"];
 };
 export type StateReadProjection = "value" | "keys" | "patch";
 type StateReadMeta = {

package/node_modules/@llblab/pi-state-flow/dist/lib/query.js

@@ -1,7 +1,7 @@
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { isObject, sameJson } from "./json.js";
-import { projectStateForModel } from "./state.js";
-import { readTemporalState } from "./temporal.js";
+import { emptyState, projectSemanticPatch, projectStateForModel } from "./state.js";
+import { readTemporalView } from "./temporal.js";
 const MAX_REFERENCE_SOURCES = 3;
 const MAX_REFERENCE_SCAN_NODES = 10_000;
 const PATH_PATTERN = /^(effective|global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?$/;
@@ -32,12 +32,12 @@ export function readStatePath(view, path, historyLimit = DEFAULT_HISTORY_LIMIT)
         const boundary = view.lineage[view.lineage.length - 1 - query.offset];
         if (!boundary)
             throw new Error("Requested history predates the proven temporal origin");
-        return { path, boundary: structuredClone(boundary), state: projectStateForModel(readTemporalState(view, query.offset, query.scope, historyLimit)) };
+        return { path, boundary: structuredClone(boundary), state: projectStateForModel(readTemporalView(view, query.offset, query.scope, historyLimit)) };
     }
     const record = view.scopes[query.scope].patches.at(-1 - query.offset);
     if (!record)
         throw new Error(`Requested ${query.scope} patch predates retained hot history`);
-    return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
+    return { path, boundary: structuredClone(record.transition), patch: projectSemanticPatch(record.patch) };
 }
 function parseValuePath(path) {
     const explicitRoot = /^(?:effective|global|cwd|session)(?:\[\d+\])?(?=\.|$)/.exec(path)?.[0];
@@ -151,7 +151,7 @@ export function findStateReferenceSources(view, path, historyLimit = DEFAULT_HIS
         }
     };
     for (const scope of ["global", "cwd", "session"]) {
-        const state = readTemporalState(view, 0, scope, historyLimit);
+        const state = readTemporalView(view, 0, scope, historyLimit);
         for (const plane of ["artifacts", "contract", "working", "intents", "lazy"]) {
             const value = state[plane];
             if (value !== undefined)
@@ -201,13 +201,13 @@ function patchAtPath(view, root, selectors, path, historyLimit) {
         throw new Error("Requested history predates the proven temporal origin");
     let patch = {};
     if (rootQuery.scope) {
-        patch = structuredClone(view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {});
+        patch = projectSemanticPatch((view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {}));
     }
     else {
         const before = view.lineage.at(-2 - rootQuery.offset);
         if (before) {
-            const current = readTemporalState(view, rootQuery.offset, undefined, historyLimit);
-            const previous = readTemporalState(view, rootQuery.offset + 1, undefined, historyLimit);
+            const current = readTemporalView(view, rootQuery.offset, undefined, historyLimit);
+            const previous = readTemporalView(view, rootQuery.offset + 1, undefined, historyLimit);
             patch = diffObjects(previous, current);
         }
     }
@@ -270,11 +270,11 @@ export function readProjectedState(view, paths, projection = "value", historyLim
             if (query.kind !== "state")
                 throw new Error("Value and keys projections require a state path");
             const readsLazy = selectors[0]?.kind === "key" && selectors[0].key === "lazy";
-            const state = readsLazy
-                ? readTemporalState(view, query.offset, query.scope, historyLimit)
-                : projectStateForModel(readTemporalState(view, query.offset, query.scope, historyLimit));
-            if (readsLazy && !Object.hasOwn(state, "lazy"))
-                state.lazy = {};
+            const raw = readTemporalView(view, query.offset, query.scope, historyLimit);
+            const state = readsLazy ? raw : projectStateForModel(raw);
+            const field = selectors.length === 1 && selectors[0]?.kind === "key" ? selectors[0].key : undefined;
+            if (projection === "value" && field !== undefined && Object.hasOwn(emptyState(), field) && !Object.hasOwn(state, field))
+                return { value: null };
             return projectValue(selectValue(state, selectors, path), projection);
         }
         catch (error) {

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

@@ -1,19 +1,20 @@
-import { type RetainedBoundaryCheckpoint, type Snapshot } from "./snapshot.ts";
+import { type InactiveMode, type RetainedBoundaryCheckpoint, type Snapshot } from "./snapshot.ts";
 export type RetainedCheckpointSelection = {
     kind: "boundary";
     checkpoint: RetainedBoundaryCheckpoint;
     skipped: string[];
 } | {
-    kind: "disabled";
+    kind: "pre-runtime";
+    mode: InactiveMode;
     skipped: string[];
 } | {
     kind: "unavailable";
     snapshot: Snapshot;
     skipped: string[];
 };
-/** Select the newest supported retained-boundary checkpoint or disabled marker; unsupported pointers fail closed. */
-export declare function selectRetainedCheckpoint(candidates: readonly unknown[]): RetainedCheckpointSelection;
-/** Withdraw a caller's join without cancelling independently owned recovery or Stop persistence. */
+/** Select the newest supported retained-boundary checkpoint or pre-runtime mode; unsupported pointers fail closed. */
+export declare function selectRetainedCheckpoint(candidates: readonly unknown[], inactiveMode?: InactiveMode): RetainedCheckpointSelection;
+/** Withdraw a caller's join without cancelling independently owned recovery or mode persistence. */
 export declare function waitForRecovery<T>(operation: Promise<T>, signal: AbortSignal): Promise<T>;
 /** A selected boundary that cannot be resolved stays unavailable; callers never fall through to older evidence. */
-export declare function selectedBoundaryFailure(cause: string): Snapshot;
+export declare function selectedBoundaryFailure(cause: string, mode?: InactiveMode): Snapshot;

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

@@ -1,28 +1,28 @@
 import { parseRetainedPiCheckpoint, migrationFailure } from "./snapshot.js";
-/** Select the newest supported retained-boundary checkpoint or disabled marker; unsupported pointers fail closed. */
-export function selectRetainedCheckpoint(candidates) {
+/** Select the newest supported retained-boundary checkpoint or pre-runtime mode; unsupported pointers fail closed. */
+export function selectRetainedCheckpoint(candidates, inactiveMode = "passive") {
     const skipped = [];
     for (const candidate of candidates) {
         let retained;
         try {
             if (typeof candidate === "object" && candidate !== null && Object.hasOwn(candidate, "revision")) {
-                return { kind: "unavailable", snapshot: migrationFailure({}, "Snapshot restoration failed: revision-pointer checkpoints are unsupported"), skipped };
+                return { kind: "unavailable", snapshot: migrationFailure({}, "Snapshot restoration failed: revision-pointer checkpoints are unsupported", inactiveMode), skipped };
             }
-            retained = parseRetainedPiCheckpoint(candidate);
+            retained = parseRetainedPiCheckpoint(candidate, inactiveMode);
         }
         catch (error) {
             skipped.push(`Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`);
             continue;
         }
-        return "disabled" in retained ? { kind: "disabled", skipped } : { kind: "boundary", checkpoint: retained, skipped };
+        return "boundary" in retained ? { kind: "boundary", checkpoint: retained, skipped } : { kind: "pre-runtime", mode: retained.mode, skipped };
     }
     return {
         kind: "unavailable",
-        snapshot: migrationFailure({}, skipped[0] ?? "Snapshot restoration failed: no supported checkpoint"),
+        snapshot: migrationFailure({}, skipped[0] ?? "Snapshot restoration failed: no supported checkpoint", inactiveMode),
         skipped,
     };
 }
-/** Withdraw a caller's join without cancelling independently owned recovery or Stop persistence. */
+/** Withdraw a caller's join without cancelling independently owned recovery or mode persistence. */
 export function waitForRecovery(operation, signal) {
     return new Promise((resolve, reject) => {
         const aborted = () => reject(signal.reason);
@@ -42,6 +42,6 @@ export function waitForRecovery(operation, signal) {
     });
 }
 /** A selected boundary that cannot be resolved stays unavailable; callers never fall through to older evidence. */
-export function selectedBoundaryFailure(cause) {
-    return migrationFailure({}, `Snapshot restoration failed: ${cause}`);
+export function selectedBoundaryFailure(cause, mode = "passive") {
+    return migrationFailure({}, `Snapshot restoration failed: ${cause}`, mode);
 }

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

@@ -3,11 +3,11 @@ import { type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./arti
 import { publishTemporalStateToFiles } from "./storage.ts";
 import { type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
-import { type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
 import { type TemporalState } from "./temporal.ts";
 export type RuntimePublication = ReturnType<typeof publishTemporalStateToFiles>;
 export interface RuntimePatchTransaction {
-    readonly states: ScopedStates;
+    readonly states: ScopedSemanticStates;
     readonly causalBasis: string;
     readonly provenance: Record<StateScope, ArtifactProvenanceRegistry>;
     publish(snapshot: Snapshot, accepted?: AcceptedTransition, provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>>): RuntimePublication;
@@ -45,6 +45,7 @@ export declare class TemporalRuntime {
     /** Canonical preparation is the default; Git backup is a later independent concern. */
     prepare(): void;
     read(offset?: number, scope?: StateScope): MaterializedState;
+    readView(offset?: number, scope?: StateScope): SemanticState;
     states(): ScopedStates;
     causalBasis(): string;
     /** Encode Pi lifecycle state against the current retained semantic boundary. */

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

@@ -6,9 +6,8 @@ import { pruneArtifactProvenance } from "./artifact.js";
 import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction } from "./storage.js";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { hashJson, sameJson } from "./json.js";
-import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, retainedBoundaryCheckpoint } from "./snapshot.js";
-import { emptyState } from "./state.js";
-import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalState, selectScopeStreamAtBoundary, validateScopeLineage } from "./temporal.js";
+import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint } from "./snapshot.js";
+import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, selectScopeStreamAtBoundary, validateScopeLineage } from "./temporal.js";
 const SCOPES = ["global", "cwd", "session"];
 const SHARED_SCOPES = ["global", "cwd"];
 function emptyProvenance() {
@@ -42,7 +41,7 @@ function removedTargetScopeConflict(scopes) {
     return new SharedScopeRemovalConflictError(scopes);
 }
 function freshEmptyScopeStream(scope, origin, historyLimit) {
-    return createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, origin, historyLimit).scopes[scope];
+    return createTemporalState({ global: {}, cwd: {}, session: {} }, origin, historyLimit).scopes[scope];
 }
 /** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
 export class TemporalRuntime {
@@ -89,7 +88,7 @@ export class TemporalRuntime {
             return false;
         if (!shared.global)
             throw new Error("Incomplete passive State Flow shared storage: CWD state exists without global state");
-        const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
+        const fresh = createTemporalState({ global: {}, cwd: {}, session: {} }, randomUUID(), this.historyLimit);
         // Global memory is valid before this CWD has ever materialized its own scope.
         const view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd ?? fresh.scopes.cwd, session: fresh.scopes.session }, `passive:files:${randomUUID()}`, this.historyLimit);
         const provenance = {
@@ -119,6 +118,11 @@ export class TemporalRuntime {
             throw new Error("State Flow temporal runtime is unavailable");
         return readTemporalState(this.view, offset, scope, this.historyLimit);
     }
+    readView(offset = 0, scope) {
+        if (!this.view)
+            throw new Error("State Flow temporal runtime is unavailable");
+        return readTemporalView(this.view, offset, scope, this.historyLimit);
+    }
     states() {
         return { global: this.read(0, "global"), cwd: this.read(0, "cwd"), session: this.read(0, "session") };
     }
@@ -130,7 +134,7 @@ export class TemporalRuntime {
     /** Encode Pi lifecycle state against the current retained semantic boundary. */
     retainedCheckpoint(snapshot) {
         if (!this.view)
-            return { disabled: true };
+            return preRuntimeCheckpoint(snapshot.config.mode);
         return retainedBoundaryCheckpoint(snapshot, this.causalBasis());
     }
     usesCanonicalFiles() {
@@ -179,7 +183,7 @@ export class TemporalRuntime {
             session: selectedSession,
         }, `restore:${checkpoint.boundary}:${randomUUID()}`, this.historyLimit);
         const snapshot = {
-            config: { enabled: checkpoint.enabled },
+            config: { mode: checkpoint.mode },
             meta: {
                 step: checkpoint.step,
                 ...(checkpoint.bootstrap === true ? { bootstrap: true } : {}),
@@ -195,7 +199,7 @@ export class TemporalRuntime {
                 for (const record of scopes.session.patches) {
                     if (record.transition.position <= boundary.position)
                         continue;
-                    for (const path of Object.keys(record.patch.artifacts ?? {}))
+                    for (const path of Object.keys(record.patch.artifacts === null ? retained : record.patch.artifacts ?? {}))
                         delete retained[path];
                 }
             }
@@ -266,8 +270,9 @@ export class TemporalRuntime {
             const meta = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).meta;
             return [scope, parseScopeProvenance(files.get(meta), meta)];
         }));
+        // Read-only recovery grants no active policy; callers select the inactive mode.
         const snapshot = {
-            config: { enabled: false },
+            config: { mode: "passive" },
             meta: { step: document.meta.step, ...(document.meta.bootstrap === true ? { bootstrap: true } : {}) },
         };
         this.view = view;
@@ -355,7 +360,7 @@ export class TemporalRuntime {
             streams.session = undefined;
         if (copy)
             streams.session = copy.stream;
-        const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
+        const fresh = createTemporalState({ global: {}, cwd: {}, session: {} }, randomUUID(), this.historyLimit);
         const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
         candidate.base = base;
         candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `files:${randomUUID()}`, this.historyLimit);
@@ -512,7 +517,7 @@ export class TemporalRuntime {
             if (!document || !stream)
                 throw new RevisionUnavailableError("Current State Flow session memory is incomplete");
             validateScopeLineage(stream, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
-            throw new RevisionUnavailableError("Existing State Flow session memory is not selected; select an accepted boundary or use /state-flow-start");
+            throw new RevisionUnavailableError("Existing State Flow session memory is not selected; select an accepted boundary or use /state-flow-active");
         }
         const origin = `patch:${randomUUID()}`;
         const streams = Object.fromEntries(SCOPES.map((scope) => {
@@ -531,7 +536,7 @@ export class TemporalRuntime {
     /** Stage and accept synchronously inside an awaited lock; expose neither selection nor raw storage operations. */
     async withPatchTransaction(action, signal) {
         return this.withPublicationTransaction((candidate, publish) => action({
-            states: candidate.states(),
+            states: readTemporalScopes(candidate.view, 0, this.historyLimit),
             causalBasis: candidate.causalBasis(),
             provenance: structuredClone(candidate.provenanceByScope),
             publish,

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

@@ -1,3 +1,4 @@
+import { type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 export declare const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 interface BranchEntry {
     type?: unknown;
@@ -21,8 +22,12 @@ export interface PassiveStopBoundary {
     at: number;
     from?: number;
     preserveContext?: true;
-    /** A same-owner failed Stop remains a write fence until a later accepted checkpoint. */
+    /** A same-owner failed mode change remains a write fence until a later accepted checkpoint. */
     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 {
     candidates: unknown[];
@@ -30,6 +35,13 @@ export interface SnapshotDiscovery {
 }
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export declare function discoverSnapshotData(branch: readonly BranchEntry[]): SnapshotDiscovery;
+/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
+export declare function findBranchPolicy(branch: readonly BranchEntry[], sessionId: string | undefined, stopEntryType: string | undefined, inactiveMode: InactiveMode): {
+    mode: StateFlowMode;
+    persistenceError?: string;
+} | undefined;
+/** Native policy bookkeeping retains an unacquired fork across extension reloads. */
+export declare function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean;
 export declare function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[];
 export declare function latestSnapshotData(branch: readonly BranchEntry[]): unknown;
 export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;

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

@@ -1,4 +1,4 @@
-import { parseRetainedPiCheckpoint } from "./snapshot.js";
+import { parseRetainedPiCheckpoint, readCheckpointMode } from "./snapshot.js";
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export function discoverSnapshotData(branch) {
@@ -16,6 +16,65 @@ export function discoverSnapshotData(branch) {
     }
     return { candidates, errors };
 }
+/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
+export function findBranchPolicy(branch, sessionId, stopEntryType, inactiveMode) {
+    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;
+                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;
+                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, sessionId, entryType) {
+    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;
+            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) {
     return discoverSnapshotData(branch).candidates;
 }
@@ -92,7 +151,7 @@ export function findPassiveStopBoundary(branch, sessionId, entryType) {
             }
             if (entry.customType !== entryType)
                 continue;
-            const { at, from, reset, owner, preserveContext, persistenceError } = entry.data ?? {};
+            const { at, from, reset, owner, preserveContext, persistenceError, mode } = entry.data ?? {};
             if (reset === true && owner === sessionId)
                 return undefined;
             if (owner !== undefined && owner !== sessionId)
@@ -103,6 +162,7 @@ export function findPassiveStopBoundary(branch, sessionId, entryType) {
                     ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
                     ...(preserveContext === true ? { preserveContext: true } : {}),
                     ...(!checkpointSeen && owner === sessionId && typeof persistenceError === "string" && persistenceError.trim().length > 0 ? { persistenceError } : {}),
+                    ...(mode === "passive" || mode === "off" ? { mode } : {}),
                 };
         }
         catch {