@llblab/pi-kit 0.12.1 → 0.14.0

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

@@ -0,0 +1,1263 @@
+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 { ArtifactReadTracker } from "./acquisition.js";
+import { loadStateFlowConfig } from "./config.js";
+import { createStateFlowTelegramAdapter } from "./telegram.js";
+import { isAbsolute, relative, resolve, sep } 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 { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
+import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
+import { recoverSnapshot } from "./recovery.js";
+import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.js";
+import { coalescePublicationTarget, createPublicationQueue } from "./publication.js";
+import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.js";
+import { runPublicationWorker } from "./publication.js";
+import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.js";
+import { isObject, sameJson } from "./json.js";
+import { readStatePath } from "./query.js";
+import { cwdScopeKey, resolveSessionAddress, sessionScopeKey, } from "./durable.js";
+import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.js";
+import { appendStateFlowDiagnostic, projectDiagnosticContent, 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 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);
+    let snapshot = emptySnapshot();
+    let scopeStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
+    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 compactionPlan;
+    let compactionInFlight = false;
+    let compactionStopped = false;
+    const compactionMarker = `state-flow-boundary:${randomUUID()}`;
+    let passiveContinuation;
+    let bootstrapContinuation;
+    let artifactRefreshPending = false;
+    let runAnchorTimestamp;
+    let runtime;
+    let activeContext;
+    let pendingPublication;
+    let rehydrationPhase;
+    let turnPublicationTarget;
+    const activePublicationWorkers = new Map();
+    let publicationStopped = false;
+    let publicationShutdown;
+    const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
+    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);
+    }
+    function createRuntime(ctx) {
+        return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot);
+    }
+    options.onRuntime?.({ read: (offset, scope) => {
+            if (!runtime)
+                throw new Error("State Flow temporal runtime is unavailable");
+            return projectStateForModel(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;
+        if (publication && activeContext)
+            recordPublication(publication, activeContext);
+        const checkpoint = persistableSnapshot(snapshot);
+        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)
+            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;
+        compactionPlan = undefined;
+        compactionInFlight = false;
+        runAnchorTimestamp = undefined;
+        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([]);
+        artifactRefreshPending = true;
+    }
+    function refreshArtifactInvalidations(ctx) {
+        artifactRefreshPending = false;
+        if (!snapshot.config.enabled) {
+            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);
+            }
+            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");
+        }
+    }
+    function installScopeStates() {
+        scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
+    }
+    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))
+            return;
+        pi.setActiveTools(snapshot.config.enabled
+            ? [...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)
+            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);
+        }
+    }
+    /** Accept an activation or lifecycle commit locally; turn-end policy queues it for the asynchronous worker. */
+    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(ctx);
+            launchPublicationWorker();
+        }
+        catch (error) {
+            ctx.ui.notify(`State Flow accepted the local commit; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        }
+    }
+    function commitStage(stage, ctx, finalizeRun) {
+        const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
+        let committed;
+        try {
+            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 });
+        }
+        catch (error) {
+            if (error instanceof SharedScopeRemovalConflictError)
+                installScopeStates();
+            throw error;
+        }
+        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();
+        }
+        persist();
+        return true;
+    }
+    function enqueueTurnPublication(ctx) {
+        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 });
+    }
+    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);
+            }
+        })();
+    }
+    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(ctx);
+                    launchPublicationWorker();
+                }
+                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;
+    }
+    function statusDiagnostics(ctx) {
+        const cwd = ctx.cwd;
+        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 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,
+            ...(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;
+            }
+        }
+        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;
+            } };
+    }
+    function restoreActiveBranch(ctx, sessionStartReason) {
+        clearRunTransient();
+        passiveContinuation = undefined;
+        bootstrapContinuation = undefined;
+        artifactInvalidations = [];
+        artifactReads.setCandidates([]);
+        artifactRefreshPending = false;
+        telegramStartPending = false;
+        activeContext = ctx;
+        const session = sessionAddress(ctx);
+        runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot);
+        installScopeStates();
+        pendingPublication = undefined;
+        branchHasSnapshot = false;
+        branchStartsWithoutRuntime = false;
+        forkInitialization = sessionStartReason === "fork";
+        try {
+            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;
+                    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;
+                }
+            });
+            branchStartsWithoutRuntime = recovery.disabledMarker === true
+                || (discovery.candidates.length === 0 && discovery.errors.length === 0);
+            const skipped = discovery.errors.length + recovery.skipped.length;
+            branchHasSnapshot = recovery.skipped.length < discovery.candidates.length;
+            if (discovery.candidates.length === 0 && discovery.errors.length > 0) {
+                snapshot = migrationFailure({}, `Snapshot restoration failed: ${discovery.errors[0]}`);
+            }
+            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();
+                }
+                else if (branchHasSnapshot && snapshot.config.enabled) {
+                    const publication = runtime.initialize(snapshot, true);
+                    recordPolicyPublication(publication, ctx);
+                }
+                installScopeStates();
+            }
+            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);
+                if (!runtime.view)
+                    snapshot = emptySnapshot();
+                installScopeStates();
+                if (snapshot.config.enabled) {
+                    branchHasSnapshot = true;
+                    persist();
+                }
+            }
+            else {
+                snapshot = emptySnapshot();
+                installScopeStates();
+            }
+            if (snapshot.config.enabled && skipped > 0) {
+                ctx.ui.notify(`State Flow recovered the previous valid snapshot after skipping ${skipped} malformed newer snapshot(s).`, "warning");
+            }
+        }
+        catch (error) {
+            const failure = migrationFailure({}, `Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`);
+            snapshot = {
+                ...snapshot,
+                config: { ...snapshot.config, enabled: false },
+                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) {
+            ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
+        }
+        if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
+            const boundary = passiveStopBoundary(ctx);
+            if (boundary !== undefined) {
+                const continuation = createPassiveContinuation(projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), boundary.at, boundary.from);
+                if (!snapshot.config.enabled)
+                    passiveContinuation = continuation;
+                else if (snapshot.meta.bootstrap)
+                    bootstrapContinuation = continuation;
+            }
+        }
+        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");
+        }
+    }
+    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",
+        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",
+        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" })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params, signal) {
+            try {
+                if (!snapshot.config.enabled)
+                    throw new Error("State Flow is disabled on this session branch");
+                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);
+                    return {
+                        content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
+                        details: { path: params.path, transitionId: result.boundary.id },
+                    };
+                }
+                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);
+            }
+        },
+    });
+    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. Set final:true when the current iteration may finish at a later turn_end. final:true does not stop reasoning, tools, or later patch_state calls. Use {final:true} when no semantic update is needed. This call must be the only State Flow barrier in its assistant response.",
+        promptSnippet: "Atomically patch global/cwd/session; final:true permits a later turn_end",
+        promptGuidelines: [
+            "Use patch_state for durable semantic changes. Before a final answer, make the iteration terminal-eligible with final:true, optionally alongside atomic global/cwd/session patches.",
+            "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.",
+        ],
+        executionMode: "sequential",
+        parameters: Type.Object({
+            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)
+                return new Text(separatedOutput(text), 0, 0);
+            if (isPartial || !config.showSuccessfulPatches)
+                return new Text(text, 0, 0);
+            return new Text(separatedOutput(theme.fg("dim", formatPatchStateArguments(context.args))), 0, 0);
+        },
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
+            try {
+                if (!snapshot.config.enabled)
+                    throw new Error("State Flow is disabled on this session branch");
+                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"]);
+                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))
+                        continue;
+                    const patch = params[scope];
+                    if (!isObject(patch))
+                        throw new Error(`patch_state ${scope} must be a semantic patch object`);
+                    if (Object.keys(patch).length === 0)
+                        throw new Error(`patch_state ${scope} cannot be empty; omit it when unchanged`);
+                    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}');
+                    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 } };
+                }
+                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) {
+                    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 } };
+            }
+            catch (error) {
+                let attempted;
+                try {
+                    attempted = structuredClone(params);
+                }
+                catch {
+                    attempted = undefined;
+                }
+                recordDiagnostic(error instanceof Error ? error.message : String(error), /concurrently|advanced/.test(String(error)) ? "publication-conflict" : "invalid-patch", ctx, {
+                    input: attempted,
+                    tool: PATCH_STATE_TOOL_NAME,
+                    toolCallId,
+                    resolutionAttempt: fallbackAttempts,
+                    terminalEligible,
+                });
+                throw separatedFailure(error);
+            }
+        },
+    });
+    function startStateFlow(ctx) {
+        if (!activeContext)
+            restoreActiveBranch(ctx);
+        telegramStartPending = false;
+        const previousSnapshot = structuredClone(snapshot);
+        const previousPassiveContinuation = passiveContinuation;
+        const previousBootstrapContinuation = bootstrapContinuation;
+        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");
+            }
+            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;
+            const publication = runtime.view
+                ? runtime.promote(snapshot) ?? runtime.publish(snapshot)
+                : runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
+            recordPolicyPublication(publication, ctx);
+            installScopeStates();
+            clearRunTransient();
+            passiveContinuation = undefined;
+            bootstrapContinuation = snapshot.meta.bootstrap
+                ? previousPassiveContinuation ?? previousBootstrapContinuation
+                : undefined;
+            deferArtifactRefresh();
+            syncStateFlowTools();
+            persist();
+            updateUi(ctx);
+            ctx.ui.notify(snapshot.meta.bootstrap
+                ? "State Flow enabled. The next complete agent run will migrate active context into state."
+                : "State Flow enabled. The next prompt starts a stateful agent run.", "info");
+            return { ok: true, message: "State Flow enabled" };
+        }
+        catch (error) {
+            snapshot = previousSnapshot;
+            passiveContinuation = previousPassiveContinuation;
+            bootstrapContinuation = previousBootstrapContinuation;
+            artifactRefreshPending = previousArtifactRefreshPending;
+            artifactInvalidations = previousArtifactInvalidations;
+            artifactReads.setCandidates(artifactInvalidations);
+            syncStateFlowTools();
+            const message = `State Flow could not initialize CWD state: ${error instanceof Error ? error.message : String(error)}`;
+            ctx.ui.notify(message, "error");
+            return { ok: false, message };
+        }
+    }
+    pi.registerCommand("state-flow-start", {
+        description: "Start State Flow mode",
+        handler: async (_args, ctx) => {
+            startStateFlow(ctx);
+        },
+    });
+    pi.registerCommand("state-flow-status", {
+        description: "Show State Flow runtime status",
+        handler: async (_args, ctx) => {
+            ctx.ui.notify(detailedStatus(snapshot, statusDiagnostics(ctx)), "info");
+        },
+    });
+    function stopStateFlow(ctx) {
+        if (!activeContext)
+            restoreActiveBranch(ctx);
+        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 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)
+            : 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;
+        clearRunTransient();
+        passiveContinuation = retainedHandoff;
+        bootstrapContinuation = undefined;
+        artifactInvalidations = [];
+        artifactReads.setCandidates([]);
+        artifactRefreshPending = false;
+        if (exitHandoff)
+            pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
+                at: stoppedAt,
+                ...(exitHandoff.activeRunStartedAt === undefined ? {} : { from: exitHandoff.activeRunStartedAt }),
+            });
+        syncStateFlowTools();
+        persist();
+        updateUi(ctx);
+        return { ok: true, message: "State Flow disabled" };
+    }
+    pi.registerCommand("state-flow-stop", {
+        description: "Stop State Flow on the current session branch",
+        handler: async (_args, ctx) => {
+            stopStateFlow(ctx);
+        },
+    });
+    const telegram = createStateFlowTelegramAdapter({
+        ...(options.telegram?.load === undefined ? {} : { load: options.telegram.load }),
+        port: {
+            snapshot: () => ({
+                enabled: snapshot.config.enabled,
+                step: snapshot.meta.step,
+                bootstrap: snapshot.meta.bootstrap === true,
+                startPending: telegramStartPending,
+            }),
+            state: (scope) => projectStateForModel(scope === "effective"
+                ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
+                : scopeStates[scope]),
+            canStartNow: () => activeContext === undefined || activeContext.isIdle(),
+            start: () => {
+                if (!activeContext)
+                    throw new Error("State Flow is not attached to an active session yet");
+                return startStateFlow(activeContext);
+            },
+            stop: () => {
+                if (!activeContext)
+                    throw new Error("State Flow is not attached to an active session yet");
+                try {
+                    return stopStateFlow(activeContext);
+                }
+                catch (error) {
+                    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+                }
+            },
+            deferStart: () => {
+                telegramStartPending = true;
+            },
+            cancelStart: () => {
+                telegramStartPending = false;
+            },
+        },
+    });
+    void telegram.ensure();
+    pi.on("before_agent_start", (event, ctx) => {
+        if (!snapshot.config.enabled)
+            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;
+            persist();
+        }
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n${stateFlowProtocol(snapshot.meta.bootstrap === true)}`,
+        };
+    });
+    pi.on("context", (event) => {
+        if (passiveContinuation) {
+            return { messages: passiveContinuationMessages(event.messages, passiveContinuation) };
+        }
+        if (!snapshot.config.enabled || 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 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] };
+        }
+        const trajectory = currentRunTrajectory(event.messages, snapshot.meta.specification, runAnchorTimestamp);
+        runAnchorTimestamp = trajectory.anchorTimestamp;
+        return {
+            messages: [
+                runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, resolutionPending),
+                ...trajectory.messages,
+            ],
+        };
+    });
+    pi.on("tool_execution_start", (event) => {
+        if (!snapshot.config.enabled)
+            return;
+        // Pi emits this before tool_call. Keep the argument object as a fallback;
+        // tool_call replaces it with the mutable, post-preflight input reference.
+        skillReads.recordStart(event.toolCallId, event.toolName, event.args);
+        artifactReads.recordStart(event.toolCallId, event.toolName, event.args);
+    });
+    pi.on("tool_call", (event, ctx) => {
+        if (!snapshot.config.enabled)
+            return;
+        const batch = assistantToolBatch(ctx, event.toolCallId);
+        const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
+        if (patchCalls > 0) {
+            if (patchCalls !== 1) {
+                return {
+                    block: true,
+                    reason: "A State Flow barrier response must contain exactly one patch_state call",
+                };
+            }
+            if (event.toolName !== PATCH_STATE_TOOL_NAME) {
+                return {
+                    block: true,
+                    reason: "Blocked by the patch_state barrier; reconsider this action after State Flow rematerializes context",
+                };
+            }
+        }
+        skillReads.recordCall(event.toolCallId, event.toolName, event.input);
+        artifactReads.recordCall(event.toolCallId, event.toolName, event.input);
+    });
+    pi.on("tool_execution_end", (event) => {
+        if (!snapshot.config.enabled)
+            return;
+        skillReads.recordEnd(event.toolCallId, event.toolName, event.isError);
+        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.
+        if (event.message.role === "user" && runAnchorTimestamp === undefined)
+            runAnchorTimestamp = event.message.timestamp;
+        if (event.message.role !== "assistant")
+            return;
+        const message = event.message;
+        if (message.stopReason === "aborted" || assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse") {
+            responseAwaitingReconciliation = false;
+            return;
+        }
+        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));
+            return;
+        }
+        responseAwaitingReconciliation = true;
+    });
+    pi.on("turn_end", (event, ctx) => {
+        const wasBootstrap = snapshot.meta.bootstrap === true;
+        if (!snapshot.config.enabled || !responseAwaitingReconciliation) {
+            updateUi(ctx);
+            return;
+        }
+        let responseCommitted = false;
+        try {
+            const response = finalizedAssistantResponse(event.message);
+            const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime.causalBasis());
+            commitStage(stage, ctx, true);
+            responseCommitted = true;
+            bootstrapContinuation = undefined;
+            rehydrationPhase = "step";
+            enqueueTurnPublication(ctx);
+            if (snapshot.meta.remotePublication?.mode === "turn-end")
+                launchPublicationWorker();
+            completedRunAccepted = !wasBootstrap;
+        }
+        catch (error) {
+            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 could not reconcile the final response: ${error instanceof Error ? error.message : String(error)}`, "error");
+        }
+        finally {
+            responseAwaitingReconciliation = false;
+        }
+        updateUi(ctx);
+    });
+    pi.on("session_before_compact", (event) => {
+        if (!compactionPlan)
+            return;
+        if (compactionStopped && event.reason === "manual" && event.customInstructions === compactionMarker)
+            return { cancel: true };
+        const result = stateFlowCompactionResult(compactionPlan, compactionMarker, event);
+        if (result === undefined || "cancel" in result)
+            return result;
+        return { compaction: result };
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        if (telegramStartPending && !snapshot.config.enabled) {
+            telegramStartPending = false;
+            startStateFlow(ctx);
+        }
+        if (snapshot.meta.remotePublication?.mode === "turn-end")
+            launchPublicationWorker();
+        if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
+            || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
+            || !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);
+        if (!plan)
+            return;
+        compactionPlan = plan;
+        compactionInFlight = true;
+        ctx.compact({
+            customInstructions: compactionMarker,
+            onComplete: () => { compactionPlan = undefined; compactionInFlight = false; },
+            onError: () => { compactionPlan = undefined; compactionInFlight = false; },
+        });
+    });
+    pi.on("session_start", (event, ctx) => {
+        rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
+        restoreActiveBranch(ctx, event.reason);
+        retryPendingPush(ctx);
+        if (snapshot.meta.remotePublication?.mode === "turn-end")
+            launchPublicationWorker();
+        updateUi(ctx);
+        void telegram.ensure();
+    });
+    pi.on("session_tree", (_event, ctx) => {
+        restoreActiveBranch(ctx);
+    });
+    pi.on("session_shutdown", (_event, ctx) => {
+        telegramStartPending = false;
+        compactionStopped = true;
+        completedRunAccepted = false;
+        telegram.dispose();
+        return shutdownPublicationWorkers(ctx);
+    });
+}