@caupulican/pi-adaptative 0.96.3 → 0.96.5

package/dist/core/reflection-controller.d.ts

@@ -13,6 +13,7 @@ import type { Api, Model, SimpleStreamOptions, Usage } from "@caupulican/pi-ai/t
 import { type IsolatedCompletionOptions, type IsolatedCompletionResult } from "./agent-session-contracts.ts";
 import type { LearningDecision } from "./autonomy/contracts.ts";
 import { type AutonomyTelemetryEvent } from "./autonomy/telemetry-events.ts";
+import { type DurableLearningClaimToken, type DurableLearningCueAttachOutcome, type DurableLearningReviewMetadata, type DurableLearningState } from "./learning/durable-learning-state.ts";
 import { type LearningAuditRecord } from "./learning/learning-audit.ts";
 import { type DemandSignals, type ReflectionResult } from "./learning/reflection-engine.ts";
 import { type ReflectionTurnAnalysis } from "./learning/reflection-turn-analysis.ts";
@@ -77,12 +78,20 @@ export interface ReflectionControllerDeps {
     getCwd?(): string;
     /** Already-loaded root skill universe; avoids a second unbounded filesystem discovery during reflection. */
     getSkillsForAudit?(): readonly Skill[];
+    /** Root-owned durable version transition state; omitted by legacy or test hosts. */
+    getDurableLearningState?(): DurableLearningState | undefined;
+    /** Installed runtime identity used only for root-owned durable transition detection. */
+    getRuntimeVersion?(): string | undefined;
+    /** Versioned durable-memory interpretation policy. */
+    getMemoryPolicyVersion?(): string | undefined;
+    /** Bounded host warning sink for fail-safe state degradation. */
+    warn?(message: string): void;
 }
 export declare const SKILL_OVERLAP_CONSOLIDATION_REASON_CODE = "skill_overlap_consolidation_proposed";
 export declare const SKILL_AUDIT_UNAVAILABLE_REASON_CODE = "skill_audit_unavailable";
 export declare const CURRENT_TURN_REFLECTION_CUSTOM_TYPE = "reflection_cue";
 export declare const CURRENT_TURN_REFLECTION_STATE_CUSTOM_TYPE = "reflection_cue_state";
