@llblab/pi-kit 0.15.0 → 0.17.0

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

@@ -2,100 +2,46 @@ import { randomUUID } from "node:crypto";
 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 { assistantToolCallCount, finalizedAssistantResponse, formatPatchStateArguments, normalizePatchStateArguments, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.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";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { SkillReadTracker } from "./skills.js";
 import { emptySnapshot, migrationFailure, persistableSnapshot, RevisionUnavailableError } from "./snapshot.js";
 import { readNativeSessionHeader } from "./continuation.js";
 import { MissingSessionRuntimeError, SharedScopeRemovalConflictError, TemporalRuntime } from "./runtime.js";
 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 { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, 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 { loadPublicationQueue, publicationQueuePath, PublicationWorkerController, resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } 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";
+import { StateFlowDiagnosticWriter, stateFlowLogPath } from "./logging.js";
 import { isGitCommitAncestor, pushGitCommit, pushGitTarget, resolveGitPushDestination } from "./git.js";
 import { ORDINARY_ARTIFACT_COMPILER, planArtifactInvalidation, } from "./artifact.js";
 import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult } from "./compaction.js";
+export { formatPatchStateArguments, normalizePatchStateArguments };
 export const PATCH_STATE_TOOL_NAME = "patch_state";
 export const READ_STATE_TOOL_NAME = "read_state";
 export const MAX_FALLBACK_ATTEMPTS = 2;
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 const PUBLICATION_SHUTDOWN_WAIT_MS = 2_000;
-const PATCH_DISPLAY_SECTION_KEYS = new Set([
-    "global",
-    "cwd",
-    "session",
-    "artifacts",
-    "contract",
-    "working",
-    "response",
-    "final",
-]);
-/** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
-export function formatPatchStateArguments(args) {
-    const seenAtIndent = new Set();
-    return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
-        const indent = line.length - line.trimStart().length;
-        const match = /^(\s+)"([^"]+)":/.exec(line);
-        if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
-            for (const seenIndent of seenAtIndent) {
-                if (seenIndent > indent)
-                    seenAtIndent.delete(seenIndent);
-            }
-            return [line];
-        }
-        const separator = seenAtIndent.has(indent) ? [""] : [];
-        seenAtIndent.add(indent);
-        return [...separator, line];
-    }).join("\n");
-}
-/** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
-export function normalizePatchStateArguments(args) {
-    if (!isObject(args) || !Object.hasOwn(args, "final"))
-        return args;
-    const value = args.final;
-    let final;
-    if (typeof value === "boolean")
-        final = value;
-    else if (value === 1)
-        final = true;
-    else if (value === 0)
-        final = false;
-    else if (typeof value === "string" && value.trim().toLowerCase() === "true")
-        final = true;
-    else if (typeof value === "string" && value.trim().toLowerCase() === "false")
-        final = false;
-    else
-        return args;
-    return { ...args, final };
-}
-/** Keep tool output visually separated from its heading with exactly one leading newline. */
-function separatedOutput(text) {
-    return `\n${text.replace(/^\n+/, "")}`;
-}
-/** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
-function separatedFailure(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
-}
 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;
@@ -120,15 +66,19 @@ export default function stateFlowExtension(pi, options = {}) {
     let pendingPublication;
     let rehydrationPhase;
     let turnPublicationTarget;
-    const activePublicationWorkers = new Map();
-    let publicationStopped = false;
     let publicationShutdown;
     const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
+    const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => activeContext?.ui.notify(message, "warning"));
+    const publicationWorker = new PublicationWorkerController({
+        resolveDestination: () => resolveGitPushDestination(repositoryRoot),
+        isAncestor: (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
+        push: (destination, target, signal) => pushGitTarget(repositoryRoot, destination, target, signal),
+        onDiverged: (dropped, target) => activeContext && recordDiagnostic(`Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`, "publication-conflict", activeContext),
+    });
     const skillReads = new SkillReadTracker();
     const artifactReads = new ArtifactReadTracker();
     const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
     let artifactInvalidations = [];
-    let loggingWarningReported = false;
     let telegramStartPending = false;
     function sessionAddress(ctx) {
         return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
@@ -179,29 +129,6 @@ export default function stateFlowExtension(pi, options = {}) {
         skillReads.clear();
         artifactReads.clear();
     }
-    function passiveStopBoundary(ctx) {
-        for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
-            try {
-                if (entry?.type !== "custom" || entry.customType !== PASSIVE_STOP_ENTRY_TYPE)
-                    continue;
-                const { at, from, reset, owner } = entry.data ?? {};
-                if (reset === true && owner === ctx.sessionManager.getSessionId())
-                    return undefined;
-                if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0)
-                    return {
-                        at,
-                        ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
-                    };
-            }
-            catch {
-                // A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
-            }
-        }
-        return undefined;
-    }
-    function retainsPhysicalSessionProjection(reason) {
-        return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
-    }
     function deferArtifactRefresh() {
         artifactInvalidations = [];
         artifactReads.setCandidates([]);
@@ -234,31 +161,19 @@ 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)));
     }
-    function assistantToolBatch(ctx, toolCallId) {
-        for (let cursor = ctx.sessionManager.getLeafEntry(); cursor; cursor = cursor.parentId ? ctx.sessionManager.getEntry(cursor.parentId) : undefined) {
-            const entry = cursor;
-            if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content))
-                continue;
-            const calls = entry.message.content.filter((block) => {
-                return typeof block === "object" && block !== null
-                    && block.type === "toolCall"
-                    && typeof block.id === "string"
-                    && typeof block.name === "string";
-            });
-            if (calls.some(({ id }) => id === toolCallId))
-                return calls.map(({ name }) => name);
-        }
-        return undefined;
-    }
     function recordPublication(publication, ctx) {
         const revision = publication.revision ?? publication.commit;
         if (revision !== undefined)
@@ -285,8 +200,8 @@ export default function stateFlowExtension(pi, options = {}) {
             return;
         turnPublicationTarget = target;
         try {
-            enqueueTurnPublication(ctx);
-            launchPublicationWorker();
+            enqueueTurnPublication();
+            publicationWorker.launch();
         }
         catch (error) {
             ctx.ui.notify(`State Flow accepted the local commit; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -329,104 +244,17 @@ export default function stateFlowExtension(pi, options = {}) {
         persist();
         return true;
     }
-    function enqueueTurnPublication(ctx) {
+    function enqueueTurnPublication() {
         const target = turnPublicationTarget;
         turnPublicationTarget = undefined;
-        if (!target)
-            return;
-        const destination = resolveGitPushDestination(repositoryRoot);
-        if (!destination)
-            return;
-        const path = publicationQueuePath(destination);
-        const previous = loadPublicationQueue(path);
-        const next = previous
-            ? coalescePublicationTarget(previous, destination, target, (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant), {
-                onDivergedLineage: (dropped) => recordDiagnostic(`Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`, "publication-conflict", ctx),
-            })
-            : createPublicationQueue(destination, target);
-        savePublicationQueue(path, next, previous);
-    }
-    function launchPublicationWorker() {
-        if (publicationStopped)
-            return;
-        let destination;
-        try {
-            destination = resolveGitPushDestination(repositoryRoot);
-        }
-        catch (error) {
-            if (error instanceof Error && /ENOENT/.test(error.message))
-                return;
-            throw error;
-        }
-        if (!destination)
-            return;
-        const path = publicationQueuePath(destination);
-        if (activePublicationWorkers.has(path))
-            return;
-        let queued;
-        let lease;
-        try {
-            queued = loadPublicationQueue(path);
-            if (!queued)
-                return;
-            lease = acquirePublicationWorkerLease(path);
-        }
-        catch {
-            return;
-        }
-        if (!lease)
-            return;
-        const controller = new AbortController();
-        const done = runPublicationWorker(queued, ({ target }) => pushGitTarget(repositoryRoot, destination, target, controller.signal), () => loadPublicationQueue(path) ?? queued, (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant)).then((result) => {
-            if (publicationStopped)
-                return; // Late outcomes belong to an unconfirmed queue, not the replacement generation.
-            const current = loadPublicationQueue(path);
-            if (!current)
-                return;
-            if (result.next === undefined) {
-                if (current.target === result.attempted.target)
-                    removePublicationQueue(path, current);
-                return;
-            }
-            if (current.target === result.attempted.target || result.next.target === current.target) {
-                savePublicationQueue(path, result.next, current);
-            }
-        }).catch(() => {
-            // Queue/CAS truth remains durable; status and a later activation expose retry.
-        }).finally(() => {
-            activePublicationWorkers.delete(path);
-            try {
-                lease.release();
-                if (!publicationStopped && loadPublicationQueue(path)?.status === "pending")
-                    launchPublicationWorker();
-            }
-            catch {
-                // Failed lease cleanup or malformed persistence stays inert until retry or repair.
-            }
-        });
-        activePublicationWorkers.set(path, { controller, done });
+        if (target)
+            publicationWorker.enqueue(target);
     }
     function shutdownPublicationWorkers(ctx) {
-        publicationStopped = true;
-        return publicationShutdown ??= (async () => {
-            const workers = [...activePublicationWorkers.values()];
-            for (const { controller } of workers)
-                controller.abort();
-            if (workers.length === 0)
-                return;
-            let timeout;
-            try {
-                const completed = await Promise.race([
-                    Promise.all(workers.map(({ done }) => done)).then(() => true),
-                    new Promise((resolve) => { timeout = setTimeout(() => resolve(false), PUBLICATION_SHUTDOWN_WAIT_MS); }),
-                ]);
-                if (!completed)
-                    ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
-            }
-            finally {
-                clearTimeout(timeout);
-            }
-        })();
+        return publicationShutdown ??= publicationWorker.shutdown(PUBLICATION_SHUTDOWN_WAIT_MS).then((completed) => {
+            if (!completed)
+                ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
+        });
     }
     function retryPendingPush(ctx) {
         if (pendingPublication === undefined || !runtime?.view)
@@ -438,8 +266,8 @@ export default function stateFlowExtension(pi, options = {}) {
             if (mode === "turn-end") {
                 turnPublicationTarget = target;
                 try {
-                    enqueueTurnPublication(ctx);
-                    launchPublicationWorker();
+                    enqueueTurnPublication();
+                    publicationWorker.launch();
                 }
                 catch (error) {
                     ctx.ui.notify(`State Flow retained local state; asynchronous publication recovery is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -646,7 +474,7 @@ export default function stateFlowExtension(pi, options = {}) {
             ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
         }
         if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
-            const boundary = passiveStopBoundary(ctx);
+            const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
             if (boundary !== undefined) {
                 const continuation = createPassiveContinuation(projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), boundary.at, boundary.from);
                 if (!snapshot.config.enabled)
@@ -655,40 +483,22 @@ 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();
         updateUi(ctx);
     }
     function recordDiagnostic(error, category, ctx, extras = {}) {
-        if (!config.logging)
-            return;
-        try {
-            const path = stateFlowLogPath(agentDir);
-            const fromRepository = relative(repositoryRoot, path);
-            if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
-                throw new Error("diagnostic path overlaps the State Flow repository");
-            }
-            appendStateFlowDiagnostic(path, {
-                at: new Date().toISOString(),
-                sessionId: sessionAddress(ctx).id,
-                cwd: resolve(ctx.cwd),
-                category,
-                error,
-                ...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
-                ...(extras.input === undefined ? {} : { input: extras.input }),
-                ...(extras.tool === undefined ? {} : { tool: extras.tool }),
-                ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
-                ...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
-                ...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
-            });
-        }
-        catch (failure) {
-            if (loggingWarningReported)
-                return;
-            loggingWarningReported = true;
-            ctx.ui.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`, "warning");
-        }
+        diagnosticWriter.record(sessionAddress(ctx).id, ctx.cwd, error, category, extras);
     }
     function continueFallbackResolution(lastWarning) {
         resolutionPending = true;
@@ -762,37 +572,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 +644,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 +675,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 +857,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 +892,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 +924,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 }));
@@ -1117,7 +963,7 @@ export default function stateFlowExtension(pi, options = {}) {
     pi.on("tool_call", (event, ctx) => {
         if (!snapshot.config.enabled)
             return;
-        const batch = assistantToolBatch(ctx, event.toolCallId);
+        const batch = findAssistantToolBatch(ctx.sessionManager, event.toolCallId);
         const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
         if (patchCalls > 0) {
             if (patchCalls !== 1) {
@@ -1182,19 +1028,23 @@ 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;
             rehydrationPhase = "step";
-            enqueueTurnPublication(ctx);
+            enqueueTurnPublication();
             if (snapshot.meta.remotePublication?.mode === "turn-end")
-                launchPublicationWorker();
+                publicationWorker.launch();
             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)}`
@@ -1221,7 +1071,7 @@ export default function stateFlowExtension(pi, options = {}) {
             startStateFlow(ctx);
         }
         if (snapshot.meta.remotePublication?.mode === "turn-end")
-            launchPublicationWorker();
+            publicationWorker.launch();
         if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
             || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
             || !shouldRequestStateFlowCompaction(ctx.getContextUsage()))
@@ -1246,7 +1096,7 @@ export default function stateFlowExtension(pi, options = {}) {
         restoreActiveBranch(ctx, event.reason);
         retryPendingPush(ctx);
         if (snapshot.meta.remotePublication?.mode === "turn-end")
-            launchPublicationWorker();
+            publicationWorker.launch();
         updateUi(ctx);
         void telegram.ensure();
     });