@llblab/pi-kit 0.14.1 → 0.16.0

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

@@ -10,6 +10,7 @@ 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";
 /** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
 export function serializeScopeStream(stream, scope, cwdIdentity) {
     validateScopeStream(stream, scope);
@@ -113,7 +114,7 @@ export function temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessio
 }
 export function sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
     const directory = sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory;
-    return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
+    return { config: join(directory, "config.json"), runtime: join(directory, RUNTIME_FILE), meta: join(directory, META_FILE) };
 }
 /** Unsupported state.json presence never becomes an anchored checkpoint. */
 export function loadScopeStream(cwd, sessionId, scope, repositoryRoot, sessionKey = sessionId) {
@@ -128,7 +129,7 @@ export function captureTemporalFileBases(cwd, sessionId, repositoryRoot, session
     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.meta])];
+        return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
     });
     return captureOwnedFileBases(paths, repositoryRoot);
 }
@@ -151,6 +152,10 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
 /** Merge authoritative owned leaves while preserving forward-compatible metadata siblings. */
 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"])
+            delete existing[key];
+    }
     const sources = serializeScopeStream(stream, scope, cwdIdentity);
     const value = {
         ...existing,
@@ -276,7 +281,7 @@ export function isStateFlowOwnedPath(candidate, repositoryRoot = getDurableRepos
         return cwdKey(segments[0])
             && sessionKey(segments[1])
             && (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
-                || segments[2] === "config.json" || segments[2] === META_FILE);
+                || segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
     }
     return false;
 }

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

@@ -6,3 +6,5 @@ export declare function resumeEpisode(snapshot: Snapshot, bootstrap: boolean): S
 export declare function stopEpisode(snapshot: Snapshot): Snapshot;
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */
 export declare function prepareRun(snapshot: Snapshot, prompt: string): boolean;
+/** Retain the full prompt only while its run remains recoverable and unfinished. */
+export declare function completeRun(snapshot: Snapshot): void;

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

@@ -25,3 +25,7 @@ export function prepareRun(snapshot, prompt) {
     snapshot.meta.validation = undefined;
     return true;
 }
+/** Retain the full prompt only while its run remains recoverable and unfinished. */
+export function completeRun(snapshot) {
+    delete snapshot.meta.specification;
+}

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

@@ -11,6 +11,11 @@ export interface StateFlowExtensionOptions {
     telegram?: {
         load?: StateFlowTelegramLoader;
     };
+    /** Test/SDK capability override; repository config remains the Pi default. */
+    passive?: {
+        bootstrap?: boolean;
+        tools?: boolean;
+    };
 }
 export declare const PATCH_STATE_TOOL_NAME = "patch_state";
 export declare const READ_STATE_TOOL_NAME = "read_state";

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

@@ -3,7 +3,7 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.js";
-import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.js";
+import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.js";
 import { ArtifactReadTracker } from "./acquisition.js";
 import { loadStateFlowConfig } from "./config.js";
 import { createStateFlowTelegramAdapter } from "./telegram.js";
@@ -16,15 +16,15 @@ import { emptyState, overlayStates, projectStateForModel } from "./state.js";
 import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility } from "./transition.js";
 import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.js";
 import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
-import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
+import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
 import { recoverSnapshot } from "./recovery.js";
 import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.js";
 import { coalescePublicationTarget, createPublicationQueue } from "./publication.js";
 import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.js";
 import { runPublicationWorker } from "./publication.js";
 import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.js";
-import { isObject, sameJson } from "./json.js";
-import { readStatePath } from "./query.js";
+import { canonicalJson, isObject, sameJson } from "./json.js";
+import { readProjectedState, readStatePath } from "./query.js";
 import { cwdScopeKey, resolveSessionAddress, sessionScopeKey, } from "./durable.js";
 import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.js";
 import { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath } from "./logging.js";
