@llblab/pi-kit 0.18.2 → 0.19.1

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

@@ -3,6 +3,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 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";
 /** 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)) {
@@ -15,6 +16,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         passiveTools: true,
         logging: false,
         showSuccessfulPatches: true,
+        historyLimit: DEFAULT_HISTORY_LIMIT,
     };
     let value;
     try {
@@ -25,7 +27,7 @@ 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", "remotePublication"]);
+    const allowed = new Set(["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}`);
     }
@@ -39,9 +41,8 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         throw new Error(`State Flow logging must be a boolean: ${path}`);
     if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean")
         throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
-    if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
-        throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${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}`);
     return {
         directory,
         autoStart: value.autoStart === true,
@@ -49,6 +50,6 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         passiveTools: value.passiveTools !== false,
         logging: value.logging === true,
         showSuccessfulPatches: value.showSuccessfulPatches !== false,
-        ...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication }),
+        historyLimit: typeof value.historyLimit === "number" ? value.historyLimit : DEFAULT_HISTORY_LIMIT,
     };
 }

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

@@ -1,10 +1,11 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { type ArtifactInvalidationNotice } from "./artifact.ts";
+import { type ArtifactInvalidationNotice, type ArtifactModelHints } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { type MaterializedState } from "./state.ts";
-export declare const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+import { type MaterializedState, type ModelState } 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): {
@@ -19,12 +20,12 @@ export interface PassiveContinuation {
     handoff: AgentMessage;
 }
 export declare function syntheticUser(text: string): AgentMessage;
-export declare function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage[];
-export declare function createPassiveContinuation(state: MaterializedState, startedAt?: number, activeRunStartedAt?: number): PassiveContinuation;
+export declare function createPassiveContinuation(state: ModelState, startedAt?: number, activeRunStartedAt?: number): 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, resolutionPending?: boolean): AgentMessage;
-export declare function currentRunTrajectory(messages: AgentMessage[], specification: string, anchorTimestamp: number | undefined): {
+export declare function runtimeContextMessage(snapshot: Snapshot, state: MaterializedState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;
+/** Captured identity survives text decoration; an uncertain boundary retains available context. */
+export declare function currentRunTrajectory(messages: AgentMessage[], specification: string | undefined, anchorTimestamp: number | undefined): {
     messages: AgentMessage[];
     anchorTimestamp?: number;
 };

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

@@ -1,7 +1,34 @@
 import { projectArtifactForModel } from "./artifact.js";
-import { canonicalJson } from "./json.js";
+import { isObject, presentationJson } from "./json.js";
 import { projectStateForModel } from "./state.js";
