@llblab/pi-kit 0.24.1 → 0.26.0

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

@@ -7,9 +7,19 @@ 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;
 }
+/**
+ * Read only mode policy, without validating or accessing semantic checkpoint metadata.
+ * Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
+ * Legacy `enabled:false` follows the caller's inactive policy.
+ */
+export declare function readCheckpointMode(value: unknown, inactiveMode?: InactiveMode): StateFlowMode | undefined;
 interface LegacyValidationFeedback {
     attempt: number;
     error: string;
@@ -52,23 +62,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,21 @@ 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 mode policy, without validating or accessing semantic checkpoint metadata.
+ * Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
+ * Legacy `enabled:false` follows the caller's inactive policy.
+ */
+export function readCheckpointMode(value, inactiveMode = "passive") {
+    if (!isObject(value))
+        return undefined;
+    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 +46,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 +76,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 +84,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 ? readCheckpointMode(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 +131,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 +146,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 = readCheckpointMode(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 +180,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);
 }

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

@@ -1,6 +1,6 @@
 import { type ArtifactCompilationUpdate, type ArtifactModelHints, type ArtifactRegistry } from "./artifact.ts";
 import { type JsonObject } from "./json.ts";
-/** The canonical semantic state shape shared by global, CWD, and session scopes. */
+/** Runtime defaults for documented semantic planes; stored objects may omit them or retain other fields. */
 export type MaterializedState = JsonObject & {
     intents: JsonObject;
     contract: JsonObject;
@@ -9,6 +9,16 @@ export type MaterializedState = JsonObject & {
     response: string;
     lazy: JsonObject;
 };
+/** Sparse semantic state: documented planes may be absent. Disk codecs select only known fields. */
+export type SemanticState = JsonObject & Partial<{
+    intents: JsonObject;
+    contract: JsonObject;
+    working: JsonObject;
+    artifacts: ArtifactRegistry;
+    response: string;
+    lazy: JsonObject;
+}>;
+export type ScopedSemanticStates = Record<StateScope, SemanticState>;
 /** Compatibility name for callers that still treat materialized state as a document. */
 export type StateDocument = MaterializedState;
 /** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
@@ -52,11 +62,14 @@ export interface ScopedStates {
 }
 export declare function emptyState(): MaterializedState;
 export declare function isMaterializedState(value: unknown): value is MaterializedState;
+/** Missing planes are valid storage, not missing authority. Present values retain their type checks. */
+export declare function isSemanticState(value: unknown): value is SemanticState;
 export declare const isStateDocument: typeof isMaterializedState;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
 export declare function updateMaterializedArtifacts(state: MaterializedState, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): MaterializedState;
 /** Overlay lower-to-higher scopes without mutating any scope document. */
-export declare function overlayStates(...scopes: readonly MaterializedState[]): MaterializedState;
+export declare function overlayStates(...scopes: readonly JsonObject[]): MaterializedState;
+/** Default-bearing SDK compatibility view; model transport uses sparse SemanticState instead. */
 export type ModelState = JsonObject & {
     intents: JsonObject;
     contract: JsonObject;
@@ -64,5 +77,11 @@ export type ModelState = JsonObject & {
     artifacts: ArtifactRegistry;
     response: string;
 };
+/** Select only owned top-level fields, preserving nested data and replay deletion markers. */
+export declare function selectSemanticFields(value: JsonObject): JsonObject;
+/** Read only documented, present planes; empty responses carry no semantic value. */
+export declare function projectSemanticState(state: JsonObject): SemanticState;
+/** Preserve deletion meaning in visible history without exposing ignored fields or empty responses. */
+export declare function projectSemanticPatch(patch: JsonObject): JsonObject;
 /** Model-visible projection: lazy bodies and runtime artifact bookkeeping stay out of ordinary context. */
-export declare function projectStateForModel(state: MaterializedState, artifactHints?: ArtifactModelHints): ModelState;
+export declare function projectStateForModel(state: SemanticState, artifactHints?: ArtifactModelHints): SemanticState;

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

@@ -10,8 +10,11 @@ export function isMaterializedState(value) {
         && isObject(value.working)
         && isObject(value.intents)
         && typeof value.response === "string"
-        && isObject(value.lazy)
-        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "intents" || key === "response" || key === "lazy");
+        && isObject(value.lazy);
+}
+/** Missing planes are valid storage, not missing authority. Present values retain their type checks. */
+export function isSemanticState(value) {
+    return isObject(value) && isMaterializedState({ ...emptyState(), ...value });
 }
 export const isStateDocument = isMaterializedState;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
@@ -27,14 +30,31 @@ export function overlayStates(...scopes) {
         return applyPatch(effective, scope);
     }, emptyState());
 }
+/** Select only owned top-level fields, preserving nested data and replay deletion markers. */
+export function selectSemanticFields(value) {
+    return structuredClone(Object.fromEntries(Object.keys(emptyState())
+        .filter((key) => Object.hasOwn(value, key))
+        .map((key) => [key, value[key]])));
+}
+/** Read only documented, present planes; empty responses carry no semantic value. */
+export function projectSemanticState(state) {
+    const projected = selectSemanticFields(state);
+    if (projected.response === "")
+        delete projected.response;
+    return projected;
+}
+/** Preserve deletion meaning in visible history without exposing ignored fields or empty responses. */
+export function projectSemanticPatch(patch) {
+    const projected = selectSemanticFields(patch);
+    if (projected.response === "")
+        projected.response = null;
+    return projected;
+}
 /** Model-visible projection: lazy bodies and runtime artifact bookkeeping stay out of ordinary context. */
 export function projectStateForModel(state, artifactHints = {}) {
-    const cloned = structuredClone(state);
-    return {
-        intents: cloned.intents,
-        contract: cloned.contract,
-        working: cloned.working,
-        artifacts: projectArtifactsForModel(cloned.artifacts, artifactHints),
-        response: cloned.response,
-    };
+    const { lazy: _hidden, ...visible } = state;
+    const projected = projectSemanticState(visible);
+    if (projected.artifacts)
+        projected.artifacts = projectArtifactsForModel(projected.artifacts, artifactHints);
+    return projected;
 }

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

@@ -1,7 +1,7 @@
 import type { ArtifactInvalidationReason } from "./artifact.ts";
-import { type RecentTransitionWindow } from "./history.ts";
+import type { RecentTransitionWindow } from "./history.ts";
 import type { Snapshot } from "./snapshot.ts";
-import { type ScopedStates, type StateScope } from "./state.ts";
+import { type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
 import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 export declare const STATUS_KEY = "state-flow";
 export type Colorize = (color: "accent" | "dim", text: string) => string;
@@ -16,6 +16,8 @@ export interface StatusDiagnostics {
     cwdScopeKey: string;
     sessionScopeKey: string;
     scopeStates: ScopedStates;
+    /** Overlay raw scopes before defaults so absent scalar planes cannot mask lower scopes. */
+    effectiveState?: SemanticState;
     recent: RecentTransitionWindow;
     historyLimit: number;
     temporal?: {
@@ -29,5 +31,5 @@ export interface StatusDiagnostics {
     publicationError?: string;
 }
 export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
-export declare function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined;
+export declare function compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined;
 export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;

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

@@ -1,27 +1,26 @@
-import { projectRecentTransitionsWithLimit } from "./history.js";
-import { retainedMemoryScopes } from "./memory.js";
 import { conciseDiagnostic } from "./protocol.js";
-import { overlayStates } from "./state.js";
+import { overlayStates, projectSemanticState } from "./state.js";
 export const STATUS_KEY = "state-flow";
 export function formatScopeRevisionVector(revisions) {
-    return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
+    return `g${revisions.global}c${revisions.cwd}s${revisions.session}`;
 }
-export function compactStatus(snapshot, revisions, colorize) {
-    if (!snapshot.config.enabled)
+export function compactStatus(snapshot, _revisions, colorize) {
+    const { mode } = snapshot.config;
+    if (mode === "off")
         return undefined;
-    return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
+    return `${colorize("accent", "state-flow")} ${colorize("dim", mode)}`;
 }
 function countArtifacts(states, scope) {
     return Object.keys(states[scope].artifacts).length;
 }
 export function detailedStatus(snapshot, diagnostics) {
-    const projectedRecent = projectRecentTransitionsWithLimit(diagnostics.historyLimit, diagnostics.recent);
     const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
-    const materialized = !available ? undefined : overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session);
-    const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2);
+    const materialized = !available ? undefined : diagnostics.effectiveState ?? projectSemanticState(overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session));
+    // Only top-level plane boundaries gain whitespace; nested user JSON stays unchanged.
+    const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2).replace(/,\n(?=  ")/g, ",\n\n");
     const invalidated = available ? String(diagnostics.staleArtifacts.length) : "unavailable";
     const invalidationLines = diagnostics.staleArtifacts.length === 0
-        ? ["Pending artifact invalidations: none"]
+        ? []
         : [
             "Pending artifact invalidations:",
             ...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
@@ -29,29 +28,21 @@ export function detailedStatus(snapshot, diagnostics) {
     const temporal = available ? diagnostics.temporal : undefined;
     const temporalLines = temporal === undefined
         ? [`Temporal materialization unavailable: ${conciseDiagnostic(diagnostics.durableStateError ?? "no selected branch runtime")}`,
-            `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
-            "Retained patch tails: unavailable"]
-        : [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
-            `Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
-            `Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
-            `Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
-    const artifacts = (scope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
-    const memoryScopes = available ? retainedMemoryScopes(diagnostics.scopeStates) : undefined;
+            `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`]
+        : [`Scope revisions: ${formatScopeRevisionVector(temporal.revisions)}`,
+            `Runtime metadata: step #${snapshot.meta.step}${snapshot.meta.bootstrap ? "; bootstrap" : ""}`,
+            `Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`];
+    const artifacts = (scope) => countArtifacts(diagnostics.scopeStates, scope);
+    const hasArtifacts = available && ["global", "cwd", "session"].some((scope) => artifacts(scope) > 0);
     return [
-        `State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
         `Repository: ${diagnostics.repositoryRoot}`,
         `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
-        "Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
-        `Runtime metadata: step #${snapshot.meta.step}; bootstrap ${snapshot.meta.bootstrap === true}`,
-        "Memory: owner state-flow; global retention enabled; global fallback active",
-        `Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
         ...temporalLines,
-        ...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after Stop: ${conciseDiagnostic(diagnostics.publicationError)}`]),
-        `Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`,
-        available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
+        ...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after mode change: ${conciseDiagnostic(diagnostics.publicationError)}`]),
+        ...(hasArtifacts ? [`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`] : []),
         ...invalidationLines,
         ...(stateJson === undefined
             ? ["Effective memory: unavailable"]
-            : [`Effective memory (${Buffer.byteLength(stateJson, "utf8")} JSON bytes; global → CWD → session overlay):`, "", stateJson]),
+            : ["Effective memory:", "", stateJson]),
     ].join("\n");
 }

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

@@ -1,9 +1,11 @@
+import type { StateFlowMode } from "./snapshot.ts";
 import type { ScopeRevisions } from "./temporal.ts";
 export declare const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export declare function stateFlowTelegramSectionSpecifiers(moduleUrl?: string): string[];
 export interface StateFlowTelegramSnapshot {
-    enabled: boolean;
+    /** The current session's selected mode. */
+    mode: StateFlowMode;
     /** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
     step: number;
     revisions?: ScopeRevisions;
@@ -12,11 +14,11 @@ export interface StateFlowTelegramSnapshot {
 }
 export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
 export interface StateFlowTelegramState {
-    artifacts: Record<string, unknown>;
-    contract: Record<string, unknown>;
-    working: Record<string, unknown>;
-    intents: Record<string, unknown>;
-    response: string;
+    artifacts?: Record<string, unknown>;
+    contract?: Record<string, unknown>;
+    working?: Record<string, unknown>;
+    intents?: Record<string, unknown>;
+    response?: string;
     lazy?: unknown;
 }
 export type StateFlowTelegramRichText = string | StateFlowTelegramRichText[] | {
@@ -92,26 +94,26 @@ export interface StateFlowTelegramPort {
     state(scope: StateFlowTelegramScope): StateFlowTelegramState;
     /** Optional additive capability; absent legacy ports retain their branch-step presentation. */
     revisions?(): ScopeRevisions;
+    /** Active may need a settled native boundary; inactive modes apply immediately. */
     canStartNow(): boolean;
-    start(): StateFlowTelegramControlResult;
-    stop(): StateFlowTelegramControlResult;
+    /** Select the current session's mode through the same lifecycle owners as the terminal commands. */
+    select(mode: StateFlowMode): StateFlowTelegramControlResult;
     deferStart(): void;
     cancelStart(): void;
 }
-export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "start" | "stop"> {
+export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "select"> {
     inspect(scope: StateFlowTelegramScope): StateFlowTelegramInspection | Promise<StateFlowTelegramInspection>;
-    start(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
-    stop(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+    select(mode: StateFlowMode): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
 }
 export interface StateFlowTelegramAdapter {
     ensure(): Promise<boolean>;
     dispose(): void;
 }
-/** 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 declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string;
-/** The submenu header repeats the button's state line; the single action matches the current state. */
-export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string) => string): StateFlowTelegramView;
-export declare function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
+export declare const STATE_FLOW_MODES: readonly ["off", "passive", "active"];
+/** One radio-style mode row followed directly by read-only scope actions. */
+export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
 export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;