pi-mega-compact 0.11.7 → 0.11.9

package/dist/extensions/dashboard-server/gather-debug-keys.js

@@ -0,0 +1,18 @@
+export const MEGACOMPACT_ENV_KEYS = [
+    "MEGACOMPACT_AUTO",
+    "MEGACOMPACT_THRESHOLD_TOKENS",
+    "MEGACOMPACT_TIER",
+    "MEGACOMPACT_DBMIRROR",
+    "MEGACOMPACT_MESSAGE_SEPARATION",
+    "MEGACOMPACT_CACHE_STRIPING",
+    "MEGACOMPACT_LEGACY_DURABLE_TRIM",
+    "MEGACOMPACT_RACE_GUARD_STRICT",
+    "MEGACOMPACT_RECALL_TAIL_INJECT",
+    "MEGACOMPACT_PGLITE_DISABLED",
+    "MEGACOMPACT_WIKI_REBUILD_EVERY",
+    "MEGACOMPACT_WIKI_SEED_FROM_TURNS",
+    "MEGACOMPACT_MEMORY_GRAPH_SEED_TURNS",
+    "MEGACOMPACT_MEMORY_GRAPH_SEED_TIER",
+    "MEGACOMPACT_MEMORY_GRAPH_SEED_BATCH",
+    "MEGACOMPACT_MEMORY_GRAPH_SEED_MAX",
+];

package/dist/extensions/dashboard-server/gather-debug.js