-export type CurrentTurnReflectionTrigger = "root-turn" | Exclude<DemandSignals["trigger"], "none">;
+export type CurrentTurnReflectionTrigger = "root-turn" | "version-change" | Exclude<DemandSignals["trigger"], "none">;
 export interface CurrentTurnReflectionCueState {
     version: 1;
     revision: number;
@@ -91,6 +100,13 @@ export interface CurrentTurnReflectionCueState {
     triggers: CurrentTurnReflectionTrigger[];
     createdAt: string;
     updatedAt: string;
+    /** Provider-hidden token proving exact ownership of one version transition. */
+    versionChange?: {
+        token: DurableLearningClaimToken;
+        metadata: DurableLearningReviewMetadata;
+    };
+    /** Provider-hidden identity of the currently accepted cue-bearing request. */
+    activeRunToken?: string;
 }
 export interface CurrentTurnReflectionCuePlan {
     message: AgentMessage;
@@ -100,27 +116,41 @@ export interface CurrentTurnReflectionCuePlan {
 export declare class ReflectionController {
     private readonly deps;
     private readonly unsubscribeSettingsChanges;
+    private readonly durableLearningOwnerId;
+    private readonly emittedWarningCodes;
     private cueStateCacheInitialized;
     private cueStateCache;
+    private activeRunToken;
     constructor(deps: ReflectionControllerDeps);
     dispose(): void;
     private isAutomaticReflectionEnabled;
     /** Latest durable cue snapshot on the active session branch; custom state never enters model context. */
     getCurrentTurnCueState(): CurrentTurnReflectionCueState | undefined;
     /** Branch/session navigation invalidates the lazy latest-state index; ordinary appends do not. */
-    invalidateCurrentTurnCueStateCache(): void;
+    invalidateCurrentTurnCueStateCache(options?: {
+        releaseActiveClaim?: boolean;
+    }): void;
     private persistCurrentTurnCueState;
+    private warnOnce;
+    private dismissCurrentTurnCue;
     private synchronizeCurrentTurnCueWithSettings;
+    private attachCurrentTurnCue;
+    /** Persist one logical ordinary cue without exposing claim metadata to callers. */
+    queueCurrentTurnCue(trigger: CurrentTurnReflectionTrigger): boolean;
     /**
-     * Persist one logical pending cue. Repeated triggers merge into the existing pending snapshot;
-     * they never append competing pending cues or retain raw transcript text.
+     * Root-turn entrypoint: reconcile installed runtime/policy state and atomically attach any exact
+     * version claim to the same provider cue. Fail-safe state faults degrade to an ordinary root cue.
      */
-    queueCurrentTurnCue(trigger: CurrentTurnReflectionTrigger): boolean;
+    queueExternalRootTurnCue(): DurableLearningCueAttachOutcome;
     /**
-     * Preview one transient provider-only cue. Discarded/replanned previews do nothing; the accepted
-     * provider-plan commit closes exactly the captured cue id + revision.
+     * Preview one transient provider-only cue. An accepted cue remains visible across provider-tool
+     * continuation requests until AgentSession reports one strict terminal success or failure.
      */
     previewCurrentTurnCue(): CurrentTurnReflectionCuePlan | undefined;
+    /** Settle one accepted cue-bearing provider run at its authoritative AgentSession boundary. */
+    finishCurrentTurnCue(messages: AgentMessage[], options: {
+        willRetry: boolean;
+    }): void;
     /** Pure completed-turn projection used only by deterministic memory synchronization. */
     analyzeCompletedTurn(messages: AgentMessage[]): ReflectionTurnAnalysis;
     /**

package/dist/core/reflection-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reflection-controller.d.ts","sourceRoot":"","sources":["../../src/core/reflection-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAiC,YAAY,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAElH,OAAO,KAAK,EACX,GAAG,EAGH,KAAK,EACL,mBAAmB,EAEnB,KAAK,EACL,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGN,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAkC,KAAK,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAG7G,OAAO,EAKN,KAAK,mBAAmB,EAGxB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,aAAa,EAGlB,KAAK,gBAAgB,EAErB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAyB,KAAK,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAC5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACX,+BAA+B,EAC/B,4BAA4B,EAC5B,yBAAyB,EACzB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,WAAW,wBAAwB;IACxC,sFAAsF;IACtF,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,IAAI,KAAK,CAAC;IAClB,oGAAoG;IACpG,iBAAiB,IAAI,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,gBAAgB,IAAI,aAAa,CAAC;IAClC,yGAAyG;IACzG,gBAAgB,IAAI,aAAa,CAAC;IAClC,gGAAgG;IAChG,8BAA8B,IAAI,MAAM,CAAC;IACzC,8DAA8D;IAC9D,8BAA8B,CAC7B,KAAK,EAAE,yBAAyB,EAChC,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAC5C,sEAAsE;IACtE,iCAAiC,CAAC,QAAQ,EAAE,4BAA4B,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClH,8FAA8F;IAC9F,kBAAkB,IAAI,eAAe,CAAC;IACtC,8EAA8E;IAC9E,iBAAiB,IAAI,cAAc,CAAC;IACpC,qFAAqF;IACrF,WAAW,IAAI,MAAM,CAAC;IACtB,sEAAsE;IACtE,cAAc,IAAI,OAAO,CAAC;IAC1B,gFAAgF;IAChF,UAAU,IAAI,OAAO,CAAC;IACtB,4FAA4F;IAC5F,mBAAmB,IAAI,WAAW,CAAC;IACnC,sEAAsE;IACtE,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C,mFAAmF;IACnF,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B,sFAAsF;IACtF,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC3D,gGAAgG;IAChG,eAAe,CACd,KAAK,EAAE,KAAK,EACZ,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,MAAM,GAAG,SAAS,CAAC;IACtB,oEAAoE;IACpE,4BAA4B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjE,4FAA4F;IAC5F,2BAA2B,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;IAC5F,0FAA0F;IAC1F,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,MAAM,CAAC;IAClB,4GAA4G;IAC5G,iBAAiB,CAAC,IAAI,SAAS,KAAK,EAAE,CAAC;CACvC;AAID,eAAO,MAAM,uCAAuC,yCAAyC,CAAC;AAG9F,eAAO,MAAM,mCAAmC,4BAA4B,CAAC;AAE7E,eAAO,MAAM,mCAAmC,mBAAmB,CAAC;AACpE,eAAO,MAAM,yCAAyC,yBAAyB,CAAC;AAEhF,MAAM,MAAM,4BAA4B,GAAG,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;AAEnG,MAAM,WAAW,6BAA6B;IAC7C,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,QAAQ,EAAE,4BAA4B,EAAE,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC5C,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,IAAI,OAAO,CAAC;IACrB,MAAM,IAAI,IAAI,CAAC;CACf;AA6DD,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAa;IACxD,OAAO,CAAC,wBAAwB,CAAS;IACzC,OAAO,CAAC,aAAa,CAA4C;IAEjE,YAAY,IAAI,EAAE,wBAAwB,EAMzC;IAED,OAAO,IAAI,IAAI,CAEd;IAED,OAAO,CAAC,4BAA4B;IASpC,yGAAyG;IACzG,sBAAsB,IAAI,6BAA6B,GAAG,SAAS,CAiBlE;IAED,kGAAkG;IAClG,kCAAkC,IAAI,IAAI,CAGzC;IAED,OAAO,CAAC,0BAA0B;IAMlC,OAAO,CAAC,qCAAqC;IAY7C;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CA6BlE;IAED;;;OAGG;IACH,qBAAqB,IAAI,4BAA4B,GAAG,SAAS,CA4ChE;IAED,wFAAwF;IACxF,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,sBAAsB,CAOrE;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAyO9F;IAED;;;;;;;;OAQG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAC9B,OAAO,EAAE,aAAa,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,8FAA8F;QAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,kGAAkG;QAClG,6BAA6B,CAAC,EAAE,OAAO,CAAC;KACxC,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgNnC;IAED,uBAAuB,IAAI,mBAAmB,EAAE,CAE/C;IAED;;;;;OAKG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CA8FrF;IAED;;;;;;OAMG;YACW,qBAAqB;IAoGnC;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IA0CnC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;CAwB/B"}
+{"version":3,"file":"reflection-controller.d.ts","sourceRoot":"","sources":["../../src/core/reflection-controller.ts"],"names":[],"mappings":"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"}

package/dist/core/reflection-controller.js

@@ -15,6 +15,7 @@ import { computeLaneAffinityKey, DEFAULT_ISOLATED_LANE_KIND, } from "./agent-ses
 import { AUTONOMY_TELEMETRY_EVENT_TYPES } from "./autonomy/telemetry-events.js";
 import { PI_OKF_TYPES } from "./context/okf-memory.js";
 import { isCurrentSessionReflectionEnabled, resolveAutoLearnSettings } from "./learning/auto-learn-settings.js";
+import { isDurableLearningClaimToken, isDurableLearningReviewMetadata, } from "./learning/durable-learning-state.js";
 import { APPLY_WRITE_REFUSED_REASON_CODE, appendLearningAuditSnapshot, contradictionsForReflectionWrite, getLearningAuditSnapshots, proposalFromReflectionWrite, rollbackPlanForReflectionWrite, } from "./learning/learning-audit.js";
 import { evaluateLearningDecision } from "./learning/learning-gate.js";
 import { ObservationStore, observationKey } from "./learning/observation-store.js";
@@ -34,11 +35,14 @@ const CURRENT_TURN_REFLECTION_CUE = [
     "Root reflection contract for this current turn:",
     "- Decide during this same turn whether the request or resulting evidence warrants durable learning.",
     "- When warranted, confront existing memory first, then use this root session's memory or skill tools now.",
+    "- Route canonical project semantics and evidence to OKF; keep ICM/workflow context as status plus OKF references, never duplicated project truth.",
+    "- Route stable collaborator preferences to USER, compact hot facts to MEMORY, and reusable procedures to skills.",
     "- Do not defer reflection, request another model turn, call an isolated completion, or launch a background learner or worker for reflection.",
     "- When nothing durable is warranted, continue normally and do not mention this cue.",
 ].join("\n");
 const CURRENT_TURN_REFLECTION_TRIGGERS = new Set([
     "root-turn",
+    "version-change",
     "complex",
     "corrective",
     "durable",
@@ -58,7 +62,12 @@ function parseCurrentTurnReflectionCueState(value) {
         candidate.triggers.length === 0 ||
         candidate.triggers.some((trigger) => !CURRENT_TURN_REFLECTION_TRIGGERS.has(trigger)) ||
         typeof candidate.createdAt !== "string" ||
-        typeof candidate.updatedAt !== "string") {
+        typeof candidate.updatedAt !== "string" ||
+        (candidate.activeRunToken !== undefined && typeof candidate.activeRunToken !== "string") ||
+        (candidate.versionChange !== undefined &&
+            (!candidate.versionChange ||
+                !isDurableLearningClaimToken(candidate.versionChange.token) ||
+                !isDurableLearningReviewMetadata(candidate.versionChange.metadata)))) {
         return undefined;
     }
     return {
@@ -69,8 +78,35 @@ function parseCurrentTurnReflectionCueState(value) {
         triggers: [...new Set(candidate.triggers)],
         createdAt: candidate.createdAt,
         updatedAt: candidate.updatedAt,
+        ...(candidate.versionChange
+            ? {
+                versionChange: {
+                    token: { ...candidate.versionChange.token },
+                    metadata: { ...candidate.versionChange.metadata },
+                },
+            }
+            : {}),
+        ...(candidate.activeRunToken ? { activeRunToken: candidate.activeRunToken } : {}),
     };
 }
+function versionClaimTokensMatch(left, right) {
+    return (left.transitionId === right.transitionId &&
+        left.claimId === right.claimId &&
+        left.ownerId === right.ownerId &&
+        left.runtimeVersion === right.runtimeVersion &&
+        left.memoryPolicyVersion === right.memoryPolicyVersion);
+}
+function hasStrictSuccessfulAssistantTerminal(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role !== "assistant")
+            continue;
+        if (message.stopReason !== "stop" || message.errorMessage)
+            return false;
+        return message.content.some((part) => part.type === "text" && part.text.trim().length > 0);
+    }
+    return false;
+}
 function parseOkfRollbackTarget(target) {
     if (!target)
         return undefined;
@@ -84,6 +120,8 @@ function parseOkfRollbackTarget(target) {
 }
 export class ReflectionController {
     constructor(deps) {
+        this.durableLearningOwnerId = randomUUID();
+        this.emittedWarningCodes = new Set();
         this.cueStateCacheInitialized = false;
         this.deps = deps;
         this.unsubscribeSettingsChanges = deps.getSettingsManager().subscribeChanges(() => {
@@ -92,6 +130,7 @@ export class ReflectionController {
         this.synchronizeCurrentTurnCueWithSettings();
     }
     dispose() {
+        this.dismissCurrentTurnCue();
         this.unsubscribeSettingsChanges();
     }
     isAutomaticReflectionEnabled() {
@@ -122,7 +161,18 @@ export class ReflectionController {
         return this.cueStateCache;
     }
     /** Branch/session navigation invalidates the lazy latest-state index; ordinary appends do not. */
-    invalidateCurrentTurnCueStateCache() {
+    invalidateCurrentTurnCueStateCache(options = {}) {
+        if (options.releaseActiveClaim) {
+            const current = this.cueStateCacheInitialized ? this.cueStateCache : undefined;
+            const isActive = current?.status === "pending" ||
+                (current?.status === "consumed" &&
+                    !!current.activeRunToken &&
+                    current.activeRunToken === this.activeRunToken);
+            if (isActive && current?.versionChange) {
+                this.deps.getDurableLearningState?.()?.releaseClaim(current.versionChange.token);
+            }
+            this.activeRunToken = undefined;
+        }
         this.cueStateCacheInitialized = false;
         this.cueStateCache = undefined;
     }
@@ -131,68 +181,184 @@ export class ReflectionController {
         this.cueStateCache = state;
         this.cueStateCacheInitialized = true;
     }
-    synchronizeCurrentTurnCueWithSettings() {
-        if (this.isAutomaticReflectionEnabled())
+    warnOnce(code, message) {
+        if (this.emittedWarningCodes.has(code))
             return;
+        this.emittedWarningCodes.add(code);
+        this.deps.warn?.(message);
+    }
+    dismissCurrentTurnCue() {
         const current = this.getCurrentTurnCueState();
-        if (current?.status !== "pending")
+        const isActive = current?.status === "pending" ||
+            (current?.status === "consumed" && !!current.activeRunToken && current.activeRunToken === this.activeRunToken);
+        if (!current || !isActive)
             return;
-        this.persistCurrentTurnCueState({
-            ...current,
-            revision: current.revision + 1,
-            status: "dismissed",
-            updatedAt: new Date().toISOString(),
-        });
+        try {
+            this.persistCurrentTurnCueState({
+                ...current,
+                revision: current.revision + 1,
+                status: "dismissed",
+                activeRunToken: undefined,
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        catch {
+            this.warnOnce("cue-dismiss-failed", "Automatic reflection cue dismissal failed; its durable claim will expire safely.");
+            return;
+        }
+        this.activeRunToken = undefined;
+        if (current.versionChange)
+            this.deps.getDurableLearningState?.()?.releaseClaim(current.versionChange.token);
+    }
+    synchronizeCurrentTurnCueWithSettings() {
+        if (this.isAutomaticReflectionEnabled())
+            return;
+        this.dismissCurrentTurnCue();
+    }
+    attachCurrentTurnCue(trigger, versionChange, clearVersionChange = false) {
+        if (!this.isAutomaticReflectionEnabled()) {
+            this.synchronizeCurrentTurnCueWithSettings();
+            return "disabled";
+        }
+        try {
+            const current = this.getCurrentTurnCueState();
+            const updatedAt = new Date().toISOString();
+            if (current?.status === "pending") {
+                if (clearVersionChange && current.versionChange) {
+                    const triggers = current.triggers.filter((existing) => existing !== "version-change");
+                    if (!triggers.includes(trigger))
+                        triggers.push(trigger);
+                    this.persistCurrentTurnCueState({
+                        ...current,
+                        revision: current.revision + 1,
+                        triggers,
+                        versionChange: undefined,
+                        updatedAt,
+                    });
+                    return "replaced-stale";
+                }
+                const alreadyHasTrigger = current.triggers.includes(trigger);
+                const alreadyHasVersionTrigger = !versionChange || current.triggers.includes("version-change");
+                const sameVersionClaim = !versionChange ||
+                    (!!current.versionChange && versionClaimTokensMatch(current.versionChange.token, versionChange.token));
+                if (alreadyHasTrigger && alreadyHasVersionTrigger && sameVersionClaim)
+                    return "coalesced";
+                const replacingVersionClaim = !!versionChange && !!current.versionChange && !sameVersionClaim;
+                const triggers = [...current.triggers];
+                if (!triggers.includes(trigger))
+                    triggers.push(trigger);
+                if (versionChange && !triggers.includes("version-change"))
+                    triggers.push("version-change");
+                this.persistCurrentTurnCueState({
+                    ...current,
+                    revision: current.revision + 1,
+                    triggers,
+                    updatedAt,
+                    ...(versionChange ? { versionChange } : {}),
+                });
+                return replacingVersionClaim ? "replaced-stale" : "attached";
+            }
+            const triggers = [trigger];
+            if (versionChange && !triggers.includes("version-change"))
+                triggers.push("version-change");
+            this.persistCurrentTurnCueState({
+                version: 1,
+                revision: 1,
+                cueId: randomUUID(),
+                status: "pending",
+                triggers,
+                createdAt: updatedAt,
+                updatedAt,
+                ...(versionChange ? { versionChange } : {}),
+            });
+            return "attached";
+        }
+        catch {
+            this.warnOnce("cue-attach-failed", "Automatic reflection cue persistence failed; durable learning was not claimed.");
+            return "failed";
+        }
+    }
+    /** Persist one logical ordinary cue without exposing claim metadata to callers. */
+    queueCurrentTurnCue(trigger) {
+        const outcome = this.attachCurrentTurnCue(trigger);
+        return outcome === "attached" || outcome === "replaced-stale";
     }
     /**
-     * Persist one logical pending cue. Repeated triggers merge into the existing pending snapshot;
-     * they never append competing pending cues or retain raw transcript text.
+     * Root-turn entrypoint: reconcile installed runtime/policy state and atomically attach any exact
+     * version claim to the same provider cue. Fail-safe state faults degrade to an ordinary root cue.
      */
-    queueCurrentTurnCue(trigger) {
+    queueExternalRootTurnCue() {
         if (!this.isAutomaticReflectionEnabled()) {
             this.synchronizeCurrentTurnCueWithSettings();
-            return false;
+            return "disabled";
         }
-        const current = this.getCurrentTurnCueState();
-        const updatedAt = new Date().toISOString();
-        if (current?.status === "pending") {
-            if (current.triggers.includes(trigger))
-                return false;
-            const next = {
-                ...current,
-                revision: current.revision + 1,
-                triggers: [...current.triggers, trigger],
-                updatedAt,
-            };
-            this.persistCurrentTurnCueState(next);
-            return true;
+        const state = this.deps.getDurableLearningState?.();
+        const runtimeVersion = this.deps.getRuntimeVersion?.();
+        const memoryPolicyVersion = this.deps.getMemoryPolicyVersion?.();
+        if (!state || !runtimeVersion || !memoryPolicyVersion) {
+            if (state && (!runtimeVersion || !memoryPolicyVersion)) {
+                this.warnOnce("version-identity-unavailable", "Installed runtime identity is unavailable; continuing with ordinary root reflection only.");
+            }
+            return this.attachCurrentTurnCue("root-turn", undefined, true);
         }
-        const next = {
-            version: 1,
-            revision: 1,
-            cueId: randomUUID(),
-            status: "pending",
-            triggers: [trigger],
-            createdAt: updatedAt,
-            updatedAt,
-        };
-        this.persistCurrentTurnCueState(next);
-        return true;
+        const result = state.reconcileClaimAndAttach({ runtimeVersion, memoryPolicyVersion }, this.durableLearningOwnerId, (token, metadata) => this.attachCurrentTurnCue("root-turn", { token, metadata }));
+        if (result.warningCode) {
+            this.warnOnce(result.warningCode, `Durable learning state warning (${result.warningCode}); semantic memory remained unchanged.`);
+        }
+        if (result.status === "attached" ||
+            result.status === "coalesced" ||
+            result.status === "replaced-stale" ||
+            result.status === "disabled" ||
+            result.status === "failed") {
+            return result.status;
+        }
+        return this.attachCurrentTurnCue("root-turn", undefined, true);
     }
     /**
-     * Preview one transient provider-only cue. Discarded/replanned previews do nothing; the accepted
-     * provider-plan commit closes exactly the captured cue id + revision.
+     * Preview one transient provider-only cue. An accepted cue remains visible across provider-tool
+     * continuation requests until AgentSession reports one strict terminal success or failure.
      */
     previewCurrentTurnCue() {
-        const current = this.getCurrentTurnCueState();
-        if (current?.status !== "pending" || !this.isAutomaticReflectionEnabled())
+        let current = this.getCurrentTurnCueState();
+        if (!current || !this.isAutomaticReflectionEnabled())
+            return undefined;
+        let pending = current.status === "pending";
+        let continuing = current.status === "consumed" && !!this.activeRunToken && current.activeRunToken === this.activeRunToken;
+        if (!pending && !continuing)
             return undefined;
+        if (continuing && current.versionChange) {
+            const renewed = this.deps.getDurableLearningState?.()?.renewClaim(current.versionChange.token) ?? false;
+            if (!renewed) {
+                const withoutStaleClaim = {
+                    ...current,
+                    revision: current.revision + 1,
+                    triggers: current.triggers.filter((trigger) => trigger !== "version-change"),
+                    versionChange: undefined,
+                    updatedAt: new Date().toISOString(),
+                };
+                try {
+                    this.persistCurrentTurnCueState(withoutStaleClaim);
+                    current = withoutStaleClaim;
+                    pending = false;
+                    continuing = true;
+                }
+                catch {
+                    this.warnOnce("cue-stale-claim-removal-failed", "A stale durable version claim could not be removed from provider cue state; version metadata was withheld.");
+                    return undefined;
+                }
+            }
+        }
         const cueId = current.cueId;
         const revision = current.revision;
+        const expectedStatus = current.status;
+        const expectedRunToken = current.activeRunToken;
+        const versionLine = current.versionChange
+            ? `\n- Installed-state transition: ${current.versionChange.metadata.reason}; runtime ${current.versionChange.metadata.previousRuntimeVersion ?? "unobserved"} to ${current.versionChange.metadata.runtimeVersion}; memory policy ${current.versionChange.metadata.previousMemoryPolicyVersion ?? "unobserved"} to ${current.versionChange.metadata.memoryPolicyVersion}. First observation is audit-only, and version movement alone is never semantic evidence. Revalidate current sources; update only the canonical durable owner when warranted.`
+            : "";
         const message = {
             role: "custom",
             customType: CURRENT_TURN_REFLECTION_CUSTOM_TYPE,
-            content: `${CURRENT_TURN_REFLECTION_CUE}\n- Pending evidence classes: ${current.triggers.join(", ")}.`,
+            content: `${CURRENT_TURN_REFLECTION_CUE}\n- Pending evidence classes: ${current.triggers.join(", ")}.${versionLine}`,
             display: false,
             details: {
                 version: 1,
@@ -200,15 +366,17 @@ export class ReflectionController {
                 automaticProviderRequests: 0,
                 cueId: current.cueId,
                 triggers: current.triggers,
+                ...(current.versionChange ? { versionChange: { ...current.versionChange.metadata } } : {}),
             },
             timestamp: Date.now(),
         };
         const isCurrent = () => {
             const latest = this.getCurrentTurnCueState();
             return (this.isAutomaticReflectionEnabled() &&
-                latest?.status === "pending" &&
+                latest?.status === expectedStatus &&
                 latest.cueId === cueId &&
-                latest.revision === revision);
+                latest.revision === revision &&
+                latest.activeRunToken === expectedRunToken);
         };
         return {
             message,
@@ -216,19 +384,80 @@ export class ReflectionController {
             commit: () => {
                 if (!isCurrent())
                     throw new Error("Reflection cue changed before provider-plan commit");
+                if (expectedStatus === "consumed")
+                    return;
                 const latest = this.getCurrentTurnCueState();
                 if (!latest)
                     throw new Error("Reflection cue disappeared before provider-plan commit");
-                const next = {
+                const activeRunToken = randomUUID();
+                this.persistCurrentTurnCueState({
                     ...latest,
                     revision: latest.revision + 1,
                     status: "consumed",
+                    activeRunToken,
                     updatedAt: new Date().toISOString(),
-                };
-                this.persistCurrentTurnCueState(next);
+                });
+                this.activeRunToken = activeRunToken;
             },
         };
     }
+    /** Settle one accepted cue-bearing provider run at its authoritative AgentSession boundary. */
+    finishCurrentTurnCue(messages, options) {
+        if (!this.isAutomaticReflectionEnabled()) {
+            this.synchronizeCurrentTurnCueWithSettings();
+            return;
+        }
+        const current = this.getCurrentTurnCueState();
+        if (current?.status !== "consumed" || !current.activeRunToken || current.activeRunToken !== this.activeRunToken) {
+            return;
+        }
+        const state = this.deps.getDurableLearningState?.();
+        if (options.willRetry) {
+            let versionChange = current.versionChange;
+            if (versionChange && !state?.renewClaim(versionChange.token))
+                versionChange = undefined;
+            try {
+                this.persistCurrentTurnCueState({
+                    ...current,
+                    revision: current.revision + 1,
+                    status: "pending",
+                    activeRunToken: undefined,
+                    triggers: versionChange
+                        ? current.triggers
+                        : current.triggers.filter((trigger) => trigger !== "version-change"),
+                    versionChange,
+                    updatedAt: new Date().toISOString(),
+                });
+                this.activeRunToken = undefined;
+            }
+            catch {
+                this.warnOnce("cue-retry-failed", "Automatic reflection cue retry persistence failed; any durable claim will expire safely.");
+            }
+            return;
+        }
+        const success = hasStrictSuccessfulAssistantTerminal(messages);
+        try {
+            this.persistCurrentTurnCueState({
+                ...current,
+                revision: current.revision + 1,
+                activeRunToken: undefined,
+                updatedAt: new Date().toISOString(),
+            });
+            this.activeRunToken = undefined;
+        }
+        catch {
+            this.warnOnce("cue-finish-failed", "Automatic reflection cue completion persistence failed; any durable claim will expire safely.");
+            return;
+        }
+        if (!current.versionChange || !state)
+            return;
+        const settled = success
+            ? state.completeReview(current.versionChange.token)
+            : state.releaseClaim(current.versionChange.token);
+        if (!settled) {
+            this.warnOnce("version-claim-settle-failed", "Durable version claim no longer matched its exact transition; no semantic memory state was marked complete.");
+        }
+    }
     /** Pure completed-turn projection used only by deterministic memory synchronization. */
     analyzeCompletedTurn(messages) {
         const settingsManager = this.deps.getSettingsManager();