@llblab/pi-kit 0.24.1 → 0.26.0

package/node_modules/@llblab/pi-state-flow/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llblab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@llblab/pi-state-flow/README.md

@@ -4,13 +4,13 @@
 
 **Incremental scoped context/memory compiler for Pi.**
 
-State Flow maintains explicit state across requests and sessions. The agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory rather than carrying every completed exchange into the next request.
+When enabled, State Flow maintains explicit state across requests and sessions. The agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory rather than carrying every completed exchange into the next request.
 
 Drawing on the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), State Flow combines durable state with Pi's native conversation context. In this hybrid, **state carries continuity between user runs; Pi's native context carries the working trajectory within a run.** The conversation is not reset after each model response or tool call. Pi retains ownership of execution, session navigation and the full inspectable trace.
 
 ## How it works
 
-A user run starts with effective memory and a new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed ordinary conversation history.
+In Active mode, a user run starts with effective memory and a new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed ordinary conversation history.
 
 ```text
 Current state + Request
@@ -30,7 +30,7 @@ Native compaction remains available for long runs. State Flow may also request a
 
 ## Installation and activation
 
-Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
+Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
 
 From NPM:
 
@@ -47,22 +47,23 @@ pi install git:github.com/llblab/pi-state-flow
 Enable active State Flow on the current branch:
 
 ```text
-/state-flow-start
+/state-flow-active
 ```
 
 Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
 
-- `/state-flow-start`: Enable the active, state-driven iteration workflow and memory-based context projection; passive mode can already save explicit patches.
+- `/state-flow-active`: Select the active, state-driven iteration workflow.
+- `/state-flow-passive`: Select ordinary conversation with both memory tools and existing-memory projection.
+- `/state-flow-off`: Remove both memory tools and all State Flow model context, without deleting memory.
 - `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
-- `/state-flow-stop`: End active episode semantics without deleting memory, even when canonical persistence fails. Interrupted work and uncompiled conversation remain available across toggles and reload; a failed write stays fenced until explicit Start safely reactivates current memory.
 
