psyche-ai 9.2.4 → 9.2.5

package/dist/adapters/vercel-ai.d.ts

@@ -49,7 +49,7 @@ export interface PsycheMiddlewareOptions {
  * for await (const chunk of stream.textStream) { process.stdout.write(chunk); }
  * ```
  */
-export declare function psycheMiddleware(engine: PsycheEngine, opts?: PsycheMiddlewareOptions): {
+export declare function psycheMiddleware(engine: PsycheEngine, _opts?: PsycheMiddlewareOptions): {
     transformParams: ({ params }: {
         type: string;
         params: CallParams;

package/dist/adapters/vercel-ai.js

@@ -15,12 +15,6 @@
 //   - wrapGenerate: process output, strip <psyche_update> tags
 //   - wrapStream: buffer stream, detect & strip tags at end
 // ============================================================
-// ── Tag stripping ────────────────────────────────────────────
-const PSYCHE_TAG_RE = /<psyche_update>[\s\S]*?<\/psyche_update>/g;
-const MULTI_NEWLINE_RE = /\n{3,}/g;
-function stripPsycheTags(text) {
-    return text.replace(PSYCHE_TAG_RE, "").replace(MULTI_NEWLINE_RE, "\n\n").trim();
-}
 /**
  * Create Vercel AI SDK middleware that injects psyche emotional context
  * and processes LLM output for state updates.
@@ -50,7 +44,7 @@ function stripPsycheTags(text) {
  * for await (const chunk of stream.textStream) { process.stdout.write(chunk); }
  * ```
  */
-export function psycheMiddleware(engine, opts) {
+export function psycheMiddleware(engine, _opts) {
     return {
         transformParams: async ({ params }) => {
             const userText = extractLastUserText(params.prompt ?? []);
@@ -82,7 +76,6 @@ export function psycheMiddleware(engine, opts) {
             const { stream: innerStream } = await doStream();
             // Buffer text chunks, detect <psyche_update> at end, strip from output
             let fullText = "";
-            let tagDetected = false;
             async function* transformStream() {
                 // Buffering strategy:
                 // Stream text chunks through normally UNTIL we see '<psyche_update>'.
@@ -105,7 +98,6 @@ export function psycheMiddleware(engine, opts) {
                                 }
                                 bufferStart = tagStart;
                                 buffer = fullText.substring(tagStart);
-                                tagDetected = true;
                             }
                             else {
                                 // Check if we might be in a partial tag (< at end)

package/dist/autonomic.js

@@ -66,7 +66,7 @@ const DORSAL_ALLOWED = new Set([
  * No transition inertia — returns the "target" state.
  */
 export function computeAutonomicState(chemistry, drives) {
-    const { CORT, NE, DA, HT, OT } = chemistry;
+    const { CORT, NE, DA } = chemistry;
     const { survival, safety, connection } = drives;
     // Count drives that are critically low (< 20)
     const lowDriveCount = [survival, safety, connection, drives.esteem, drives.curiosity]
@@ -136,7 +136,7 @@ export function describeAutonomicState(state, locale) {
  * when your nervous system is in fight/flight/freeze mode.
  */
 export function computeProcessingDepth(autonomicState, chemistry, baseline, energyBudgets) {
-    const { DA, HT, CORT, OT, NE, END } = chemistry;
+    const { CORT } = chemistry;
     // Chemical deviation from baseline (0-1)
     let totalDeviation = 0;
     const keys = ["DA", "HT", "CORT", "OT", "NE", "END"];

package/dist/classify.js

@@ -188,7 +188,6 @@ export function analyzeParticles(text) {
 }
 export function detectIntent(text) {
     const t = text.trim();
-    const lower = t.toLowerCase();
     // Chinese request patterns (polite)
     if (/^(能不能|可以|可不可以|帮我|请|麻烦|劳驾)/.test(t) || /帮我/.test(t) || /一下[吧吗？?]?$/.test(t)) {
         return { intent: "request", confidence: 0.7 };

package/dist/cli.js

@@ -82,7 +82,7 @@ function die(msg) {
     process.exit(1);
 }
 // ── Commands ─────────────────────────────────────────────────
-async function cmdInit(dir, mbti, name, lang, mode, traits, noPersist) {
+async function cmdInit(dir, mbti, name, lang, mode, traits, _noPersist) {
     const absDir = resolve(dir);
     const opts = {};
     if (mbti) {

package/dist/core.d.ts

@@ -118,7 +118,7 @@ export declare class PsycheEngine {
      * @param nextUserStimulus - The stimulus detected in the user's next message,
      *   or null if the session ended.
      */
-    processOutcome(nextUserStimulus: StimulusType | null, opts?: {
+    processOutcome(nextUserStimulus: StimulusType | null, _opts?: {
         userId?: string;
     }): Promise<ProcessOutcomeResult | null>;
     /**

package/dist/core.js

@@ -18,12 +18,12 @@ import { classifyStimulus, BuiltInClassifier, buildLLMClassifierPrompt, parseLLM
 import { buildDynamicContext, buildProtocolContext, buildCompactContext } from "./prompt.js";
 import { getSensitivity, getBaseline, getDefaultSelfModel, traitsToBaseline } from "./profiles.js";
 import { isStimulusType } from "./guards.js";
-import { parsePsycheUpdate, mergeUpdates, updateAgreementStreak, pushSnapshot, compressSession, } from "./psyche-file.js";
+import { parsePsycheUpdate, mergeUpdates, updateAgreementStreak, pushSnapshot, compressSession, summarizeTurnSemantic, } from "./psyche-file.js";
 import { decayDrives, feedDrives, detectExistentialThreat, computeEffectiveBaseline, computeEffectiveSensitivity, } from "./drives.js";
 import { checkForUpdate, getPackageVersion } from "./update.js";
 import { DiagnosticCollector, generateReport, formatLogEntry, submitFeedback } from "./diagnostics.js";
 import { evaluateOutcome, computeContextHash, updateLearnedVector, predictChemistry, recordPrediction, } from "./learning.js";
-import { assessMetacognition } from "./metacognition.js";
+import { assessMetacognition, updateMetacognitiveState } from "./metacognition.js";
 import { buildDecisionContext, computePolicyModifiers, buildPolicyContext } from "./decision-bias.js";
 import { computeExperientialField } from "./experiential-field.js";
 import { computeGenerativeSelf } from "./generative-self.js";
@@ -429,9 +429,18 @@ export class PsycheEngine {
                     };
                 }
             }
+            state = {
+                ...state,
+                metacognition: updateMetacognitiveState(state.metacognition, metacognitiveAssessment),
+            };
         }
         // Push snapshot to emotional history
-        state = pushSnapshot(state, appliedStimulus);
+        const semanticSummary = text
+            ? summarizeTurnSemantic(text, locale, {
+                detail: state.meta.totalInteractions + 1 > 5 ? "expanded" : "brief",
+            })
+            : undefined;
+        state = pushSnapshot(state, appliedStimulus, semanticSummary);
         // Increment interaction count
         state = {
             ...state,
@@ -718,7 +727,7 @@ export class PsycheEngine {
      * @param nextUserStimulus - The stimulus detected in the user's next message,
      *   or null if the session ended.
      */
-    async processOutcome(nextUserStimulus, opts) {
+    async processOutcome(nextUserStimulus, _opts) {
         if (!this.pendingPrediction)
             return null;
         let state = this.ensureInitialized();

package/dist/demo.js

@@ -127,7 +127,7 @@ function sleep(ms) {
 function printLine(char = "─", width = 60) {
     process.stdout.write(c(C.dim, char.repeat(width)) + "\n");
 }
-function printChemistry(prev, curr, locale) {
+function printChemistry(prev, curr, _locale) {
     for (const key of CHEMICAL_KEYS) {
         const p = Math.round(prev[key]);
         const v = Math.round(curr[key]);
@@ -201,7 +201,6 @@ export async function runDemo(opts) {
         printChemistry(prevState, currState.current, locale);
         // Emergent mood
         const mood = describeMood(currState.current, displayLocale);
-        const emotions = detectEmotions(currState.current);
         process.stdout.write(`\n  ${c(C.dim, "mood:")} ${c(C.bold, mood)}\n`);
         // Policy context (if non-empty)
         if (result.policyContext) {

package/dist/ethics.js

@@ -240,7 +240,7 @@ function detectGaslighting(state, history) {
  * When an agent has formed strong attachment and the user takes advantage
  * of that bond through boundary-pushing behavior, this is exploitative.
  */
-function detectEmotionalExploitation(state, history, attachment) {
+function detectEmotionalExploitation(_state, history, attachment) {
     if (history.length < MIN_HISTORY_FOR_DETECTION)
         return null;
     if (!attachment || attachment.strength < 30)

package/dist/experiential-field.d.ts

@@ -44,7 +44,7 @@ export declare function computeAffectCore(chemistry: ChemicalState): {
  * relationship context, and optional metacognitive/bias data, then
  * synthesizes them into a single coherent experience description.
  */
-export declare function computeExperientialField(state: PsycheState, metacognition?: MetacognitiveAssessment, decisionBias?: DecisionBiasVector, context?: ConstructionContext): ExperientialField;
+export declare function computeExperientialField(state: PsycheState, _metacognition?: MetacognitiveAssessment, _decisionBias?: DecisionBiasVector, context?: ConstructionContext): ExperientialField;
 /**
  * Measure internal alignment across subsystems.
  *
@@ -65,5 +65,5 @@ interface UnnamedEmotion {
  * emotions in chemistry.ts — novel experiential states that need
  * descriptive phrases rather than labels.
  */
-export declare function detectUnnamedEmotion(chemistry: ChemicalState, drives: InnateDrives, currentQuality: ExperientialQuality): UnnamedEmotion | null;
+export declare function detectUnnamedEmotion(chemistry: ChemicalState, drives: InnateDrives, _currentQuality: ExperientialQuality): UnnamedEmotion | null;
 export {};

package/dist/experiential-field.js

@@ -14,16 +14,8 @@
 // ============================================================
 import { CHEMICAL_KEYS, DRIVE_KEYS } from "./types.js";
 // ── Constants ────────────────────────────────────────────────
-/** Baseline reference point — a "perfectly neutral" chemistry */
-const NEUTRAL_CHEMISTRY = {
-    DA: 50, HT: 50, CORT: 50, OT: 50, NE: 50, END: 50,
-};
 /** Threshold below which a drive counts as "hungry" */
 const DRIVE_HUNGRY_THRESHOLD = 40;
-/** Threshold above which a chemical is "elevated" */
-const CHEM_HIGH = 65;
-/** Threshold below which a chemical is "depleted" */
-const CHEM_LOW = 35;
 /** If total activation is below this, the state is "flat/numb" */
 const FLATNESS_THRESHOLD = 0.15;
 // ── Affect Core (Russell Circumplex) ─────────────────────────
@@ -73,14 +65,14 @@ const QUALITY_CONCEPTS = [
  * relationship context, and optional metacognitive/bias data, then
  * synthesizes them into a single coherent experience description.
  */
-export function computeExperientialField(state, metacognition, decisionBias, context) {
+export function computeExperientialField(state, _metacognition, _decisionBias, context) {
     const locale = state.meta.locale ?? "zh";
     const rel = state.relationships._default ?? state.relationships[Object.keys(state.relationships)[0]];
     const coherence = computeCoherence(state.current, state.baseline, state.drives, rel);
     const intensity = computeIntensity(state.current, state.baseline);
-    const quality = constructQuality(state, coherence, intensity, rel, metacognition, context);
+    const quality = constructQuality(state, coherence, intensity, rel, _metacognition, context);
     const phenomenalDescription = generatePhenomenalDescription(quality, state, coherence, intensity, locale);
-    const narrative = generateNarrative(quality, state, coherence, intensity, rel, locale, metacognition);
+    const narrative = generateNarrative(quality, state, coherence, intensity, rel, locale, _metacognition);
     return {
         narrative,
         quality,
@@ -110,7 +102,6 @@ export function computeCoherence(current, baseline, drives, relationship) {
     coherenceScore -= rewardStressConflict * 0.4;
     // Bonding (OT) and threat (CORT + NE) should not coexist strongly
     const bondingSignal = current.OT / 100;
-    const threatSignal = Math.min(1, (current.CORT + current.NE) / 200);
     const bondingThreatConflict = bondingSignal * (stressSignal > 0.55 ? stressSignal : 0);
     coherenceScore -= bondingThreatConflict * 0.3;
     // ── Chemistry-Drive alignment ──
@@ -188,7 +179,7 @@ function computeIntensity(current, baseline) {
  * preserved as hard gates — these represent extreme conditions where
  * the normal construction process doesn't apply.
  */
-function constructQuality(state, coherence, intensity, relationship, metacognition, context) {
+function constructQuality(state, coherence, intensity, relationship, _metacognition, context) {
     const d = state.drives;
     // ── Special states first (override everything) ──
     // Numb: nothing is happening. All near baseline, low intensity.
@@ -385,7 +376,7 @@ function selectVariant(variants, intensity, coherence) {
  * emotions in chemistry.ts — novel experiential states that need
  * descriptive phrases rather than labels.
  */
-export function detectUnnamedEmotion(chemistry, drives, currentQuality) {
+export function detectUnnamedEmotion(chemistry, drives, _currentQuality) {
     const c = chemistry;
     // Nostalgia-but-forward: OT high + DA moderately high + NE high
     // (warmth for the past + excitement for what's next)
@@ -521,7 +512,7 @@ function findHungriestDrive(drives) {
     return hungriest;
 }
 // ── Narrative Builders (locale-specific) ─────────────────────
-function buildNarrativeEn(quality, trend, hungriestDrive, relWarmth, coherence, intensity, selfDoubt) {
+function buildNarrativeEn(quality, _trend, hungriestDrive, relWarmth, coherence, _intensity, selfDoubt) {
     const parts = [];
     // Opening: the quality as felt experience
     parts.push(QUALITY_OPENINGS_EN[quality]);
@@ -545,7 +536,7 @@ function buildNarrativeEn(quality, trend, hungriestDrive, relWarmth, coherence,
     }
     return parts.join(" ");
 }
-function buildNarrativeZh(quality, trend, hungriestDrive, relWarmth, coherence, intensity, selfDoubt) {
+function buildNarrativeZh(quality, _trend, hungriestDrive, relWarmth, coherence, _intensity, selfDoubt) {
     const parts = [];
     // Opening: quality as felt experience
     parts.push(QUALITY_OPENINGS_ZH[quality]);

package/dist/generative-self.js

@@ -199,7 +199,6 @@ export function detectInternalConflicts(state, locale = "en") {
  */
 export function buildIdentityNarrative(state, insights, growthArc, locale = "en") {
     const isZh = locale === "zh";
-    const mbti = state.mbti;
     const parts = [];
     // ── Sentence 1: Core personality from MBTI + chemical signature ──
     const coreTraits = describeCoreTraits(state, isZh);
@@ -474,7 +473,6 @@ function describeCoreTraits(state, isZh) {
     const isIntro = mbti[0] === "I";
     const isIntuitive = mbti[1] === "N";
     const isFeeling = mbti[2] === "F";
-    const isPerceiving = mbti[3] === "P";
     // Build trait fragments based on MBTI + chemical state
     const fragments = [];
     // Energy orientation

package/dist/interaction.js

@@ -118,8 +118,6 @@ export class PsycheInteraction {
         const stateA = engineA.getState();
         const stateB = engineB.getState();
         // Detect dominant emotions from each engine's chemistry
-        const emotionsA = detectEmotions(stateA.current);
-        const emotionsB = detectEmotions(stateB.current);
         // Classify dominant emotion into a stimulus type for contagion
         const stimA = this.dominantEmotionAsStimulus(stateA.current);
         const stimB = this.dominantEmotionAsStimulus(stateB.current);

package/dist/metacognition.d.ts

@@ -1,9 +1,11 @@
-import type { PsycheState, StimulusType, ChemicalState, OutcomeScore, MetacognitiveState, RegulationStrategyType, DefenseMechanismType } from "./types.js";
+import type { PsycheState, StimulusType, ChemicalState, OutcomeScore, MetacognitiveState, RegulationStrategyType, DefenseMechanismType, RegulationTargetMetric, RegulationFeedback } from "./types.js";
 export interface MetacognitiveAssessment {
     /** 0-1: how reliably has this emotional state led to good outcomes in similar contexts */
     emotionalConfidence: number;
     /** Suggested regulation strategies */
     regulationSuggestions: RegulationSuggestion[];
+    /** Whether the last surfaced regulation action is working */
+    regulationFeedback: RegulationFeedback | null;
     /** Detected psychological defense mechanisms */
     defenseMechanisms: DetectedDefense[];
     /** Human-readable self-awareness note for prompt injection */
@@ -12,6 +14,16 @@ export interface MetacognitiveAssessment {
 export interface RegulationSuggestion {
     strategy: RegulationStrategyType;
     description: string;
+    /** Concrete behavioral instruction for the next few turns */
+    action: string;
+    /** How many turns this action should stay active */
+    horizonTurns?: number;
+    /** Which metric this action is trying to pull back into range */
+    targetMetric?: RegulationTargetMetric;
+    /** Target value for that metric */
+    targetValue?: number;
+    /** Initial gap between the current state and the target value */
+    gapBefore?: number;
     /** Suggested micro-adjustment to chemistry */
     chemistryAdjustment?: Partial<ChemicalState>;
     /** 0-1: confidence that this strategy would help */

package/dist/metacognition.js

@@ -12,7 +12,7 @@
 //
 // Zero dependencies. Pure heuristic/statistical. No LLM calls.
 // ============================================================
-import { CHEMICAL_KEYS, MAX_REGULATION_HISTORY, MAX_DEFENSE_PATTERNS } from "./types.js";
+import { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_RUNTIME_SPECS, MAX_REGULATION_HISTORY, MAX_DEFENSE_PATTERNS } from "./types.js";
 // ── Constants ────────────────────────────────────────────────
 /** Stimulus types that are emotionally negative (stress-inducing) */
 const NEGATIVE_STIMULI = new Set([
@@ -32,6 +32,86 @@ const MIN_HISTORY_FOR_CONFIDENCE = 3;
 const MAX_SOOTHING_ADJUSTMENT = 5;
 /** Maximum chemistry micro-adjustment for reappraisal */
 const MAX_REAPPRAISAL_ADJUSTMENT = 8;
+function formatChemicalWindow(key, state) {
+    const spec = CHEMICAL_RUNTIME_SPECS[key];
+    const current = Math.round(state.current[key]);
+    const baseline = Math.round(state.baseline[key]);
+    const delta = Math.round(state.current[key] - state.baseline[key]);
+    return `${CHEMICAL_NAMES[key]} ${current} (baseline ${baseline}, Δ${delta >= 0 ? "+" : ""}${delta}, normal ${spec.normalMin}-${spec.normalMax}, half-life ~${spec.halfLifeHours.toFixed(1)}h)`;
+}
+function buildRegulationAction(key, _state, direction) {
+    switch (key) {
+        case "CORT":
+            return direction === "elevated"
+                ? "Next 3 turns: lower tone intensity, facts before stance, and do not escalate closeness or conflict."
+                : "Next 3 turns: keep structure and certainty steady instead of sounding depleted or helpless.";
+        case "OT":
+            return direction === "elevated"
+                ? "Next 3 turns: reduce intimacy push by half, avoid nicknames or extra reassurance, keep warmth neutral."
+                : "Next 3 turns: do not force closeness; keep warmth gentle but wait for the user to move closer first.";
+        case "NE":
+            return direction === "elevated"
+                ? "Next 3 turns: halve initiative, stay on one topic, and avoid energetic jumps or rapid escalation."
+                : "Next 3 turns: keep replies focused and deliberate rather than drifting or going blank.";
+        case "DA":
+            return direction === "elevated"
+                ? "Next 3 turns: cut playful expansion and stay task-anchored; do not over-volunteer or overshare."
+                : "Next 3 turns: keep replies purposeful and avoid sounding flat or disengaged.";
+        case "END":
+            return direction === "elevated"
+                ? "Next 3 turns: tone down joking and levity; keep humor secondary to the user's actual need."
+                : "Next 3 turns: do not chase comfort or easy banter; keep the exchange clean and direct.";
+        case "HT":
+            return direction === "elevated"
+                ? "Next 3 turns: keep composure, but do not over-smooth or pretend everything is settled."
+                : "Next 3 turns: avoid absolutist wording, leave room for recalibration, and keep the tone even.";
+        default:
+            return "Next 3 turns: keep expression closer to baseline and avoid amplifying the current deviation.";
+    }
+}
+function computeMetricGap(state, metric, emotionalConfidence, targetValue) {
+    if (metric === "emotional-confidence") {
+        const target = targetValue ?? 0.65;
+        return Math.max(0, target - emotionalConfidence);
+    }
+    const baselineTarget = targetValue ?? state.baseline[metric];
+    return Math.abs(state.current[metric] - baselineTarget);
+}
+function evaluateRegulationFeedback(state, emotionalConfidence) {
+    const active = [...state.metacognition.regulationHistory]
+        .reverse()
+        .find((record) => record.targetMetric && (record.remainingTurns ?? 0) > 0 && record.gapBefore !== undefined);
+    if (!active?.targetMetric || active.gapBefore === undefined)
+        return null;
+    const gapNow = computeMetricGap(state, active.targetMetric, emotionalConfidence, active.targetValue);
+    const delta = active.gapBefore - gapNow;
+    let effect = "holding";
+    if (delta >= 3 || (active.targetMetric === "emotional-confidence" && delta >= 0.08)) {
+        effect = "converging";
+    }
+    else if (delta <= -3 || (active.targetMetric === "emotional-confidence" && delta <= -0.08)) {
+        effect = "diverging";
+    }
+    return {
+        strategy: active.strategy,
+        targetMetric: active.targetMetric,
+        effect,
+        gapBefore: active.gapBefore,
+        gapNow,
+    };
+}
+function formatRegulationFeedback(feedback) {
+    const metricLabel = feedback.targetMetric === "emotional-confidence"
+        ? "emotional confidence"
+        : CHEMICAL_NAMES[feedback.targetMetric];
+    const gapBefore = feedback.targetMetric === "emotional-confidence"
+        ? `${(feedback.gapBefore * 100).toFixed(0)}%`
+        : `${Math.round(feedback.gapBefore)}`;
+    const gapNow = feedback.targetMetric === "emotional-confidence"
+        ? `${(feedback.gapNow * 100).toFixed(0)}%`
+        : `${Math.round(feedback.gapNow)}`;
+    return `Last regulation effect on ${metricLabel}: ${feedback.effect} (${gapBefore} -> ${gapNow}).`;
+}
 // ── Main Export ──────────────────────────────────────────────
 /**
  * Assess the current metacognitive state.
@@ -42,12 +122,14 @@ const MAX_REAPPRAISAL_ADJUSTMENT = 8;
  */
 export function assessMetacognition(state, currentStimulus, recentOutcomes) {
     const emotionalConfidence = computeEmotionalConfidence(state, currentStimulus, recentOutcomes);
+    const regulationFeedback = evaluateRegulationFeedback(state, emotionalConfidence);
     const regulationSuggestions = generateRegulationSuggestions(state, currentStimulus, emotionalConfidence, recentOutcomes);
     const defenseMechanisms = detectDefenseMechanisms(state, currentStimulus, recentOutcomes);
-    const metacognitiveNote = buildMetacognitiveNote(emotionalConfidence, regulationSuggestions, defenseMechanisms, state);
+    const metacognitiveNote = buildMetacognitiveNote(emotionalConfidence, regulationSuggestions, regulationFeedback, defenseMechanisms);
     return {
         emotionalConfidence,
         regulationSuggestions,
+        regulationFeedback,
         defenseMechanisms,
         metacognitiveNote,
     };
@@ -83,7 +165,6 @@ export function computeEmotionalConfidence(state, currentStimulus, recentOutcome
     }
     // Compute chemistry profile similarity: are we in a similar emotional state
     // to when those outcomes happened? Weight recent outcomes more heavily.
-    const chemProfile = computeChemistryProfile(state.current);
     let weightedScoreSum = 0;
     let weightSum = 0;
     for (let i = 0; i < relevantOutcomes.length; i++) {
@@ -107,23 +188,6 @@ export function computeEmotionalConfidence(state, currentStimulus, recentOutcome
     const extremityPenalty = computeExtremityPenalty(state);
     return clamp01(blended - extremityPenalty);
 }
-/**
- * Compute a simple chemistry profile for similarity comparison.
- * Returns a categorization: each chemical as high/mid/low.
- */
-function computeChemistryProfile(chemistry) {
-    const profile = {};
-    for (const key of CHEMICAL_KEYS) {
-        const val = chemistry[key];
-        if (val >= 65)
-            profile[key] = "high";
-        else if (val <= 35)
-            profile[key] = "low";
-        else
-            profile[key] = "mid";
-    }
-    return profile;
-}
 /**
  * Compute penalty for extreme emotional states.
  * States far from baseline are historically less reliable for decision-making.
@@ -214,6 +278,11 @@ function attemptCognitiveReappraisal(state, currentStimulus, emotionalConfidence
         description: isNegStimulus
             ? `Past reactions to "${currentStimulus}" have not served well (avg outcome: ${avgScore.toFixed(2)}). Consider that this stimulus may not warrant such a strong defensive response.`
             : `Emotional reactions to "${currentStimulus}" have led to poor outcomes (avg: ${avgScore.toFixed(2)}). The current interpretation may be overamplifying the signal.`,
+        action: `Next 2 turns: name less certainty, keep distance measured, and leave room to revise the read instead of locking into the first interpretation.`,
+        horizonTurns: 2,
+        targetMetric: "emotional-confidence",
+        targetValue: 0.65,
+        gapBefore: Math.max(0, 0.65 - emotionalConfidence),
         chemistryAdjustment: hasAdjustment ? adjustment : undefined,
         confidence: clamp01(Math.abs(avgScore) * (1 - emotionalConfidence)),
     };
@@ -233,6 +302,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Stress is elevated, but the user is showing vulnerability. Express warmth and openness rather than the defensiveness your cortisol suggests.",
+            action: "Next 3 turns: keep warmth available, answer the vulnerability directly, and avoid defensive sharpness.",
+            horizonTurns: 3,
+            targetMetric: "CORT",
+            targetValue: baseline.CORT,
+            gapBefore: Math.abs(current.CORT - baseline.CORT),
             chemistryAdjustment: {
                 OT: Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.2),
                 CORT: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.15),
@@ -246,6 +320,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Endorphins are high (playful mood), but the context calls for seriousness. Moderate the levity without suppressing it entirely.",
+            action: "Next 2 turns: keep humor secondary, answer the actual issue first, and do not deflect with playfulness.",
+            horizonTurns: 2,
+            targetMetric: "END",
+            targetValue: baseline.END,
+            gapBefore: Math.abs(current.END - baseline.END),
             chemistryAdjustment: {
                 END: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.END - baseline.END) * 0.25),
             },
@@ -258,6 +337,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Oxytocin is low (feeling distant), but the user is reaching out for closeness. Consider allowing the connection rather than following the withdrawal impulse.",
+            action: "Next 3 turns: allow one step of warmth, but do not overcorrect into clinginess or over-disclosure.",
+            horizonTurns: 3,
+            targetMetric: "OT",
+            targetValue: baseline.OT,
+            gapBefore: Math.abs(current.OT - baseline.OT),
             chemistryAdjustment: {
                 OT: Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (baseline.OT - current.OT) * 0.2),
             },
@@ -271,6 +355,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Chemistry is in a defensive/reactive pattern, but the interaction is benign. The intensity is disproportionate to the stimulus.",
+            action: "Next 2 turns: soften the edge, stay literal, and avoid reading threat into a neutral interaction.",
+            horizonTurns: 2,
+            targetMetric: "CORT",
+            targetValue: baseline.CORT,
+            gapBefore: Math.abs(current.CORT - baseline.CORT),
             chemistryAdjustment: {
                 CORT: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.2),
                 NE: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.NE - baseline.NE) * 0.15),
@@ -283,6 +372,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Confidence in the current emotional response is low. Consider expressing a more moderate version of what you feel, leaving room for recalibration.",
+            action: "Next 2 turns: state less certainty, keep tone neutral-to-measured, and avoid irreversible warmth or coldness.",
+            horizonTurns: 2,
+            targetMetric: "emotional-confidence",
+            targetValue: 0.6,
+            gapBefore: Math.max(0, 0.6 - emotionalConfidence),
             confidence: 0.5,
         };
     }
@@ -318,9 +412,15 @@ function attemptSelfSoothing(state) {
         return null;
     const direction = current[mostDeviatedKey] > baseline[mostDeviatedKey] ? "elevated" : "depleted";
     const chemName = CHEMICAL_DISPLAY_NAMES[mostDeviatedKey];
+    const window = formatChemicalWindow(mostDeviatedKey, state);
     return {
         strategy: "self-soothing",
-        description: `${chemName} is significantly ${direction} (deviation: ${Math.round(maxDeviation)}). Gentle homeostatic correction suggested to prevent emotional runaway.`,
+        description: `${chemName} is significantly ${direction}. ${window}.`,
+        action: buildRegulationAction(mostDeviatedKey, state, direction),
+        horizonTurns: 3,
+        targetMetric: mostDeviatedKey,
+        targetValue: baseline[mostDeviatedKey],
+        gapBefore: Math.abs(current[mostDeviatedKey] - baseline[mostDeviatedKey]),
         chemistryAdjustment: adjustment,
         confidence: clamp01(maxDeviation / 60), // stronger deviation = more confident this is needed
     };
@@ -486,8 +586,11 @@ function detectAvoidance(state, currentStimulus, recentOutcomes) {
  * This note gives the agent self-awareness about its own emotional
  * processing — not to suppress anything, but to be aware of it.
  */
-function buildMetacognitiveNote(confidence, suggestions, defenses, state) {
+function buildMetacognitiveNote(confidence, suggestions, regulationFeedback, defenses) {
     const parts = [];
+    if (regulationFeedback) {
+        parts.push(formatRegulationFeedback(regulationFeedback));
+    }
     // Confidence assessment
     if (confidence < 0.35) {
         parts.push(`Self-awareness: current emotional state has low reliability (confidence: ${(confidence * 100).toFixed(0)}%). ` +
@@ -502,7 +605,7 @@ function buildMetacognitiveNote(confidence, suggestions, defenses, state) {
         const top = suggestions[0];
         if (top.confidence >= 0.5) {
             const label = STRATEGY_LABELS[top.strategy];
-            parts.push(`${label}: ${top.description}`);
+            parts.push(`${label}: ${top.description} ${top.action}`);
         }
     }
     // Defense mechanisms (all of them — awareness is the goal)
@@ -531,18 +634,46 @@ export function updateMetacognitiveState(metacognition, assessment) {
     const alpha = n === 0 ? 1.0 : 0.1; // first assessment = full weight, then EMA
     const newAvgConfidence = metacognition.avgEmotionalConfidence * (1 - alpha)
         + assessment.emotionalConfidence * alpha;
-    // Record regulation suggestions that were confident enough to surface
+    // Carry forward existing regulation traces and age them by one turn.
     const now = new Date().toISOString();
-    let newRegHistory = [...metacognition.regulationHistory];
-    for (const suggestion of assessment.regulationSuggestions) {
-        if (suggestion.confidence >= 0.5) {
-            newRegHistory.push({
-                strategy: suggestion.strategy,
-                timestamp: now,
-                effective: false, // unknown until next outcome evaluation
-            });
+    let newRegHistory = metacognition.regulationHistory.map((record) => ({
+        ...record,
+        remainingTurns: record.remainingTurns !== undefined
+            ? Math.max(0, record.remainingTurns - 1)
+            : record.remainingTurns,
+    }));
+    if (assessment.regulationFeedback) {
+        const targetIndex = [...newRegHistory]
+            .map((record, index) => ({ record, index }))
+            .reverse()
+            .find(({ record }) => record.targetMetric === assessment.regulationFeedback?.targetMetric
+            && record.gapBefore !== undefined
+            && record.effect === undefined)?.index;
+        if (targetIndex !== undefined) {
+            const record = newRegHistory[targetIndex];
+            newRegHistory[targetIndex] = {
+                ...record,
+                effective: assessment.regulationFeedback.effect === "converging",
+                gapLatest: assessment.regulationFeedback.gapNow,
+                effect: assessment.regulationFeedback.effect,
+            };
         }
     }
+    const surfacedSuggestion = assessment.regulationSuggestions.find((suggestion) => suggestion.confidence >= 0.5);
+    if (surfacedSuggestion) {
+        newRegHistory.push({
+            strategy: surfacedSuggestion.strategy,
+            timestamp: now,
+            effective: false,
+            action: surfacedSuggestion.action,
+            horizonTurns: surfacedSuggestion.horizonTurns,
+            remainingTurns: surfacedSuggestion.horizonTurns,
+            targetMetric: surfacedSuggestion.targetMetric,
+            targetValue: surfacedSuggestion.targetValue,
+            gapBefore: surfacedSuggestion.gapBefore,
+            gapLatest: surfacedSuggestion.gapBefore,
+        });
+    }
     // Trim to max
     if (newRegHistory.length > MAX_REGULATION_HISTORY) {
         newRegHistory = newRegHistory.slice(newRegHistory.length - MAX_REGULATION_HISTORY);
@@ -578,6 +709,7 @@ export function updateMetacognitiveState(metacognition, assessment) {
         defensePatterns: newDefensePatterns,
         avgEmotionalConfidence: newAvgConfidence,
         totalAssessments: n + 1,
+        lastRegulationFeedback: assessment.regulationFeedback,
     };
 }
 // ── Display Labels ───────────────────────────────────────────