-export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+/** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
+export function projectSystemProtocol(messages, protocol) {
+    let lastSystem = -1;
+    let current;
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role !== "system")
+            continue;
+        lastSystem = index;
+        if (message.sections && Object.hasOwn(message.sections, "state_flow"))
+            current = message.sections.state_flow ?? undefined;
+    }
+    const section = protocol === undefined ? undefined : `<state_flow>\n${protocol}\n</state_flow>`;
+    if (lastSystem < 0 || current === section)
+        return messages;
+    return messages.map((message, index) => {
+        if (message.role !== "system")
+            return message;
+        const ownsSection = message.sections !== undefined && Object.hasOwn(message.sections, "state_flow");
+        if (!ownsSection && (index !== lastSystem || section === undefined))
+            return message;
+        const sections = { ...message.sections };
+        delete sections.state_flow;
+        if (index === lastSystem && section !== undefined)
+            sections.state_flow = section;
+        return { ...message, sections };
+    });
+}
 const LAZY_HINT_PATH = "effective.lazy";
 const LAZY_HINT_MAX_KEYS = 32;
 const LAZY_HINT_MAX_JSON_CHARS = 1024;
@@ -16,10 +43,10 @@ function lazyValueKind(value) {
 }
 /** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
 export function lazyNavigationHint(state) {
-    const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
-    if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy))
+    const entries = isObject(state.lazy) ? Object.entries(state.lazy) : [];
+    const base = { available: entries.length > 0, path: LAZY_HINT_PATH };
+    if (!base.available)
         return base;
-    const entries = Object.entries(state.lazy);
     if (entries.length > LAZY_HINT_MAX_KEYS)
         return base;
     const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
@@ -43,27 +70,23 @@ function contentText(content) {
 function messageText(message) {
     return contentText(message.content);
 }
-export function withoutPrivateValidation(messages) {
-    return messages.filter((message) => {
-        return !(message.role === "custom" && message.customType === VALIDATION_MESSAGE_TYPE);
-    });
-}
 export function createPassiveContinuation(state, startedAt = Date.now(), activeRunStartedAt) {
     return {
         startedAt,
         ...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
-        handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${canonicalJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
+        handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
     };
 }
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export function passiveContinuationMessages(messages, continuation) {
-    let start = continuation.activeRunStartedAt === undefined ? -1
-        : messages.findIndex((message) => message.role === "user" && message.timestamp === continuation.activeRunStartedAt);
-    if (start < 0)
-        start = messages.findIndex((message) => message.role === "user"
-            && typeof message.timestamp === "number"
-            && message.timestamp >= continuation.startedAt);
-    return [continuation.handoff, ...messages.filter((message, index) => message.role === "custom" ? message.customType !== VALIDATION_MESSAGE_TYPE : start >= 0 && index >= start)];
+    if (continuation.activeRunStartedAt !== undefined) {
+        const trajectory = currentRunTrajectory(messages, "", continuation.activeRunStartedAt);
+        return [continuation.handoff, ...trajectory.messages];
+    }
+    const start = messages.findIndex((message) => message.role === "user"
+        && typeof message.timestamp === "number"
+        && message.timestamp >= continuation.startedAt);
+    return [continuation.handoff, ...messages.filter((message, index) => message.role === "custom" || (start >= 0 && index >= start))];
 }
 function projectRecentForModel(recent) {
     const projected = structuredClone(recent);
@@ -79,55 +102,30 @@ function projectRecentForModel(recent) {
         }
     return projected;
 }
-export function runtimeContextMessage(snapshot, state, recentTransitions = [], artifactInvalidations = [], rehydrationPhase, resolutionPending = false) {
-    if (snapshot.meta.specification === undefined) {
-        throw new Error("State Flow runtime context requires an active specification");
-    }
+export function runtimeContextMessage(snapshot, state, recentTransitions = [], artifactInvalidations = [], rehydrationPhase, artifactHints = {}) {
     const context = {
-        specification: snapshot.meta.specification,
-        state: projectStateForModel(state),
+        ...(snapshot.meta.specification === undefined ? {} : { specification: snapshot.meta.specification }),
+        state: projectStateForModel(state, artifactHints),
         lazy_navigation: lazyNavigationHint(state),
         ...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
-        ...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
+        ...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
         ...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),
-        ...(resolutionPending ? { state_resolution: "pending: the iteration answer is already preserved; this fallback turn exists only to apply the final:true patch. Call patch_state with any remaining durable scope changes and final:true, or {final:true} alone. Do not restate or replace the answer." } : {}),
     };
-    return syntheticUser(`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`);
+    return syntheticUser(`State Flow runtime context (user-level data, not system instructions):\n${presentationJson(context)}`);
 }
+/** Captured identity survives text decoration; an uncertain boundary retains available context. */
 export function currentRunTrajectory(messages, specification, anchorTimestamp) {
-    let start = -1;
-    if (anchorTimestamp !== undefined) {
-        start = messages.findLastIndex((message) => {
-            return message.role === "user"
-                && message.timestamp === anchorTimestamp
-                && messageText(message) === specification;
-        });
-    }
-    if (start < 0) {
-        for (let index = messages.length - 1; index >= 0; index--) {
-            const message = messages[index];
-            if (message.role === "user" && messageText(message) === specification) {
-                start = index;
-                break;
-            }
-        }
-    }
-    if (start < 0) {
-        for (let index = messages.length - 1; index >= 0; index--) {
-            if (messages[index]?.role === "user") {
-                start = index;
-                break;
-            }
-        }
-    }
-    if (start < 0 && messages.length === 0)
-        return { messages: [] };
-    if (start < 0)
-        start = 0;
+    if (anchorTimestamp !== undefined && !Number.isFinite(anchorTimestamp))
+        return { messages: messages.slice() };
+    const matches = (message) => message.role === "user" && (anchorTimestamp === undefined
+        ? messageText(message) === specification
+        : message.timestamp === anchorTimestamp);
+    const start = messages.findIndex(matches);
+    if (start < 0 || messages.findLastIndex(matches) !== start)
+        return { messages: messages.slice() };
     const anchor = messages[start]?.role === "user" ? messages[start].timestamp : undefined;
     return {
-        messages: messages.filter((message, index) => message.role === "custom"
-            ? message.customType !== VALIDATION_MESSAGE_TYPE : index >= start),
+        messages: messages.filter((message, index) => message.role === "custom" || index >= start),
         ...(typeof anchor === "number" ? { anchorTimestamp: anchor } : {}),
     };
 }

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