-Active mode is **opt-in**. Passive memory projection and the memory tools are enabled by default: existing state can be read or explicitly patched without an active episode or State Flow compaction. Every materially changed owner advances its independent scope revision even in passive mode, without displaying an active-mode status. When active, terminal and Telegram status render the Effective revision vector as `G15/C8/S31`; passive Telegram shows `State Flow: off`. Requested Global, CWD and Session snapshots show their own `#revision`, while Effective shows the vector. Inspection waits cancelably for a coherent shared view, with matching data and revisions, without publishing state or advancing a counter. Stop returns to the configured passive behavior. `autoStart` can enable active mode for genuinely new sessions; resumed branches restore their own enablement. See [configuration](docs/usage.md#configuration).
+New sessions default to **Off**; select Passive for ordinary conversation with memory tools, or Active for state-driven episodes. Passive projects state only after a validated memory view is available. Off removes State Flow's model-facing tools and context without deleting memory. Mode changes affect only this session; the global default applies only to new sessions. See [mode semantics](docs/usage.md#active-passive-and-configured-off), [configuration](docs/usage.md#configuration) and [status and controls](docs/usage.md#status-and-controls).
 
 ### Active, passive, off
 
 - `Active`: Memory tools are available; the agent consolidates necessary final state changes before completing an iteration. Subsequent iterations use accepted state and new input rather than completed prior reasoning.
-- `Passive`: Memory tools and existing-state projection remain available by default. Patching is on demand, and ordinary conversation context continues without State Flow's active iteration reset.
-- `Configured off`: With the branch inactive and both `passiveTools` and `passiveBootstrap` false, neither memory tool nor bootstrap/state projection is exposed to the model. `autoStart: false` alone does not turn memory off.
+- `Passive`: Both memory tools and existing-state projection remain available. Patching is on demand, and ordinary conversation context continues without State Flow's active iteration reset.
+- `Off`: Neither memory tool nor State Flow context—including a frozen passive handoff—is exposed to the model. Startup/reload/tree attachment does not read or restore memory; selecting Off cancels pending memory waits and records only native policy/bookmarks. Explicit Passive/Active acquires memory later. Stored memory and Pi's native trace remain intact.
 
 Modes select agent behavior, not a different disk persistence or fork-copy mechanism. Final consolidation does not require an empty ceremonial patch, and context projection does not delete native history. See [mode semantics and bootstrap terminology](docs/usage.md#active-passive-and-configured-off).
 
@@ -82,16 +83,18 @@ The agent receives the **effective view** of this composition, not three unrelat
 
 ### Semantic planes
 
-Every scope uses the same shape:
+Runtime views provide these documented planes:
 
 - `intents`: Active commitments to future action.
 - `contract`: Requirements, decisions, constraints and interface commitments.
 - `working`: Observations, results, uncertainties and current continuation.
 - `artifacts`: Source-addressed descriptions and compiled knowledge.
-- `response`: The exact latest accepted answer, including an empty string, captured by the runtime only in Session. Global and CWD retain an empty structural slot; Effective inherits the Session value.
+- `response`: The exact latest accepted answer, including an empty string, captured by the runtime only in Session. Global/CWD receive no newly accepted answers; stored scopes may omit response entirely. Effective uses the highest-priority nonempty value.
 - `lazy`: Supporting memory available through explicit reads, with its body omitted from baseline model context.
 
-These planes organize ordinary JSON rather than imposing a project-specific schema. The model updates the semantic planes except `response`, which is runtime-owned. Global and CWD revisions are shared by their canonical stores, Session has its own revision, and Effective has no scalar owner: its identity is the `G#/C#/S#` vector. One atomic patch advances each materially changed scope once. Memory remains fallible: storing an observation does not make it current or correct.
+Stored checkpoints and patches may omit any documented plane, including `intents`, `lazy` or `response`. Current and historical views assemble only known fields actually present in the selected scopes, without filling absent fields. Empty `response` is treated as absent. Checkpoint and patch readers ignore unknown top-level fields; writers emit only known fields. Nested data within known planes is unrestricted. Reading or starting never rewrites data just to normalize it; missing fields are not a storage-format error.
+
+These planes organize ordinary JSON rather than imposing a project-specific schema. The model updates the semantic planes except `response`, which is runtime-owned. Global and CWD revisions are shared by their canonical stores, Session has its own revision, and Effective has no scalar owner: its identity is the `g#c#s#` vector. One atomic patch advances each materially changed scope once. Memory remains fallible: storing an observation does not make it current or correct.
 
 Registered Pi Skills may be compiled into source-addressed artifacts when durable guidance is useful. Pi's resource provenance determines ownership: user Skills map to global, project Skills to CWD and temporary Skills to session. A matching source hash needs no update; an uncompiled read remains ordinary volatile context and does not block unrelated patches.
 
@@ -134,11 +137,11 @@ The default store is `~/.pi/agent/state-flow/`, independent of registered source
 
 **Persistence is optimistic across abrupt shutdown.** Short publication exclusion preserves independent shared fields between cooperating writers; the last accepted write wins on overlap. Per-file atomic replacement does not guarantee power-loss survival or crash-atomic recovery. That [accepted limitation](docs/filesystem-recovery.md#power-loss-durability) is not a release gate; no additional recovery journal or storage format is planned.
 
-**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. A busy store explicitly defers backup when Pi provides no cancellable settlement wait (including SDK 0.87); a later accepted turn retries without changing memory or blocking native Abort. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Session shutdown waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
+**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. A busy store explicitly defers backup when Pi provides no cancellable settlement wait (including SDK 0.87); a later accepted turn retries without changing memory or blocking native Abort. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Off cancels pending captures and its admitted push without rolling back accepted state or backup commits; canceled work emits no late memory warnings. Shutdown cancels owned pushes and waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
 
-Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration. Explicit Start is a mode change, not historical restoration: it activates validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated. Malformed storage, unsafe fork copying and concurrent writes remain fenced. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
+Memory-enabled resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory; Off defers this acquisition. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration. Explicit Start is a mode change, not historical restoration: it activates validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated. Malformed storage, unsafe fork copying and concurrent writes remain fenced. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
 
-SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Accepted-runtime Stop switches local policy/context immediately and awaits runtime-only persistence. Current-head Start also awaits coherent capture/acceptance before enabling mode; Stop or selection can cancel its wait. Telegram acknowledges controls early. Startup/recovery and exact restoration/fork still require migration, including Start's initial-attachment and unaccepted-fork paths.
+SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Selecting Passive switches local policy/context immediately and awaits runtime-only persistence. Off instead cancels owned memory waits and saves only native mode/continuation/fork bookkeeping, without validating or rewriting canonical storage. Explicit Off inspection may read current stored values through a disposable validated reader; it does not activate memory, install cache or change the selected historical/fork boundary. Missing private authority remains unavailable. Active waits for coherent capture/acceptance; another mode or selection can withdraw its wait. Passive retains independently owned restoration/fork work; Off cancels it and defers later acquisition. Failed Passive persistence preserves local policy and fences publication until accepted activation.
 
 The canonical storage-format boundary introduced in 0.17 still applies: current versions accept only the canonical store contract and provide no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
 

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

@@ -12,8 +12,8 @@ export { retainedMemoryScopes } from "./lib/memory.ts";
 export { planKnowledgeRehydration, type RehydrationOptions, type RehydrationPhase, type RehydrationPlan, type RehydrationRead, type RehydrationRoute } from "./lib/rehydration.ts";
 export { TemporalRuntime } from "./lib/runtime.ts";
 export { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./lib/skills.ts";
-export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts, type AtomicScopePatches, type MaterializedState, type ScopedPatch, type ScopedStates, type ScopePatch, type SemanticTransition, type StateDocument, type StatePatch, type StateScope, type TerminalTransition } from "./lib/state.ts";
+export { emptyState, isMaterializedState, isSemanticState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts, type AtomicScopePatches, type MaterializedState, type ScopedPatch, type ScopedStates, type ScopedSemanticStates, type ScopePatch, type SemanticState, type SemanticTransition, type StateDocument, type StatePatch, type StateScope, type TerminalTransition } from "./lib/state.ts";
 export { PublicationBusyError } from "./lib/storage.ts";
 export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID, type StateFlowTelegramAdapter, type StateFlowTelegramButton, type StateFlowTelegramCallbackContext, type StateFlowTelegramControlResult, type StateFlowTelegramInspection, type StateFlowTelegramInspectionPort, type StateFlowTelegramLoader, type StateFlowTelegramModules, type StateFlowTelegramPort, type StateFlowTelegramSectionContext, type StateFlowTelegramSectionModule, type StateFlowTelegramSnapshot, type StateFlowTelegramView } from "./lib/telegram.ts";
-export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
+export { advanceTemporalState, readTemporalState, readTemporalView, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
 export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";

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

@@ -11,8 +11,8 @@ export { retainedMemoryScopes } from "./lib/memory.js";
 export { planKnowledgeRehydration } from "./lib/rehydration.js";
 export { TemporalRuntime } from "./lib/runtime.js";
 export { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER } from "./lib/skills.js";
-export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts } from "./lib/state.js";
+export { emptyState, isMaterializedState, isSemanticState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts } from "./lib/state.js";
 export { PublicationBusyError } from "./lib/storage.js";
 export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID } from "./lib/telegram.js";
-export { advanceTemporalState, readTemporalState, temporalScopeRevisions } from "./lib/temporal.js";
+export { advanceTemporalState, readTemporalState, readTemporalView, temporalScopeRevisions } from "./lib/temporal.js";
 export { parseStateReadPath, readStatePath } from "./lib/query.js";

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

@@ -1,4 +1,4 @@
-import type { CompactionResult } from "@earendil-works/pi-coding-agent";
+import { type CompactionResult } from "@earendil-works/pi-coding-agent";
 export declare const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
 /** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
 export declare const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24000;

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

@@ -1,4 +1,4 @@
-import { estimateTokens } from "@earendil-works/pi-agent-core";
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
 export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
 /** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
 export const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24_000;

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

@@ -1,9 +1,11 @@
+import { type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 export interface StateFlowConfig {
     /** Canonical State Flow repository. SDK callers may still override it explicitly. */
     directory: string;
-    autoStart: boolean;
-    passiveBootstrap: boolean;
-    passiveTools: boolean;
+    /** Default mode for genuinely new sessions only; each session owns its selected mode. */
+    mode: StateFlowMode;
+    /** Non-active fallback for legacy `enabled:false` evidence and unavailable selections; never serialized. */
+    inactiveMode: InactiveMode;
     /** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
     logging: boolean;
     /** Show successful patch_state arguments in the interactive tool row. */
@@ -12,3 +14,5 @@ export interface StateFlowConfig {
 }
 /** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
 export declare function loadStateFlowConfig(agentDir?: string, repositoryRoot?: string): StateFlowConfig;
+/** Explicit modes never carry a separate passive policy: only Off stays off when inactive. */
+export declare function inactiveModeFor(mode: StateFlowMode): InactiveMode;

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

@@ -5,15 +5,15 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.js";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { isObject } from "./json.js";
+import { isStateFlowMode } from "./snapshot.js";
 /** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
 export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = getDurableRepositoryRoot(agentDir)) {
     const directory = repositoryRoot;
     const path = join(directory, "config.json");
     const defaults = {
         directory,
-        autoStart: false,
-        passiveBootstrap: true,
-        passiveTools: true,
+        mode: "off",
+        inactiveMode: "off",
         logging: false,
         showSuccessfulPatches: true,
         historyLimit: DEFAULT_HISTORY_LIMIT,
@@ -27,10 +27,13 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
     catch (error) {
         throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
     }
-    const allowed = new Set(["autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
+    // autoStart/passiveBootstrap/passiveTools are read-only compatibility inputs; explicit mode is authoritative.
+    const allowed = new Set(["mode", "autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
     if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
         throw new Error(`State Flow configuration contains unknown settings: ${path}`);
     }
+    if (Object.hasOwn(value, "mode") && !isStateFlowMode(value.mode))
+        throw new Error(`State Flow mode must be "active", "passive" or "off": ${path}`);
     if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean")
         throw new Error(`State Flow autoStart must be a boolean: ${path}`);
     if (Object.hasOwn(value, "passiveBootstrap") && typeof value.passiveBootstrap !== "boolean")
@@ -43,13 +46,19 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
     if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || value.historyLimit < 0 || value.historyLimit > MAX_HISTORY_LIMIT))
         throw new Error(`State Flow historyLimit must be an integer from 0 to ${MAX_HISTORY_LIMIT}: ${path}`);
+    const legacyInactive = value.passiveBootstrap !== false || value.passiveTools !== false ? "passive" : "off";
+    const hasLegacyMode = Object.hasOwn(value, "autoStart") || Object.hasOwn(value, "passiveBootstrap") || Object.hasOwn(value, "passiveTools");
+    const mode = isStateFlowMode(value.mode) ? value.mode : value.autoStart === true ? "active" : hasLegacyMode ? legacyInactive : "off";
     return {
         directory,
-        autoStart: value.autoStart === true,
-        passiveBootstrap: value.passiveBootstrap !== false,
-        passiveTools: value.passiveTools !== false,
+        mode,
+        inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : hasLegacyMode ? legacyInactive : "off",
         logging: value.logging === true,
         showSuccessfulPatches: value.showSuccessfulPatches !== false,
         historyLimit: typeof value.historyLimit === "number" ? value.historyLimit : DEFAULT_HISTORY_LIMIT,
     };
 }
+/** Explicit modes never carry a separate passive policy: only Off stays off when inactive. */
+export function inactiveModeFor(mode) {
+    return mode === "off" ? "off" : "passive";
+}

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

@@ -4,12 +4,12 @@ import type { RecentTransitionWindow } from "./history.ts";
 import { type JsonValue } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { type AtomicScopePatches, type MaterializedState, type ModelState } from "./state.ts";
+import { type AtomicScopePatches, type SemanticState } from "./state.ts";
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export declare function projectSystemProtocol(messages: AgentMessage[], protocol: string | undefined): AgentMessage[];
 type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
 /** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
-export declare function lazyNavigationHint(state: MaterializedState): {
+export declare function lazyNavigationHint(state: SemanticState): {
     available: boolean;
     path: string;
     keys?: Record<string, LazyValueKind>;
@@ -22,7 +22,7 @@ export type ModelStateUpdate = {
     deleted: true;
 });
 /** Exact projected replacements, not authored merge patches; paths are unambiguous key/index segments. */
-export declare function acceptedStateUpdates(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches): {
+export declare function acceptedStateUpdates(before: SemanticState, after: SemanticState, patches: AtomicScopePatches): {
     effective: ModelStateUpdate[];
     lazy_navigation?: {
         available: boolean;
@@ -31,14 +31,14 @@ export declare function acceptedStateUpdates(before: MaterializedState, after: M
     } | undefined;
 };
 export interface ContextView {
-    state: ModelState;
+    state: SemanticState;
     lazy_navigation?: ReturnType<typeof lazyNavigationHint>;
     artifact_invalidations: readonly ArtifactInvalidationNotice[];
     knowledge_rehydration: {
         phase: RehydrationPhase;
     } | null;
 }
-export declare function contextView(state: MaterializedState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView;
+export declare function contextView(state: SemanticState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView;
 /** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
 export declare class ContextProjection {
     private identity;
@@ -48,7 +48,7 @@ export declare class ContextProjection {
     private notices;
     reset(): void;
     /** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
-    acceptPatch(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches, hints: ArtifactModelHints): {
+    acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints): {
         effective: ModelStateUpdate[];
         lazy_navigation?: {
             available: boolean;
@@ -65,13 +65,13 @@ export interface PassiveContinuation {
     activeRunStartedAt?: number;
     preserveContext?: true;
     handoff: AgentMessage;
-    state: ModelState;
+    state: SemanticState;
 }
 export declare function syntheticUser(text: string): AgentMessage;
-export declare function createPassiveContinuation(state: ModelState, startedAt?: number, activeRunStartedAt?: number, preserveContext?: boolean): PassiveContinuation;
+export declare function createPassiveContinuation(state: SemanticState, startedAt?: number, activeRunStartedAt?: number, preserveContext?: boolean): PassiveContinuation;
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export declare function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[];
-export declare function runtimeContextMessage(snapshot: Snapshot, state: MaterializedState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;
+export declare function runtimeContextMessage(snapshot: Snapshot, state: SemanticState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;
 /** Render a view already projected by this domain without cloning the full semantic overlay twice. */
 export declare function runtimeContextHead(snapshot: Snapshot, view: ContextView, recentTransitions?: RecentTransitionWindow): AgentMessage;
 /** Captured identity survives text decoration; an uncertain boundary retains available context. */

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { projectArtifactForModel } from "./artifact.js";
 import { applyPatch, isObject, presentationJson, sameJson } from "./json.js";
-import { projectStateForModel } from "./state.js";
+import { projectSemanticPatch, projectStateForModel } from "./state.js";
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export function projectSystemProtocol(messages, protocol) {
     let lastSystem = -1;
@@ -74,8 +74,8 @@ function projectedStateUpdates(previous, current, patches, beforeNavigation, nav
     const diff = (left, right, path) => {
         if (left === undefined && right === undefined || left !== undefined && right !== undefined && sameJson(left, right))
             return;
-        if (isObject(left) && isObject(right)) {
-            for (const key of new Set([...Object.keys(left), ...Object.keys(right)]))
+        if (isObject(right) && (isObject(left) || left === undefined && path.length === 1 && Object.keys(right).length > 0)) {
+            for (const key of new Set([...Object.keys(left ?? {}), ...Object.keys(right)]))
                 diff(child(left, key), child(right, key), [...path, key]);
         }
         else if (Array.isArray(left) && Array.isArray(right) && left.length === right.length) {
@@ -336,8 +336,9 @@ function projectRecentForModel(recent) {
     const projected = structuredClone(recent);
     for (const record of projected)
         for (const transition of record.transitions) {
+            transition.patch = projectSemanticPatch(transition.patch);
             delete transition.patch.lazy;
-            if (transition.patch.artifacts === undefined)
+            if (!isObject(transition.patch.artifacts))
                 continue;
             for (const [path, entry] of Object.entries(transition.patch.artifacts)) {
                 Object.defineProperty(transition.patch.artifacts, path, {

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

@@ -149,8 +149,8 @@ export async function inspectStateFlowContinuationProvenance(header, repositoryR
             const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
             if (!runtime)
                 throw new Error("incomplete canonical session runtime");
-            if (!runtime.config.enabled)
-                return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+            if (runtime.config.mode !== "active")
+                return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow is not active on selected runtime" };
             const streams = ["global", "cwd", "session"].map((scope) => {
                 const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
                 return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope, scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));

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

@@ -1,6 +1,6 @@
 import { type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { type ScopeStream, type TemporalState } from "./temporal.ts";
-import type { StateScope } from "./state.ts";
+import { type StateScope } from "./state.ts";
 /** Canonical semantic sources plus runtime-owned temporal metadata. */
 export interface ScopeStreamSources {
     checkpoint: string;

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

@@ -6,6 +6,7 @@ import { parseArtifactProvenanceRegistry, serializeArtifactProvenanceRegistry, }
 import { MAX_HISTORY_LIMIT } from "./history.js";
 import { canonicalJson, isJsonValue, isObject } from "./json.js";
 import { validateScopeStream, validateTemporalState } from "./temporal.js";
+import { selectSemanticFields } from "./state.js";
 const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
 const CHECKPOINT_FILE = "checkpoint.json";
@@ -33,8 +34,8 @@ export function serializeScopeStream(stream, scope, cwdIdentity) {
     if (scope !== "cwd" && cwdIdentity !== undefined)
         throw new Error("Only State Flow CWD scope serialization accepts a CWD identity");
     return {
-        checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
-        patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
+        checkpoint: `${canonicalJson(selectSemanticFields(stream.checkpoint.state))}\n`,
+        patches: stream.patches.map((record) => `${canonicalJson(selectSemanticFields(record.patch))}\n`).join(""),
         temporal: {
             revision: stream.revision,
             checkpoint: structuredClone(stream.checkpoint.through),
@@ -96,8 +97,10 @@ export function classifyScopeStream(checkpointSource, patchesSource, scope, expe
         // 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
         // semantic tail; discarded ancestry cannot be reconstructed without inventing history.
         revision: temporal.revision === undefined ? patches.length : temporal.revision,
-        checkpoint: { through: temporal.checkpoint, state: checkpoint },
-        patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+        checkpoint: { through: temporal.checkpoint, state: isObject(checkpoint) ? selectSemanticFields(checkpoint) : checkpoint },
+        patches: patches.map((patch, index) => ({
+            transition: boundaries[index], patch: isObject(patch) ? selectSemanticFields(patch) : patch,
+        })),
     };
     validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
     return { kind: "present", stream };

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

@@ -1,9 +1,9 @@
-import { type Snapshot } from "./snapshot.ts";
+import { type InactiveMode, type Snapshot } from "./snapshot.ts";
 export declare function startEpisode(bootstrap: boolean): Snapshot;
 /** Re-enable a branch checkpoint without discarding its runtime config or provenance. */
 export declare function resumeEpisode(snapshot: Snapshot, bootstrap: boolean): Snapshot;
-/** Disable only this branch; durable defaults and session history remain intact. */
-export declare function stopEpisode(snapshot: Snapshot): Snapshot;
+/** Select an inactive mode for only this branch; durable defaults and session history remain intact. */
+export declare function deactivateEpisode(snapshot: Snapshot, mode: InactiveMode): Snapshot;
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */
 export declare function prepareRun(snapshot: Snapshot, prompt: string): boolean;
 /** Retain the full prompt only while its run remains recoverable and unfinished. */

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

@@ -1,6 +1,6 @@
 import { emptySnapshot } from "./snapshot.js";
 export function startEpisode(bootstrap) {
-    const snapshot = emptySnapshot(true);
+    const snapshot = emptySnapshot("active");
     if (bootstrap)
         snapshot.meta.bootstrap = true;
     return snapshot;
@@ -8,15 +8,15 @@ export function startEpisode(bootstrap) {
 /** Re-enable a branch checkpoint without discarding its runtime config or provenance. */
 export function resumeEpisode(snapshot, bootstrap) {
     const next = structuredClone(snapshot);
-    next.config.enabled = true;
+    next.config.mode = "active";
     if (bootstrap)
         next.meta.bootstrap = true;
     return next;
 }
-/** Disable only this branch; durable defaults and session history remain intact. */
-export function stopEpisode(snapshot) {
+/** Select an inactive mode for only this branch; durable defaults and session history remain intact. */
+export function deactivateEpisode(snapshot, mode) {
     const next = structuredClone(snapshot);
-    next.config.enabled = false;
+    next.config.mode = mode;
     return next;
 }
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatPatchStateArguments } from "./protocol.ts";
+import { type StateFlowMode } from "./snapshot.ts";
 import { type ModelState, type StateScope } from "./state.ts";
 import { type StateFlowTelegramLoader } from "./telegram.ts";
 export interface StateFlowExtensionOptions {
@@ -11,11 +12,8 @@ export interface StateFlowExtensionOptions {
     telegram?: {
         load?: StateFlowTelegramLoader;
     };
-    /** Test/SDK capability override; repository config remains the Pi default. */
-    passive?: {
-        bootstrap?: boolean;
-        tools?: boolean;
-    };
+    /** Test/SDK override of the default mode for new sessions; repository config remains the Pi default. */
+    mode?: StateFlowMode;
 }
 export { formatPatchStateArguments };
 export declare const PATCH_STATE_TOOL_NAME = "patch_state";