@caupulican/pi-adaptative 0.94.0 → 0.95.0

package/dist/core/reflection-controller.js

@@ -1,148 +1,243 @@
 /**
- * Native reflection + learning-write controller.
+ * Root-session reflection cue + explicit learning-write controller.
  *
- * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the end-of-loop reflection
- * pass (R2), the isolated-completion primitive it runs on, and the learning-apply/rollback path that
- * turns reflection writes into gated, audited durable memory/skill changes. It mutates NO session
- * fields — every durable effect goes through the bundled memory tool, the session log (via deps), or
- * the skills dir; the whole pass is best-effort and never throws into the turn loop. Reads live
- * session state (model/agent/registry/memory/settings) through narrow deps accessors rather than the
- * whole AgentSession.
+ * Automatic reflection is a hidden cue in the root orchestrator's ordinary provider turn. This
+ * controller never schedules an automatic provider request. The isolated completion and structured
+ * reflection pass remain explicit compatibility/application seams for owner-invoked callers. Every
+ * durable effect goes through the bundled memory tool, the session log (via deps), or the skills dir.
  */
-import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { runAgentLoop, startAgentProviderRequest } from "@caupulican/pi-agent-core/agent-loop";
 import { resolveModelThinkingLevel } from "@caupulican/pi-ai/models";
 import { computeLaneAffinityKey, DEFAULT_ISOLATED_LANE_KIND, } from "./agent-session-contracts.js";
 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 { 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";
 import { decideDemand, ReflectionEngine, } from "./learning/reflection-engine.js";
-import { analyzeReflectionTurn, boundReflectionSemanticText, reflectionTriggerPriority, } from "./learning/reflection-turn-analysis.js";
-import { resolveCliModel } from "./model-resolver.js";
+import { analyzeReflectionTurn } from "./learning/reflection-turn-analysis.js";
 import { registerInFlightWork } from "./reload-blockers.js";
-import { runSkillAudit } from "./tools/skill-audit.js";
+import { DEFAULT_BOUNDED_SKILL_AUDIT_LIMITS, runSkillAudit } from "./tools/skill-audit.js";
 // reasonCode when an automatic skill promotion is blocked by an overlap with an existing skill
 // (skill_audit's similarity threshold) and routed to a consolidation proposal instead of a blind write.
 export const SKILL_OVERLAP_CONSOLIDATION_REASON_CODE = "skill_overlap_consolidation_proposed";
 // reasonCode when the overlap audit itself fails — the promotion is held (not written unaudited)
 // rather than silently skipping the check.
 export const SKILL_AUDIT_UNAVAILABLE_REASON_CODE = "skill_audit_unavailable";
-const REFLECTION_MIN_INTERVAL_MS = 45_000;
-const REFLECTION_PENDING_MAX_CHARS = 12_000;
-const REFLECTION_DIGEST_HISTORY_SIZE = 64;
+export const CURRENT_TURN_REFLECTION_CUSTOM_TYPE = "reflection_cue";
+export const CURRENT_TURN_REFLECTION_STATE_CUSTOM_TYPE = "reflection_cue_state";
+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.",
+    "- 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",
+    "complex",
+    "corrective",
+    "durable",
+    "session-end",
+]);
+function parseCurrentTurnReflectionCueState(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value;
+    if (candidate.version !== 1 ||
+        typeof candidate.revision !== "number" ||
+        !Number.isSafeInteger(candidate.revision) ||
+        candidate.revision < 1 ||
+        typeof candidate.cueId !== "string" ||
+        (candidate.status !== "pending" && candidate.status !== "consumed" && candidate.status !== "dismissed") ||
+        !Array.isArray(candidate.triggers) ||
+        candidate.triggers.length === 0 ||
+        candidate.triggers.some((trigger) => !CURRENT_TURN_REFLECTION_TRIGGERS.has(trigger)) ||
+        typeof candidate.createdAt !== "string" ||
+        typeof candidate.updatedAt !== "string") {
+        return undefined;
+    }
+    return {
+        version: 1,
+        revision: candidate.revision,
+        cueId: candidate.cueId,
+        status: candidate.status,
+        triggers: [...new Set(candidate.triggers)],
+        createdAt: candidate.createdAt,
+        updatedAt: candidate.updatedAt,
+    };
+}
+function parseOkfRollbackTarget(target) {
+    if (!target)
+        return undefined;
+    const separator = target.indexOf("\0");
+    if (separator <= 0 || separator === target.length - 1)
+        return undefined;
+    const type = target.slice(0, separator);
+    if (!PI_OKF_TYPES.includes(type))
+        return undefined;
+    return { type: type, title: target.slice(separator + 1) };
+}
 export class ReflectionController {
     constructor(deps) {
-        this.pendingTurns = [];
-        this.scheduledDigests = new Set();
-        this.lastScheduledPassAt = 0;
+        this.cueStateCacheInitialized = false;
         this.deps = deps;
+        this.unsubscribeSettingsChanges = deps.getSettingsManager().subscribeChanges(() => {
+            this.synchronizeCurrentTurnCueWithSettings();
+        });
+        this.synchronizeCurrentTurnCueWithSettings();
     }
-    /** Analyze once, schedule bounded background reflection when warranted, and return filtered turn text for sync hooks. */
-    scheduleFromTurn(messages, contextHeadroomPct) {
-        const settings = this.deps.getSettingsManager().getAutoLearnSettings();
-        const analysis = analyzeReflectionTurn(messages, settings.complexTaskToolCalls ?? 12);
-        const enabled = settings.enabled !== false &&
-            settings.reflectionReview !== false &&
-            process.env.PI_NATIVE_REFLECTION !== "0" &&
-            process.env.PI_AUTO_LEARN_CHILD !== "1" &&
-            !this.deps.isChildSession() &&
-            !this.deps.isDisposed();
-        if (!enabled || analysis.trigger === "none" || this.scheduledDigests.has(analysis.digest))
-            return analysis;
-        this.scheduledDigests.add(analysis.digest);
-        while (this.scheduledDigests.size > REFLECTION_DIGEST_HISTORY_SIZE) {
-            const oldest = this.scheduledDigests.values().next().value;
-            if (typeof oldest !== "string")
+    dispose() {
+        this.unsubscribeSettingsChanges();
+    }
+    isAutomaticReflectionEnabled() {
+        const settingsManager = this.deps.getSettingsManager();
+        const settings = resolveAutoLearnSettings(settingsManager.getAutonomySettings().mode, settingsManager.getAutoLearnSettings());
+        return isCurrentSessionReflectionEnabled(settings) && !this.deps.isChildSession() && !this.deps.isDisposed();
+    }
+    /** Latest durable cue snapshot on the active session branch; custom state never enters model context. */
+    getCurrentTurnCueState() {
+        if (this.cueStateCacheInitialized)
+            return this.cueStateCache;
+        const sessionManager = this.deps.getSessionManager();
+        let fromId;
+        while (true) {
+            const entry = sessionManager.getLatestCustomEntryOnBranch(CURRENT_TURN_REFLECTION_STATE_CUSTOM_TYPE, fromId);
+            if (!entry)
                 break;
-            this.scheduledDigests.delete(oldest);
-        }
-        this.pendingTurns.push({ analysis, contextHeadroomPct });
-        let pendingChars = this.pendingTurns.reduce((total, turn) => total + turn.analysis.recentTurnText.length, 0);
-        while (this.pendingTurns.length > 1 && pendingChars > REFLECTION_PENDING_MAX_CHARS) {
-            pendingChars -= this.pendingTurns.shift()?.analysis.recentTurnText.length ?? 0;
+            const state = parseCurrentTurnReflectionCueState(entry.data);
+            if (state) {
+                this.cueStateCache = state;
+                break;
+            }
+            if (!entry.parentId)
+                break;
+            fromId = entry.parentId;
         }
-        this.schedulePendingPass();
-        return analysis;
+        this.cueStateCacheInitialized = true;
+        return this.cueStateCache;
+    }
+    /** Branch/session navigation invalidates the lazy latest-state index; ordinary appends do not. */
+    invalidateCurrentTurnCueStateCache() {
+        this.cueStateCacheInitialized = false;
+        this.cueStateCache = undefined;
+    }
+    persistCurrentTurnCueState(state) {
+        this.deps.getSessionManager().appendCustomEntry(CURRENT_TURN_REFLECTION_STATE_CUSTOM_TYPE, state);
+        this.cueStateCache = state;
+        this.cueStateCacheInitialized = true;
     }
-    schedulePendingPass() {
-        if (this.activeScheduledPass || this.scheduledTimer || this.pendingTurns.length === 0 || this.deps.isDisposed()) {
+    synchronizeCurrentTurnCueWithSettings() {
+        if (this.isAutomaticReflectionEnabled())
             return;
-        }
-        const delay = Math.max(0, REFLECTION_MIN_INTERVAL_MS - (Date.now() - this.lastScheduledPassAt));
-        if (delay > 0) {
-            this.scheduledTimer = setTimeout(() => {
-                this.scheduledTimer = undefined;
-                this.startPendingPass();
-            }, delay);
-            this.scheduledTimer.unref?.();
+        const current = this.getCurrentTurnCueState();
+        if (current?.status !== "pending")
             return;
-        }
-        this.startPendingPass();
+        this.persistCurrentTurnCueState({
+            ...current,
+            revision: current.revision + 1,
+            status: "dismissed",
+            updatedAt: new Date().toISOString(),
+        });
     }
-    startPendingPass() {
-        if (this.activeScheduledPass || this.pendingTurns.length === 0 || this.deps.isDisposed())
-            return;
-        const turns = this.pendingTurns.splice(0);
-        const trigger = turns.reduce((selected, turn) => reflectionTriggerPriority(turn.analysis.trigger) > reflectionTriggerPriority(selected)
-            ? turn.analysis.trigger
-            : selected, "none");
-        const recentTurnText = boundReflectionSemanticText(turns.map((turn) => turn.analysis.recentTurnText).join("\n---\n"), REFLECTION_PENDING_MAX_CHARS);
-        const reportDigest = createHash("sha256")
-            .update(turns.map((turn) => turn.analysis.digest).join("\0"))
-            .digest("hex")
-            .slice(0, 24);
-        const settings = this.deps.getSettingsManager().getAutoLearnSettings();
-        let model;
-        if (settings.model && settings.model !== "active") {
-            const resolved = resolveCliModel({ cliModel: settings.model, modelRegistry: this.deps.getModelRegistry() });
-            if (resolved.model && this.deps.getModelRegistry().hasConfiguredAuth(resolved.model))
-                model = resolved.model;
+    /**
+     * Persist one logical pending cue. Repeated triggers merge into the existing pending snapshot;
+     * they never append competing pending cues or retain raw transcript text.
+     */
+    queueCurrentTurnCue(trigger) {
+        if (!this.isAutomaticReflectionEnabled()) {
+            this.synchronizeCurrentTurnCueWithSettings();
+            return false;
         }
-        const toolCallCount = turns.reduce((total, turn) => total + turn.analysis.toolCallCount, 0);
-        const contextHeadroomPct = Math.min(...turns.map((turn) => turn.contextHeadroomPct));
-        this.lastScheduledPassAt = Date.now();
-        this.activeScheduledPass = (async () => {
-            try {
-                await this.runReflectionPass({
-                    signals: {
-                        trigger,
-                        toolCallCount,
-                        hadCorrection: turns.some((turn) => turn.analysis.hadCorrection),
-                        contextHeadroomPct,
-                        usefulLately: 0,
-                    },
-                    recentTurnText,
-                    reportId: `reflection:${reportDigest}`,
-                    model,
-                    thinkingLevel: settings.thinkingLevel ?? "low",
-                    explicitUserMemoryInstruction: turns.every((turn) => turn.analysis.explicitUserMemoryInstruction),
-                });
-            }
-            catch {
-                // Best-effort background learning must never disrupt the foreground turn.
-            }
-            finally {
-                this.activeScheduledPass = undefined;
-                this.schedulePendingPass();
-            }
-        })();
+        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 next = {
+            version: 1,
+            revision: 1,
+            cueId: randomUUID(),
+            status: "pending",
+            triggers: [trigger],
+            createdAt: updatedAt,
+            updatedAt,
+        };
+        this.persistCurrentTurnCueState(next);
+        return true;
     }
-    cancelScheduled() {
-        if (this.scheduledTimer)
-            clearTimeout(this.scheduledTimer);
-        this.scheduledTimer = undefined;
-        this.pendingTurns.length = 0;
+    /**
+     * Preview one transient provider-only cue. Discarded/replanned previews do nothing; the accepted
+     * provider-plan commit closes exactly the captured cue id + revision.
+     */
+    previewCurrentTurnCue() {
+        const current = this.getCurrentTurnCueState();
+        if (current?.status !== "pending" || !this.isAutomaticReflectionEnabled())
+            return undefined;
+        const cueId = current.cueId;
+        const revision = current.revision;
+        const message = {
+            role: "custom",
+            customType: CURRENT_TURN_REFLECTION_CUSTOM_TYPE,
+            content: `${CURRENT_TURN_REFLECTION_CUE}\n- Pending evidence classes: ${current.triggers.join(", ")}.`,
+            display: false,
+            details: {
+                version: 1,
+                scope: "root-current-turn",
+                automaticProviderRequests: 0,
+                cueId: current.cueId,
+                triggers: current.triggers,
+            },
+            timestamp: Date.now(),
+        };
+        const isCurrent = () => {
+            const latest = this.getCurrentTurnCueState();
+            return (this.isAutomaticReflectionEnabled() &&
+                latest?.status === "pending" &&
+                latest.cueId === cueId &&
+                latest.revision === revision);
+        };
+        return {
+            message,
+            isCurrent,
+            commit: () => {
+                if (!isCurrent())
+                    throw new Error("Reflection cue changed before provider-plan commit");
+                const latest = this.getCurrentTurnCueState();
+                if (!latest)
+                    throw new Error("Reflection cue disappeared before provider-plan commit");
+                const next = {
+                    ...latest,
+                    revision: latest.revision + 1,
+                    status: "consumed",
+                    updatedAt: new Date().toISOString(),
+                };
+                this.persistCurrentTurnCueState(next);
+            },
+        };
     }
-    async waitForActivePass() {
-        while (this.activeScheduledPass)
-            await this.activeScheduledPass;
+    /** Pure completed-turn projection used only by deterministic memory synchronization. */
+    analyzeCompletedTurn(messages) {
+        const settingsManager = this.deps.getSettingsManager();
+        const settings = resolveAutoLearnSettings(settingsManager.getAutonomySettings().mode, settingsManager.getAutoLearnSettings());
+        return analyzeReflectionTurn(messages, settings.complexTaskToolCalls);
     }
     /**
-     * Run an LLM completion fully ISOLATED from the main session — the load-bearing primitive for
-     * reflection and bounded child lanes (adaptive-agent design §6c/§7).
+     * Run an explicit LLM completion fully ISOLATED from the main session for bounded host-owned
+     * consumers. Automatic reflection never reaches this primitive.
      *
      * Isolation invariants (audited by codex): builds fresh context (no main history), defaults to no
      * tools, and passes **no real `sessionId`** — only a deterministic SYNTHETIC cache-affinity key
@@ -151,8 +246,8 @@ export class ReflectionController {
      * and applies a turn bound only when its owner explicitly supplies one. It cannot mutate `agent.state.messages`, append session entries, or touch the
      * foreground tool registry. Mirrors `generateSummary()`'s one-shot mechanics otherwise.
      *
-     * Returns the result even on an error/aborted stop reason (callers — e.g. a background reflection
-     * microtask — decide whether to act); it does not throw on a model-level error.
+     * Returns the result even on an error/aborted stop reason; the explicit caller decides whether to
+     * act, and a model-level error is returned rather than thrown.
      */
     async runIsolatedCompletion(opts) {
         if (opts.maxTurns !== undefined && (!Number.isSafeInteger(opts.maxTurns) || opts.maxTurns <= 0)) {
@@ -358,10 +453,10 @@ export class ReflectionController {
         }
     }
     /**
-     * Native end-of-loop reflection pass (R2). Demand-gates (zero-I/O), and when warranted runs the
-     * {@link ReflectionEngine} via an isolated completion ({@link runIsolatedCompletion}), applies the
-     * resulting memory writes through the bundled `memory` tool, and accounts the reflection's token
-     * cost via the cost-aggregation surface so it stays visible and net-negative-auditable.
+     * Explicit compatibility/application seam for an owner-invoked structured reflection pass. This
+     * method can make an isolated provider request, so automatic current-turn reflection never calls
+     * it. Demand-gates (zero-I/O), applies resulting writes through the bundled `memory` tool, and
+     * accounts the explicitly requested pass through the spawned-usage surface.
      *
      * Returns `null` when the gate skips (or in a child session, which must not learn). The whole pass
      * is best-effort: a model/parse error yields no writes, never throws into the caller.
@@ -392,8 +487,13 @@ export class ReflectionController {
         const result = await new ReflectionEngine().reflect({
             recentTurnText: input.recentTurnText,
             // Read memory FRESH (not the prefix-cache-frozen system-prompt block) so confront-before-write
-            // sees writes made earlier this session.
-            existingMemory: this.deps.getMemoryManager().buildSystemPromptBlockFresh() || "",
+            // sees writes made earlier this session, including bounded structured OKF records.
+            existingMemory: [
+                this.deps.getMemoryManager().buildSystemPromptBlockFresh(),
+                this.deps.getFreshOkfMemoryForReflection(),
+            ]
+                .filter((block) => block.trim().length > 0)
+                .join("\n\n"),
             plan,
             complete,
         });
@@ -418,7 +518,7 @@ export class ReflectionController {
             writeIndex += 1;
             const proposalId = `${input.reportId ?? "reflection"}-w${writeIndex}`;
             const proposal = proposalFromReflectionWrite(write, proposalId);
-            const rollback = rollbackPlanForReflectionWrite(write);
+            const plannedRollback = rollbackPlanForReflectionWrite(write);
             let observations = 1;
             if (policy.enabled) {
                 try {
@@ -523,8 +623,10 @@ export class ReflectionController {
             // throwing. Capture that outcome instead of assuming "decision.kind === apply" means it landed
             // — otherwise a refused write leaves a phantom "apply" audit whose rollback later fails
             // not-found (or, worse, misfires against whatever now occupies that text).
-            const applied = decision.kind === "apply" && !skillPromotionBlock ? await this._applyReflectionWrite(write, signal) : false;
-            const writeFailed = decision.kind === "apply" && !skillPromotionBlock && !applied;
+            const applyResult = decision.kind === "apply" && !skillPromotionBlock
+                ? await this._applyReflectionWrite(write, signal)
+                : { applied: false };
+            const writeFailed = decision.kind === "apply" && !skillPromotionBlock && !applyResult.applied;
             if (decision.kind !== "no-op") {
                 auditSequence += 1;
                 appendLearningAuditSnapshot(this.deps.getSessionManager(), {
@@ -547,7 +649,9 @@ export class ReflectionController {
                     decision,
                     // No rollback plan on a failed apply or a held/proposed promotion — nothing durable
                     // landed in either case, so there is nothing to undo.
-                    rollback: skillPromotionBlock || writeFailed ? undefined : rollback,
+                    rollback: decision.kind === "apply" && !skillPromotionBlock && !writeFailed
+                        ? (applyResult.rollback ?? plannedRollback)
+                        : undefined,
                     createdAt: new Date().toISOString(),
                 });
             }
@@ -590,7 +694,7 @@ export class ReflectionController {
             case "memory_remove": {
                 if (!rollback.target)
                     return { ok: false, reason: "missing_rollback_target" };
-                if (!(await this._applyReflectionWrite({ kind: "memory_remove", target: rollback.target }))) {
+                if (!(await this._applyReflectionWrite({ kind: "memory_remove", target: rollback.target })).applied) {
                     return { ok: false, reason: "rollback_apply_failed" };
                 }
                 break;
@@ -604,7 +708,7 @@ export class ReflectionController {
                     target: rollback.target,
                     text: rollback.previous,
                 });
-                if (!applied)
+                if (!applied.applied)
                     return { ok: false, reason: "rollback_apply_failed" };
                 break;
             }
@@ -616,6 +720,36 @@ export class ReflectionController {
                     section: "MEMORY",
                     text: rollback.previous,
                 });
+                if (!applied.applied)
+                    return { ok: false, reason: "rollback_apply_failed" };
+                break;
+            }
+            case "okf_remove": {
+                const target = parseOkfRollbackTarget(rollback.target);
+                if (!target)
+                    return { ok: false, reason: "missing_rollback_target" };
+                const applied = await this.deps.rollbackStructuredReflectionWrite({
+                    ...target,
+                    expectedDigest: rollback.expectedDigest,
+                    removeRecord: true,
+                });
+                if (!applied)
+                    return { ok: false, reason: "rollback_apply_failed" };
+                break;
+            }
+            case "okf_organize": {
+                if (!rollback.target || rollback.previous === undefined) {
+                    return { ok: false, reason: "missing_rollback_target" };
+                }
+                const target = parseOkfRollbackTarget(rollback.target);
+                if (!target)
+                    return { ok: false, reason: "missing_rollback_target" };
+                const applied = await this.deps.rollbackStructuredReflectionWrite({
+                    ...target,
+                    expectedDigest: rollback.expectedDigest,
+                    sourceText: rollback.previous,
+                    removeRecord: rollback.removeOkf === true,
+                });
                 if (!applied)
                     return { ok: false, reason: "rollback_apply_failed" };
                 break;
@@ -657,7 +791,35 @@ export class ReflectionController {
             const promoted = this._promoteReflectionSkill(write.name, write.description, write.body);
             if (promoted)
                 this.deps.refreshLiveSkills?.();
-            return promoted;
+            return { applied: promoted };
+        }
+        if (write.kind === "okf_add" || write.kind === "okf_organize") {
+            try {
+                const result = await this.deps.applyStructuredReflectionWrite(write, signal);
+                if (!result.applied || result.digest === undefined)
+                    return { applied: false };
+                return {
+                    applied: true,
+                    rollback: write.kind === "okf_add"
+                        ? {
+                            kind: "okf_remove",
+                            target: `${write.type}\0${write.title}`,
+                            expectedDigest: result.digest,
+                            instructions: "Remove only the exact structured OKF record created by this reflection.",
+                        }
+                        : {
+                            kind: "okf_organize",
+                            target: `${write.type}\0${write.title}`,
+                            previous: write.sourceText,
+                            expectedDigest: result.digest,
+                            removeOkf: result.created,
+                            instructions: "Restore the exact hot-memory source first, then remove only the OKF record created by this reflection.",
+                        },
+                };
+            }
+            catch {
+                return { applied: false };
+            }
         }
         const memTool = this.deps
             .getMemoryManager()
@@ -665,7 +827,7 @@ export class ReflectionController {
             .find((t) => t.name === "memory");
         const exec = memTool?.execute;
         if (!exec)
-            return false;
+            return { applied: false };
         const run = (params) => exec("reflection", params, signal, undefined, undefined);
         if (write.kind === "memory_add") {
             try {
@@ -674,11 +836,11 @@ export class ReflectionController {
                     target: write.section === "USER" ? "user" : "memory",
                     content: write.text,
                 });
-                return res?.details?.success === true;
+                return { applied: res?.details?.success === true };
             }
             catch {
                 // best-effort; reflection writes must never throw into the turn loop
-                return false;
+                return { applied: false };
             }
         }
         // replace / remove carry no target file — try MEMORY.md, then USER.md. The memory tool reports
@@ -692,16 +854,16 @@ export class ReflectionController {
                     : { action: "remove", target, oldContent: write.target };
                 const res = await run(params);
                 if (res?.details?.success === true)
-                    return true; // applied
+                    return { applied: true }; // applied
                 if (!/not found/i.test(String(res?.details?.error ?? "")))
-                    return false; // real failure — don't misapply
+                    return { applied: false }; // real failure
                 // substring simply absent from this file — try the next target
             }
             catch {
                 // defensive: if the tool ever does throw, try the next target
             }
         }
-        return false;
+        return { applied: false };
     }
     /**
      * The same skill_audit overlap check the model-invoked `skillify` tool enforces
@@ -716,7 +878,13 @@ export class ReflectionController {
     _checkSkillPromotionOverlap(write) {
         try {
             const cwd = this.deps.getCwd?.() ?? process.cwd();
-            const audit = runSkillAudit(cwd, write);
+            const audit = runSkillAudit(cwd, write, this.deps.getSkillsForAudit?.(), undefined, DEFAULT_BOUNDED_SKILL_AUDIT_LIMITS);
+            if (audit.truncated) {
+                return {
+                    reasonCode: SKILL_AUDIT_UNAVAILABLE_REASON_CODE,
+                    note: "skill overlap audit exceeded its bounded universe; promotion held rather than written unaudited",
+                };
+            }
             const overlap = audit.nearDuplicates.find((d) => d.a === "[draft]" || d.b === "[draft]");
             if (!overlap)
                 return undefined;