@@ -0,0 +1,129 @@
+/**
+ * gather-debug.ts — assemble a diagnostic bundle for bug reports.
+ *
+ * POST /api/maintenance/gather-debug → DebugBundleResponse. Reads local
+ * SQLite + FS only (PREVENT-PI-004: zero network). Each section is non-fatal:
+ * a read failure records `{ error }` for that section and continues, so the
+ * bundle always returns 200 with whatever could be gathered.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { defaultMetricsPath, defaultEventsPath } from "../../src/monitoring.js";
+import { ownVersion } from "../mega-runtime/helpers.js";
+import { MEGACOMPACT_ENV_KEYS } from "./gather-debug-keys.js";
+/** Event-name patterns that indicate a critical/compaction class of error. */
+const CRITICAL_PATTERN = /critical|overflow|already[.\s-]?compacted|compaction[.\s-]?failed|stream[.\s-]?death|poisoned|prefix_stability/i;
+const require = createRequire(import.meta.url);
+/** Lazy store opener (mirrors routes-maintenance.ts's lazyStoreUtils). */
+function openStoreDb(ctx) {
+    const mod = require("../../src/store/sqlite/utils.js");
+    return mod.openStore(ctx.stateDir);
+}
+/** Lazy maintenance loaders (mirrors routes-maintenance.ts's lazyMaintenance). */
+function loadMaintenance() {
+    return require("../../src/store/sqlite/maintenance.js");
+}
+/** Send the debug bundle as JSON. Always 200 (partial on read failure). */
+export function sendGatherDebug(res, ctx) {
+    const result = {
+        builtAt: Date.now(),
+        version: ownVersion(),
+        stateDir: ctx.stateDir,
+        config: {},
+        schemaHealth: { error: "not fetched" },
+        storeStats: { error: "not fetched" },
+        dashboardSnapshot: { error: "not fetched" },
+        recentEvents: [],
+        criticalEvents: [],
+    };
+    // 1. Config flags (no secrets — MEGACOMPACT_* only)
+    for (const key of MEGACOMPACT_ENV_KEYS) {
+        result.config[key] = process.env[key] ?? "<default>";
+    }
+    // 2. Schema health
+    try {
+        const maint = loadMaintenance();
+        const integrity = maint.integrityCheck(ctx.stateDir);
+        const db = openStoreDb(ctx);
+        const metaRow = db
+            .prepare("SELECT value FROM meta WHERE key = ?")
+            .get("schema_version");
+        const schemaVersion = metaRow ? Number(metaRow.value) : 0;
+        const fkRows = db.prepare("PRAGMA foreign_key_check").all();
+        result.schemaHealth = {
+            type: "schema-health",
+            schemaVersion,
+            integrity,
+            fkCheck: fkRows.map((r) => JSON.stringify(r)),
+            columns: [],
+            healthy: true,
+        };
+    }
+    catch (e) {
+        result.schemaHealth = { error: e instanceof Error ? e.message : String(e) };
+    }
+    // 3. Store stats
+    try {
+        const maint = loadMaintenance();
+        const raw = maint.getDbStats(ctx.stateDir);
+        result.storeStats = {
+            type: "db-stats",
+            tables: Object.entries(raw.tableCounts).map(([table, rowCount]) => ({ table, rowCount })),
+            storage: {
+                files: { dbBytes: raw.dbBytes, walBytes: raw.walBytes, shmBytes: raw.shmBytes },
+                pageSize: raw.pageSize,
+                pageCount: raw.pageCount,
+                freelistPages: raw.freelistPages,
+            },
+        };
+    }
+    catch (e) {
+        result.storeStats = { error: e instanceof Error ? e.message : String(e) };
+    }
+    // 4. Dashboard snapshot
+    try {
+        const path = defaultMetricsPath(ctx.stateDir);
+        if (existsSync(path)) {
+            const raw = readFileSync(path, "utf-8");
+            result.dashboardSnapshot = JSON.parse(raw);
+        }
+        else {
+            result.dashboardSnapshot = { error: "no snapshot" };
+        }
+    }
+    catch (e) {
+        result.dashboardSnapshot = { error: e instanceof Error ? e.message : String(e) };
+    }
+    // 5. Recent + critical events (tail ~200 lines of events.log)
+    try {
+        const path = defaultEventsPath(ctx.stateDir);
+        if (existsSync(path)) {
+            const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+            for (const line of lines.slice(-200)) {
+                try {
+                    const ev = JSON.parse(line);
+                    result.recentEvents.push(ev);
+                    if (CRITICAL_PATTERN.test(line))
+                        result.criticalEvents.push(ev);
+                }
+                catch {
+                    continue; // skip unparseable line (PREVENT-001)
+                }
+            }
+        }
+    }
+    catch (e) {
+        result.recentEvents = [{ error: e instanceof Error ? e.message : String(e) }];
+    }
+    // Send (local helper to avoid importing sendJson from a non-exporting module)
+    try {
+        const body = JSON.stringify(result);
+        res.writeHead(200, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end(body);
+    }
+    catch {
+        // last resort — never leave the response hanging
+        res.writeHead(500, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end('{"error":"failed to serialize debug bundle"}');
+    }
+}

package/dist/extensions/dashboard-server/routes-maintenance.js

@@ -11,6 +11,7 @@
  * SQLite only; zero network calls.
  */
 import { createRequire } from "node:module";
+import { sendGatherDebug } from "./gather-debug.js";
 // ---------------------------------------------------------------------------
 // Lazy imports (via createRequire)
 // ---------------------------------------------------------------------------
@@ -48,6 +49,11 @@ export function handleMaintenance(req, res, ctx) {
         handleMaintenanceAction(req, res, ctx);
         return true;
     }
+    // ── POST /api/maintenance/gather-debug ──────────────────────────
+    if (method === "POST" && url === "/api/maintenance/gather-debug") {
+        sendGatherDebug(res, ctx);
+        return true;
+    }
     // ── GET /api/maintenance ──────────────────────────────────────────
     if (method === "GET" && url === "/api/maintenance") {
         sendDbStats(res, ctx);

package/dist/extensions/dashboard-server/routes-memory-map.js

@@ -1,7 +1,8 @@
 /**
- * routes-memory-map.ts — GET /api/memory-map route handler (S46).
+ * routes-memory-map.ts — GET /api/memory-map route handler (S46/D3).
  *
  * Builds a memory graph from the local SQLite store and returns it as JSON.
+ * D3: surfaces nodeType on each node and the GraphValidationReport.
  * Uses an inline require to the pi-agnostic src/memoryGraph.ts builder.
  */
 import { createRequire } from "node:module";
@@ -16,19 +17,8 @@ export function handleMemoryMap(req, res, ctx) {
         return false;
     // guardrails-allow PREVENT-PI-004: local loopback-only dashboard server — reads the local SQLite store for graph data.
     const { buildMemoryGraph } = _req("../../src/memoryGraph.js");
-    const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : undefined;
-    const threshold = typeof parsed.query.threshold === "string" ? Number.parseFloat(parsed.query.threshold) : undefined;
-    const maxEdges = typeof parsed.query.maxEdgesPerNode === "string" ? Number.parseInt(parsed.query.maxEdgesPerNode, 10) : undefined;
-    const raptorEdges = parsed.query.includeRaptorEdges === "false" ? false : true;
-    const temporalEdges = parsed.query.includeTemporalEdges === "false" ? false : true;
-    const graph = buildMemoryGraph({
-        sessionId,
-        similarityThreshold: threshold,
-        maxEdgesPerNode: maxEdges,
-        stateDir: ctx.stateDir,
-        includeRaptorEdges: raptorEdges,
-        includeTemporalEdges: temporalEdges,
-    });
+    const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : "";
+    const graph = buildMemoryGraph(sessionId, ctx.stateDir);
     const nodes = graph.nodes.map((n) => ({
         id: n.id,
         sessionId: n.sessionId,
@@ -41,9 +31,12 @@ export function handleMemoryMap(req, res, ctx) {
         topicSummary: n.topicSummary,
         decisionCount: n.decisionCount,
         textSnippet: n.textSnippet,
+        // D3: pass through nodeType for UI node-shape encoding
+        nodeType: n.nodeType,
     }));
     const edges = graph.edges;
-    const response = { nodes, edges, metadata: graph.metadata };
+    // D3: surface the validation report (optional in the response type for backward compat)
+    const response = { nodes, edges, metadata: graph.metadata, validation: graph.validation };
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify(response));
     return true;

package/dist/extensions/mega-commands.js

@@ -9,12 +9,12 @@ import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import { normalizeSessionId } from "../src/store.js";
 import { listCheckpoints, latestModelSnapshot, countInjectedGlobal, listRepoRegistry } from "../src/store/sqlite.js";
 import { decompressSmart } from "../src/store/compression.js";
-import { loadMetrics, fpRate, p95, defaultMetricsPath } from "../src/monitoring.js";
+import { loadMetrics, fpRate, p95, defaultMetricsPath, defaultEventsPath } from "../src/monitoring.js";
 import { C, recentUserQuery } from "./mega-runtime.js";
 import { runCompact, doRecall, doRecallAsync } from "./mega-pipeline.js";
 import { vectorStats, vectorRepoStats, vectorDataInvariant } from "../src/vectorStore.js";
 import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only (no network)
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { createRequire } from "node:module";
@@ -260,6 +260,58 @@ export function registerCommands(pi, runtime, config) {
                 `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
         },
     });
+    /**
+     * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+     * Best-effort, non-fatal — returns true if a low-quality signal was found.
+     */
+    /**
+     * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+     * Best-effort, non-fatal — returns true if a low-quality signal was found.
+     */
+    function checkRecallQuality(stateDir) {
+        const eventPaths = [
+            defaultEventsPath(stateDir),
+            path.join(stateDir, "mega-compact.log"),
+        ];
+        for (const fp of eventPaths) {
+            try {
+                if (!existsSync(fp))
+                    continue;
+                const buf = readFileSync(fp, { encoding: "utf-8" });
+                // Only scan last 64 KiB of the file
+                const tail = buf.length > 65536 ? buf.slice(buf.length - 65536) : buf;
+                const lines = tail.split("\n").filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        // guardrails-allow PREVENT-001: JSON.parse with null check
+                        const parsed = JSON.parse(line);
+                        if (typeof parsed !== "object" || parsed === null)
+                            continue;
+                        // Check for recall_metrics_low_quality event (latest format)
+                        if (parsed.event === "recall_metrics_low_quality" && parsed.score !== undefined) {
+                            if (typeof parsed.score === "number" && parsed.score < 0.4)
+                                return true;
+                        }
+                        // Check for recall_metrics with low relevanceScore
+                        if (parsed.event === "recall_metrics" && parsed.relevanceScore !== undefined) {
+                            if (typeof parsed.relevanceScore === "number" && parsed.relevanceScore < 0.4)
+                                return true;
+                        }
+                        // Check for RecallQualityEvent format from monitoring.ts
+                        if (parsed.score !== undefined && typeof parsed.score === "number" && parsed.score < 0.4)
+                            return true;
+                    }
+                    catch {
+                        // skip unparseable lines
+                    }
+                }
+            }
+            catch {
+                // non-fatal: skip if can't read
+            }
+        }
+        return false;
+    }
     pi.registerCommand("mega-setup", {
         description: "Local embedding setup wizard — detect available embedders and configure mega-compact.",
         handler: async (_args, ctx) => {
@@ -335,6 +387,10 @@ export function registerCommands(pi, runtime, config) {
                 catch {
                     // require error
                 }
+                // --- 2.5 Quality check ---
+                // Scan recent events for low recall quality (best-effort, non-fatal)
+                const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
+                const lowRecallQuality = checkRecallQuality(stateDir);
                 const choices = [];
                 if (ollamaDetected && ollamaRunning) {
                     const model = ollamaModels.find((m) => m.includes("nomic-embed") ||
@@ -370,6 +426,9 @@ export function registerCommands(pi, runtime, config) {
                 });
                 // --- 4. Prompt user ---
                 log(`Current embedder: ${currentEmbedder}`);
+                if (lowRecallQuality) {
+                    log("Tap: recent recall quality is low. Consider switching to Ollama or llama.cpp for better results.");
+                }
                 let selected = "trigram";
                 if (choices.length > 1) {
                     try {
@@ -403,7 +462,6 @@ export function registerCommands(pi, runtime, config) {
                     ];
                     const envContent = lines.join("\n") + "\n";
                     // Write .mega-compact.env to state dir
-                    const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
                     try {
                         mkdirSync(stateDir, { recursive: true });
                         writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
@@ -421,7 +479,6 @@ export function registerCommands(pi, runtime, config) {
                         `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
                     ];
                     const envContent = lines.join("\n") + "\n";
-                    const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
                     try {
                         mkdirSync(stateDir, { recursive: true });
                         writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
@@ -435,7 +492,10 @@ export function registerCommands(pi, runtime, config) {
                     log("ONNX Runtime configuration is experimental.\n\nSet MEGACOMPACT_EMBEDDING_URL to your local ONNX server URL, or see docs for manual setup.\nKeeping TrigramEmbedder for now.");
                 }
                 else {
-                    log("Keeping TrigramEmbedder (default). No configuration needed.");
+                    const qualityTip = lowRecallQuality
+                        ? " Recent recall quality is low — consider running /mega-setup again to switch to Ollama or llama.cpp for better results."
+                        : "";
+                    log(`Keeping TrigramEmbedder (default). No configuration needed.${qualityTip}`);
                 }
             }
             catch (e) {

package/dist/extensions/mega-config.js

@@ -168,11 +168,18 @@ export function loadConfig() {
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
         messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", false),
+        cacheStriping: envBool("MEGACOMPACT_CACHE_STRIPING", false),
         tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
         ragQueryReformulation: envBool("MEGACOMPACT_QUERY_REFORMULATION", false),
         ragTieredRouter: envBool("MEGACOMPACT_TIERED_ROUTER", false),
         ragRecallMetrics: envBool("MEGACOMPACT_RECALL_METRICS", false),
         ragMemoryGraph: envBool("MEGACOMPACT_MEMORY_GRAPH", false),
+        wikiSeedFromTurns: envBool("MEGACOMPACT_WIKI_SEED_FROM_TURNS", true),
+        memoryGraphSeedTurns: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_TURNS", true),
+        memoryGraphSeedTurnContent: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_TURN_CONTENT", true),
+        memoryGraphSeedMemories: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_MEMORIES", true),
+        memoryGraphCrossTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_CROSS_TYPE_THRESHOLD", 0.85),
+        memoryGraphWithinTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_WITHIN_TYPE_THRESHOLD", 0.7),
         // D.1: env-overridable recompact delta (minimum context growth % before
         // re-compacting instead of replaying the cached live trim). Default 50.
         recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

package/dist/extensions/mega-events/agent-handlers.js

@@ -9,6 +9,9 @@ import { classifyError, classifyErrorDetailed, errorRetryBackoffMs, extractError
 import { safeSendUserMessage } from "./send-safe.js";
 import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
+import { defaultEmbedder } from "../../src/embedder.js";
+import { storeTopicEmbedding, loadTopicEmbedding, detectTopicShift, } from "./separated-prompt.js";
+import { refreshStripeAssignments as writeStripeAssignments, } from "../../src/cache-stripe-impl.js";
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(pi, runtime, config) {
     // ---- Agent tracking for real-time widget + status-line updates ---------
@@ -130,10 +133,21 @@ export function registerAgentHandlers(pi, runtime, config) {
                     // context-handler.ts:258-287 so both call sites stay in sync.
                     const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
                     const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+                    // CRITICAL-OVER ESCAPE HATCH: when context is critically over the
+                    // window (>= 90%), force the durable ctx.compact() even if
+                    // piCompactWouldNoop says it would no-op ("Already compacted").
+                    // Without this, the on-disk transcript never truncates and the
+                    // session stays overflowed on every resume — the "Already
+                    // compacted" + overflow death-spiral (2026-08-01 incident). The
+                    // cooldown still applies (we don't spam compact), but the no-op
+                    // gate is bypassed when critical. pi's ctx.compact() may throw
+                    // "Already compacted" in the truly-no-op case — wrapped in
+                    // try/catch so the throw is non-fatal.
+                    const criticalOver = (runtime.lastCtxPercent ?? 0) >= 90;
                     if (sinceCompact < cooldownMs) {
                         runtime.diagAgentEndDurableSkipRecent++;
                     }
-                    else if (!piCompactWouldNoop(ctx)) {
+                    else if (criticalOver || !piCompactWouldNoop(ctx)) {
                         runtime.debounceUntil = now + 2000;
                         runtime.diagAgentEndDurable++;
                         runtime.logger.info("agent-end-durable-trigger", {
@@ -150,6 +164,7 @@ export function registerAgentHandlers(pi, runtime, config) {
                             // would re-check before it lands.
                             const stamp = runtime.rt.lastNativeCompactAt;
                             const liveSid = runtime.rt.sessionId;
+                            const liveCritical = criticalOver;
                             setTimeout(() => {
                                 try {
                                     if (runtime.rt.sessionId !== liveSid)
@@ -161,19 +176,26 @@ export function registerAgentHandlers(pi, runtime, config) {
                                     if (runtime.rt.lastNativeCompactAt !== stamp &&
                                         since2 < cooldownMs)
                                         return;
-                                    if (piCompactWouldNoop(ctx))
+                                    // CRITICAL-OVER ESCAPE HATCH: bypass the no-op gate when
+                                    // critical (captured at handler time) so the durable trim fires.
+                                    if (!liveCritical && piCompactWouldNoop(ctx))
                                         return;
                                     ctx.compact({
                                         customInstructions: undefined,
-                                    }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated.
+                                    }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. May throw "Already compacted" when the escape hatch forces it — caught below.
                                 }
                                 catch {
-                                    /* non-fatal */
+                                    /* non-fatal: "Already compacted" throws are expected when the critical-over hatch forces a no-op compact */
                                 }
                             }, 500);
                         }
                         else {
-                            ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastNativeCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+                            try {
+                                ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. May throw "Already compacted" when the critical-over escape hatch forces it — caught.
+                            }
+                            catch {
+                                /* non-fatal */
+                            }
                         }
                         didDurableTrim = true;
                     }
@@ -712,5 +734,52 @@ export function registerAgentHandlers(pi, runtime, config) {
         catch {
             /* non-fatal: a classifier/retry failure never breaks the agent loop */
         }
+        // P3.5: topic-shift stripe refresh. When MEGACOMPACT_CACHE_STRIPING is ON,
+        // embed the current turn, detect topic shift vs. the previous turn, and
+        // refresh cache stripe assignments when shifted (or first turn). Best-effort:
+        // failures log + continue, never break the agent loop.
+        if (config.cacheStriping) {
+            try {
+                const stateDir = runtime.currentStateDir;
+                const sessionId = runtime.rt.sessionId;
+                const currentTurn = event.turnIndex;
+                const embedder = defaultEmbedder();
+                // (a) Extract text from the assistant's response for topic embedding.
+                let textToEmbed = "";
+                const msg = event.message;
+                if (msg.role === "assistant" && Array.isArray(msg.content)) {
+                    for (const part of msg.content) {
+                        if ("text" in part && typeof part.text === "string") {
+                            textToEmbed += part.text + " ";
+                        }
+                    }
+                }
+                textToEmbed = textToEmbed.trim() || `turn-${currentTurn}`;
+                const embedding = new Float32Array(embedder.embed(textToEmbed));
+                storeTopicEmbedding(stateDir, sessionId, currentTurn, embedding);
+                // (b) Load previous turn's embedding and detect topic shift.
+                const prevEmb = currentTurn > 0
+                    ? loadTopicEmbedding(stateDir, sessionId, currentTurn - 1)
+                    : null;
+                const shifted = currentTurn === 0 || detectTopicShift(embedding, prevEmb);
+                // (c) If shifted (or first turn), refresh stripe assignments (WRITE path).
+                let chunkCount = 0;
+                if (shifted) {
+                    chunkCount = writeStripeAssignments(stateDir, undefined, embedder, (detail) => runtime.logger.info("stripe_refresh_detail", {
+                        detail,
+                        turnIndex: currentTurn,
+                    }));
+                }
+                // (d) Log the refresh outcome.
+                runtime.logger.info("stripe_refresh", {
+                    turnIndex: currentTurn,
+                    shifted,
+                    chunkCount,
+                });
+            }
+            catch {
+                /* non-fatal: stripe refresh never breaks the agent loop */
+            }
+        }
     });
 }