@framers/agentos 0.10.22 → 0.10.24

package/dist/cognition/substrate/MetapromptExecutor.js

@@ -13,15 +13,42 @@
  *
  * @module cognitive_substrate/MetapromptExecutor
  */
-import { GMIMood, GMIPrimeState, } from './IGMI.js';
+import { GMIMood, } from './IGMI.js';
 import { GMIEventType } from './GMIEvent.js';
 import { GMIError, GMIErrorCode, createGMIErrorFromError } from '../../core/utils/errors.js';
+/** Longest time {@link MetapromptExecutor.drain} waits by default, in milliseconds. */
+const DEFAULT_DRAIN_TIMEOUT_MS = 5000;
+/**
+ * Longest a queued unit of metaprompt work may run before the queue moves on
+ * without it, in milliseconds. Each metaprompt LLM call also carries it as its
+ * request timeout, so a stalled provider call is normally cut off first.
+ */
+const DEFAULT_RUN_TIMEOUT_MS = 120000;
+/**
+ * Working-memory keys that hold the GMI's own state. A metaprompt changes
+ * mood, user and task context through its update fields, which the GMI
+ * persists under these keys; an imprint that wrote them would bypass that
+ * path (and race it after a deadline) or fire a manual trigger.
+ */
+function isGmiStateKey(key) {
+    return (key === 'currentGmiMood' ||
+        key === 'currentUserContext' ||
+        key === 'currentTaskContext' ||
+        key === 'gmi_sentiment_history' ||
+        key.startsWith('manual_trigger_') ||
+        key.startsWith('metaprompt_turn_counter_'));
+}
 /**
  * Handles metaprompt trigger checking, execution, and state application.
  *
- * Owns the `metaPromptTriggerCounters` map and the `selfReflectionIntervalTurns`
- * / `turnsSinceLastReflection` counters (though the latter are not currently
- * incremented by the executor itself — the GMI's turn loop still manages them).
+ * The metaprompts that fire on one turn are queued as one background batch.
+ * Batches and manual self-reflection cycles run one at a time, in the order
+ * they were queued, so two of them never race on the mood and context they
+ * update, and the turn that triggered a batch does not wait for its LLM calls.
+ * Metaprompt work never changes the GMI's lifecycle state; that state belongs
+ * to the turn loop.
+ *
+ * Owns the per-metaprompt turn counters used by `turn_interval` triggers.
  *
  * All GMI state mutations flow back through callbacks so the executor never
  * directly mutates GMI internals.
@@ -36,6 +63,29 @@ export class MetapromptExecutor {
         this.config = config;
         /** Per-metaprompt turn counters for `turn_interval` triggers. */
         this.metaPromptTriggerCounters = new Map();
+        /**
+         * Tail of the metaprompt work queue. Every batch and self-reflection cycle
+         * chains onto it, so only one runs at a time. It never rejects.
+         */
+        this.queueTail = Promise.resolve();
+        /** Number of batches and self-reflection cycles that are queued or running. */
+        this.inFlight = 0;
+        /** Metaprompt ids already reported as unable to fire, so each is reported once. */
+        this.invalidTriggerWarnings = new Set();
+        /** Set by {@link MetapromptExecutor.close}: no further work starts, and late results are discarded. */
+        this.closed = false;
+        /** User turns counted so far, to tell whether a queued event batch still belongs to the latest turn. */
+        this.countedTurns = 0;
+        /** Deadline for each queued unit of work, in milliseconds (see DEFAULT_RUN_TIMEOUT_MS). */
+        this.runTimeoutMs = DEFAULT_RUN_TIMEOUT_MS;
+        /**
+         * The last memory imprint write queued for each key. Writes to one key run
+         * in the order they were made: a unit that passes its deadline mid-write
+         * releases the queue, but a later unit's write to the same key waits for
+         * that write, so it is never overwritten by it. Writes to other keys do
+         * not wait, so one stalled write cannot hold back the rest.
+         */
+        this.writeTails = new Map();
         /** Turns elapsed since the last self-reflection. */
         this.turnsSinceLastReflection = 0;
         this.selfReflectionIntervalTurns = 5; // Will be overridden by initialize
