@llblab/pi-kit 0.24.1 → 0.26.0

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

@@ -20,35 +20,50 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url)
         new URL("../../../pi-telegram/dist/api/sections.js", moduleUrl).href,
     ];
 }
-/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
+/** Main-menu section label shows only the current session mode. */
 export function formatStateFlowSectionLabel(snapshot) {
-    if (!snapshot.enabled)
-        return "🌀 State Flow: off";
-    return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
+    return `🌀 State Flow: ${snapshot.mode}`;
 }
-/** Shared live value: plain in the button label, monospaced in the submenu state line. */
-function stateFlowLabelValue(snapshot) {
-    if (!snapshot.enabled)
-        return "off";
-    return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
+export const STATE_FLOW_MODES = ["off", "passive", "active"];
+const STATE_FLOW_MODE_LABELS = { off: "Off", passive: "Passive", active: "Active" };
+const STATE_FLOW_SELECTED_MARKERS = { off: "🟡", passive: "🟣", active: "🟢" };
+function isStateFlowModeAction(value) {
+    return STATE_FLOW_MODES.includes(value);
 }
-/** Submenu state line: the same identity as the button label, with the live value in monospace. */
-function formatStateFlowSectionHeader(snapshot) {
-    return `<b>🌀 State Flow: <code>${stateFlowLabelValue(snapshot)}</code></b>`;
+function modeReceiptNotice(mode, result) {
+    if (result.ok && (result.message === `State Flow ${mode}` || result.message === `State Flow is already ${mode}`))
+        return undefined;
+    return result.message;
 }
-/** Short help under the state line: what State Flow is and why its action button exists. */
-const STATE_FLOW_SECTION_HELP = "Accepted memory remains visible in active and passive modes. Start or Stop changes episode behavior, not state access.";
-/** The submenu header repeats the button's state line; the single action matches the current state. */
+/** One radio-style mode row followed directly by read-only scope actions. */
 export function buildStateFlowSectionView(snapshot, callbackData) {
-    const action = snapshot.enabled
-        ? { text: "⏹ Stop", callback_data: callbackData("stop") }
-        : { text: "▶️ Start", callback_data: callbackData("start") };
+    const modes = STATE_FLOW_MODES.map((mode) => ({
+        text: `${mode === snapshot.mode ? STATE_FLOW_SELECTED_MARKERS[mode] : "⚫️"} ${STATE_FLOW_MODE_LABELS[mode]}`,
+        callback_data: callbackData(mode),
+    }));
     return {
-        text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
+        text: [
+            `<b>🌀 State Flow:</b> <code>${snapshot.mode}</code>`,
+            "",
+            "<b>Mode</b> — choose a workflow (switching modes never erases stored memory):",
+            "",
+            "<code>-</code> <code>off</code> (default): regular chat without State Flow memory tools or context.",
+            "<code>-</code> <code>passive</code>: regular chat with memory tools; available combined memory enters the agent's context.",
+            "<code>-</code> <code>active</code>: same memory access; each completed answer closes a cycle, and the next request starts from saved state, not the full chat.",
+            "",
+            "<b>Inspect memory</b> — view stored state even in Off:",
+            "",
+            "<code>-</code> <code>global</code>: memory shared across projects and sessions.",
+            "<code>-</code> <code>cwd</code>: memory shared by sessions in this directory.",
+            "<code>-</code> <code>session</code>: private memory for this session, kept on resume.",
+            "<code>-</code> <code>effective</code>: merged Global, CWD and Session state; the agent can use it when memory is enabled and available.",
+        ].join("\n"),
         parseMode: "html",
         replyMarkup: { inline_keyboard: [
-                [action],
-                [{ text: "👁 Show state", callback_data: callbackData("show-state") }],
+                modes,
+                ...[["global", "cwd"], ["session", "effective"]].map((row) => row.map((scope) => ({
+                    text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope),
+                }))),
             ] },
     };
 }
@@ -58,17 +73,6 @@ const STATE_FLOW_SCOPE_LABELS = {
     session: "💬 Session",
     effective: "🧬 Effective",
 };
-export function buildStateFlowScopeChooser(callbackData) {
-    return {
-        text: "<b>👁 Show state:</b>",
-        parseMode: "html",
-        replyMarkup: { inline_keyboard: [
-                ...["global", "cwd", "session", "effective"].map((scope) => [
-                    { text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope) },
-                ]),
-            ] },
-    };
-}
 // The complete message serializes each preformatted field one additional time;
 // 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
 const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