@@ -95,7 +95,12 @@ function separatedFailure(error) {
 }
 export default function stateFlowExtension(pi, options = {}) {
     const agentDir = options.agentDir ?? getAgentDir();
-    const config = loadStateFlowConfig(agentDir);
+    const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
+    const config = {
+        ...loadedConfig,
+        passiveBootstrap: options.passive?.bootstrap ?? loadedConfig.passiveBootstrap,
+        passiveTools: options.passive?.tools ?? loadedConfig.passiveTools,
+    };
     let snapshot = emptySnapshot();
     let scopeStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
     let branchHasSnapshot = false;
@@ -234,12 +239,16 @@ export default function stateFlowExtension(pi, options = {}) {
     function installScopeStates() {
         scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
     }
+    function passiveToolsAvailable() {
+        return snapshot.config.enabled || config.passiveTools;
+    }
     function syncStateFlowTools() {
         const active = pi.getActiveTools();
         const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
-        if (owned.every((name) => active.includes(name) === snapshot.config.enabled))
+        const available = passiveToolsAvailable();
+        if (owned.every((name) => active.includes(name) === available))
             return;
-        pi.setActiveTools(snapshot.config.enabled
+        pi.setActiveTools(available
             ? [...new Set([...active, ...owned])]
             : active.filter((name) => !owned.includes(name)));
     }
@@ -655,6 +664,15 @@ export default function stateFlowExtension(pi, options = {}) {
                     bootstrapContinuation = continuation;
             }
         }
+        if (!snapshot.config.enabled && (config.passiveBootstrap || config.passiveTools) && !runtime?.view) {
+            try {
+                runtime?.loadPassive();
+                installScopeStates();
+            }
+            catch (error) {
+                ctx.ui.notify(`State Flow passive memory is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            }
+        }
         if (snapshot.config.enabled)
             deferArtifactRefresh();
         syncStateFlowTools();
@@ -762,37 +780,44 @@ export default function stateFlowExtension(pi, options = {}) {
     pi.registerTool({
         name: READ_STATE_TOOL_NAME,
         label: "Read State",
-        description: "Read State Flow through a unified path such as state, state[1], state.cwd[2], or state.global.patches[0]. The legacy offset/scope form remains accepted. Read-only and lazy; unavailable hot history is an error.",
-        promptSnippet: "Read cached state or accepted scope patches with a unified path",
+        description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary.",
+        promptSnippet: "Read exact state values, structures, or historical semantic patches",
         parameters: Type.Object({
-            path: Type.Optional(Type.String({ description: "Unified query path; current aliases use index 0" })),
-            offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 7, description: "Legacy accepted-transition offset; defaults to 0" })),
-            scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"], { description: "Legacy projection at the same boundary; defaults to effective" })),
+            path: Type.Optional(Type.String({ description: "One semantic path; unscoped paths use effective, explicit roots may use effective/global/cwd/session and historical [N], and arrays support half-open [start..end] ranges" })),
+            paths: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Ordered query paths evaluated as one all-or-error read" })),
+            projection: Type.Optional(StringEnum(["value", "keys", "patch"], { description: "Value snapshot by default, structural keys with minimal meta, or the selected historical semantic patch" })),
         }, { additionalProperties: false }),
         async execute(_toolCallId, params, signal) {
             try {
-                if (!snapshot.config.enabled)
-                    throw new Error("State Flow is disabled on this session branch");
+                if (!passiveToolsAvailable())
+                    throw new Error("State Flow tools are disabled by configuration");
                 if (signal?.aborted)
                     throw new Error("State Flow read was aborted");
                 if (!runtime?.view)
                     throw new Error("State Flow temporal runtime is unavailable");
-                if (params.path !== undefined) {
-                    if (params.offset !== undefined || params.scope !== undefined)
-                        throw new Error("read_state path cannot be combined with legacy offset or scope");
-                    const result = readStatePath(runtime.view, params.path);
+                if (params.path === undefined && params.paths === undefined)
+                    throw new Error("read_state requires path or paths");
+                if (params.path !== undefined && params.paths !== undefined)
+                    throw new Error("read_state accepts path or paths, not both");
+                {
+                    const paths = params.paths ?? [params.path];
+                    if (paths.length === 1 && /^(?:global|cwd|session)\.patches(?:\[\d+\])?$/.test(paths[0])) {
+                        if (params.projection !== undefined && params.projection !== "value")
+                            throw new Error("Scope patch paths support only the value projection");
+                        const result = readStatePath(runtime.view, paths[0]);
+                        if (!("patch" in result))
+                            throw new Error("Expected a scope patch path");
+                        return {
+                            content: [{ type: "text", text: `\n${JSON.stringify({ patch: result.patch })}` }],
+                            details: { path: paths[0], transitionId: result.boundary.id },
+                        };
+                    }
+                    const result = readProjectedState(runtime.view, paths, params.projection);
                     return {
                         content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
-                        details: { path: params.path, transitionId: result.boundary.id },
+                        details: { ...(params.path === undefined ? { paths } : { path: params.path }), projection: params.projection ?? "value" },
                     };
                 }
-                const { offset = 0, scope = "effective" } = params;
-                const state = runtime.read(offset, scope === "effective" ? undefined : scope);
-                const boundary = runtime.view.lineage.at(-1 - offset);
-                return {
-                    content: [{ type: "text", text: `\n${JSON.stringify({ offset, scope, boundary, state: projectStateForModel(state) })}` }],
-                    details: { offset, scope, transitionId: boundary.id },
-                };
             }
             catch (error) {
                 throw separatedFailure(error);
@@ -827,8 +852,8 @@ export default function stateFlowExtension(pi, options = {}) {
         },
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
             try {
-                if (!snapshot.config.enabled)
-                    throw new Error("State Flow is disabled on this session branch");
+                if (!passiveToolsAvailable())
+                    throw new Error("State Flow tools are disabled by configuration");
                 if (signal?.aborted)
                     throw new Error("State Flow patch was aborted before materialization");
                 if (!isObject(params))
@@ -858,17 +883,29 @@ export default function stateFlowExtension(pi, options = {}) {
                     }
                     if (params.final !== true)
                         throw new Error('patch_state requires at least one scope patch or {"final":true}');
+                    if (!snapshot.config.enabled)
+                        return { content: [{ type: "text", text: "\nState unchanged; passive turns have no terminal barrier." }], details: { final: false } };
                     validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
                     terminalEligible = true;
                     return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
                 }
+                if (!runtime?.view) {
+                    runtime ??= createRuntime(ctx);
+                    runtime.prepare();
+                    const publication = runtime.initialize(snapshot, true, undefined, true);
+                    recordPolicyPublication(publication, ctx);
+                    installScopeStates();
+                    branchHasSnapshot = true;
+                }
+                runtime.migrateLegacyStorage();
+                installScopeStates();
                 const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
                 const semanticChange = ["global", "cwd", "session"].some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
                 const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
                 if (!semanticChange && !provenanceChange)
                     throw new Error('patch_state scope patches must materially update state or required provenance; omit them and use {"final":true} when unchanged');
                 commitStage(stage, ctx, false);
-                if (params.final === true) {
+                if (params.final === true && snapshot.config.enabled) {
                     terminalEligible = true;
                 }
                 updateUi(ctx);
@@ -1028,9 +1065,15 @@ export default function stateFlowExtension(pi, options = {}) {
                 bootstrap: snapshot.meta.bootstrap === true,
                 startPending: telegramStartPending,
             }),
-            state: (scope) => projectStateForModel(scope === "effective"
-                ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
-                : scopeStates[scope]),
+            state: (scope) => {
+                const selected = scope === "effective"
+                    ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
+                    : scopeStates[scope];
+                return {
+                    ...projectStateForModel(selected),
+                    ...(Object.hasOwn(selected, "lazy") ? { lazy: structuredClone(selected.lazy) } : {}),
+                };
+            },
             canStartNow: () => activeContext === undefined || activeContext.isIdle(),
             start: () => {
                 if (!activeContext)
@@ -1057,8 +1100,13 @@ export default function stateFlowExtension(pi, options = {}) {
     });
     void telegram.ensure();
     pi.on("before_agent_start", (event, ctx) => {
-        if (!snapshot.config.enabled)
-            return;
+        if (!snapshot.config.enabled) {
+            if (!config.passiveBootstrap || !runtime?.view)
+                return;
+            return {
+                systemPrompt: `${event.systemPrompt}\n\nState Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns do not require final:true and never trigger State Flow continuation or compaction.`,
+            };
+        }
         skillReads.clear();
         artifactReads.clear();
         if (artifactRefreshPending)
@@ -1084,7 +1132,13 @@ export default function stateFlowExtension(pi, options = {}) {
         if (passiveContinuation) {
             return { messages: passiveContinuationMessages(event.messages, passiveContinuation) };
         }
-        if (!snapshot.config.enabled || snapshot.meta.specification === undefined)
+        if (!snapshot.config.enabled) {
+            if (!config.passiveBootstrap || !runtime?.view)
+                return;
+            const state = projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session));
+            return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${canonicalJson({ state, lazy_navigation: lazyNavigationHint(state) })}`), ...event.messages] };
+        }
+        if (snapshot.meta.specification === undefined)
             return;
         const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
         const invalidations = artifactInvalidations.map(({ path, reason }) => ({ path, reason }));
@@ -1182,9 +1236,11 @@ export default function stateFlowExtension(pi, options = {}) {
             return;
         }
         let responseCommitted = false;
+        const specification = snapshot.meta.specification;
         try {
             const response = finalizedAssistantResponse(event.message);
             const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime.causalBasis());
+            completeRun(snapshot);
             commitStage(stage, ctx, true);
             responseCommitted = true;
             bootstrapContinuation = undefined;
@@ -1195,6 +1251,8 @@ export default function stateFlowExtension(pi, options = {}) {
             completedRunAccepted = !wasBootstrap;
         }
         catch (error) {
+            if (!responseCommitted && specification !== undefined)
+                snapshot.meta.specification = specification;
             recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
             ctx.ui.notify(responseCommitted
                 ? `State Flow committed the final response; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`

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

@@ -1,6 +1,6 @@
 // Domain: durable Git revision reads, compare-and-swap publication, and exact-commit push retry.
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, relative, resolve, sep } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -10,7 +10,7 @@ import { planLegacyStorageMigration } from "./migration.js";
 import { sameJson } from "./json.js";
 import { validateTemporalState } from "./temporal.js";
 import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
-import { assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.js";
+import { acquirePublicationLock, assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.js";
 const GIT_TIMEOUT_MS = 15_000;
 const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
 function git(repositoryRoot, args, options = {}) {
@@ -72,13 +72,7 @@ function withPublicationLock(repositoryRoot, action) {
         const root = assertRepositoryRoot(lockedRoot);
         const common = resolve(root, git(root, ["rev-parse", "--git-common-dir"]).stdout.trim());
         const path = resolve(common, "state-flow-publication.lock");
-        let descriptor;
-        try {
-            descriptor = openSync(path, "wx", 0o600);
-        }
-        catch (error) {
-            throw new Error(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
-        }
+        const descriptor = acquirePublicationLock(path, (cause) => new Error(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause }));
         try {
             writeFileSync(descriptor, `${process.pid}\n`);
             return action(root);
@@ -180,16 +174,15 @@ export function loadTemporalRevision(cwd, sessionId, repositoryRoot, revision, s
     const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
     const readFile = revisionFileReader(root, revision, [
         ...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
-        canonicalRuntime.config, canonicalRuntime.meta,
+        canonicalRuntime.config, canonicalRuntime.runtime,
     ]);
     const files = [];
     const scopes = {};
     const provenance = { global: {}, cwd: {}, session: {} };
     for (const { scope, paths } of scopePaths) {
         const selected = revisionScopeFiles(readFile, paths);
-        files.push(selected.checkpoint, selected.patches, ...(scope === "session" ? [] : [selected.meta]));
-        if (scope !== "session")
-            provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
+        files.push(selected.checkpoint, selected.patches, selected.meta);
+        provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
         try {
             scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope, scope === "cwd" ? cwd : undefined, selected.meta.content);
         }
@@ -198,16 +191,19 @@ export function loadTemporalRevision(cwd, sessionId, repositoryRoot, revision, s
         }
     }
     const readRuntime = (paths) => ({
-        paths, config: readFile(paths.config), meta: readFile(paths.meta),
+        paths, config: readFile(paths.config), runtime: readFile(paths.runtime), meta: readFile(paths.meta),
     });
-    const { paths: runtimePaths, config, meta } = readRuntime(canonicalRuntime);
-    files.push(config, meta);
-    const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
+    const { paths: runtimePaths, config, runtime, meta } = readRuntime(canonicalRuntime);
+    files.push(config, runtime);
+    const document = parseSessionRuntime(config.content, runtime.content, cwd, sessionId, meta.content);
     if (document === undefined)
         return { base: { head: revision, files }, scopes, provenance };
-    provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
+    if (Object.keys(provenance.session).length === 0 && document.meta.artifacts !== undefined) {
+        provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
+    }
+    const runtimeOwnerPath = runtime.content === undefined ? runtimePaths.meta : runtimePaths.runtime;
     const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
-        relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
+        relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimeOwnerPath, root),
     ]).stdout.trim();
     assertReadableRevision(root, owner);
     let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
@@ -342,7 +338,7 @@ export function adoptFileStateToGit(cwd, sessionId, repositoryRoot, revision, sn
         throw new Error("Git adoption must preserve the semantic step");
     const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
     runtime.meta.temporalRevision = "self";
-    const sources = serializeSessionRuntime(runtime, cwd, sessionId, selected.view.scopes.session, selected.base.files.find(({ path }) => path === sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey).meta)?.content);
+    const sources = serializeSessionRuntime(runtime, cwd, sessionId);
     initializeGitRepository(repositoryRoot);
     return withPublicationLock(repositoryRoot, (root) => {
         const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -351,13 +347,14 @@ export function adoptFileStateToGit(cwd, sessionId, repositoryRoot, revision, sn
         const provenancePaths = new Set([
             temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
             temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
+            temporalScopePaths(cwd, sessionId, "session", root, sessionKey).meta,
         ]);
         // Preserve exact valid scope bytes; only runtime provenance changes representation.
         const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
             || path.endsWith("patches.jsonl")
             || (provenancePaths.has(path) && identity !== "missing"))
             .map(({ path, content }) => ({ path, content: content }));
-        updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
+        updates.push({ path: paths.config, content: sources.config }, { path: paths.runtime, content: sources.runtime });
         const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head, path).content === content)
             ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
         if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
@@ -379,7 +376,7 @@ function includeUncommittedCohort(cwd, sessionId, root, current, updates, change
         return { scope, pair: desired([paths.checkpoint, paths.patches]) };
     });
     const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
-    const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.meta]) : [];
+    const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.runtime]) : [];
     const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head, [...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
     const absentFromHead = (files) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
     for (const { scope, pair } of pairs) {
@@ -405,7 +402,7 @@ export function publishTemporalStateToGit(cwd, sessionId, view, scopes, base, re
         if (runtime?.meta.publication === "files")
             throw new Error("Git publication requires explicit Git provenance");
         const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-        const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content, current.files.find(({ path }) => path === runtimePaths.meta)?.content, cwd, sessionId);
+        const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content, current.files.find(({ path }) => path === runtimePaths.runtime)?.content, cwd, sessionId, current.files.find(({ path }) => path === runtimePaths.meta)?.content);
         if (previousRuntime?.meta.publication === "files")
             throw new Error("File-only storage requires explicit full-cohort Git adoption");
         const runtimeOnly = runtime?.meta.temporalRevision !== undefined && runtime.meta.temporalRevision !== "self";

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

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { isJsonValue, isObject, sameJson, validatePatch } from "./json.js";
 export const RECENT_TRANSITION_LIMIT = 7;
 const SCOPES = new Set(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response", "lazy"]);
 /** Normalize accepted replacements into recursive-merge replay, including removals. */
 function replayPatch(before, after) {
     const entries = [];
@@ -28,9 +28,13 @@ function validateScopedPatch(value) {
     }
     validatePatch(value.patch);
     for (const [key, field] of Object.entries(value.patch)) {
-        if (!PATCH_KEYS.has(key) || (key === "response"
-            ? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
-            throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
+        const valid = key === "response"
+            ? value.scope === "session" && typeof field === "string"
+            : key === "lazy"
+                ? field !== null
+                : PATCH_KEYS.has(key) && isObject(field);
+        if (!PATCH_KEYS.has(key) || !valid) {
+            throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
         }
     }
 }

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

@@ -1,4 +1,28 @@
 import { createHash } from "node:crypto";
+const ARRAY_INDEX_SELECTOR = /^\[(0|[1-9]\d*)\]$/;
+function isIndexedArrayPatch(value) {
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((key) => ARRAY_INDEX_SELECTOR.test(key));
+}
+function applyArrayPatch(state, patch) {
+    const next = structuredClone(state);
+    for (const [selector, value] of Object.entries(patch)) {
+        const match = ARRAY_INDEX_SELECTOR.exec(selector);
+        const index = Number(match[1]);
+        if (!Number.isSafeInteger(index) || index >= next.length) {
+            throw new Error(`State patch array index ${selector} is out of bounds for length ${next.length}`);
+        }
+        if (value === null)
+            throw new Error(`State patch array index ${selector} cannot be deleted; replace the whole array instead`);
+        const current = next[index];
+        next[index] = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
+            ? applyArrayPatch(current, value)
+            : isObject(current) && isObject(value)
+                ? applyPatch(current, value)
+                : structuredClone(value);
+    }
+    return next;
+}
 export function applyPatch(state, patch) {
     const next = structuredClone(state);
     for (const [key, value] of Object.entries(patch)) {
@@ -7,9 +31,11 @@ export function applyPatch(state, patch) {
             continue;
         }
         const current = next[key];
-        const materialized = isObject(current) && isObject(value)
-            ? applyPatch(current, value)
-            : structuredClone(value);
+        const materialized = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
+            ? applyArrayPatch(current, value)
+            : isObject(current) && isObject(value)
+                ? applyPatch(current, value)
+                : structuredClone(value);
         Object.defineProperty(next, key, {
             value: materialized,
             enumerable: true,

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

@@ -2,7 +2,7 @@
 import { lstatSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { captureOwnedFileBases, cwdScopePaths, parseScopeStream, serializeScopeMetadata, serializeScopeStream, sessionScopeKey, sessionScopePaths, } from "./durable.js";
-import { canonicalJson } from "./json.js";
+import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
 /** Discover every owner-proven CWD and session cohort beneath the configured store. */
 function migrationDirectories(cwd, sessionId, root, sessionKey) {
     const selectedCwd = cwdScopePaths(cwd, root).directory;
@@ -58,12 +58,14 @@ function migrationDirectories(cwd, sessionId, root, sessionKey) {
             if (!identity || typeof identity !== "object" || Array.isArray(identity))
                 continue;
             const owner = identity;
-            if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0)
-                directories.push({ directory, scope: "session" });
+            if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
+                directories.push({ directory, scope: "session", cwdIdentity: cwdOwner, sessionId: owner.sessionId });
+            }
         }
     }
-    if (!directories.some(({ directory }) => directory === selectedSession))
-        directories.push({ directory: selectedSession, scope: "session" });
+    if (!directories.some(({ directory }) => directory === selectedSession)) {
+        directories.push({ directory: selectedSession, scope: "session", cwdIdentity: resolve(cwd), sessionId });
+    }
     return directories;
 }
 /** Read-only activation eligibility, before global migration or any repository publication. */
@@ -82,12 +84,16 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
 /** Detect predecessor snapshots or temporal envelopes without mutating the store. */
 export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
     const root = resolve(repositoryRoot);
-    return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory }) => {
+    return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
         if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined)
             return false;
         try {
             const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
-            return meta === null || typeof meta !== "object" || !("temporal" in meta);
+            if (meta === null || typeof meta !== "object" || !("temporal" in meta))
+                return true;
+            return scope === "session"
+                && lstatSync(join(directory, "runtime.json"), { throwIfNoEntry: false }) === undefined
+                && ("identity" in meta || "lineage" in meta);
         }
         catch {
             return true;
@@ -98,31 +104,41 @@ export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey
 export function planLegacyStorageMigration(cwd, sessionId, repositoryRoot, _origin, sessionKey = sessionId) {
     const root = resolve(repositoryRoot);
     const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
-    const paths = directories.flatMap(({ directory }) => [
+    const paths = directories.flatMap(({ directory, scope }) => [
         join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
+        ...(scope === "session" ? [join(directory, "config.json"), join(directory, "runtime.json")] : []),
     ]);
     const bases = captureOwnedFileBases(paths, root);
     const byPath = new Map(bases.map((base) => [base.path, base]));
     const updates = [];
     const scopes = [];
-    for (const { scope, directory, cwdIdentity } of directories) {
+    for (const { scope, directory, cwdIdentity, sessionId: ownedSessionId } of directories) {
         const checkpoint = byPath.get(join(directory, "checkpoint.json"));
         const patches = byPath.get(join(directory, "patches.jsonl"));
         const meta = byPath.get(join(directory, "meta.json"));
         if (checkpoint.content !== undefined) {
-            const stream = parseScopeStream(checkpoint.content, patches.content, scope, cwdIdentity, meta.content);
-            const source = serializeScopeStream(stream, scope, cwdIdentity);
-            let metadata = serializeScopeMetadata(undefined, stream, scope, cwdIdentity, meta.content);
+            const stream = parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
+            const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwdIdentity : undefined);
+            const metadata = serializeScopeMetadata(undefined, stream, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
+            const cohortUpdates = [
+                ...(checkpoint.content === source.checkpoint ? [] : [{ path: checkpoint.path, content: source.checkpoint }]),
+                ...(patches.content === source.patches ? [] : [{ path: patches.path, content: source.patches }]),
+                ...(meta.content === metadata ? [] : [{ path: meta.path, content: metadata }]),
+            ];
             if (scope === "session") {
-                const runtime = JSON.parse(metadata);
-                runtime.revision = "self";
-                runtime.temporalRevision = "self";
-                metadata = `${canonicalJson(runtime)}\n`;
+                const config = byPath.get(join(directory, "config.json"));
+                const runtimeFile = byPath.get(join(directory, "runtime.json"));
+                const runtime = parseSessionRuntime(config.content, runtimeFile.content, cwdIdentity, ownedSessionId, meta.content);
+                if (runtime !== undefined) {
+                    const serialized = serializeSessionRuntime(runtime, cwdIdentity, ownedSessionId);
+                    if (runtimeFile.content !== serialized.runtime)
+                        cohortUpdates.push({ path: runtimeFile.path, content: serialized.runtime });
+                }
             }
-            if (checkpoint.content !== source.checkpoint || patches.content !== source.patches || meta.content !== metadata) {
+            if (cohortUpdates.length > 0) {
                 if (!scopes.includes(scope))
                     scopes.push(scope);
-                updates.push({ path: checkpoint.path, content: source.checkpoint }, { path: patches.path, content: source.patches }, { path: meta.path, content: metadata });
+                updates.push(...cohortUpdates);
             }
             continue;
         }