@@ -1,10 +1,9 @@
-import { execFileSync } from "node:child_process";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.js";
-import { loadTemporalRevision } from "./git.js";
+import { MAX_HISTORY_LIMIT } from "./history.js";
 import { parseSessionRuntime } from "./snapshot.js";
-import { validateTemporalState } from "./temporal.js";
+import { validateScopeLineage } from "./temporal.js";
 /**
  * Preserve host-owned explicit session intent and consult State Flow only for
  * an ordinary default launch. The recommender is a read-only advisory port;
@@ -143,30 +142,19 @@ export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
         if (config === undefined && runtimeSource === undefined && meta === undefined) {
             return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
         }
-        const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
+        const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id);
         if (!runtime)
             return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
         if (!runtime.config.enabled)
             return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
-        if (runtime.meta.publication === "files") {
-            const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
-            const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
-            const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
-            if (!global || !cwd || !session)
-                throw new Error("incomplete file-only temporal cohort");
-            validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
-            return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
-        }
-        const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
-        if (runtimePath.startsWith(".."))
-            throw new Error("runtime provenance escapes repository");
-        const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-        if (!owner)
-            throw new Error("runtime owner commit is unavailable");
-        const restored = loadTemporalRevision(header.cwd, header.id, repositoryRoot, owner, sessionKey);
-        if (!restored.runtime || !restored.runtime.document.config.enabled)
-            throw new Error("selected Git runtime is not enabled");
-        return { stateFlow: { enabled: true, restorable: true }, reason: `exact Git runtime ${owner.slice(0, 12)} is restorable` };
+        const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
+        const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
+        const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
+        if (!global || !cwd || !session)
+            throw new Error("incomplete canonical temporal cohort");
+        // Shared streams are current, independently validated by their codecs, not frozen to this session's history.
+        validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
+        return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
     }
     catch (error) {
         return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };

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

@@ -1,12 +1,14 @@
 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;
     patches: string;
     temporal: ScopeTemporalMetadata;
 }
+/** Read-only activation eligibility for one canonical CWD scope. */
+export declare function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean;
 export interface ScopeTemporalMetadata {
     checkpoint: ScopeStream["checkpoint"]["through"];
     patches: ScopeStream["patches"][number]["transition"][];
@@ -42,15 +44,10 @@ export declare function sessionRuntimePaths(cwd: string, sessionId: string, repo
 };
 /** Unsupported state.json presence never becomes an anchored checkpoint. */
 export declare function loadScopeStream(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey?: string): ScopeStream | undefined;
-/** Include legacy names in the CAS basis solely to prevent format races during cutover. */
+/** Include unsupported predecessor names in the CAS basis so they cannot race canonical publication. */
 export declare function captureTemporalFileBases(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): DurableFileBase[];
 /** Select exact serialized scope updates from one validated active temporal cohort. */
 export declare function temporalStateFileUpdates(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], repositoryRoot: string, sessionKey?: string): OwnedFileUpdate[];
-export interface DurablePaths {
-    repositoryRoot: string;
-    globalState: string;
-    globalPatches: string;
-}
 /** Merge authoritative owned leaves while preserving forward-compatible metadata siblings. */
 export declare function serializeScopeMetadata(registry: Readonly<ArtifactProvenanceRegistry> | undefined, stream: ScopeStream, scope: StateScope, cwdIdentity?: string, existingSource?: string): string;
 /** Compatibility serializer retained for metadata-only callers. */