@@ -113,10 +117,10 @@ export function renderStateFlowRichState(scope, revisions, state) {
                 text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
                 size: 3,
             },
-            ...fields.map((field) => ({
+            ...fields.filter((field) => state[field] !== undefined && state[field] !== "").map((field) => ({
                 type: "details",
                 summary: { type: "code", text: field },
-                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
+                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
             })),
         ],
         skip_entity_detection: true,
@@ -131,20 +135,16 @@ function buildStateFlowTelegramSection(port, isActive) {
         id: STATE_FLOW_TELEGRAM_ID,
         label: "🌀 State Flow",
         getLabel: () => formatStateFlowSectionLabel(port.snapshot()),
-        render: (ctx) => buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
+        render: (ctx) => buildStateFlowSectionView(port.snapshot(), (action, payload) => ctx.callbackData(action, payload)),
         handleCallback: async (ctx) => {
-            // cancel/refresh remain routable for keyboards sent by earlier versions.
-            if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back")
+            // Keyboards sent by earlier versions re-render (start/stop/refresh) or withdraw deferral (cancel); they change no mode.
+            const legacy = ctx.action === "start" || ctx.action === "stop" || ctx.action === "cancel" || ctx.action === "refresh";
+            if (!isStateFlowModeAction(ctx.action) && !legacy && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back")
                 return "pass";
             const request = ++interaction;
             let notice;
             let acknowledged = false;
             try {
-                if (ctx.action === "show-state") {
-                    await ctx.answerCallback();
-                    await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
-                    return "handled";
-                }
                 if (ctx.action === "inspect") {
                     if (!isStateFlowTelegramScope(ctx.payload))
                         throw new Error("Unknown State Flow scope");
@@ -167,25 +167,25 @@ function buildStateFlowTelegramSection(port, isActive) {
                         await ctx.answerCallback();
                     return "handled";
                 }
-                const action = ctx.action === "stop" || (ctx.action === "start" && port.canStartNow()) ? ctx.action : undefined;
-                if (action) {
+                const mode = isStateFlowModeAction(ctx.action) && (ctx.action !== "active" || port.canStartNow()) ? ctx.action : undefined;
+                if (mode) {
                     if ("inspect" in port) {
                         acknowledged = true;
-                        // Start the control immediately and acknowledge in parallel; neither promise can reject unobserved.
+                        // Apply the control immediately and acknowledge in parallel; neither promise can reject unobserved.
                         const [, result] = await Promise.all([
-                            ctx.answerCallback(action === "stop" ? "Stopping State Flow" : "Starting State Flow"),
-                            Promise.resolve().then(() => port[action]()),
+                            ctx.answerCallback(`Switching State Flow to ${mode}`),
+                            Promise.resolve().then(() => port.select(mode)),
                         ]);
                         if (result.signal?.aborted)
                             return "handled";
-                        notice = result.message;
+                        notice = modeReceiptNotice(mode, result);
                     }
                     else
-                        notice = port[action]().message;
+                        notice = modeReceiptNotice(mode, port.select(mode));
                 }
-                else if (ctx.action === "start") {
+                else if (ctx.action === "active") {
                     port.deferStart();
-                    notice = "State Flow will start after the current turn";
+                    notice = "State Flow will become active after the current turn";
                 }
                 else if (ctx.action === "cancel") {
                     port.cancelStart();
@@ -198,7 +198,7 @@ function buildStateFlowTelegramSection(port, isActive) {
             if (request !== interaction || !isActive())
                 return "handled";
             const summary = notice === undefined ? undefined : conciseDiagnostic(notice, 200);
-            const view = buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action));
+            const view = buildStateFlowSectionView(port.snapshot(), (action, payload) => ctx.callbackData(action, payload));
             if (acknowledged && summary !== undefined) {
                 // Callback queries can expire during storage waits; retain errors in the existing menu instead.
                 view.text += `\n\n${summary.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}`;

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

@@ -1,5 +1,5 @@
 import { type RecentScopePatch } from "./history.ts";
-import { type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type StateScope } from "./state.ts";
 /** Owns hot temporal algebra; excludes filesystem, Git, identity allocation, and Pi lifecycle. */
 export interface TransitionBoundary {
     id: string;
@@ -9,7 +9,7 @@ export interface TransitionBoundary {
 }
 export interface ScopeCheckpoint {
     through: TransitionBoundary;
-    state: MaterializedState;
+    state: SemanticState;
 }
 export interface TemporalPatch {
     transition: TransitionBoundary;
@@ -37,7 +37,7 @@ export declare function validateTemporalState(view: TemporalState, historyLimit?
 /** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
 export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string, historyLimit?: number): TemporalState;
 /** New or migrated state starts at a proven current boundary, with no invented past. */
-export declare function createTemporalState(states: ScopedStates, id: string, historyLimit?: number): TemporalState;
+export declare function createTemporalState(states: ScopedSemanticStates, id: string, historyLimit?: number): TemporalState;
 /** Fold retained tails to a lower configured limit without inventing history. */
 export declare function constrainTemporalState(view: TemporalState, historyLimit: number): TemporalState;
 /** Select one scope at a proven retained boundary from its owning runtime lineage. */
@@ -46,7 +46,11 @@ export declare function selectScopeStreamAtBoundary(stream: ScopeStream, scope:
 export declare function selectTemporalStateBoundary(view: TemporalState, boundaryId: string, historyLimit?: number): TemporalState;
 /** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
 export declare function temporalScopeRevisions(view: TemporalState): ScopeRevisions;
-/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
+/** Exact scope semantics for authored staging; defaults must never become implicit writes. */
+export declare function readTemporalScopes(view: TemporalState, offset?: number, historyLimit?: number): ScopedSemanticStates;
+/** Sparse current/historical view: unknown planes and absent values never become effective data. */
+export declare function readTemporalView(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): SemanticState;
+/** Internal defaulted materialization for consumers that require object registries. */
 export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
 export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string, historyLimit?: number): TemporalState;

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

@@ -1,6 +1,6 @@
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, validateRecentTransition } from "./history.js";
 import { applyPatch, containsNull, isJsonValue, isObject, sameJson } from "./json.js";
-import { isMaterializedState, overlayStates } from "./state.js";
+import { emptyState, isSemanticState, overlayStates, projectSemanticState } from "./state.js";
 const SCOPES = ["global", "cwd", "session"];
 function validateHistoryLimit(limit) {
     if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_HISTORY_LIMIT) {
@@ -16,14 +16,20 @@ function validateBoundary(boundary) {
         throw new Error("Invalid State Flow temporal boundary");
     }
 }
-function validateState(state) {
-    if (!isJsonValue(state) || !isMaterializedState(state) || containsNull(state)) {
-        throw new Error("Invalid temporal materialized semantic state");
-    }
+function validateState(state, location) {
+    const json = isJsonValue(state);
+    const hasNull = json && isObject(state) && Object.keys(emptyState()).some((key) => containsNull(state[key]));
+    if (json && isSemanticState(state) && !hasNull)
+        return;
+    const reason = !json ? "expected finite, acyclic JSON data"
+        : !isObject(state) ? "expected a semantic object"
+            : hasNull ? "null is not allowed"
+                : "invalid semantic fields or artifact metadata";
+    throw new Error(`Invalid temporal materialized semantic state${location ? ` in ${location}` : ""}: ${reason}`);
 }
-function apply(state, patch) {
+function apply(state, patch, location) {
     const next = applyPatch(state, patch);
-    validateState(next);
+    validateState(next, location);
     return next;
 }
 function sameBoundary(left, right) {
@@ -42,7 +48,7 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
     }
     const stream = value;
     validateBoundary(stream.checkpoint.through);
-    validateState(stream.checkpoint.state);
+    validateState(stream.checkpoint.state, `${scope} checkpoint`);
     if (stream.patches.length > historyLimit)
         throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
     if (stream.revision < stream.patches.length)
@@ -62,9 +68,7 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
             throw new Error("Disconnected State Flow temporal ancestry");
         }
         validateRecentTransition({ id: record.transition.id, at: 0, transitions: [{ scope, patch: record.patch }] });
-        const next = apply(state, record.patch);
-        if (sameJson(next, state))
-            throw new Error("Temporal scope tail contains a semantic no-op");
+        const next = apply(state, record.patch, `${scope} tail`);
         state = next;
         previous = record.transition;
         identities.add(previous.id);
@@ -244,21 +248,33 @@ export function temporalScopeRevisions(view) {
     }
     return revisions;
 }
-/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
-export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+function readBoundary(view, offset, historyLimit) {
     validateHistoryLimit(historyLimit);
     if (!Number.isSafeInteger(offset) || offset < 0 || offset > historyLimit) {
         throw new Error(`State Flow hot-history offset must be an integer from 0 to ${historyLimit}`);
     }
-    if (scope !== undefined && !SCOPES.includes(scope))
-        throw new Error("Unknown temporal scope");
     validateTemporalState(view, historyLimit);
     const boundary = view.lineage[view.lineage.length - 1 - offset];
     if (!boundary)
         throw new Error("Requested history predates the proven temporal origin");
-    if (scope !== undefined)
-        return scopeAt(view.scopes[scope], boundary);
-    return overlayStates(...SCOPES.map((owner) => scopeAt(view.scopes[owner], boundary)));
+    return boundary;
+}
+/** Exact scope semantics for authored staging; defaults must never become implicit writes. */
+export function readTemporalScopes(view, offset = 0, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    const boundary = readBoundary(view, offset, historyLimit);
+    return { global: scopeAt(view.scopes.global, boundary), cwd: scopeAt(view.scopes.cwd, boundary), session: scopeAt(view.scopes.session, boundary) };
+}
+/** Sparse current/historical view: unknown planes and absent values never become effective data. */
+export function readTemporalView(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    if (scope !== undefined && !SCOPES.includes(scope))
+        throw new Error("Unknown temporal scope");
+    const boundary = readBoundary(view, offset, historyLimit);
+    const owners = scope === undefined ? SCOPES : [scope];
+    return owners.reduce((state, owner) => applyPatch(state, projectSemanticState(scopeAt(view.scopes[owner], boundary))), {});
+}
+/** Internal defaulted materialization for consumers that require object registries. */
+export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    return overlayStates(readTemporalView(view, offset, scope, historyLimit));
 }
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
 export function advanceTemporalState(view, transitions, id, historyLimit = DEFAULT_HISTORY_LIMIT) {

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

@@ -3,9 +3,9 @@ import type { SuccessfulArtifactRead } from "./acquisition.ts";
 import { type AcceptedTransition } from "./history.ts";
 import { type SuccessfulSkillRead } from "./skills.ts";
 import type { Snapshot } from "./snapshot.ts";
-import type { AtomicScopePatches, ScopedStates, StateScope, TerminalTransition } from "./state.ts";
+import type { AtomicScopePatches, ScopedSemanticStates, StateScope, TerminalTransition } from "./state.ts";
 export interface StagedScopedTransition {
-    nextStates: ScopedStates;
+    nextStates: ScopedSemanticStates;
     stateHashes: Record<StateScope, string>;
     /** Fresh runtime-owned provenance for artifacts compiled in this transition. */
     provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>>;
@@ -13,11 +13,11 @@ export interface StagedScopedTransition {
     committed: boolean;
 }
 /** Stage one canonical atomic scope cohort without changing the finalized response. */
-export declare function stageAtomicScopePatches(currentStates: ScopedStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
-export declare function stageScopedTransition(currentStates: ScopedStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+export declare function stageAtomicScopePatches(currentStates: ScopedSemanticStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+export declare function stageScopedTransition(currentStates: ScopedSemanticStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
 /** Commit one accepted transition; durable publication receives all changed scopes as one cohort. */
 export interface CommitScopedTransitionOptions {
     /** Runtime response reconciliation finalizes bootstrap lifecycle state. */
     finalizeRun?: boolean;
 }
-export declare function commitScopedTransition(snapshot: Snapshot, states: ScopedStates, stage: StagedScopedTransition, publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void, causalBasis: string, options?: CommitScopedTransitionOptions): boolean;
+export declare function commitScopedTransition(snapshot: Snapshot, states: ScopedSemanticStates, stage: StagedScopedTransition, publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void, causalBasis: string, options?: CommitScopedTransitionOptions): boolean;

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

@@ -2,6 +2,7 @@ import { compileArtifact, ORDINARY_ARTIFACT_COMPILER, validateArtifactMetadata,
 import { createAcceptedTransition } from "./history.js";
 import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
 import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
+import { emptyState } from "./state.js";
 const SCOPES = new Set(["global", "cwd", "session"]);
 const PATCH_KEYS = new Set(["intents", "contract", "working", "artifacts", "lazy"]);
 function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
@@ -82,7 +83,7 @@ function compileReadSkills(scope, nextState, patch, successfulSkillReads, proven
     }
 }
 function validateMaterializedTransition(nextState, scope) {
-    if (containsNull(nextState)) {
+    if (Object.keys(emptyState()).some((key) => containsNull(nextState[key]))) {
         throw new Error("Materialized state cannot contain null; use null only as an object-key deletion marker");
     }
     validateArtifactRegistry(nextState.artifacts, `${scope}.artifacts`);
@@ -111,16 +112,6 @@ function validateScopePatch(scope, patch) {
     if (isObject(patch.artifacts))
         validateModelArtifactPatch(patch.artifacts, `${scope}.artifacts`);
 }
-function completePatch(patch, response) {
-    return {
-        artifacts: patch.artifacts ?? {},
-        contract: patch.contract ?? {},
-        working: patch.working ?? {},
-        intents: patch.intents ?? {},
-        response,
-        lazy: structuredClone(patch.lazy ?? {}),
-    };
-}
 /** Stage all scope updates against one immutable basis before any state is published. */
 function stageScopedSemanticTransition(currentStates, transition, successfulSkillReads, causalBasis, successfulArtifactReads, acceptedResponse) {
     if (!Array.isArray(transition.transitions))
@@ -146,14 +137,17 @@ function stageScopedSemanticTransition(currentStates, transition, successfulSkil
     const provenanceUpdates = { global: {}, cwd: {}, session: {} };
     for (const scope of SCOPES) {
         const authored = patches.get(scope) ?? {};
-        const response = scope === "session" && acceptedResponse !== undefined
-            ? acceptedResponse
-            : currentStates[scope].response;
-        const patch = completePatch(authored, response);
-        const nextState = applyPatch(currentStates[scope], patch);
-        compileReadArtifacts(nextState, { artifacts: authored.artifacts ?? {} }, artifactReads.filter((read) => (read.scope ?? "global") === scope), provenanceUpdates[scope]);
-        compileReadSkills(scope, nextState, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
-        validateMaterializedTransition(nextState, scope);
+        const patch = { ...authored, ...(scope === "session" && acceptedResponse !== undefined ? { response: acceptedResponse } : {}) };
+        const materialized = applyPatch({ ...emptyState(), ...currentStates[scope] }, patch);
+        compileReadArtifacts(materialized, { artifacts: authored.artifacts ?? {} }, artifactReads.filter((read) => (read.scope ?? "global") === scope), provenanceUpdates[scope]);
+        compileReadSkills(scope, materialized, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
+        validateMaterializedTransition(materialized, scope);
+        const nextState = materialized;
+        for (const key of Object.keys(emptyState())) {
+            if (!Object.hasOwn(currentStates[scope], key) && !Object.hasOwn(patch, key)
+                && !(key === "artifacts" && Object.keys(provenanceUpdates[scope]).length > 0))
+                delete nextState[key];
+        }
         nextStates[scope] = nextState;
     }
     return {

package/node_modules/@llblab/pi-state-flow/dist/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.21.0",
+  "version": "0.24.0",
+  "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [
@@ -66,17 +67,17 @@
     "node": ">=22.19.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.87.0",
-    "@earendil-works/pi-ai": ">=0.87.0",
-    "@earendil-works/pi-coding-agent": ">=0.87.0",
-    "@earendil-works/pi-tui": ">=0.87.0"
+    "@earendil-works/pi-agent-core": ">=1.0.0",
+    "@earendil-works/pi-ai": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.87.0",
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
-    "@types/node": "latest",
-    "typescript": "latest"
+    "@earendil-works/pi-agent-core": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@types/node": "^26.4.0",
+    "typescript": "^7.0.2"
   }
 }

package/node_modules/@llblab/pi-state-flow/dist/skills/state-flow-guide/SKILL.md

@@ -15,7 +15,7 @@ State Flow's on-demand operational reference. Resolve the usage question or iden
 
 Passive tools access memory without starting an episode. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
 
-Operator commands: `/state-flow-status` inspects; `/state-flow-start` enables the current branch; `/state-flow-stop` ends active semantics without erasing memory or necessarily disabling passive tools.
+Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode without operator authorization.
 
 ## Map
 
@@ -56,7 +56,7 @@ Call `patch_state` alone per assistant response; await acceptance before depende
 
 The runtime waits cancelably for publication ownership, then applies authored Global/CWD operations to current canonical values. Untouched fields survive; overlapping targets follow successful acceptance order. Correct repeats succeed as `State already current.` without another semantic revision. Do not repeat external actions during a memory wait, or rebuild an entire scope from an older snapshot. Session ownership/history fences remain private, not a universal merge.
 
-Semantic planes `intents`, `contract`, `working`, `artifacts`, and the required `lazy` root are objects; nested lazy values may contain ordinary JSON without stored nulls. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
+When present, semantic planes `intents`, `contract`, `working`, `artifacts`, and `lazy` are objects; nested lazy values may contain ordinary JSON without stored nulls. Stored checkpoints and patches may omit any documented plane. Current and historical views assemble only known fields present in the selected scopes. Absent fields and empty responses are omitted from views. Checkpoint/tail readers ignore unknown top-level fields, and writers emit only known fields. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `patch_state` keeps its documented field grammar. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
 
 Illustrative deletion, only for an actually completed intent and after satisfying pending acquisitions:
 

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

@@ -1,10 +1,11 @@
 # State Flow documentation
 
-- [Usage and recovery](usage.md): Configuration, new/resumed sessions, Start/Stop, diagnostics, privacy, and storage recovery.
+- [Usage and recovery](usage.md): Configuration, new/resumed sessions, Active/Passive/Off controls, diagnostics, privacy, and storage recovery.
 - [Architecture](architecture.md): Semantic state, temporal algebra, Pi lifecycle, storage, publication, artifacts, and embedding contracts.
 - [Lazy state](lazy-state.md): Implemented ordinary-JSON lazy planes, an effective-by-default `lazy` read path, pure state/patch snapshots, narrow structural `meta` + `keys`, and recursive indexed array patches.
 - [Filesystem recovery](filesystem-recovery.md): Cohort-wide absence, partial-presence, malformed-evidence, repair-authority, and transaction rules.
 - [Temporal acceptance](temporal-acceptance.md): Required temporal properties and their executable witnesses.
 - [SDK compatibility](compatibility.md): Tested dependency stacks, public lifecycle seams, isolated validation, and host limits.
 - [Physical fork contract](fork-contract.md): Session-stream copying, live shared memory, child ownership/origin, and tested support boundaries.
+- [Agent contract relocation ledger](agent-contract-relocation.md): Source-bound paragraph-to-owner parity map for the compact `AGENTS.md`, with transferred clauses and validation evidence.
 - [Session performance](performance.md): Reproducible native-Pi/stateful workloads, long-session resume measurements, two-process publication probes, and evidence limits.

package/node_modules/@llblab/pi-state-flow/docs/agent-contract-relocation.md

@@ -0,0 +1,72 @@
+# Agent contract relocation ledger
+
+This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pre-compaction `AGENTS.md` (SHA-256 `0d328eacc96d6b67c5eb036a51adc27e1dcd24d20bb6695f2fff6d5a3c87737b`; source lines 3–58, based on commit `70baecde` plus the Passive-footprint and `barrier-block` edits). Each `L##` identifies exactly one original bullet/paragraph. Its destination is the current owner of that paragraph's reusable contract; where necessary, a compact root rule or executable witness is also named. The root remains approximately 1,300 words; its 0.23.0 default-mode rule supersedes the original Passive-default clause. This is a reviewed documentation trace, not a claim that prose links alone prove runtime correctness.
+
+## Composition, semantics, and model access
+
+- L03 domain ownership, entrypoint and mirrored tests → [composition](architecture.md#composition), [invariant tests](../tests/invariants.test.ts).
+- L04 Active opt-in, former Passive default/conditional projection, Off → [configuration](usage.md#configuration), [mode behavior](usage.md#active-passive-and-configured-off).
+- L05 three session-owned mode workflows and global default → [mode behavior](usage.md#active-passive-and-configured-off), [configuration](usage.md#configuration).
+- L06 native trace, frozen head, run anchors and foreign context → [Pi lifecycle](architecture.md#pi-lifecycle), [context limits](performance.md#context-projection-and-trajectory-selection), [lifecycle witnesses](temporal-acceptance.md#required-properties-and-witnesses).
+- L07 sparse planes, projection, lazy filtering and intents → [semantic state](architecture.md#semantic-state), [model tools](architecture.md#model-tools), [lazy state](lazy-state.md).
+- L08 artifact entries and hidden provenance → [artifact routing](architecture.md#artifact-routing).
+- L09 exact registered-path observation → [artifact routing](architecture.md#artifact-routing), [source acquisition](usage.md#memory-and-source-acquisition).
+- L10 compilation classifier, fingerprints and Skill masking → [artifact routing](architecture.md#artifact-routing).
+- L11 stable exact-path acquisition and fork provenance → [artifact routing](architecture.md#artifact-routing), [Git/restore provenance](architecture.md#optional-git-backup), [fork contract](fork-contract.md).
+- L12 global config, legacy modes and limits → [configuration](usage.md#configuration), [mode compatibility](compatibility.md#mode-configuration-compatibility).
+- L13 session runtime/config/checkpoints and continuation authority → [storage and identity](architecture.md#storage-and-identity), [session continuation](architecture.md#session-continuation), [mode restoration](compatibility.md#mode-selection-and-memory-restoration).
+- L14 overlay, scope ownership and Skill routing → [semantic state](architecture.md#semantic-state), [artifact routing](architecture.md#artifact-routing).
+- L17 composed historical offsets → [temporal model](architecture.md#temporal-model).
+- L18 lazy historical reads and tool availability → [model tools](architecture.md#model-tools), [lazy navigation](usage.md#lazy-navigation-and-historical-reading).
+- L27 patch grammar, shared-head staging and private ownership → [model tools](architecture.md#model-tools), [asynchronous transaction](architecture.md#asynchronous-storage-transaction).
+- L28 barrier and minimal acceptance receipts → [Pi lifecycle](architecture.md#pi-lifecycle), [tool preflight evidence](performance.md#tool-preflight-parent-traversal).
+- L29 accepted-response reconciliation and cancellation → [Pi lifecycle](architecture.md#pi-lifecycle), [session behavior](usage.md#session-behavior).
+- L35 omission, empty-scope rejection and response equivalence → [model tools](architecture.md#model-tools), [temporal model](architecture.md#temporal-model).
+- L37 public-boundary draft detachment → [storage and identity](architecture.md#storage-and-identity), [COW evidence](performance.md#memory-only-owned-draft-cow).
+- L38 recursive patch/null and replay → [model tools](architecture.md#model-tools), [semantic state](architecture.md#semantic-state).
+- L39 no project schemas or size/action ledgers → [model tools](architecture.md#model-tools), [operational boundaries](../README.md#operational-boundaries).
+- L49 no strict boundedness claim → [operational boundaries](../README.md#operational-boundaries), [performance limits](performance.md#scope).
+- L51 tool toggle and Passive read/write boundary → [mode behavior](usage.md#active-passive-and-configured-off), [model tools](architecture.md#model-tools).
+
+## Canonical storage, lifecycle, and backup
+
+- L15 anchored checkpoints/tails and retention folding → [temporal model](architecture.md#temporal-model), [storage and identity](architecture.md#storage-and-identity).
+- L16 opaque causal identity, origins and shared drift → [temporal model](architecture.md#temporal-model), [Pi lifecycle](architecture.md#pi-lifecycle).
+- L19 canonical layout and identity → [storage and identity](architecture.md#storage-and-identity).
+- L20 optimistic durability, optional backup and contention → [power-loss boundary](filesystem-recovery.md#power-loss-durability), [asynchronous transaction](architecture.md#asynchronous-storage-transaction), [optional Git backup](architecture.md#optional-git-backup).
+- L21 cohort classification and missing shared pairs → [recovery](usage.md#missing-partial-and-malformed-storage), [transaction rule](filesystem-recovery.md#transaction-rule).
+- L22 predecessor formats and no in-place migration → [format boundary](usage.md#moving-a-store-and-the-017-format-boundary), [optional Git backup](architecture.md#optional-git-backup).
+- L23 exact-file CAS, awaited transaction and rollback → [asynchronous transaction](architecture.md#asynchronous-storage-transaction), [storage and identity](architecture.md#storage-and-identity), [transaction rule](filesystem-recovery.md#transaction-rule).
+- L24 initialization and exact-source fork → [Pi lifecycle](architecture.md#pi-lifecycle), [fork contract](fork-contract.md).
+- L25 retained-boundary restore, failed-Stop read-only recovery and selection races → [Pi lifecycle](architecture.md#pi-lifecycle), [mode restoration](compatibility.md#mode-selection-and-memory-restoration).
+- L26 independent revisions, backup capture/index/push/shutdown → [temporal model](architecture.md#temporal-model), [optional Git backup](architecture.md#optional-git-backup).
+- L40 first active context preparation, abort and specification authority → [Pi lifecycle](architecture.md#pi-lifecycle), [pre-inference cancellation](compatibility.md#pre-inference-cancellation).
+- L41 one existing-session bootstrap run → [session behavior](usage.md#session-behavior).
+- L42 selected-branch retained-boundary restoration → [Pi lifecycle](architecture.md#pi-lifecycle), [fork contract](fork-contract.md).
+- L44 Start/current-head acceptance and Active default → [asynchronous transaction](architecture.md#asynchronous-storage-transaction), [mode behavior](usage.md#active-passive-and-configured-off).
+- L45 Passive/Off persistence and frozen Stop handoff → [Pi lifecycle](architecture.md#pi-lifecycle), [mode operations](usage.md#lifecycle-operations), [mode restoration](compatibility.md#mode-selection-and-memory-restoration).
+- L46 failed-Stop marker and fence → [storage recovery](usage.md#storage-and-recovery), [Pi lifecycle](architecture.md#pi-lifecycle).
+- L47 settled native compaction boundary → [session behavior](usage.md#session-behavior), [SDK settlement](compatibility.md#settlement-cancellation), [lifecycle witnesses](temporal-acceptance.md#required-properties-and-witnesses).
+
+## Operator, agent, and development policy
+
+- L30 terminal handoff plane routing → [operational guidance](architecture.md#operational-guidance-and-memory-curation), [semantic state](architecture.md#semantic-state).
+- L31 consequential evidence, semantic references and dangling hints → [model tools](architecture.md#model-tools), [lazy navigation](usage.md#lazy-navigation-and-historical-reading), [memory curation](architecture.md#operational-guidance-and-memory-curation).
+- L32 volatile observation and external-effects revalidation → [operational boundaries](../README.md#operational-boundaries), [memory guidance](usage.md#memory-and-source-acquisition).
+- L33 registered Skill acquisition → [artifact routing](architecture.md#artifact-routing).
+- L34 bounded curation and verified transfers → [operational guidance](architecture.md#operational-guidance-and-memory-curation), [memory Skill](../skills/state-flow-memory/SKILL.md).
+- L36 logging categories, privacy and error elision → [diagnostic privacy](usage.md#diagnostic-logging-and-privacy), [barrier contract](architecture.md#pi-lifecycle).
+- L43 terminal status and read-only scope inspection → [status and controls](usage.md#status-and-controls), [observability](architecture.md#observability).
+- L48 system section, context refresh and foreign prompt precedence → [Pi lifecycle](architecture.md#pi-lifecycle), [host context compatibility](compatibility.md#context-tools-and-provider-input).
+- L50 extension-agnostic core and Telegram controls/receipts → [composition](architecture.md#composition), [observability](architecture.md#observability), [Telegram compatibility](compatibility.md#telegram-adapter).
+- L52 tag release authority and version alignment → [release workflow](../.github/workflows/release.yml), [release boundary](../BACKLOG.md#release-boundary). Retain the durable no-token constraint in compact `AGENTS.md` until a permanent developer contract owns it.
+- L53 opt-in benchmark location and source identity → [benchmark guide](../benchmarks/README.md), [performance validation](performance.md#validation-and-reporting).
+- L54 provider callback completion witness → [temporal acceptance](temporal-acceptance.md#required-properties-and-witnesses), [integration tests](../tests/integration.test.ts).
+- L55 awaited fixture handlers and withdrawal witness → [temporal acceptance](temporal-acceptance.md#required-properties-and-witnesses), [extension tests](../tests/extension.test.ts).
+- L56 tracked `dist/` and build/package parity → [release workflow](../.github/workflows/release.yml), [release invariant tests](../tests/invariants.test.ts). Retain the developer rule in compact `AGENTS.md` unless a durable release guide takes ownership.
+- L57 current docs vs delivery history → [documentation index](README.md), compact `AGENTS.md` (durable documentation policy).
+- L58 validation order → compact `AGENTS.md` (durable development rule), [validation procedure](compatibility.md#validation-procedure).
+
+## Verification evidence
+
+The map names all 56 source paragraphs exactly once. Each was compared with its destinations; the highest-risk clause groups were checked explicitly: L06/L45 native run anchors and Stop context, L23–L26 CAS/backup/rollback, L28 receipt-elision bounds, L31 reference/epistemic limits, L36 diagnostic privacy, L47 native compaction and L50 callback revocation. An additional exact-code-token audit exposed otherwise easy-to-lose clauses: legacy `{disabled:true}`, in-memory header key derivation, materialization equality, `contract.compiled_skills` rejection, Skill compiler revision, runtime-origin null exception and normalized artifact replay. Those are now stated in architecture; terse `patches[n]` and `{value:null, hint:[...]}` from the source are represented there by the more precise scoped patch path and expanded dangling-reference sentinel. The remaining uniquely durable developer rules, including no live-store fixture edits, stay in the compact root. `tests/invariants.test.ts` is unchanged; native and domain-specific witnesses remain in their named test files. Package, context and domain-DAG validation establish the final checked boundary; they cannot substitute for semantic judgment about future models.