@@ -44,62 +94,199 @@ export class MetapromptExecutor {
     // Public API
     // ---------------------------------------------------------------------------
     /**
-     * Checks all metaprompt triggers and executes any that fire.
+     * Checks all metaprompt triggers and queues any that fire.
      *
      * Iterates through the persona's metaprompt definitions, evaluating each
      * trigger type:
-     * - `turn_interval`: increments a counter and fires when the interval is reached.
+     * - `turn_interval`: counts user turns and fires on every `intervalTurns`-th
+     *   one, so an interval of N fires on user turns N, 2N, 3N and so on.
      * - `event_based`: fires if the event type is in the pending events set.
      * - `manual`: fires if a flag was set in working memory.
      *
-     * Triggered metaprompts are executed in parallel via `Promise.allSettled`.
-     * Execution errors are logged but do not block the turn.
+     * The metaprompts that fire are queued as one background batch and this
+     * method returns without waiting for their LLM calls. Batches run one at a
+     * time; inside a batch the metaprompts run in parallel via
+     * `Promise.allSettled`. Execution errors are logged to the reasoning trace
+     * and never reach the turn.
      *
      * @param turnId - The current turn identifier (for tracing).
+     * @param options - `countTurn` says whether this turn counts toward
+     *   `turn_interval` triggers. Pass `false` for turns that are not user
+     *   messages, such as tool continuations and system turns. Defaults to `true`.
      */
-    async checkAndTriggerMetaprompts(turnId) {
+    async checkAndTriggerMetaprompts(turnId, options = {}) {
         const persona = this.config.getPersona();
         if (!persona.metaPrompts || persona.metaPrompts.length === 0) {
             return;
         }
+        const countTurn = options.countTurn !== false;
+        if (countTurn)
+            this.countedTurns += 1;
+        const queuedAtTurn = this.countedTurns;
         const triggeredMetaPrompts = [];
         const pendingEvents = this.config.getPendingEvents();
         for (const metaPrompt of persona.metaPrompts) {
-            if (!metaPrompt.trigger)
+            const trigger = metaPrompt.trigger;
+            if (!trigger)
                 continue;
-            if (metaPrompt.trigger.type === 'turn_interval') {
-                const counter = await this.getMetapromptTurnCounter(metaPrompt.id);
-                if (counter >= metaPrompt.trigger.intervalTurns) {
-                    triggeredMetaPrompts.push(metaPrompt);
-                    await this.resetMetapromptTurnCounter(metaPrompt.id);
+            switch (trigger.type) {
+                case 'turn_interval':
+                    if (countTurn && (await this.advanceTurnInterval(metaPrompt, trigger.intervalTurns))) {
+                        triggeredMetaPrompts.push(metaPrompt);
+                    }
+                    break;
+                case 'event_based': {
+                    const eventName = trigger.eventName;
+                    if (pendingEvents.has(eventName)) {
+                        triggeredMetaPrompts.push(metaPrompt);
+                        pendingEvents.delete(eventName);
+                    }
+                    break;
                 }
-                else {
-                    await this.incrementMetapromptTurnCounter(metaPrompt.id);
+                case 'manual': {
+                    const manualFlag = await this.config.workingMemory.get(`manual_trigger_${metaPrompt.id}`);
+                    if (manualFlag) {
+                        triggeredMetaPrompts.push(metaPrompt);
+                        await this.config.workingMemory.delete(`manual_trigger_${metaPrompt.id}`);
+                    }
+                    break;
                 }
-            }
-            else if (metaPrompt.trigger.type === 'event_based') {
-                const eventName = metaPrompt.trigger.eventName;
-                if (pendingEvents.has(eventName)) {
-                    triggeredMetaPrompts.push(metaPrompt);
-                    pendingEvents.delete(eventName);
-                }
-            }
-            else if (metaPrompt.trigger.type === 'manual') {
-                const manualFlag = await this.config.workingMemory.get(`manual_trigger_${metaPrompt.id}`);
-                if (manualFlag) {
-                    triggeredMetaPrompts.push(metaPrompt);
-                    await this.config.workingMemory.delete(`manual_trigger_${metaPrompt.id}`);
+                default: {
+                    // Persona JSON is cast rather than type-checked, so other trigger
+                    // types reach this point at runtime. Nothing ever fires them.
+                    const unsupportedType = String(trigger.type);
+                    this.warnInvalidTrigger(metaPrompt, `trigger type '${unsupportedType}' is not supported (expected turn_interval, event_based or manual)`);
                 }
             }
         }
         if (triggeredMetaPrompts.length > 0) {
             this.config.addTraceEntry('SELF_REFLECTION_TRIGGERED', `${triggeredMetaPrompts.length} metaprompt(s) triggered`, { ids: triggeredMetaPrompts.map((m) => m.id), turnId });
-            this.executeMetaprompts(triggeredMetaPrompts).catch((err) => {
-                console.error(`GMI (ID: ${this.config.getGmiId()}): Metaprompt execution error:`, err);
-                this.config.addTraceEntry('ERROR', 'Metaprompt execution failed', { error: err.message });
+            // Queue the batch and return: the turn does not wait for metaprompt LLM calls.
+            void this.enqueue('Metaprompt execution', (run) => {
+                // An event-based metaprompt reacts to the turn that raised the event
+                // (a frustrated or confused message). If a newer user turn has been
+                // counted while this batch waited behind a slow one, that evidence is
+                // gone, so it is dropped rather than applied to a later mood.
+                const current = this.countedTurns === queuedAtTurn;
+                const runnable = current
+                    ? triggeredMetaPrompts
+                    : triggeredMetaPrompts.filter((mp) => mp.trigger?.type !== 'event_based');
+                if (runnable.length < triggeredMetaPrompts.length) {
+                    this.config.addTraceEntry('DEBUG', 'Skipped event-based metaprompts whose triggering turn has passed.', {
+                        ids: triggeredMetaPrompts.filter((mp) => !runnable.includes(mp)).map((mp) => mp.id),
+                    });
+                }
+                return this.executeMetaprompts(runnable, run);
             });
         }
     }
+    /**
+     * Reports whether a metaprompt batch or self-reflection cycle is queued or running.
+     *
+     * @returns `true` while any metaprompt work is pending.
+     */
+    isRunning() {
+        // A unit released at its deadline can leave a memory write running.
+        return this.inFlight > 0 || this.writeTails.size > 0;
+    }
+    /**
+     * Resolves once every queued metaprompt batch and self-reflection cycle has
+     * settled, including work queued while waiting. Never rejects.
+     */
+    async whenIdle() {
+        let tail;
+        do {
+            tail = this.queueTail;
+            await tail;
+            // Memory writes a unit started before its deadline outlive the unit.
+            await Promise.all(this.writeTails.values());
+        } while (tail !== this.queueTail || this.writeTails.size > 0);
+    }
+    /**
+     * Waits for queued and running metaprompt work to settle, for at most
+     * `timeoutMs`. The GMI calls this during shutdown so that a batch still in
+     * flight can store its updates before working memory closes, while a
+     * provider call that never settles cannot hold shutdown open.
+     *
+     * @param timeoutMs - Longest wait, in milliseconds.
+     * @returns `true` when all work settled, `false` when the wait timed out.
+     */
+    async drain(timeoutMs = DEFAULT_DRAIN_TIMEOUT_MS) {
+        if (!this.isRunning())
+            return true;
+        let resolveTimedOut;
+        const timedOut = new Promise((resolve) => {
+            resolveTimedOut = resolve;
+        });
+        const timer = setTimeout(() => resolveTimedOut(false), timeoutMs);
+        // Waiting on a hung provider call must not keep the process alive.
+        timer.unref?.();
+        try {
+            return await Promise.race([this.whenIdle().then(() => true), timedOut]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Stops the queue for good, as the GMI shuts down: work that has not started
+     * is skipped, and results of work still running are discarded instead of
+     * applied to memories that are closing.
+     */
+    close() {
+        this.closed = true;
+    }
+    /**
+     * Chains one unit of metaprompt work onto the queue, so it starts only after
+     * all earlier work has settled. A failure is logged to the console and the
+     * reasoning trace, and the queue moves on to the next unit.
+     *
+     * @param label - Name used in failure logs (for example 'Metaprompt execution').
+     * @param task - The work to run.
+     * @returns A promise that settles when this unit finishes. It never rejects.
+     */
+    enqueue(label, task) {
+        this.inFlight += 1;
+        let overdue = false;
+        const run = { isStale: () => overdue || this.closed };
+        const unit = async () => {
+            if (this.closed)
+                return;
+            // A provider call that never settles would hold the queue forever;
+            // past the deadline the queue moves on, and the unit's late results
+            // are discarded (run.isStale()).
+            const timeoutMs = this.runTimeoutMs;
+            let timer;
+            const deadline = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), timeoutMs);
+                timer.unref?.();
+            });
+            try {
+                const outcome = await Promise.race([task(run).then(() => 'done'), deadline]);
+                if (outcome === 'timeout') {
+                    overdue = true;
+                    this.config.addTraceEntry('WARNING', `${label} did not finish within ${timeoutMs}ms; its results will be discarded.`);
+                }
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+        const settled = this.queueTail
+            .then(unit)
+            .catch((error) => {
+            console.error(`GMI (ID: ${this.config.getGmiId()}): ${label} failed:`, error);
+            this.config.addTraceEntry('ERROR', `${label} failed`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => {
+            this.inFlight -= 1;
+        });
+        this.queueTail = settled;
+        return settled;
+    }
     /**
      * Gets the turn counter for a specific metaprompt.
      *
@@ -124,9 +311,7 @@ export class MetapromptExecutor {
      */
     async incrementMetapromptTurnCounter(metapromptId) {
         const current = await this.getMetapromptTurnCounter(metapromptId);
-        const newValue = current + 1;
-        this.metaPromptTriggerCounters.set(metapromptId, newValue);
-        await this.config.workingMemory.set(`metaprompt_turn_counter_${metapromptId}`, newValue);
+        await this.setMetapromptTurnCounter(metapromptId, current + 1);
     }
     /**
      * Resets the turn counter for a specific metaprompt to zero.
@@ -134,25 +319,85 @@ export class MetapromptExecutor {
      * @param metapromptId - The metaprompt identifier.
      */
     async resetMetapromptTurnCounter(metapromptId) {
-        this.metaPromptTriggerCounters.set(metapromptId, 0);
-        await this.config.workingMemory.set(`metaprompt_turn_counter_${metapromptId}`, 0);
+        await this.setMetapromptTurnCounter(metapromptId, 0);
     }
     /**
-     * Executes multiple metaprompts in parallel using `Promise.allSettled`.
+     * Sets the turn counter for a specific metaprompt, in memory and in working
+     * memory, where it survives across GMI instances.
      *
-     * Transitions the GMI to REFLECTING state during execution, restoring the
-     * previous state afterwards.
+     * @param metapromptId - The metaprompt identifier.
+     * @param value - The number of counted user turns since the metaprompt last fired.
+     */
+    async setMetapromptTurnCounter(metapromptId, value) {
+        this.metaPromptTriggerCounters.set(metapromptId, value);
+        await this.config.workingMemory.set(`metaprompt_turn_counter_${metapromptId}`, value);
+    }
+    /**
+     * Counts one user turn toward a `turn_interval` metaprompt and reports
+     * whether the metaprompt fires on it.
+     *
+     * The counter holds the user turns counted since the metaprompt last fired.
+     * It is incremented first, so an interval of N fires on user turns N, 2N,
+     * 3N and so on, and it resets to zero when the metaprompt fires. A counter
+     * already above the interval fires on the next counted turn.
+     *
+     * Persona JSON is not type-checked, so the interval is validated here: a
+     * value that is not a finite number of at least 1 never fires and is
+     * reported once through `warnInvalidTrigger`.
+     *
+     * @param metaPrompt - The metaprompt whose counter advances.
+     * @param intervalTurns - The trigger's `intervalTurns`, as read from the persona.
+     * @returns `true` when the metaprompt fires on this turn.
+     */
+    async advanceTurnInterval(metaPrompt, intervalTurns) {
+        if (typeof intervalTurns !== 'number' || !Number.isFinite(intervalTurns) || intervalTurns < 1) {
+            this.warnInvalidTrigger(metaPrompt, `intervalTurns must be a number >= 1 (got ${String(intervalTurns)})`);
+            return false;
+        }
+        const counted = (await this.getMetapromptTurnCounter(metaPrompt.id)) + 1;
+        if (counted >= Math.floor(intervalTurns)) {
+            await this.resetMetapromptTurnCounter(metaPrompt.id);
+            return true;
+        }
+        await this.setMetapromptTurnCounter(metaPrompt.id, counted);
+        return false;
+    }
+    /**
+     * Reports a metaprompt whose trigger can never fire. Each metaprompt id is
+     * reported once per executor, with one WARNING trace entry and one console
+     * warning, so a misconfigured persona does not flood the trace every turn.
+     *
+     * @param metaPrompt - The metaprompt that will not run.
+     * @param reason - Why its trigger cannot fire.
+     */
+    warnInvalidTrigger(metaPrompt, reason) {
+        if (this.invalidTriggerWarnings.has(metaPrompt.id))
+            return;
+        this.invalidTriggerWarnings.add(metaPrompt.id);
+        const message = `Metaprompt '${metaPrompt.id}' will not run: ${reason}.`;
+        console.warn(`GMI (ID: ${this.config.getGmiId()}): ${message}`);
+        this.config.addTraceEntry('WARNING', message, {
+            metapromptId: metaPrompt.id,
+            trigger: metaPrompt.trigger,
+        });
+    }
+    /**
+     * Executes one batch of metaprompts in parallel using `Promise.allSettled`.
+     *
+     * A failed metaprompt is recorded as an ERROR trace entry and does not stop
+     * the others. The batch never changes the GMI's lifecycle state: it runs in
+     * the background, so the turn that triggered it may have finished and a
+     * later turn may be in progress. {@link MetapromptExecutor.checkAndTriggerMetaprompts}
+     * queues batches so that they run one at a time.
      *
      * @param metaPrompts - The metaprompt definitions to execute.
      */
-    async executeMetaprompts(metaPrompts) {
+    async executeMetaprompts(metaPrompts, run) {
         if (metaPrompts.length === 0)
             return;
-        const previousState = this.config.getState();
-        this.config.setState(GMIPrimeState.REFLECTING);
         this.config.addTraceEntry('SELF_REFLECTION_START', `Executing ${metaPrompts.length} metaprompt(s)`, { ids: metaPrompts.map((m) => m.id) });
         try {
-            const results = await Promise.allSettled(metaPrompts.map((mp) => this.executeMetapromptHandler(mp)));
+            const results = await Promise.allSettled(metaPrompts.map((mp) => this.executeMetapromptHandler(mp, run)));
             results.forEach((result, idx) => {
                 if (result.status === 'rejected') {
                     this.config.addTraceEntry('ERROR', `Metaprompt '${metaPrompts[idx].id}' failed: ${result.reason}`, { error: result.reason });
@@ -164,11 +409,6 @@ export class MetapromptExecutor {
             this.config.addTraceEntry('ERROR', gmiError.message, gmiError.toPlainObject());
         }
         finally {
-            const disallowedStates = new Set([
-                GMIPrimeState.IDLE,
-                GMIPrimeState.INITIALIZING,
-            ]);
-            this.config.setState(disallowedStates.has(previousState) ? GMIPrimeState.READY : previousState);
             this.config.addTraceEntry('SELF_REFLECTION_COMPLETE', 'Metaprompt execution cycle complete');
         }
     }
@@ -180,22 +420,22 @@ export class MetapromptExecutor {
      *
      * @param metaPrompt - The metaprompt definition to execute.
      */
-    async executeMetapromptHandler(metaPrompt) {
+    async executeMetapromptHandler(metaPrompt, run) {
         switch (metaPrompt.id) {
             case 'gmi_self_trait_adjustment':
-                return this.handleTraitAdjustment(metaPrompt);
+                return this.handleTraitAdjustment(metaPrompt, run);
             case 'gmi_frustration_recovery':
-                return this.handleFrustrationRecovery(metaPrompt);
+                return this.handleFrustrationRecovery(metaPrompt, run);
             case 'gmi_confusion_clarification':
-                return this.handleConfusionClarification(metaPrompt);
+                return this.handleConfusionClarification(metaPrompt, run);
             case 'gmi_satisfaction_reinforcement':
-                return this.handleSatisfactionReinforcement(metaPrompt);
+                return this.handleSatisfactionReinforcement(metaPrompt, run);
             case 'gmi_error_recovery':
-                return this.handleErrorRecovery(metaPrompt);
+                return this.handleErrorRecovery(metaPrompt, run);
             case 'gmi_engagement_boost':
-                return this.handleEngagementBoost(metaPrompt);
+                return this.handleEngagementBoost(metaPrompt, run);
             default:
-                return this.handleGenericMetaprompt(metaPrompt);
+                return this.handleGenericMetaprompt(metaPrompt, run);
         }
     }
     /**
@@ -206,7 +446,7 @@ export class MetapromptExecutor {
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleTraitAdjustment(metaPrompt) {
+    async handleTraitAdjustment(metaPrompt, run) {
         const evidenceHistory = this.config.getConversationHistory().slice(-10);
         const evidenceTrace = this.config.getReasoningTraceEntries().slice(-20);
         const evidence = {
@@ -222,15 +462,15 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Handler for the frustration recovery metaprompt.
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleFrustrationRecovery(metaPrompt) {
+    async handleFrustrationRecovery(metaPrompt, run) {
         const sentimentHistory = await this.config.workingMemory.get('gmi_sentiment_history');
         const recentErrors = this.config.getReasoningTraceEntries()
             .slice(-10)
@@ -245,15 +485,15 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Handler for the confusion clarification metaprompt.
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleConfusionClarification(metaPrompt) {
+    async handleConfusionClarification(metaPrompt, run) {
         const sentimentHistory = await this.config.workingMemory.get('gmi_sentiment_history');
         const lastConfusionEvent = this.config.getEventHistory()
             .slice()
@@ -270,15 +510,15 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Handler for the satisfaction reinforcement metaprompt.
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleSatisfactionReinforcement(metaPrompt) {
+    async handleSatisfactionReinforcement(metaPrompt, run) {
         const sentimentHistory = await this.config.workingMemory.get('gmi_sentiment_history');
         const variables = {
             current_sentiment: this.config.getUserContext().currentSentiment || 'positive',
@@ -289,15 +529,15 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Handler for the error recovery metaprompt.
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleErrorRecovery(metaPrompt) {
+    async handleErrorRecovery(metaPrompt, run) {
         const recentErrors = this.config.getReasoningTraceEntries()
             .slice(-10)
             .filter((e) => e.type === 'ERROR');
@@ -308,15 +548,15 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Handler for the engagement boost metaprompt.
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleEngagementBoost(metaPrompt) {
+    async handleEngagementBoost(metaPrompt, run) {
         const sentimentHistory = await this.config.workingMemory.get('gmi_sentiment_history');
         const variables = {
             consecutive_neutral: (sentimentHistory?.consecutiveConfusion || 4).toString(),
@@ -325,8 +565,8 @@ export class MetapromptExecutor {
             user_skill: this.config.getUserContext().skillLevel || 'unknown',
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Generic handler for custom metaprompts that don't have a dedicated handler.
@@ -335,7 +575,7 @@ export class MetapromptExecutor {
      *
      * @param metaPrompt - The metaprompt definition.
      */
-    async handleGenericMetaprompt(metaPrompt) {
+    async handleGenericMetaprompt(metaPrompt, run) {
         const variables = {
             recent_conversation: JSON.stringify(this.config.getConversationHistory().slice(-5)),
             recent_reasoning: JSON.stringify(this.config.getReasoningTraceEntries().slice(-10)),
@@ -344,22 +584,24 @@ export class MetapromptExecutor {
             task_complexity: this.config.getTaskContext().complexity || 'unknown',
             current_sentiment: this.config.getUserContext().currentSentiment || 'neutral',
         };
-        const response = await this.executeMetapromptWithVariables(metaPrompt, variables);
-        await this.applyMetapromptUpdates(response, metaPrompt.id);
+        const response = await this.executeMetapromptWithVariables(metaPrompt, variables, run);
+        await this.applyMetapromptUpdates(response, metaPrompt.id, run);
     }
     /**
      * Executes a metaprompt template with variable substitution and LLM call.
      *
      * 1. Extracts the template string from the metaprompt definition.
      * 2. Substitutes `{{variable}}` placeholders with provided values.
-     * 3. Calls the LLM with JSON response format.
-     * 4. Parses the JSON response with LLM-based recovery via IUtilityAI.
+     * 3. Resolves the model and provider: the metaprompt's own, then the
+     *    persona defaults, then the GMI defaults.
+     * 4. Calls the LLM with JSON response format.
+     * 5. Parses the JSON response with LLM-based recovery via IUtilityAI.
      *
      * @param metaPrompt - The metaprompt definition.
      * @param variables - Key-value pairs to substitute into the template.
      * @returns The parsed JSON response from the LLM.
      */
-    async executeMetapromptWithVariables(metaPrompt, variables) {
+    async executeMetapromptWithVariables(metaPrompt, variables, run) {
         let template;
         if (typeof metaPrompt.promptTemplate === 'string') {
             template = metaPrompt.promptTemplate;
@@ -371,27 +613,39 @@ export class MetapromptExecutor {
         for (const [key, value] of Object.entries(variables)) {
             finalPrompt = finalPrompt.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
         }
-        const persona = this.config.getPersona();
-        const modelId = metaPrompt.modelId || persona.defaultModelId;
-        const providerId = metaPrompt.providerId || persona.defaultProviderId;
-        if (!modelId || !providerId) {
-            throw new GMIError('No model or provider specified for metaprompt', GMIErrorCode.CONFIGURATION_ERROR);
-        }
+        // Same resolution as the self-reflection path: the metaprompt's own model
+        // and provider, then the persona defaults, then the GMI's configured
+        // defaults. Throws a CONFIGURATION_ERROR GMIError when nothing resolves.
+        const { modelId, providerId } = this.config.getModelAndProvider(metaPrompt.modelId, metaPrompt.providerId);
         this.config.addTraceEntry('DEBUG', `Executing metaprompt '${metaPrompt.id}'`, { modelId, providerId });
         const completionOptions = {
             temperature: metaPrompt.temperature ?? 0.3,
             maxTokens: metaPrompt.maxOutputTokens ?? 512,
             responseFormat: { type: 'json_object' },
+            // Bounds a stalled provider call before the queue's own deadline does.
+            requestTimeout: this.runTimeoutMs,
         };
         const provider = this.config.llmProviderManager.getProvider(providerId);
         if (!provider) {
             throw new GMIError(`Provider '${providerId}' not found for metaprompt '${metaPrompt.id}'.`, GMIErrorCode.LLM_PROVIDER_UNAVAILABLE);
         }
+        // A run can go stale while its handler awaits memory reads; it then
+        // starts no provider call whose answer would be discarded.
+        if (run?.isStale()) {
+            this.config.addTraceEntry('WARNING', `Discarded late results of metaprompt '${metaPrompt.id}'.`);
+            return null;
+        }
         const result = await provider.generateCompletion(modelId, [{ role: 'user', content: finalPrompt }], completionOptions);
         const responseContent = result.choices?.[0]?.message?.content;
         if (!responseContent || typeof responseContent !== 'string') {
             throw new GMIError(`Metaprompt '${metaPrompt.id}' returned no valid content.`, GMIErrorCode.LLM_PROVIDER_ERROR, { response: result });
         }
+        // A run that went stale while the provider answered is discarded anyway,
+        // so no JSON repair call is made on its behalf.
+        if (run?.isStale()) {
+            this.config.addTraceEntry('WARNING', `Discarded late results of metaprompt '${metaPrompt.id}'.`);
+            return null;
+        }
         const parseOptions = {
             attemptFixWithLLM: true,
             llmModelIdForFix: modelId,
@@ -408,10 +662,20 @@ export class MetapromptExecutor {
      *
      * @param updates - The parsed updates from the metaprompt LLM response.
      * @param metapromptId - The ID of the metaprompt that produced these updates.
+     * @param run - The queued unit applying them; once it is stale, nothing
+     *   more is applied.
+     * @returns Keys of the memory imprints stored.
      */
-    async applyMetapromptUpdates(updates, metapromptId) {
+    async applyMetapromptUpdates(updates, metapromptId, run) {
+        const storedImprintKeys = [];
         if (!updates)
-            return;
+            return storedImprintKeys;
+        if (run?.isStale()) {
+            // The queue moved on without this unit, or the GMI shut down: its
+            // results would land on state that no longer matches its evidence.
+            this.config.addTraceEntry('WARNING', `Discarded late results of metaprompt '${metapromptId}'.`);
+            return storedImprintKeys;
+        }
         let stateChanged = false;
         // Mood update — GMIMood enum values are lowercase (e.g., 'focused'),
         // but LLM responses may return either case. Normalize to lowercase for comparison.
@@ -440,13 +704,27 @@ export class MetapromptExecutor {
         // Memory imprints
         if (updates.newMemoryImprints && Array.isArray(updates.newMemoryImprints)) {
             for (const imprint of updates.newMemoryImprints) {
+                // A write can outlast the run's deadline. Once the queue has moved
+                // on or the GMI has shut down, the remaining imprints would overwrite
+                // newer values or reach a closed memory, so they are dropped.
+                if (run?.isStale()) {
+                    this.config.addTraceEntry('WARNING', `Discarded late results of metaprompt '${metapromptId}'.`);
+                    break;
+                }
+                if (imprint.key && isGmiStateKey(imprint.key)) {
+                    this.config.addTraceEntry('WARNING', `Skipped memory imprint '${imprint.key}' from metaprompt '${metapromptId}': the key holds GMI state.`);
+                    continue;
+                }
                 if (imprint.key) {
-                    await this.config.workingMemory.set(imprint.key, imprint.value);
+                    const stored = await this.writeInOrder(run, imprint.key, () => this.config.workingMemory.set(imprint.key, imprint.value));
+                    if (!stored) {
+                        this.config.addTraceEntry('WARNING', `Discarded late results of metaprompt '${metapromptId}'.`);
+                        break;
+                    }
+                    storedImprintKeys.push(imprint.key);
+                    stateChanged = true;
                 }
             }
-            if (updates.newMemoryImprints.length > 0) {
-                stateChanged = true;
-            }
         }
         // Log state change
         if (stateChanged) {
@@ -457,13 +735,43 @@ export class MetapromptExecutor {
                 rationale: updates.adjustmentRationale || updates.recoveryStrategy || updates.clarificationStrategy || updates.engagementStrategy || updates.mitigationStrategy,
             });
         }
+        return storedImprintKeys;
+    }
+    /**
+     * Runs one memory write after every write to the same key queued before
+     * it, unless `run` has gone stale by the time its turn comes.
+     *
+     * @param run The unit making the write.
+     * @param key The working-memory key written.
+     * @param write The write itself.
+     * @returns Whether the write ran.
+     */
+    writeInOrder(run, key, write) {
+        const previous = this.writeTails.get(key) ?? Promise.resolve();
+        const result = previous.then(async () => {
+            if (run?.isStale())
+                return false;
+            await write();
+            return true;
+        });
+        const tail = result.then(() => undefined, () => undefined);
+        this.writeTails.set(key, tail);
+        // Forget the key once its last queued write settles.
+        void tail.then(() => {
+            if (this.writeTails.get(key) === tail)
+                this.writeTails.delete(key);
+        });
+        return result;
     }
     /**
      * Triggers and processes a full self-reflection cycle using the
      * `gmi_self_trait_adjustment` metaprompt.
      *
-     * Performs the same work as `handleTraitAdjustment` plus guard checks
-     * (already reflecting, no metaprompt defined) and explicit state management.
+     * Performs the same work as `handleTraitAdjustment`, behind two guards: the
+     * cycle is skipped when the persona defines no such metaprompt, and when a
+     * metaprompt batch or another cycle is already queued or running. The cycle
+     * runs on the metaprompt queue and never changes the GMI's lifecycle state.
+     * The returned promise settles when the cycle has finished.
      */
     async triggerAndProcessSelfReflection() {
         const persona = this.config.getPersona();
@@ -472,12 +780,20 @@ export class MetapromptExecutor {
             this.config.addTraceEntry('SELF_REFLECTION_SKIPPED', "Self-reflection disabled or no 'gmi_self_trait_adjustment' meta-prompt.");
             return;
         }
-        if (this.config.getState() === GMIPrimeState.REFLECTING) {
+        if (this.isRunning()) {
             this.config.addTraceEntry('SELF_REFLECTION_SKIPPED', 'Self-reflection already in progress.');
             return;
         }
-        const previousState = this.config.getState();
-        this.config.setState(GMIPrimeState.REFLECTING);
+        await this.enqueue('Self-reflection', (run) => this.runSelfReflectionCycle(reflectionMetaPromptDef, run));
+    }
+    /**
+     * Runs one self-reflection cycle for the `gmi_self_trait_adjustment`
+     * metaprompt: gathers evidence, calls the LLM, and applies the parsed
+     * updates. Errors are recorded in the reasoning trace and not rethrown.
+     *
+     * @param reflectionMetaPromptDef - The `gmi_self_trait_adjustment` definition.
+     */
+    async runSelfReflectionCycle(reflectionMetaPromptDef, run) {
         this.config.addTraceEntry('SELF_REFLECTION_START', 'Starting self-reflection cycle.');
         try {
             const evidence = {
@@ -505,16 +821,27 @@ export class MetapromptExecutor {
             if (!provider) {
                 throw new GMIError(`Provider '${providerId}' not found for self-reflection.`, GMIErrorCode.LLM_PROVIDER_UNAVAILABLE);
             }
+            if (run?.isStale()) {
+                this.config.addTraceEntry('WARNING', "Discarded late results of metaprompt 'gmi_self_trait_adjustment'.");
+                return;
+            }
             const llmResponse = await provider.generateCompletion(modelId, [{ role: 'user', content: metaPromptText }], {
                 maxTokens: reflectionMetaPromptDef.maxOutputTokens || 512,
                 temperature: reflectionMetaPromptDef.temperature || 0.3,
                 responseFormat: { type: 'json_object' },
+                requestTimeout: this.runTimeoutMs,
             });
             const responseContent = llmResponse.choices?.[0]?.message?.content;
             if (!responseContent || typeof responseContent !== 'string') {
                 throw new GMIError('Self-reflection LLM call returned no valid content.', GMIErrorCode.LLM_PROVIDER_ERROR, { response: llmResponse });
             }
             this.config.addTraceEntry('SELF_REFLECTION_DETAIL', 'LLM response for reflection received.', { preview: responseContent.substring(0, 100) });
+            // A cycle that went stale while the provider answered is discarded
+            // anyway, so no JSON repair call is made on its behalf.
+            if (run?.isStale()) {
+                this.config.addTraceEntry('WARNING', "Discarded late results of metaprompt 'gmi_self_trait_adjustment'.");
+                return;
+            }
             const parseOptions = {
                 attemptFixWithLLM: true,
                 llmModelIdForFix: reflectionMetaPromptDef.modelId || modelId,
@@ -526,10 +853,11 @@ export class MetapromptExecutor {
             }
             this.config.addTraceEntry('SELF_REFLECTION_DETAIL', 'Parsed trait update suggestions.', { suggestions: parsedUpdates });
             // Apply updates via callbacks
-            await this.applyMetapromptUpdates(parsedUpdates, 'gmi_self_trait_adjustment');
-            // Handle memory imprints specifically for the trace
-            if (parsedUpdates.newMemoryImprints && parsedUpdates.newMemoryImprints.length > 0) {
-                this.config.addTraceEntry('STATE_CHANGE', 'New memory imprints added from self-reflection.', { imprints: parsedUpdates.newMemoryImprints.map((i) => i.key) });
+            const storedImprintKeys = await this.applyMetapromptUpdates(parsedUpdates, 'gmi_self_trait_adjustment', run);
+            // Trace only the imprints that were stored: a late or stale run
+            // stores none, and later reflections read this trace as evidence.
+            if (storedImprintKeys.length > 0) {
+                this.config.addTraceEntry('STATE_CHANGE', 'New memory imprints added from self-reflection.', { imprints: storedImprintKeys });
             }
             if (parsedUpdates.adjustmentRationale) {
                 this.config.addTraceEntry('SELF_REFLECTION_DETAIL', 'Self-reflection rationale recorded.', { rationale: parsedUpdates.adjustmentRationale });
@@ -541,11 +869,6 @@ export class MetapromptExecutor {
             console.error(`GMI (ID: ${this.config.getGmiId()}) self-reflection error:`, gmiError);
         }
         finally {
-            const disallowedStates = new Set([
-                GMIPrimeState.IDLE,
-                GMIPrimeState.INITIALIZING,
-            ]);
-            this.config.setState(disallowedStates.has(previousState) ? GMIPrimeState.READY : previousState);
             this.config.addTraceEntry('SELF_REFLECTION_COMPLETE', 'Self-reflection cycle finished.');
         }
     }