@llblab/pi-kit 0.24.0 → 0.25.0

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 } from "./snapshot.ts";
 export declare const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 interface BranchEntry {
     type?: unknown;
@@ -21,8 +22,10 @@ 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;
 }
 export interface SnapshotDiscovery {
     candidates: unknown[];

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

@@ -92,7 +92,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 +103,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 {

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

@@ -7,8 +7,12 @@ export declare class RevisionUnavailableError extends Error {
 /** Expired history cannot be restored, but explicit activation may use validated current memory. */
 export declare class HistoryBoundaryExpiredError extends RevisionUnavailableError {
 }
+export type StateFlowMode = "active" | "passive" | "off";
+export type InactiveMode = Exclude<StateFlowMode, "active">;
+export declare function isStateFlowMode(value: unknown): value is StateFlowMode;
+/** The session's selected mode is the only serialized behavior switch. */
 export interface SnapshotConfig {
-    enabled: boolean;
+    mode: StateFlowMode;
 }
 interface LegacyValidationFeedback {
     attempt: number;
@@ -52,23 +56,28 @@ export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: st
     config: string;
     runtime: string;
 };
+/** Legacy `enabled:false` decodes as non-active; native checkpoints, not this file, select branch policy. */
 export declare function parseSessionRuntime(config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined;
-export declare function emptySnapshot(enabled?: boolean): Snapshot;
+export declare function emptySnapshot(mode?: StateFlowMode): Snapshot;
 export type RetainedBoundaryCheckpoint = {
     boundary: string;
-    enabled: boolean;
+    mode: StateFlowMode;
     step: number;
     bootstrap?: true;
     specification?: string;
 };
-export type RetainedPiCheckpoint = RetainedBoundaryCheckpoint | {
-    disabled: true;
+/** A proven pre-runtime branch retains only its explicit inactive choice, never semantic storage. */
+export type PreRuntimeCheckpoint = {
+    mode: InactiveMode;
 };
+export type RetainedPiCheckpoint = RetainedBoundaryCheckpoint | PreRuntimeCheckpoint;
 export type FileRevision = `file:${string}`;
 export declare function isFileRevision(value: unknown): value is FileRevision;
 /** Encode branch lifecycle against one retained temporal identity without semantic or backup data. */
 export declare function retainedBoundaryCheckpoint(snapshot: Snapshot, boundary: string): RetainedBoundaryCheckpoint;
-/** Decode the 0.17 retained-window checkpoint contract. */
-export declare function parseRetainedPiCheckpoint(value: unknown): RetainedPiCheckpoint;
-export declare function migrationFailure(data: JsonObject, error: string): Snapshot;
+/** Encode an explicit inactive choice on a branch that has no accepted runtime. */
+export declare function preRuntimeCheckpoint(mode: StateFlowMode): PreRuntimeCheckpoint;
+/** Decode the retained-window checkpoint contract; legacy `enabled`/`{disabled:true}` markers map through `inactiveMode`. */
+export declare function parseRetainedPiCheckpoint(value: unknown, inactiveMode?: InactiveMode): RetainedPiCheckpoint;
+export declare function migrationFailure(data: JsonObject, error: string, mode?: InactiveMode): Snapshot;
 export {};

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

@@ -11,6 +11,18 @@ export class RevisionUnavailableError extends Error {
 /** Expired history cannot be restored, but explicit activation may use validated current memory. */
 export class HistoryBoundaryExpiredError extends RevisionUnavailableError {
 }
+export function isStateFlowMode(value) {
+    return value === "active" || value === "passive" || value === "off";
+}
+/**
+ * Read-only compatibility for session config and native checkpoints written before `mode`:
+ * `enabled:true` stays active; `enabled:false` stays the caller's inactive policy.
+ */
+function decodeLegacyMode(value, inactiveMode) {
+    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;
+}
 export function validateSessionRuntime(value, cwd, sessionId) {
     if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
         || !isObject(value.config) || !isObject(value.meta))
@@ -31,7 +43,7 @@ export function validateSessionRuntime(value, cwd, sessionId) {
     }
     const runtimeFields = Object.fromEntries(Object.entries(fields).filter(([key]) => known.has(key)));
     const normalized = {
-        config: { enabled: value.config.enabled === true },
+        config: { mode: isStateFlowMode(value.config.mode) ? value.config.mode : "off" },
         meta: restoredMeta(runtimeFields),
     };
     if (runtimeFields.bootstrap === false)
@@ -61,6 +73,7 @@ export function serializeSessionRuntime(runtime, cwd, sessionId) {
     const { temporal: _retiredTemporal, artifacts: _legacyArtifacts, ...runtimeMeta } = runtime.meta;
     return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
 }
+/** Legacy `enabled:false` decodes as non-active; native checkpoints, not this file, select branch policy. */
 export function parseSessionRuntime(config, runtimeSource, cwd, sessionId) {
     if (config === undefined && runtimeSource === undefined)
         return undefined;
@@ -68,14 +81,20 @@ export function parseSessionRuntime(config, runtimeSource, cwd, sessionId) {
         throw new Error("Incomplete State Flow config/runtime pair");
     let runtime;
     try {
-        runtime = { config: JSON.parse(config), meta: JSON.parse(runtimeSource) };
+        const settings = JSON.parse(config);
+        const mode = isObject(settings) && Object.keys(settings).length === 1 ? decodeLegacyMode(settings, "passive") : undefined;
+        if (mode === undefined)
+            throw new Error("Invalid State Flow runtime configuration or counters");
+        runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
     }
-    catch {
-        throw new Error("State Flow session runtime contains invalid JSON");
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new Error("State Flow session runtime contains invalid JSON");
+        throw error;
     }
     validateSessionRuntime(runtime, cwd, sessionId);
     const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
-    return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
+    return { config: { mode: runtime.config.mode }, meta: runtimeMeta };
 }
 function restoredStep(value) {
     return typeof value === "number"
@@ -109,11 +128,11 @@ function restoredMeta(value, legacy = {}) {
         ...(meta.bootstrap === true ? { bootstrap: true } : {}),
     };
 }
-function envelope(enabled, meta) {
-    return { config: { enabled }, meta };
+function envelope(mode, meta) {
+    return { config: { mode }, meta };
 }
-export function emptySnapshot(enabled = false) {
-    return envelope(enabled, { step: 0 });
+export function emptySnapshot(mode = "passive") {
+    return envelope(mode, { step: 0 });
 }
 export function isFileRevision(value) {
     return typeof value === "string" && /^file:[0-9a-f]{64}$/.test(value);
@@ -124,23 +143,33 @@ export function retainedBoundaryCheckpoint(snapshot, boundary) {
         throw new Error("Checkpoint requires a retained temporal boundary identity");
     const checkpoint = {
         boundary,
-        enabled: snapshot.config.enabled,
+        mode: snapshot.config.mode,
         step: snapshot.meta.step,
         ...(snapshot.meta.bootstrap === true ? { bootstrap: true } : {}),
         ...(snapshot.meta.specification === undefined ? {} : { specification: snapshot.meta.specification }),
     };
     return parseRetainedPiCheckpoint(checkpoint);
 }
-/** Decode the 0.17 retained-window checkpoint contract. */
-export function parseRetainedPiCheckpoint(value) {
+/** Encode an explicit inactive choice on a branch that has no accepted runtime. */
+export function preRuntimeCheckpoint(mode) {
+    if (mode === "active")
+        throw new Error("An active State Flow branch requires a retained semantic boundary");
+    return { mode };
+}
+/** Decode the retained-window checkpoint contract; legacy `enabled`/`{disabled:true}` markers map through `inactiveMode`. */
+export function parseRetainedPiCheckpoint(value, inactiveMode = "passive") {
     if (!isObject(value))
         throw new Error("Invalid State Flow retained-boundary checkpoint");
-    if (Object.keys(value).length === 1 && value.disabled === true)
-        return { disabled: true };
-    const allowed = new Set(["boundary", "enabled", "step", "bootstrap", "specification"]);
-    if (Object.keys(value).some((key) => !allowed.has(key))
+    const keys = Object.keys(value);
+    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);
+    if (keys.some((key) => !allowed.has(key))
         || typeof value.boundary !== "string" || value.boundary.trim().length === 0
-        || typeof value.enabled !== "boolean"
+        || mode === undefined
         || !Number.isSafeInteger(value.step) || value.step < 0 || value.step > MAX_RESTORED_STEP
         || (value.bootstrap !== undefined && value.bootstrap !== true)
         || (value.specification !== undefined && typeof value.specification !== "string")) {
@@ -148,18 +177,18 @@ export function parseRetainedPiCheckpoint(value) {
     }
     return {
         boundary: value.boundary,
-        enabled: value.enabled,
+        mode,
         step: value.step,
         ...(value.bootstrap === true ? { bootstrap: true } : {}),
         ...(typeof value.specification === "string" ? { specification: value.specification } : {}),
     };
 }
-export function migrationFailure(data, error) {
+export function migrationFailure(data, error, mode = "passive") {
     const meta = restoredMeta(data.meta, data);
     meta.validation = {
         attempt: 0,
         error,
         instruction: "Start a fresh State Flow episode; null is reserved for patch deletion.",
     };
-    return envelope(false, meta);
+    return envelope(mode, meta);
 }