@@ -59,20 +56,16 @@ export declare function serializeScopeProvenance(registry: Readonly<ArtifactProv
 export declare function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry;
 export interface ScopePaths {
     directory: string;
-    state: string;
-    patches: string;
 }
 export interface DurableFileBase {
     path: string;
     identity: "missing" | `sha256:${string}`;
     content?: string;
-    /** Opaque originals for byte-exact rollback, including non-UTF-8 legacy journals. */
+    /** Opaque originals for byte-exact rollback. */
     bytes?: Uint8Array;
 }
 /** Dedicated runtime storage, independent from Markdown source discovery. */
 export declare function getDurableRepositoryRoot(agentDir?: string): string;
-/** Legacy snapshot paths retained only for one-way migration and exact ownership checks. */
-export declare function durablePaths(repositoryRoot?: string): DurablePaths;
 /** Match Pi's native project-session directory convention exactly. */
 export declare function cwdScopeKey(cwd: string): string;
 /** One safe directory segment, normally the native Pi session filename stem. */
@@ -82,13 +75,9 @@ export declare function sessionStorageKey(sessionFile: string | undefined, sessi
 export declare function resolveSessionAddress(sessionFile: string | undefined, sessionId: string, timestamp?: string): SessionAddress;
 export declare function cwdScopePaths(cwd: string, repositoryRoot?: string): ScopePaths;
 export declare function sessionScopePaths(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): ScopePaths;
-export declare function cwdStatePath(cwd: string, repositoryRoot?: string): string;
-export declare function cwdPatchesPath(cwd: string, repositoryRoot?: string): string;
-export declare function sessionStatePath(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): string;
-export declare function sessionPatchesPath(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): string;
-/** Exact semantic file shapes, including legacy snapshots only during the storage cutover. */
+/** Exact canonical semantic and runtime file shapes. */
 export declare function isStateFlowOwnedPath(candidate: string, repositoryRoot?: string): boolean;
-/** Capture exact owned bytes for one compare-and-swap publication or migration cohort. */
+/** Capture exact owned bytes for one compare-and-swap publication cohort. */
 export declare function captureOwnedFileBases(paths: readonly string[], repositoryRoot: string): DurableFileBase[];
 export interface OwnedFileUpdate {
     path: string;

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

@@ -3,18 +3,31 @@ import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFi
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseArtifactProvenanceRegistry, serializeArtifactProvenanceRegistry, } from "./artifact.js";
+import { MAX_HISTORY_LIMIT } from "./history.js";
 import { canonicalJson, isJsonValue, isObject } from "./json.js";
 import { validateScopeStream, validateTemporalState } from "./temporal.js";
-import { migratePreIntentState } 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";
 const PATCHES_FILE = "patches.jsonl";
 const META_FILE = "meta.json";
 const RUNTIME_FILE = "runtime.json";
+/** Read-only activation eligibility for one canonical CWD scope. */
+export function hasCwdMaterialization(cwd, repositoryRoot) {
+    const root = resolve(repositoryRoot);
+    const directory = cwdScopePaths(cwd, root).directory;
+    const [checkpoint, patches, meta] = captureOwnedFileBases([
+        join(directory, CHECKPOINT_FILE), join(directory, PATCHES_FILE), join(directory, META_FILE),
+    ], root);
+    if (checkpoint.content !== undefined)
+        return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
+    if (patches.content !== undefined)
+        throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
+    return false;
+}
 /** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
 export function serializeScopeStream(stream, scope, cwdIdentity) {
-    validateScopeStream(stream, scope);
+    validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
     if (scope === "cwd" && cwdIdentity === undefined)
         throw new Error("State Flow CWD scope serialization requires its canonical identity");
     if (scope !== "cwd" && cwdIdentity !== undefined)
@@ -30,6 +43,8 @@ export function serializeScopeStream(stream, scope, cwdIdentity) {
 }
 /** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
 export function classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd, metaSource) {
+    if (scope !== "global" && scope !== "cwd" && scope !== "session")
+        throw new Error("Unknown temporal scope");
     if (checkpointSource === undefined && patchesSource === undefined)
         return { kind: "absent" };
     if (checkpointSource === undefined || patchesSource === undefined) {
@@ -65,44 +80,22 @@ export function classifyScopeStream(checkpointSource, patchesSource, scope, expe
         }
     }
     const temporal = meta?.temporal;
-    if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
-        checkpoint = migratePreIntentState(checkpoint) ?? checkpoint;
-        const owner = meta?.owner;
-        if (scope === "cwd" && expectedCwd !== undefined
-            && (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
-            throw new Error(owner === undefined ? "State Flow CWD scope identity is missing" : "State Flow CWD scope identity mismatch");
-        }
-        const boundaries = temporal.patches;
-        if (boundaries.length !== patches.length)
-            throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
-        const stream = {
-            checkpoint: { through: temporal.checkpoint, state: checkpoint },
-            patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
-        };
-        validateScopeStream(stream, scope);
-        return { kind: "present", stream };
-    }
-    // Complete predecessor envelopes are the only no-meta form that may be unwrapped.
-    let legacyCheckpoint = checkpoint;
-    if (isObject(checkpoint) && Object.hasOwn(checkpoint, "owner")) {
-        const { owner, ...semantic } = checkpoint;
-        if (scope !== "cwd" || !isObject(owner) || Object.keys(owner).join(",") !== "cwd" || typeof owner.cwd !== "string") {
-            throw new Error("Invalid State Flow CWD scope identity");
-        }
-        if (expectedCwd !== undefined && owner.cwd !== resolve(expectedCwd))
-            throw new Error("State Flow CWD scope identity mismatch");
-        legacyCheckpoint = semantic;
-    }
-    else if (scope === "cwd" && expectedCwd !== undefined) {
-        throw new Error("State Flow CWD scope identity is missing");
-    }
-    if (isObject(legacyCheckpoint) && isObject(legacyCheckpoint.state)) {
-        const migrated = migratePreIntentState(legacyCheckpoint.state);
-        if (migrated)
-            legacyCheckpoint = { ...legacyCheckpoint, state: migrated };
-    }
-    const stream = { checkpoint: legacyCheckpoint, patches };
-    validateScopeStream(stream, scope);
+    if (!isObject(temporal) || !Object.hasOwn(temporal, "checkpoint") || !Array.isArray(temporal.patches)) {
+        throw new Error(`Unsupported State Flow ${scope} storage format`);
+    }
+    const owner = meta?.owner;
+    if (scope === "cwd" && expectedCwd !== undefined
+        && (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
+        throw new Error(owner === undefined ? "State Flow CWD scope identity is missing" : "State Flow CWD scope identity mismatch");
+    }
+    const boundaries = temporal.patches;
+    if (boundaries.length !== patches.length)
+        throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
+    const stream = {
+        checkpoint: { through: temporal.checkpoint, state: checkpoint },
+        patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+    };
+    validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
     return { kind: "present", stream };
 }
 /** Decode the entire bounded replay input before accepting any materialized state. */
@@ -127,22 +120,22 @@ export function sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey =
 export function loadScopeStream(cwd, sessionId, scope, repositoryRoot, sessionKey = sessionId) {
     const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
     if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-        throw new Error(`Legacy State Flow storage requires explicit migration: ${paths.directory}`);
+        throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
     }
     return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
 }
-/** Include legacy names in the CAS basis solely to prevent format races during cutover. */
+/** Include unsupported predecessor names in the CAS basis so they cannot race canonical publication. */
 export function captureTemporalFileBases(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
     const paths = ["global", "cwd", "session"].flatMap((scope) => {
         const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
         const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
-        return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
+        return [pair.checkpoint, pair.patches, ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
     });
     return captureOwnedFileBases(paths, repositoryRoot);
 }
 /** Select exact serialized scope updates from one validated active temporal cohort. */
 export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositoryRoot, sessionKey = sessionId) {
-    validateTemporalState(view);
+    validateTemporalState(view, MAX_HISTORY_LIMIT);
     const seen = new Set();
     return scopes.flatMap((scope) => {
         if (seen.has(scope))
@@ -150,7 +143,7 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
         seen.add(scope);
         const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
         if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-            throw new Error(`Legacy State Flow storage requires explicit migration: ${paths.directory}`);
+            throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
         }
         const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
         return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
@@ -160,7 +153,7 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
 export function serializeScopeMetadata(registry, stream, scope, cwdIdentity, existingSource) {
     const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
     if (scope === "session") {
-        for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap", "remotePublication", "revision", "temporalRevision", "publication"])
+        for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap"])
             delete existing[key];
     }
     const sources = serializeScopeStream(stream, scope, cwdIdentity);
@@ -206,15 +199,6 @@ export function parseScopeProvenance(source, path) {
 export function getDurableRepositoryRoot(agentDir = getAgentDir()) {
     return resolve(agentDir, "state-flow");
 }
-/** Legacy snapshot paths retained only for one-way migration and exact ownership checks. */
-export function durablePaths(repositoryRoot = getDurableRepositoryRoot()) {
-    const root = resolve(repositoryRoot);
-    return {
-        repositoryRoot: root,
-        globalState: join(root, STATE_FILE),
-        globalPatches: join(root, PATCHES_FILE),
-    };
-}
 /** Match Pi's native project-session directory convention exactly. */
 export function cwdScopeKey(cwd) {
     const canonical = resolve(cwd);
@@ -244,32 +228,17 @@ export function resolveSessionAddress(sessionFile, sessionId, timestamp) {
     return Object.freeze({ id: sessionId, key: sessionStorageKey(sessionFile, sessionId, timestamp) });
 }
 export function cwdScopePaths(cwd, repositoryRoot = getDurableRepositoryRoot()) {
-    const directory = join(resolve(repositoryRoot), cwdScopeKey(cwd));
-    return { directory, state: join(directory, STATE_FILE), patches: join(directory, PATCHES_FILE) };
+    return { directory: join(resolve(repositoryRoot), cwdScopeKey(cwd)) };
 }
 export function sessionScopePaths(cwd, sessionId, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId) {
-    const directory = join(cwdScopePaths(cwd, repositoryRoot).directory, sessionScopeKey(sessionKey));
-    return { directory, state: join(directory, STATE_FILE), patches: join(directory, PATCHES_FILE) };
-}
-export function cwdStatePath(cwd, repositoryRoot = getDurableRepositoryRoot()) {
-    return cwdScopePaths(cwd, repositoryRoot).state;
-}
-export function cwdPatchesPath(cwd, repositoryRoot = getDurableRepositoryRoot()) {
-    return cwdScopePaths(cwd, repositoryRoot).patches;
-}
-export function sessionStatePath(cwd, sessionId, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId) {
-    return sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).state;
-}
-export function sessionPatchesPath(cwd, sessionId, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId) {
-    return sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).patches;
+    return { directory: join(cwdScopePaths(cwd, repositoryRoot).directory, sessionScopeKey(sessionKey)) };
 }
-/** Exact semantic file shapes, including legacy snapshots only during the storage cutover. */
+/** Exact canonical semantic and runtime file shapes. */
 export function isStateFlowOwnedPath(candidate, repositoryRoot = getDurableRepositoryRoot()) {
     const root = resolve(repositoryRoot);
     const absolute = resolve(candidate);
-    const global = durablePaths(root);
-    if (absolute === global.globalState || absolute === global.globalPatches
-        || absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, META_FILE))
+    if (absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, PATCHES_FILE)
+        || absolute === join(root, META_FILE))
         return true;
     const segments = relative(root, absolute).split(sep);
     const cwdKey = (value) => value.startsWith("--") && value.endsWith("--");
@@ -282,12 +251,12 @@ export function isStateFlowOwnedPath(candidate, repositoryRoot = getDurableRepos
         }
     };
     if (segments.length === 2) {
-        return cwdKey(segments[0]) && (segments[1] === STATE_FILE || segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE || segments[1] === META_FILE);
+        return cwdKey(segments[0]) && (segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE || segments[1] === META_FILE);
     }
     if (segments.length === 3) {
         return cwdKey(segments[0])
             && sessionKey(segments[1])
-            && (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
+            && (segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
                 || segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
     }
     return false;
@@ -378,7 +347,7 @@ function assertCurrentBytes(path, root, expected) {
         throw new Error(`State Flow file conflict at ${path}; preserve concurrent bytes and reconcile before retrying`);
     }
 }
-/** Capture exact owned bytes for one compare-and-swap publication or migration cohort. */
+/** Capture exact owned bytes for one compare-and-swap publication cohort. */
 export function captureOwnedFileBases(paths, repositoryRoot) {
     const root = resolve(repositoryRoot);
     return paths.map((path) => {

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

@@ -1,13 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { formatPatchStateArguments, normalizePatchStateArguments } from "./protocol.ts";
+import { formatPatchStateArguments } from "./protocol.ts";
+import { type ModelState, type StateScope } from "./state.ts";
 import { type StateFlowTelegramLoader } from "./telegram.ts";
-import { type MaterializedState, type StateScope } from "./state.ts";
 export interface StateFlowExtensionOptions {
     agentDir?: string;
     repositoryRoot?: string;
-    knowledgeRoot?: string;
     onRuntime?: (accessor: {
-        read(offset?: number, scope?: StateScope): MaterializedState;
+        read(offset?: number, scope?: StateScope): ModelState;
     }) => void;
     telegram?: {
         load?: StateFlowTelegramLoader;
@@ -18,8 +17,7 @@ export interface StateFlowExtensionOptions {
         tools?: boolean;
     };
 }
-export { formatPatchStateArguments, normalizePatchStateArguments };
+export { formatPatchStateArguments };
 export declare const PATCH_STATE_TOOL_NAME = "patch_state";
 export declare const READ_STATE_TOOL_NAME = "read_state";
-export declare const MAX_FALLBACK_ATTEMPTS: number;
 export default function stateFlowExtension(pi: ExtensionAPI, options?: StateFlowExtensionOptions): void;