@llblab/pi-kit 0.18.2 → 0.19.0

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

@@ -1,39 +1,36 @@
-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, formatPatchStateArguments, normalizePatchStateArguments, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
-import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation } from "./context.js";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { ArtifactReadTracker } from "./acquisition.js";
+import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, ORDINARY_ARTIFACT_COMPILER, sameArtifactSourceFingerprint, } from "./artifact.js";
+import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult } from "./compaction.js";
 import { loadStateFlowConfig } from "./config.js";
-import { createStateFlowTelegramAdapter } from "./telegram.js";
-import { isAbsolute, resolve } from "node:path";
-import { SkillReadTracker } from "./skills.js";
-import { emptySnapshot, migrationFailure, persistableSnapshot, RevisionUnavailableError } from "./snapshot.js";
+import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, projectSystemProtocol, runtimeContextMessage, syntheticUser } from "./context.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, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.js";
-import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
-import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
-import { recoverSnapshot } from "./recovery.js";
-import { loadPublicationQueue, publicationQueuePath, PublicationWorkerController, resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.js";
-import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.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 { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
+import { backupCurrentStateFlowFiles } from "./git.js";
+import { projectRecentTransitionsWithLimit } from "./history.js";
+import { isObject, presentationJson, sameJson } from "./json.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 };
+import { assistantToolCallCount, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
+import { readProjectedState, readStatePath } from "./query.js";
+import { recoverSnapshot } from "./recovery.js";
+import { SharedScopeRemovalConflictError, TemporalRuntime } from "./runtime.js";
+import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.js";
+import { SkillReadTracker } from "./skills.js";
+import { emptySnapshot, migrationFailure } from "./snapshot.js";
+import { emptyState, overlayStates, projectStateForModel } from "./state.js";
+import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
+import { createStateFlowTelegramAdapter } from "./telegram.js";
+import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition } from "./transition.js";
+export { formatPatchStateArguments };
 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;
 export default function stateFlowExtension(pi, options = {}) {
     const agentDir = options.agentDir ?? getAgentDir();
     const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
@@ -47,12 +44,9 @@ export default function stateFlowExtension(pi, options = {}) {
     let branchHasSnapshot = false;
     let branchStartsWithoutRuntime = false;
     let forkInitialization = false;
-    let terminalEligible = false;
-    let resolutionPending = false;
-    let fallbackAttempts = 0;
-    let fallbackFailureReported = false;
     let responseAwaitingReconciliation = false;
     let completedRunAccepted = false;
+    let turnAcceptedForBackup = false;
     let compactionPlan;
     let compactionInFlight = false;
     let compactionStopped = false;
@@ -63,69 +57,62 @@ export default function stateFlowExtension(pi, options = {}) {
     let runAnchorTimestamp;
     let runtime;
     let activeContext;
-    let pendingPublication;
     let rehydrationPhase;
-    let turnPublicationTarget;
-    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),
-    });
+    let backupPending = false;
     const skillReads = new SkillReadTracker();
     const artifactReads = new ArtifactReadTracker();
-    const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
     let artifactInvalidations = [];
+    let artifactHints = {};
+    const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
     let telegramStartPending = false;
     function sessionAddress(ctx) {
         return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
     }
     function createRuntime(ctx) {
-        return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot);
+        return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
+    }
+    function projectModelState(state) {
+        return projectStateForModel(state, artifactHints);
+    }
+    function assertSelectedBranchAvailable() {
+        if (snapshot.meta.validation?.attempt === 0) {
+            throw new Error(`State Flow selected branch is unavailable: ${snapshot.meta.validation.error}. Restore its canonical files and retry /state-flow-start, or select a retained boundary.`);
+        }
     }
     options.onRuntime?.({ read: (offset, scope) => {
+            if (scope === "session")
+                assertSelectedBranchAvailable();
             if (!runtime)
                 throw new Error("State Flow temporal runtime is unavailable");
-            return projectStateForModel(runtime.read(offset, scope));
+            return projectModelState(runtime.read(offset, scope));
         } });
     function persist() {
-        const mode = snapshot.meta.remotePublication?.mode ?? "transition";
-        const publication = runtime?.view ? runtime.publish(snapshot, false, undefined, { pushRemote: mode === "transition" }) : undefined;
-        if (publication?.commit && mode === "turn-end")
-            turnPublicationTarget = publication.commit;
+        assertSelectedBranchAvailable();
+        const previousView = runtime?.view;
+        const publication = !branchStartsWithoutRuntime && runtime?.view ? runtime.publish(snapshot, false, undefined) : undefined;
+        if (runtime?.view !== previousView)
+            installScopeStates();
         if (publication && activeContext)
             recordPublication(publication, activeContext);
-        const checkpoint = persistableSnapshot(snapshot);
+        const checkpoint = branchStartsWithoutRuntime ? { disabled: true } : runtime?.retainedCheckpoint(snapshot) ?? { disabled: true };
         if ("disabled" in checkpoint && !branchStartsWithoutRuntime) {
             throw new Error("State Flow cannot checkpoint an unproven branch as ordinary disabled; restore a valid checkpoint first");
         }
         pi.appendEntry(SNAPSHOT_ENTRY_TYPE, checkpoint);
-        if ("revision" in checkpoint)
+        if ("boundary" in checkpoint)
             branchStartsWithoutRuntime = false;
     }
     function updateUi(ctx) {
         ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
     }
-    function setPendingPublication(value) {
-        pendingPublication = value === undefined ? undefined : structuredClone(value);
-        if (value === undefined)
-            delete snapshot.meta.pendingPublication;
-        else
-            snapshot.meta.pendingPublication = structuredClone(value);
-    }
     function clearRunTransient() {
-        terminalEligible = false;
-        resolutionPending = false;
-        fallbackAttempts = 0;
-        fallbackFailureReported = false;
         responseAwaitingReconciliation = false;
         completedRunAccepted = false;
+        turnAcceptedForBackup = false;
         compactionPlan = undefined;
         compactionInFlight = false;
-        runAnchorTimestamp = undefined;
         skillReads.clear();
         artifactReads.clear();
     }
@@ -134,29 +121,64 @@ export default function stateFlowExtension(pi, options = {}) {
         artifactReads.setCandidates([]);
         artifactRefreshPending = true;
     }
-    function refreshArtifactInvalidations(ctx) {
-        artifactRefreshPending = false;
-        if (!snapshot.config.enabled) {
+    function refreshArtifactHints() {
+        if (!runtime?.view) {
+            artifactHints = {};
             artifactInvalidations = [];
             artifactReads.setCandidates([]);
             return;
         }
-        try {
-            const discovery = globalMarkdown.refresh(Object.keys(scopeStates.global.artifacts));
-            const plan = planArtifactInvalidation(discovery.sources, scopeStates.global.artifacts, ORDINARY_ARTIFACT_COMPILER, { removed: discovery.removed }, runtime?.artifactProvenance("global") ?? {});
-            artifactInvalidations = structuredClone(plan.requiresCompilation);
-            if (plan.removed.length > 0) {
-                const removals = Object.fromEntries(plan.removed.map((path) => [path, null]));
-                const stage = stageAtomicScopePatches(scopeStates, { global: { artifacts: removals } }, [], runtime.causalBasis());
-                commitStage(stage, ctx, false);
+        const paths = new Set();
+        for (const scope of ["global", "cwd", "session"])
+            for (const path of Object.keys(scopeStates[scope].artifacts))
+                paths.add(path);
+        const observations = new Map(inspectRegisteredArtifactPaths(paths).map((observation) => [observation.path, observation]));
+        const nextHints = {};
+        const nextInvalidations = new Map();
+        for (const scope of ["global", "cwd", "session"]) {
+            const provenance = runtime.artifactProvenance(scope);
+            for (const [path, metadata] of Object.entries(scopeStates[scope].artifacts)) {
+                delete nextHints[path];
+                nextInvalidations.delete(path);
+                if (metadata.kind === "skill")
+                    continue;
+                const observed = observations.get(path);
+                if (observed?.kind !== "present")
+                    continue;
+                const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, provenance[path]);
+                if (need.kind !== "requires-compilation")
+                    continue;
+                if (need.reason === "source-changed")
+                    nextHints[path] = SOURCE_CHANGED_HINT;
+                nextInvalidations.set(path, { path, scope, reason: need.reason });
             }
-            artifactReads.setCandidates(artifactInvalidations);
         }
-        catch (error) {
-            artifactInvalidations = [];
-            artifactReads.setCandidates([]);
-            ctx.ui.notify(`State Flow could not discover global Markdown sources: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        artifactHints = nextHints;
+        artifactInvalidations = [...nextInvalidations.values()].sort((left, right) => left.path.localeCompare(right.path));
+        artifactReads.setCandidates(artifactInvalidations);
+    }
+    function removeMissingRegisteredArtifacts(ctx) {
+        if (!snapshot.config.enabled || !runtime?.view)
+            return;
+        const owners = new Map();
+        for (const scope of ["global", "cwd", "session"])
+            for (const path of Object.keys(scopeStates[scope].artifacts)) {
+                owners.set(path, [...owners.get(path) ?? [], scope]);
+            }
+        const removals = {};
+        for (const observation of inspectRegisteredArtifactPaths(owners.keys())) {
+            if (observation.kind !== "missing")
+                continue;
+            for (const scope of owners.get(observation.path) ?? []) {
+                const artifacts = (removals[scope]?.artifacts ?? {});
+                removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
+            }
+        }
+        if (Object.keys(removals).length > 0) {
+            const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
+            commitStage(stage, ctx, false);
         }
+        refreshArtifactHints();
     }
     function installScopeStates() {
         scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
@@ -174,38 +196,15 @@ export default function stateFlowExtension(pi, options = {}) {
             ? [...new Set([...active, ...owned])]
             : active.filter((name) => !owned.includes(name)));
     }
-    function recordPublication(publication, ctx) {
-        const revision = publication.revision ?? publication.commit;
-        if (revision !== undefined)
-            snapshot.meta.durableBase = revision;
-        if (publication.push?.status === "pending") {
-            setPendingPublication({
-                commit: publication.push.commit,
-                error: publication.push.error ?? "unknown push failure",
-            });
-            ctx.ui.notify(`State Flow accepted durable commit ${publication.push.commit.slice(0, 12)}, but push is pending: ${publication.push.error}`, "warning");
-        }
-        else if (revision !== undefined) {
-            setPendingPublication(undefined);
-        }
+    function recordPublication(_publication, _ctx) {
+        // A passive view is not runtime authority; only accepted canonical publication establishes it.
+        branchStartsWithoutRuntime = false;
+        backupPending = true;
     }
-    /** Accept an activation or lifecycle commit locally; turn-end policy queues it for the asynchronous worker. */
+    /** Record accepted lifecycle persistence; Git backup is scheduled only after an accepted turn settles. */
     function recordPolicyPublication(publication, ctx) {
-        if (!publication)
-            return;
-        recordPublication(publication, ctx);
-        const mode = snapshot.meta.remotePublication?.mode ?? "transition";
-        const target = publication.commit ?? publication.revision;
-        if (mode !== "turn-end" || target === undefined || !/^[0-9a-f]{40,64}$/.test(target))
-            return;
-        turnPublicationTarget = target;
-        try {
-            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");
-        }
+        if (publication)
+            recordPublication(publication, ctx);
     }
     function commitStage(stage, ctx, finalizeRun) {
         const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
@@ -214,13 +213,9 @@ export default function stateFlowExtension(pi, options = {}) {
             committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
                 if (!runtime?.view)
                     throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
-                const mode = nextSnapshot.meta.remotePublication?.mode ?? "transition";
                 const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, {
-                    pushRemote: mode === "transition",
                     provenance: stage.provenanceUpdates,
                 });
-                if (publication?.commit && mode === "turn-end")
-                    turnPublicationTarget = publication.commit;
                 if (publication)
                     recordPublication(publication, ctx);
             }, runtime.causalBasis(), { finalizeRun });
@@ -233,61 +228,13 @@ export default function stateFlowExtension(pi, options = {}) {
         if (!committed)
             return false;
         installScopeStates();
-        // A preserved primary response commits mid-run; pending acquisition obligations must
-        // still block final eligibility until the fallback turns resolve or expire.
-        if (!(finalizeRun && resolutionPending)) {
-            artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
-            artifactReads.setCandidates(artifactInvalidations);
-            skillReads.clear();
-            artifactReads.clear();
-        }
+        artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
+        artifactReads.setCandidates(artifactInvalidations);
+        skillReads.clear();
+        artifactReads.clear();
         persist();
         return true;
     }
-    function enqueueTurnPublication() {
-        const target = turnPublicationTarget;
-        turnPublicationTarget = undefined;
-        if (target)
-            publicationWorker.enqueue(target);
-    }
-    function shutdownPublicationWorkers(ctx) {
-        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)
-            return;
-        const mode = snapshot.meta.remotePublication?.mode ?? "transition";
-        if (mode !== "transition") {
-            const target = pendingPublication.commit;
-            setPendingPublication(undefined);
-            if (mode === "turn-end") {
-                turnPublicationTarget = target;
-                try {
-                    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");
-                }
-            }
-            return;
-        }
-        const result = pushGitCommit(repositoryRoot, pendingPublication.commit);
-        if (result.status !== "pending") {
-            setPendingPublication(undefined);
-            persist();
-            ctx.ui.notify(result.status === "local"
-                ? `State Flow retained local-only durable commit ${result.commit.slice(0, 12)}; no remote configured.`
-                : `State Flow pushed pending durable commit ${result.commit.slice(0, 12)}.`, "info");
-        }
-        else {
-            setPendingPublication({ commit: result.commit, error: result.error ?? "unknown push failure" });
-            persist();
-        }
-    }
     function currentRehydrationPhase() {
         return rehydrationPhase;
     }
@@ -296,86 +243,36 @@ export default function stateFlowExtension(pi, options = {}) {
         const diagnosticStates = scopeStates;
         const view = runtime?.view;
         const diagnosticRecent = runtime?.recent() ?? [];
-        const durableStateError = view ? undefined
-            : snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error : "no temporal runtime is selected on this branch";
-        let staleArtifacts = [];
-        let artifactFreshnessError;
-        if (durableStateError !== undefined) {
-            artifactFreshnessError = "durable global artifact registry is unavailable";
-        }
-        else {
-            try {
-                const discovery = globalMarkdown.refresh(Object.keys(diagnosticStates.global.artifacts));
-                artifactFreshnessError = discovery.unavailable;
-                const plan = planArtifactInvalidation(discovery.sources, diagnosticStates.global.artifacts, ORDINARY_ARTIFACT_COMPILER, { removed: discovery.removed }, runtime?.artifactProvenance("global") ?? {});
-                staleArtifacts = [
-                    ...plan.requiresCompilation.map(({ path, reason }) => ({ scope: "global", path, reason })),
-                    ...plan.removed.map((path) => ({ scope: "global", path, reason: "source-removed" })),
-                ];
-            }
-            catch (error) {
-                artifactFreshnessError = error instanceof Error ? error.message : String(error);
-            }
-        }
+        const durableStateError = snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error
+            : view ? undefined : "no temporal runtime is selected on this branch";
+        const staleArtifacts = durableStateError === undefined
+            ? artifactInvalidations.map(({ path, scope, reason }) => ({ scope: scope ?? "global", path, reason }))
+            : [];
         const session = sessionAddress(ctx);
-        let publicationQueue;
-        let publicationQueueError;
-        try {
-            const destination = resolveGitPushDestination(repositoryRoot);
-            publicationQueue = destination ? loadPublicationQueue(publicationQueuePath(destination)) : undefined;
-        }
-        catch (error) {
-            publicationQueue = undefined;
-            publicationQueueError = error instanceof Error ? error.message : String(error);
-        }
         return {
             repositoryRoot,
             cwdScopeKey: cwdScopeKey(cwd),
             sessionScopeKey: sessionScopeKey(session.key),
             scopeStates: diagnosticStates,
             recent: diagnosticRecent,
+            historyLimit: config.historyLimit,
             ...(view === undefined ? {} : { temporal: {
                     head: structuredClone(view.lineage.at(-1)),
                     historyDepth: view.lineage.length - 1,
                     tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
                 } }),
             staleArtifacts,
-            ...(artifactFreshnessError === undefined ? {} : { artifactFreshnessError }),
             ...(durableStateError === undefined ? {} : { durableStateError }),
-            ...(pendingPublication === undefined ? {} : { pendingPublication }),
-            ...(publicationQueue === undefined ? {} : { publicationQueue }),
-            ...(publicationQueueError === undefined ? {} : { publicationQueueError }),
         };
     }
-    function prepareBranchRestore(ctx, revision, legacy) {
-        if (!forkInitialization) {
-            try {
-                return runtime.prepareRestore(revision, legacy);
-            }
-            catch (error) {
-                if (error instanceof MissingSessionRuntimeError && typeof ctx.sessionManager.getHeader()?.parentSession === "string") {
-                    throw new RevisionUnavailableError("State Flow checkpoint has no child-owned runtime; select a child checkpoint or resume the parent");
-                }
-                throw error;
-            }
-        }
+    function forkSource(ctx) {
         const file = ctx.sessionManager.getHeader()?.parentSession;
         if (typeof file !== "string" || !isAbsolute(file))
             throw new Error("State Flow fork requires a persisted native parent session");
         const parent = readNativeSessionHeader(file);
         if (parent.cwd !== resolve(ctx.cwd))
             throw new Error("State Flow fork parent CWD identity mismatch");
-        const source = resolveSessionAddress(parent.file, parent.id, parent.timestamp);
-        const prepared = runtime.prepareFork(source, revision);
-        return { snapshot: prepared.snapshot, restore: () => {
-                const accepted = prepared.fork();
-                snapshot = accepted.snapshot;
-                recordPolicyPublication(accepted.publication, ctx);
-                // Copied Stop markers belong to the parent, including after a child reload/resume.
-                pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner: ctx.sessionManager.getSessionId() });
-                forkInitialization = false;
-                return snapshot;
-            } };
+        return resolveSessionAddress(parent.file, parent.id, parent.timestamp);
     }
     function restoreActiveBranch(ctx, sessionStartReason) {
         clearRunTransient();
@@ -387,9 +284,8 @@ export default function stateFlowExtension(pi, options = {}) {
         telegramStartPending = false;
         activeContext = ctx;
         const session = sessionAddress(ctx);
-        runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot);
+        runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot, undefined, config.historyLimit);
         installScopeStates();
-        pendingPublication = undefined;
         branchHasSnapshot = false;
         branchStartsWithoutRuntime = false;
         forkInitialization = sessionStartReason === "fork";
@@ -397,18 +293,27 @@ export default function stateFlowExtension(pi, options = {}) {
             const branch = ctx.sessionManager.getBranch();
             const discovery = discoverSnapshotData(branch);
             let restoreSelected;
-            const recovery = recoverSnapshot(discovery.candidates, (revision) => {
-                try {
-                    const prepared = prepareBranchRestore(ctx, revision);
-                    restoreSelected = prepared.restore;
+            const recovery = recoverSnapshot(discovery.candidates, (checkpoint) => {
+                if (forkInitialization) {
+                    const prepared = runtime.prepareBoundaryFork(forkSource(ctx), checkpoint);
+                    restoreSelected = () => {
+                        const accepted = prepared.fork();
+                        snapshot = accepted.snapshot;
+                        recordPolicyPublication(accepted.publication, ctx);
+                        pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner: ctx.sessionManager.getSessionId() });
+                        forkInitialization = false;
+                        return snapshot;
+                    };
                     return prepared.snapshot;
                 }
-                catch (error) {
-                    // A failed source proof never licenses an older/empty private copy.
-                    if (forkInitialization)
-                        throw new RevisionUnavailableError(`Cannot copy State Flow fork source: ${error instanceof Error ? error.message : String(error)}`);
-                    throw error;
-                }
+                const prepared = runtime.prepareBoundaryRestore(checkpoint);
+                restoreSelected = () => {
+                    const restored = prepared.restore();
+                    const publication = runtime.acceptRestoredOrigin(restored);
+                    recordPolicyPublication(publication, ctx);
+                    return restored;
+                };
+                return prepared.snapshot;
             });
             branchStartsWithoutRuntime = recovery.disabledMarker === true
                 || (discovery.candidates.length === 0 && discovery.errors.length === 0);
@@ -419,11 +324,9 @@ export default function stateFlowExtension(pi, options = {}) {
             }
             else if (discovery.candidates.length > 0) {
                 snapshot = recovery.snapshot;
-                if (branchHasSnapshot && snapshot.meta.durableBase) {
-                    const selectedRevision = snapshot.meta.durableBase;
-                    snapshot = restoreSelected ? restoreSelected() : prepareBranchRestore(ctx, selectedRevision, snapshot).restore();
-                    if (snapshot.meta.durableBase !== selectedRevision)
-                        persist();
+                if (branchHasSnapshot && restoreSelected) {
+                    snapshot = restoreSelected();
+                    persist();
                 }
                 else if (branchHasSnapshot && snapshot.config.enabled) {
                     const publication = runtime.initialize(snapshot, true);
@@ -433,7 +336,6 @@ export default function stateFlowExtension(pi, options = {}) {
             }
             else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
                 snapshot = startEpisode(hasPriorConversation(branch));
-                snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(resolveRemotePublicationPolicy(config.remotePublication, { legacyRuntime: false }));
                 runtime.prepare();
                 const initialization = runtime.initialize(snapshot, true);
                 recordPolicyPublication(initialization, ctx);
@@ -461,22 +363,16 @@ export default function stateFlowExtension(pi, options = {}) {
                 meta: { ...snapshot.meta, validation: failure.meta.validation },
             };
         }
-        if (branchHasSnapshot && snapshot.meta.remotePublication === undefined) {
-            snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(resolveRemotePublicationPolicy(undefined, { legacyRuntime: true }));
-        }
-        if (snapshot.config.enabled && snapshot.meta.remotePublication === undefined) {
-            snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(resolveRemotePublicationPolicy(undefined, { legacyRuntime: true }));
-        }
-        pendingPublication = snapshot.meta.pendingPublication === undefined
-            ? undefined
-            : structuredClone(snapshot.meta.pendingPublication);
         if (!snapshot.config.enabled && snapshot.meta.validation?.attempt === 0) {
+            // A failed acceptance may have installed a prepared view; only shared passive reads may survive.
+            runtime = createRuntime(ctx);
+            installScopeStates();
             ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
         }
         if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
             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);
+                const continuation = createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), boundary.at, boundary.from);
                 if (!snapshot.config.enabled)
                     passiveContinuation = continuation;
                 else if (snapshot.meta.bootstrap)
@@ -500,75 +396,6 @@ export default function stateFlowExtension(pi, options = {}) {
     function recordDiagnostic(error, category, ctx, extras = {}) {
         diagnosticWriter.record(sessionAddress(ctx).id, ctx.cwd, error, category, extras);
     }
-    function continueFallbackResolution(lastWarning) {
-        resolutionPending = true;
-        pi.sendMessage({
-            customType: VALIDATION_MESSAGE_TYPE,
-            content: lastWarning
-                ? "This is the last State Flow fallback turn. The iteration's answer is preserved and will not change. Apply the final:true patch now: call patch_state with any remaining durable scope changes and final:true, or with {\"final\":true} when nothing remains. Do not restate the answer."
-                : "The iteration's answer is preserved as the final response; later turns cannot replace it. Apply the final:true patch: call patch_state with any durable scope changes from this iteration (including required artifact or Skill compilation) and final:true, or with {\"final\":true} when nothing remains to persist. Do not restate the answer.",
-            display: false,
-        }, { deliverAs: "steer", triggerTurn: true });
-    }
-    /** Preserve the primary answer as this iteration's response and steer bounded fallback turns whose only purpose is the final:true patch. */
-    function beginFallbackResolution(ctx, message, reason) {
-        responseAwaitingReconciliation = true;
-        fallbackAttempts = 0;
-        fallbackFailureReported = false;
-        recordDiagnostic(`Preserved the terminal draft as the iteration response; fallback resolution started: ${reason}`, "terminal-pending", ctx, {
-            content: message.content,
-            resolutionAttempt: 0,
-            terminalEligible,
-        });
-        continueFallbackResolution(MAX_FALLBACK_ATTEMPTS === 1);
-    }
-    /** Fallback turns never become the response; they exist only to supply the final:true patch. */
-    function resolveFallbackTurn(ctx, message) {
-        let resolved = terminalEligible;
-        if (resolved) {
-            try {
-                validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
-            }
-            catch (error) {
-                resolved = false;
-                recordDiagnostic(error instanceof Error ? error.message : String(error), "terminal-pending", ctx, {
-                    content: message.content,
-                    resolutionAttempt: fallbackAttempts,
-                    terminalEligible,
-                });
-            }
-        }
-        if (resolved) {
-            resolutionPending = false;
-            recordDiagnostic(`Fallback resolution obtained final:true after ${fallbackAttempts} fallback turn${fallbackAttempts === 1 ? "" : "s"}; the preserved answer stands`, "finalization", ctx, {
-                content: message.content,
-                resolutionAttempt: fallbackAttempts,
-                terminalEligible,
-            });
-            return { message: { ...message, role: "assistant", content: [] } };
-        }
-        fallbackAttempts = Math.min(MAX_FALLBACK_ATTEMPTS, fallbackAttempts + 1);
-        if (fallbackAttempts < MAX_FALLBACK_ATTEMPTS) {
-            recordDiagnostic(`Fallback turn ended without final:true (${fallbackAttempts}/${MAX_FALLBACK_ATTEMPTS})`, "terminal-pending", ctx, {
-                content: message.content,
-                resolutionAttempt: fallbackAttempts,
-                terminalEligible,
-            });
-            continueFallbackResolution(fallbackAttempts + 1 >= MAX_FALLBACK_ATTEMPTS);
-            return { message: { ...message, role: "assistant", content: [] } };
-        }
-        resolutionPending = false;
-        recordDiagnostic(`Fallback resolution exhausted without final:true (${fallbackAttempts}/${MAX_FALLBACK_ATTEMPTS}); the preserved response and current state remain`, "finalization", ctx, {
-            content: message.content,
-            resolutionAttempt: fallbackAttempts,
-            terminalEligible,
-        });
-        if (!fallbackFailureReported) {
-            fallbackFailureReported = true;
-            ctx.ui.notify(`State Flow kept the preserved answer; no final:true patch arrived after ${MAX_FALLBACK_ATTEMPTS} fallback turns, so the iteration closed with its current state.`, "warning");
-        }
-        return { message: { ...message, role: "assistant", content: [] } };
-    }
     pi.registerTool({
         name: READ_STATE_TOOL_NAME,
         label: "Read State",
@@ -593,10 +420,12 @@ export default function stateFlowExtension(pi, options = {}) {
                     throw new Error("read_state accepts path or paths, not both");
                 {
                     const paths = params.paths ?? [params.path];
+                    if (paths.some((path) => /^session(?:\.|\[|$)/.test(path)))
+                        assertSelectedBranchAvailable();
                     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]);
+                        const result = readStatePath(runtime.view, paths[0], config.historyLimit);
                         if (!("patch" in result))
                             throw new Error("Expected a scope patch path");
                         return {
@@ -604,7 +433,7 @@ export default function stateFlowExtension(pi, options = {}) {
                             details: { path: paths[0], transitionId: result.boundary.id },
                         };
                     }
-                    const result = readProjectedState(runtime.view, paths, params.projection);
+                    const result = readProjectedState(runtime.view, paths, params.projection, config.historyLimit);
                     return {
                         content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
                         details: { ...(params.path === undefined ? { paths } : { path: params.path }), projection: params.projection ?? "value" },
@@ -619,10 +448,10 @@ export default function stateFlowExtension(pi, options = {}) {
     pi.registerTool({
         name: PATCH_STATE_TOOL_NAME,
         label: "Patch State",
-        description: "The sole State Flow semantic mutation protocol. Supply any combination of global, cwd, and session patches; all supplied scopes commit atomically. In an active State Flow episode, set final:true when the current iteration may finish at a later turn_end; use {final:true} when no semantic update is needed. Passive turns have no terminal barrier: never call patch_state only to set final:true. This call must be the only State Flow barrier in its assistant response.",
-        promptSnippet: "Atomically patch global/cwd/session; active episodes use final:true before turn_end",
+        description: "The sole State Flow semantic mutation protocol. Supply one or more global, cwd, or session patches; all supplied scopes commit atomically. This call must be the only State Flow barrier in its assistant response.",
+        promptSnippet: "Atomically patch one or more global/cwd/session scopes",
         promptGuidelines: [
-            "Use patch_state for durable semantic changes. Only in an active State Flow episode, make the iteration terminal-eligible before a final answer with final:true, optionally alongside atomic global/cwd/session patches. In passive mode, never call patch_state only to set final:true.",
+            "Use patch_state only for material durable semantic changes; ordinary answers need no finalization call.",
             "Use patch_state as reconciliation, not append-only notes: place new knowledge at the narrowest valid scope and remove superseded or completed state from touched branches.",
             "Call patch_state alone in an assistant response; after its acknowledgement, further reasoning, tools, and later patch_state calls remain allowed.",
         ],
@@ -631,9 +460,7 @@ export default function stateFlowExtension(pi, options = {}) {
             global: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional global semantic patch" })),
             cwd: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional project semantic patch" })),
             session: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional session semantic patch" })),
-            final: Type.Optional(Type.Boolean({ description: "Set exactly true to permit this iteration to finish at a later turn_end" })),
         }, { additionalProperties: false }),
-        prepareArguments: normalizePatchStateArguments,
         renderResult(result, { isPartial }, theme, context) {
             const text = result.content.find((block) => block.type === "text")?.text ?? "";
             if (context.isError)
@@ -646,17 +473,16 @@ export default function stateFlowExtension(pi, options = {}) {
             try {
                 if (!passiveToolsAvailable())
                     throw new Error("State Flow tools are disabled by configuration");
+                assertSelectedBranchAvailable();
                 if (signal?.aborted)
                     throw new Error("State Flow patch was aborted before materialization");
                 if (!isObject(params))
                     throw new Error("patch_state requires an object");
-                const allowed = new Set(["global", "cwd", "session", "final"]);
+                const allowed = new Set(["global", "cwd", "session"]);
                 for (const key of Object.keys(params)) {
                     if (!allowed.has(key))
                         throw new Error(`patch_state does not accept field ${key}`);
                 }
-                if (Object.hasOwn(params, "final") && typeof params.final !== "boolean")
-                    throw new Error("patch_state final must be a Boolean when supplied");
                 const patches = {};
                 for (const scope of ["global", "cwd", "session"]) {
                     if (!Object.hasOwn(params, scope))
@@ -669,18 +495,8 @@ export default function stateFlowExtension(pi, options = {}) {
                     patches[scope] = patch;
                 }
                 const scopes = Object.keys(patches);
-                if (scopes.length === 0) {
-                    if (params.final === false) {
-                        return { content: [{ type: "text", text: "\nState unchanged; iteration remains non-terminal." }], details: { final: false } };
-                    }
-                    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 (scopes.length === 0)
+                    throw new Error("patch_state requires at least one materially changed scope patch");
                 if (!runtime?.view) {
                     runtime ??= createRuntime(ctx);
                     runtime.prepare();
@@ -689,20 +505,22 @@ export default function stateFlowExtension(pi, options = {}) {
                     installScopeStates();
                     branchHasSnapshot = true;
                 }
-                runtime.migrateLegacyStorage();
                 installScopeStates();
+                for (const acquired of artifactReads.successful.values()) {
+                    const observation = inspectRegisteredArtifactPaths([acquired.path])[0];
+                    if (acquired.sourceFingerprint === undefined || observation?.kind !== "present"
+                        || !sameArtifactSourceFingerprint(acquired.sourceFingerprint, observation.fingerprint)) {
+                        throw new Error(`Artifact source changed after acquisition: ${acquired.path}`);
+                    }
+                }
                 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');
+                    throw new Error("patch_state scope patches must materially update state or required provenance");
                 commitStage(stage, ctx, false);
-                if (params.final === true && snapshot.config.enabled) {
-                    terminalEligible = true;
-                }
                 updateUi(ctx);
-                const publication = pendingPublication === undefined ? "" : "; durable publication pending";
-                return { content: [{ type: "text", text: `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}${publication}.` }], details: { scopes, final: params.final === true, step: snapshot.meta.step } };
+                return { content: [{ type: "text", text: `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.` }], details: { scopes, step: snapshot.meta.step } };
             }
             catch (error) {
                 let attempted;
@@ -716,8 +534,6 @@ export default function stateFlowExtension(pi, options = {}) {
                     input: attempted,
                     tool: PATCH_STATE_TOOL_NAME,
                     toolCallId,
-                    resolutionAttempt: fallbackAttempts,
-                    terminalEligible,
                 });
                 throw separatedFailure(error);
             }
@@ -733,35 +549,30 @@ export default function stateFlowExtension(pi, options = {}) {
         const previousArtifactRefreshPending = artifactRefreshPending;
         const previousArtifactInvalidations = structuredClone(artifactInvalidations);
         try {
-            if (!runtime?.view && !snapshot.meta.durableBase && !branchStartsWithoutRuntime) {
-                throw new Error("Selected branch revision is unavailable; restore its original Git history before starting State Flow");
+            if (!branchStartsWithoutRuntime && (!runtime?.view || snapshot.meta.validation?.attempt === 0)) {
+                const retryFork = forkInitialization;
+                restoreActiveBranch(ctx, retryFork ? "fork" : undefined);
             }
+            assertSelectedBranchAvailable();
+            if (!runtime?.view && !branchStartsWithoutRuntime)
+                throw new Error("Selected State Flow boundary is unavailable; restore its canonical files before starting State Flow");
             const branch = ctx.sessionManager.getBranch();
             activeContext = ctx;
             runtime ??= createRuntime(ctx);
             if (branchStartsWithoutRuntime)
                 runtime.prepare();
-            runtime.migrateLegacyStorage();
             const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
                 && (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
-            if (!runtime.view && snapshot.meta.durableBase) {
-                snapshot = prepareBranchRestore(ctx, snapshot.meta.durableBase, snapshot).restore();
-                setPendingPublication(snapshot.meta.pendingPublication);
-                branchHasSnapshot = true;
-            }
             const existingBranch = branchHasSnapshot;
             snapshot = existingBranch
                 ? resumeEpisode(snapshot, bootstrap)
                 : startEpisode(bootstrap);
-            if (snapshot.meta.remotePublication === undefined) {
-                snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(resolveRemotePublicationPolicy(existingBranch ? undefined : config.remotePublication, { legacyRuntime: existingBranch }));
-            }
             branchHasSnapshot = true;
             // Activation reasserts the selected session stream as a complete cohort. A resumed
             // branch may have no reusable temporal revision after an extension upgrade; a
             // runtime-only write would then reject its selected session as an omitted change.
             const publication = runtime.view
-                ? runtime.promote(snapshot) ?? runtime.publish(snapshot, true)
+                ? runtime.publish(snapshot, true)
                 : runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
             recordPolicyPublication(publication, ctx);
             installScopeStates();
@@ -807,25 +618,18 @@ export default function stateFlowExtension(pi, options = {}) {
     function stopStateFlow(ctx) {
         if (!activeContext)
             restoreActiveBranch(ctx);
+        assertSelectedBranchAvailable();
         telegramStartPending = false;
-        let selected = runtime;
-        let current = snapshot;
-        if (!selected?.view && snapshot.meta.durableBase) {
-            selected = createRuntime(ctx);
-            current = selected.restore(snapshot.meta.durableBase, snapshot);
-        }
+        const current = snapshot;
         const stoppedAt = Date.now();
-        const exitStates = selected?.view ? selected.states() : undefined;
-        const exitHandoff = current.config.enabled && exitStates
-            ? createPassiveContinuation(projectStateForModel(overlayStates(exitStates.global, exitStates.cwd, exitStates.session)), stoppedAt, ctx.isIdle() ? undefined : runAnchorTimestamp)
+        const stopped = stopEpisode(current);
+        const publication = !branchStartsWithoutRuntime && runtime?.view ? runtime.publish(stopped) : undefined;
+        installScopeStates();
+        // Freeze the accepted shared adoption, not the pre-publication cache.
+        const exitHandoff = current.config.enabled && runtime?.view
+            ? createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), stoppedAt, ctx.isIdle() ? undefined : runAnchorTimestamp)
             : undefined;
         const retainedHandoff = exitHandoff ?? (!current.config.enabled ? passiveContinuation : undefined);
-        const stopped = stopEpisode(current);
-        const publication = selected?.view ? selected.publish(stopped) : undefined;
-        if (selected !== runtime) {
-            runtime = selected;
-            installScopeStates();
-        }
         snapshot = stopped;
         recordPolicyPublication(publication, ctx);
         branchHasSnapshot = true;
@@ -861,13 +665,12 @@ export default function stateFlowExtension(pi, options = {}) {
                 startPending: telegramStartPending,
             }),
             state: (scope) => {
+                if (scope === "session")
+                    assertSelectedBranchAvailable();
                 const selected = scope === "effective"
                     ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
                     : scopeStates[scope];
-                return {
-                    ...projectStateForModel(selected),
-                    ...(Object.hasOwn(selected, "lazy") ? { lazy: structuredClone(selected.lazy) } : {}),
-                };
+                return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
             },
             canStartNow: () => activeContext === undefined || activeContext.isIdle(),
             start: () => {
@@ -895,62 +698,65 @@ export default function stateFlowExtension(pi, options = {}) {
     });
     void telegram.ensure();
     pi.on("before_agent_start", (event, ctx) => {
+        // Native run identity is independent of semantic enablement and survives mode toggles.
+        runAnchorTimestamp = undefined;
         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.`,
-            };
+            (event.systemPromptOptions.sections ??= {}).state_flow = PASSIVE_MEMORY_PROTOCOL;
+            return;
         }
         skillReads.clear();
         artifactReads.clear();
-        if (artifactRefreshPending)
-            refreshArtifactInvalidations(ctx);
-        terminalEligible = false;
-        resolutionPending = false;
-        fallbackAttempts = 0;
-        fallbackFailureReported = false;
         responseAwaitingReconciliation = false;
         completedRunAccepted = false;
         const rotatesRun = snapshot.meta.specification !== undefined;
         if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap")
             rehydrationPhase = "step";
-        if (prepareRun(snapshot, event.prompt)) {
-            runAnchorTimestamp = undefined;
+        if (prepareRun(snapshot, event.prompt))
             persist();
+        try {
+            removeMissingRegisteredArtifacts(ctx);
         }
-        return {
-            systemPrompt: `${event.systemPrompt}\n\n${stateFlowProtocol(snapshot.meta.bootstrap === true)}`,
-        };
+        catch (error) {
+            ctx.ui.notify(`State Flow could not reconcile missing artifact sources: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        }
+        artifactRefreshPending = false;
+        (event.systemPromptOptions.sections ??= {}).state_flow = stateFlowProtocol(snapshot.meta.bootstrap === true);
+    });
+    pi.on("context_with_system", (event) => {
+        const protocol = snapshot.config.enabled ? stateFlowProtocol(snapshot.meta.bootstrap === true)
+            : config.passiveBootstrap && runtime?.view ? PASSIVE_MEMORY_PROTOCOL : undefined;
+        return { messages: projectSystemProtocol(event.messages, protocol) };
     });
     pi.on("context", (event) => {
+        if (runtime?.view)
+            refreshArtifactHints();
         if (passiveContinuation) {
             return { messages: passiveContinuationMessages(event.messages, passiveContinuation) };
         }
         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] };
+            const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
+            const state = projectModelState(effective);
+            return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...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 }));
-        const recentTransitions = projectRecentTransitionsWithLimit(RECENT_TRANSITION_LIMIT, runtime?.recent() ?? []);
+        const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
+        const recentTransitions = projectRecentTransitionsWithLimit(config.historyLimit, runtime?.recent() ?? []);
         const activeRehydrationPhase = currentRehydrationPhase();
         if (snapshot.meta.bootstrap) {
             const sourceMessages = bootstrapContinuation
                 ? passiveContinuationMessages(event.messages, bootstrapContinuation)
                 : event.messages;
-            const messages = withoutPrivateValidation(sourceMessages);
-            return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, resolutionPending), ...messages] };
+            return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints), ...sourceMessages] };
         }
+        // Native user events own the run anchor; projection must never rebase it.
         const trajectory = currentRunTrajectory(event.messages, snapshot.meta.specification, runAnchorTimestamp);
-        runAnchorTimestamp = trajectory.anchorTimestamp;
         return {
             messages: [
-                runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, resolutionPending),
+                runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints),
                 ...trajectory.messages,
             ],
         };
@@ -992,11 +798,11 @@ export default function stateFlowExtension(pi, options = {}) {
         artifactReads.recordEnd(event.toolCallId, event.toolName, event.isError);
     });
     pi.on("message_end", (event, ctx) => {
-        if (!snapshot.config.enabled)
-            return;
-        // Capture the first native user boundary even during bootstrap; steering keeps that anchor.
+        // Observe actual user events even while disabled; Start/Stop cannot invent or erase them.
         if (event.message.role === "user" && runAnchorTimestamp === undefined)
             runAnchorTimestamp = event.message.timestamp;
+        if (!snapshot.config.enabled)
+            return;
         if (event.message.role !== "assistant")
             return;
         const message = event.message;
@@ -1006,20 +812,7 @@ export default function stateFlowExtension(pi, options = {}) {
         }
         if (message.stopReason === "length" || message.stopReason === "error") {
             responseAwaitingReconciliation = false;
-            recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content, terminalEligible });
-            return;
-        }
-        if (resolutionPending)
-            return resolveFallbackTurn(ctx, message);
-        if (!terminalEligible) {
-            beginFallbackResolution(ctx, message, "the terminal draft ended without State Flow eligibility");
-            return;
-        }
-        try {
-            validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
-        }
-        catch (error) {
-            beginFallbackResolution(ctx, message, error instanceof Error ? error.message : String(error));
+            recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content });
             return;
         }
         responseAwaitingReconciliation = true;
@@ -1040,17 +833,15 @@ export default function stateFlowExtension(pi, options = {}) {
             responseCommitted = true;
             bootstrapContinuation = undefined;
             rehydrationPhase = "step";
-            enqueueTurnPublication();
-            if (snapshot.meta.remotePublication?.mode === "turn-end")
-                publicationWorker.launch();
             completedRunAccepted = !wasBootstrap;
+            turnAcceptedForBackup = true;
         }
         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)}`
+                ? `State Flow accepted the final response; a post-acceptance lifecycle update failed: ${error instanceof Error ? error.message : String(error)}`
                 : `State Flow could not reconcile the final response: ${error instanceof Error ? error.message : String(error)}`, "error");
         }
         finally {
@@ -1068,42 +859,56 @@ export default function stateFlowExtension(pi, options = {}) {
             return result;
         return { compaction: result };
     });
-    pi.on("agent_settled", (_event, ctx) => {
+    pi.on("agent_before_settle", (_event, ctx) => {
+        if (!turnAcceptedForBackup)
+            return;
+        turnAcceptedForBackup = false;
+        if (!backupPending)
+            return;
+        backupPending = false;
+        try {
+            if (existsSync(join(repositoryRoot, ".git")))
+                backupCurrentStateFlowFiles(repositoryRoot);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            recordDiagnostic(message, "publication-conflict", ctx);
+            ctx.ui.notify(`State Flow accepted canonical state; Git backup failed: ${message}`, "warning");
+        }
+    });
+    pi.on("agent_settled", async (_event, ctx) => {
         if (telegramStartPending && !snapshot.config.enabled) {
             telegramStartPending = false;
             startStateFlow(ctx);
         }
-        if (snapshot.meta.remotePublication?.mode === "turn-end")
-            publicationWorker.launch();
-        if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
-            || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
+        if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap
+            || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !runtime?.view
             || !shouldRequestStateFlowCompaction(ctx.getContextUsage()))
             return;
         completedRunAccepted = false;
         const entries = ctx.sessionManager.buildContextEntries();
         if (!hasCompactionSizedTranscript(entries))
             return;
-        const plan = planStateFlowCompaction(entries, snapshot.meta.durableBase, snapshot.meta.step);
+        const plan = planStateFlowCompaction(entries, runtime.causalBasis(), snapshot.meta.step, runAnchorTimestamp);
         if (!plan)
             return;
         compactionPlan = plan;
         compactionInFlight = true;
-        ctx.compact({
-            customInstructions: compactionMarker,
-            onComplete: () => { compactionPlan = undefined; compactionInFlight = false; },
-            onError: () => { compactionPlan = undefined; compactionInFlight = false; },
+        // Pi dispatches deferred companion prompts after all settled handlers return.
+        await new Promise((resolve) => {
+            const finished = () => { compactionPlan = undefined; compactionInFlight = false; resolve(); };
+            ctx.compact({ customInstructions: compactionMarker, onComplete: finished, onError: finished });
         });
     });
     pi.on("session_start", (event, ctx) => {
+        runAnchorTimestamp = undefined;
         rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
         restoreActiveBranch(ctx, event.reason);
-        retryPendingPush(ctx);
-        if (snapshot.meta.remotePublication?.mode === "turn-end")
-            publicationWorker.launch();
         updateUi(ctx);
         void telegram.ensure();
     });
     pi.on("session_tree", (_event, ctx) => {
+        runAnchorTimestamp = undefined;
         restoreActiveBranch(ctx);
     });
     pi.on("session_shutdown", (_event, ctx) => {
@@ -1111,6 +916,5 @@ export default function stateFlowExtension(pi, options = {}) {
         compactionStopped = true;
         completedRunAccepted = false;
         telegram.dispose();
-        return shutdownPublicationWorkers(ctx);
     });
 }