@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/agents/run-thread.ts

@@ -13,7 +13,7 @@ import { autoCompactionKeepLast, compactAgentThread } from "@/lib/agents/thread-
 import { kickBoundaryCompaction, kickWarmSummaryRefresh, pendingCompactionBoundarySeq } from "@/lib/agents/warm-summary-background";
 import { moveThreadContextBoundary } from "@/lib/agents/context-boundary";
 import { getForegroundTabPresence } from "@/lib/api/foreground-presence";
-import { addMessage, capToolEventPayload, countThreadMessagesFromSeq, getMessagesPage, isValidThreadContextCursor, pruneThreadMessages, getRecentlyUsedToolNames, getRecentMessagesWindow, getThread, getThreadMessageBySeq, mergeMessageMetadata, touchThread, updateMessageContent, type MessageTranscriptStatus, type PersistedToolEvent } from "@/lib/stores/threads";
+import { addMessage, capToolEventPayload, countForegroundThreadMessages, getMessagesPage, isValidThreadContextCursor, pruneThreadMessages, getRecentlyUsedToolNames, getRecentMessagesWindow, getThread, getThreadMessageBySeq, mergeMessageMetadata, touchThread, updateMessageContent, type MessageTranscriptStatus, type PersistedToolEvent } from "@/lib/stores/threads";
 import { transcriptText } from "@/lib/agents/conversation-summary";
 import { getMaskRunContext } from "@/lib/redaction/context";
 import { recordToolUsage } from "@/lib/stores/tool-stats";
@@ -22,6 +22,14 @@ import { startScheduler } from "@/lib/scheduler";
 import { recall, type RecalledMemory } from "@/lib/embeddings";
 import { getMemoryPolicy } from "@/lib/stores/app-settings";
 import { validateAssistantOutput } from "@/lib/agents/output-validator";
+import {
+  buildWorkflowStepRetryNudge,
+  collectWorkflowContractFailures,
+  planWorkflowStepRetries,
+  WORKFLOW_TURN_AUTO_RETRY_LIMIT,
+  workflowProgressArgs,
+  type WorkflowProgressObservation,
+} from "@/lib/agents/workflow-step-retry";
 import { getDefaultModelConfig, getModelConfig, getModelParams, isModelConfigEnabled, listEnabledModelConfigs } from "@/lib/stores/model-config";
 import {
   buildHistoryWindow,
@@ -162,10 +170,19 @@ function hotTurnBoundary(
   return boundary?.seq ?? null;
 }
 
+// The topic-aware boundary keeps the whole active topic hot, so user turns
+// since the pin usually still exceed the limit right after a commit. Without a
+// cooldown every following turn re-runs the topic LLM pass only to land on the
+// same pin. Skip the next half-limit turns (2 rows per turn) before re-checking.
+export function hotTurnCooldownUntil(messageCount: number, hotTurnLimit: number | null | undefined): number {
+  const turnLimit = hotTurnLimit ?? DEFAULT_HOT_TURN_LIMIT;
+  const skipTurns = Math.max(1, Math.ceil(Math.max(1, turnLimit) / 2));
+  return messageCount + skipTurns * 2 + 1;
+}
+
 async function maybeAutoCompactOversizedThread(
   agentId: string,
   threadId: string,
-  messageCount: number,
   onCompacting?: () => void,
   preserveNewestMessages = 0,
 ): Promise<void> {
@@ -173,12 +190,17 @@ async function maybeAutoCompactOversizedThread(
   const keepLast = autoCompactionKeepLast(cap);
   const retainedMessages = keepLast + preserveNewestMessages;
   const triggerAt = cap + (cap - keepLast);
-  if (!Number.isFinite(cap) || cap <= 0 || messageCount < triggerAt) return;
+  if (!Number.isFinite(cap) || cap <= 0) return;
+  // Only foreground rows are ever pruned; counting bridge/watcher/scheduled
+  // rows would re-trigger an LLM compaction on every turn of a busy bridge
+  // agent without ever bringing the count back under the cap.
+  const messageCount = countForegroundThreadMessages(threadId);
+  if (messageCount < triggerAt) return;
   try {
     // A pin that already keeps the hot tier within the retained range must not
     // be pulled back to the cutoff, nor re-summarised by an LLM on every turn.
     const pinSeq = getThread(threadId)?.hot_since_seq ?? null;
-    if (pinSeq !== null && countThreadMessagesFromSeq(threadId, pinSeq) <= retainedMessages) {
+    if (pinSeq !== null && countForegroundThreadMessages(threadId, pinSeq) <= retainedMessages) {
       pruneThreadMessages(threadId, retainedMessages, pinSeq);
       return;
     }
@@ -229,7 +251,6 @@ export class RunThreadError extends Error {
 
 export interface PersistedThreadRunUserMessage {
   attachments?: ContentPart[];
-  messageCountBefore: number;
   idleMsBefore: number | null;
   userMessageId: string;
   storedContent: string;
@@ -248,7 +269,6 @@ export async function persistThreadRunUserMessage(
     throw new RunThreadError(400, "message required", "message_required");
   }
 
-  const messageCountBefore = thread.message_count;
   const autoBoundaryScope = req.context_profile?.history_scope
     ?? (req.user_category === "bridge" ? "bridge" : "foreground");
   const idleMsBefore = isAutoBoundaryEligibleCategory(req.user_category)
@@ -279,7 +299,6 @@ export async function persistThreadRunUserMessage(
 
   return {
     attachments: spilledAttachments,
-    messageCountBefore,
     idleMsBefore,
     userMessageId: userMessage.msg_id,
     storedContent: stored,
@@ -478,8 +497,8 @@ export async function prepareThreadRun(req: ThreadRunRequest): Promise<PreparedT
     await maybeAutoCompactOversizedThread(
       agentCfg.id,
       req.thread_id,
-      req._message_count_before_user ?? thread.message_count,
       req._onCompacting,
+
       req._user_message_persisted ? 2 : 0,
     );
   }
@@ -544,7 +563,11 @@ export async function prepareThreadRun(req: ThreadRunRequest): Promise<PreparedT
         && latestThread.message_count < (latestThread.auto_boundary_locked_until_msg_count ?? 0);
       if (!locked) {
         const boundary = hotTurnBoundary(req.thread_id, agentCfg, autoBoundaryScope);
-        if (boundary !== null) kickBoundaryCompaction(req.thread_id, boundary);
+        if (boundary !== null) {
+          kickBoundaryCompaction(req.thread_id, boundary, {
+            autoBoundaryLockedUntilMessageCount: hotTurnCooldownUntil(latestThread?.message_count ?? 0, agentCfg.hot_turn_limit),
+          });
+        }
       }
     }
   }
@@ -1135,6 +1158,10 @@ async function* stallRetryStream(
   // turns where the model's claimed action didn't actually happen.
   const toolCallIds = new Map<string, string>();
   const failedProxyCallIds = new Set<string>();
+  // workflow_progress calls (direct or proxied) awaiting their result, so the
+  // step contract can be checked from observed tool output at turn end.
+  const pendingWorkflowArgs = new Map<string, Record<string, unknown>>();
+  const workflowObservations: WorkflowProgressObservation[] = [];
   let loopedToolName: string | null = null;
   let doneChunk: StreamChunk | null = null;
   let sawError = false;
@@ -1153,7 +1180,11 @@ async function* stallRetryStream(
       const name = unwrapInvokedToolName(rawName, args);
       if (name) {
         toolNames.push(name);
-        if (typeof data?.id === "string") toolCallIds.set(data.id, name);
+        if (typeof data?.id === "string") {
+          toolCallIds.set(data.id, name);
+          const workflowArgs = workflowProgressArgs(rawName, args);
+          if (workflowArgs) pendingWorkflowArgs.set(data.id, workflowArgs);
+        }
         const sig = toolCallSignature(rawName, args);
         const count = (signatureCounts.get(sig) ?? 0) + 1;
         signatureCounts.set(sig, count);
@@ -1183,6 +1214,10 @@ async function* stallRetryStream(
           failedProxyCallIds.add(data.id);
         }
       }
+      if (typeof data?.id === "string" && pendingWorkflowArgs.has(data.id)) {
+        workflowObservations.push({ args: pendingWorkflowArgs.get(data.id), result: data.result });
+        pendingWorkflowArgs.delete(data.id);
+      }
       const summary = summarizeRetryValue(data?.result).trim();
       if (summary) {
         const clipped = summary.length > 240 ? `${summary.slice(0, 237)}...` : summary;
@@ -1322,6 +1357,10 @@ async function* stallRetryStream(
   const citationFail = uncitedHighClaims.length > 0;
 
   if (!stalled && !looped && fabrication.ok && !citationFail) {
+    if (!sawError && workflowObservations.length > 0) {
+      yield* workflowStepRetryStream(workflowObservations, originalReq, retriesLeft, attemptAbort, doneChunk, textBuf, toolNames, toolResultSummaries);
+      return;
+    }
     if (doneChunk) yield doneChunk;
     return;
   }
@@ -1449,6 +1488,67 @@ async function* stallRetryStream(
   }
 }
 
+// Workflow step contract auto-retry. Runs only after every other quality
+// gate passed, and has its own per-step budget (WORKFLOW_STEP_MAX_ATTEMPTS)
+// so a stall retry earlier in the turn never starves it. The retry is an
+// append-mode continuation: the turn's work stays visible, followed by the
+// model redoing only the failed steps.
+async function* workflowStepRetryStream(
+  observations: readonly WorkflowProgressObservation[],
+  originalReq: ThreadRunRequest,
+  stallRetriesLeft: number,
+  attemptAbort: AbortController,
+  doneChunk: StreamChunk | null,
+  textBuf: string,
+  toolNames: readonly string[],
+  toolResultSummaries: readonly string[],
+): AsyncGenerator<StreamChunk> {
+  const spent = originalReq._workflow_step_retries ?? {};
+  const failures = collectWorkflowContractFailures(observations);
+  const { retry, exhausted } = planWorkflowStepRetries(failures, spent);
+  const spentTotal = Object.values(spent).reduce((sum, n) => sum + n, 0);
+
+  if (retry.length === 0 || spentTotal >= WORKFLOW_TURN_AUTO_RETRY_LIMIT) {
+    const unresolved = [...exhausted, ...retry];
+    if (unresolved.length > 0) {
+      console.warn(
+        `[workflow-retry] contract still failing after auto-retry: ${unresolved.map((f) => f.key).join(", ")} thread=${originalReq.thread_id}`,
+      );
+      yield {
+        type: "text_delta",
+        data: {
+          delta: `\n\n*⚠️ Workflow step${unresolved.length === 1 ? "" : "s"} still failing the step contract after automatic retries: ${unresolved.slice(0, 4).map((f) => `"${f.label}"`).join(", ")}. Use the step's retry button or review it manually.*`,
+        },
+      };
+    }
+    if (doneChunk) yield doneChunk;
+    return;
+  }
+
+  console.warn(
+    `[workflow-retry] retrying ${retry.map((f) => `${f.key}#${f.attempt}`).join(", ")} thread=${originalReq.thread_id}`,
+  );
+  yield { type: "text_delta", data: { delta: "\n\n↻ " } };
+  const nudge = buildWorkflowStepRetryNudge(retry);
+  const retryContext = buildRetryContextSummary(textBuf, [...toolNames], [...toolResultSummaries]);
+  const nudgeWithContext = retryContext ? `${nudge}\n\n${retryContext}` : nudge;
+  const nextSpent: Record<string, number> = { ...spent };
+  for (const failure of retry) nextSpent[failure.key] = (nextSpent[failure.key] ?? 0) + 1;
+
+  attemptAbort.abort("workflow_step_retry");
+  const next = await prepareThreadRun({
+    ...originalReq,
+    message: nudgeWithContext,
+    attachments: undefined,
+    _stall_retries_left: stallRetriesLeft,
+    _workflow_step_retries: nextSpent,
+    _retry_count: (originalReq._retry_count ?? 0) + 1,
+    _skip_persist_message: true,
+    _history_append_message: nudgeWithContext,
+  });
+  for await (const chunk of next.stream) yield chunk;
+}
+
 export interface AssistantUsageSnapshot {
   input_tokens: number;
   output_tokens: number;

package/lib/agents/sqlite-checkpoint-saver.test.ts

@@ -165,3 +165,94 @@ describe("NodeSqliteSaver", () => {
     expect(tuple).toBeUndefined();
   });
 });
+
+describe("NodeSqliteSaver edge cases", () => {
+  async function chain(saver: NodeSqliteSaver, thread: string, count: number, ns = ""): Promise<string[]> {
+    const ids: string[] = [];
+    let parent: string | undefined;
+    for (let i = 0; i < count; i++) {
+      const ck = newCheckpoint();
+      await saver.put(
+        { configurable: { thread_id: thread, checkpoint_ns: ns, ...(parent ? { checkpoint_id: parent } : {}) } },
+        ck,
+        { ...META_BASE, step: i },
+      );
+      ids.push(ck.id);
+      parent = ck.id;
+    }
+    return ids;
+  }
+
+  it("links each checkpoint to its parent and returns no parent for the first one", async () => {
+    const saver = newSaver();
+    const [first, second] = await chain(saver, "t-parent", 2);
+    const latest = await saver.getTuple(cfg("t-parent"));
+    expect(latest?.checkpoint.id).toBe(second);
+    expect(latest?.parentConfig?.configurable?.checkpoint_id).toBe(first);
+    expect((await saver.getTuple(cfg("t-parent", first)))?.parentConfig).toBeUndefined();
+  });
+
+  it("keeps checkpoint namespaces (subgraphs) isolated within one thread", async () => {
+    const saver = newSaver();
+    const [root] = await chain(saver, "t-ns", 1, "");
+    const [child] = await chain(saver, "t-ns", 1, "sub:1");
+    const rootLatest = await saver.getTuple({ configurable: { thread_id: "t-ns", checkpoint_ns: "" } });
+    const childLatest = await saver.getTuple({ configurable: { thread_id: "t-ns", checkpoint_ns: "sub:1" } });
+    expect(rootLatest?.checkpoint.id).toBe(root);
+    expect(childLatest?.checkpoint.id).toBe(child);
+    expect(childLatest?.config.configurable?.checkpoint_ns).toBe("sub:1");
+  });
+
+  it("pages list() with before, newest first, without repeating the cursor", async () => {
+    const saver = newSaver();
+    const ids = await chain(saver, "t-before", 4);
+    const page = [];
+    for await (const tuple of saver.list(cfg("t-before"), { before: cfg("t-before", ids[2]), limit: 10 })) page.push(tuple.checkpoint.id);
+    expect(page).toEqual([ids[1], ids[0]]);
+  });
+
+  it("returns pending writes for the checkpoint they belong to, and replaces a retried task's writes", async () => {
+    const saver = newSaver();
+    const [first, second] = await chain(saver, "t-writes", 2);
+    await saver.putWrites(cfg("t-writes", second), [["messages", { text: "draft" }], ["status", "running"]], "task-1");
+    await saver.putWrites(cfg("t-writes", second), [["messages", { text: "final" }], ["status", "done"]], "task-1");
+    await saver.putWrites(cfg("t-writes", first), [["messages", { text: "old" }]], "task-0");
+
+    const latest = await saver.getTuple(cfg("t-writes"));
+    expect(latest?.pendingWrites).toEqual([
+      ["task-1", "messages", { text: "final" }],
+      ["task-1", "status", "done"],
+    ]);
+    const older = await saver.getTuple(cfg("t-writes", first));
+    expect(older?.pendingWrites).toEqual([["task-0", "messages", { text: "old" }]]);
+  });
+
+  it("round-trips non-ASCII and large channel values", async () => {
+    const saver = newSaver();
+    const ck = newCheckpoint();
+    const text = `你好 👋 ${"x".repeat(200_000)}`;
+    (ck.channel_values as Record<string, unknown>).messages = [{ text }];
+    await saver.put(cfg("t-big"), ck, META_BASE);
+    await saver.putWrites(cfg("t-big", ck.id), [["note", text]], "task");
+    const tuple = await saver.getTuple(cfg("t-big"));
+    expect((tuple?.checkpoint.channel_values as Record<string, unknown>).messages).toEqual([{ text }]);
+    expect(tuple?.pendingWrites?.[0][2]).toBe(text);
+  });
+
+  it("rejects writes without a checkpoint_id and puts without a thread_id", async () => {
+    const saver = newSaver();
+    await expect(saver.putWrites(cfg("t-x"), [["c", 1]], "task")).rejects.toThrow(/checkpoint_id/);
+    await expect(saver.put({ configurable: {} }, newCheckpoint(), META_BASE)).rejects.toThrow(/thread_id/);
+  });
+
+  it("deleteThread leaves other threads untouched", async () => {
+    const saver = newSaver();
+    const [keep] = await chain(saver, "t-keep", 1);
+    const [drop] = await chain(saver, "t-drop", 1);
+    await saver.putWrites(cfg("t-keep", keep), [["c", 1]], "task");
+    await saver.putWrites(cfg("t-drop", drop), [["c", 2]], "task");
+    await saver.deleteThread("t-drop");
+    expect(await saver.getTuple(cfg("t-drop"))).toBeUndefined();
+    expect((await saver.getTuple(cfg("t-keep")))?.pendingWrites).toEqual([["task", "c", 1]]);
+  });
+});

package/lib/agents/thread-activity.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { finishRun, startRun } from "./run-registry";
+import { __resetCompactionAttemptsForTests, runTrackedCompaction } from "./thread-compaction-state";
+import { getThreadActivity } from "./thread-activity";
+
+describe("getThreadActivity", () => {
+  afterEach(() => __resetCompactionAttemptsForTests());
+
+  it("is idle for a thread with nothing running", () => {
+    expect(getThreadActivity(`idle-${Date.now()}`)).toEqual({ run: null, queue_depth: 0, compaction: null, busy: false });
+  });
+
+  it("reports the live run phase and drops it once the run finishes", () => {
+    const tid = `run-${Date.now()}`;
+    const run = startRun(tid, "agent-1");
+    const live = getThreadActivity(tid);
+    expect(live.busy).toBe(true);
+    expect(live.run).toMatchObject({ phase: "starting", label: "Starting…", agent_id: "agent-1" });
+    finishRun(run, "done");
+    expect(getThreadActivity(tid).run).toBeNull();
+  });
+
+  it("reports a compaction with no run as busy", () => {
+    const tid = `compact-${Date.now()}`;
+    void runTrackedCompaction(tid, "auto", 7, () => new Promise<void>(() => {}), 60_000);
+    const snapshot = getThreadActivity(tid);
+    expect(snapshot.busy).toBe(true);
+    expect(snapshot.run).toBeNull();
+    expect(snapshot.compaction).toMatchObject({ kind: "auto", boundary_seq: 7 });
+  });
+});

package/lib/agents/thread-activity.ts

@@ -0,0 +1,27 @@
+import { getRun } from "@/lib/agents/run-registry";
+import { getQueueDepth } from "@/lib/agents/run-queue";
+import { currentCompaction, type CompactionKind } from "@/lib/agents/thread-compaction-state";
+
+/** What a thread is doing right now, as one snapshot the UI can poll. */
+export interface ThreadActivity {
+  /** The live agent turn, if one is running. */
+  run: { phase: string; label: string; started_at: number; agent_id: string | null } | null;
+  /** Turns held in the per-thread queue, including one about to start. */
+  queue_depth: number;
+  /** The most significant compaction running on the thread, if any. */
+  compaction: { kind: CompactionKind; boundary_seq: number | null; started_at: number; deadline_at: number } | null;
+  busy: boolean;
+}
+
+export function getThreadActivity(threadId: string): ThreadActivity {
+  const active = getRun(threadId);
+  const run = active && active.status === "running"
+    ? { phase: active.phase, label: active.phase_label, started_at: active.started_at, agent_id: active.agent_id }
+    : null;
+  const queue_depth = getQueueDepth(threadId);
+  const attempt = currentCompaction(threadId);
+  const compaction = attempt
+    ? { kind: attempt.kind, boundary_seq: attempt.boundarySeq, started_at: attempt.startedAt, deadline_at: attempt.deadlineAt }
+    : null;
+  return { run, queue_depth, compaction, busy: run !== null || queue_depth > 0 || compaction !== null };
+}

package/lib/agents/thread-compaction-state.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/lib/env/config", () => ({ getConfig: () => ({ compactionTimeoutMs: 60_000 }) }));
+
+import {
+  CompactionTimeoutError,
+  __resetCompactionAttemptsForTests,
+  currentCompaction,
+  getCompactionAttempt,
+  isCompactionRunning,
+  runTrackedCompaction,
+  type CompactionAttempt,
+} from "./thread-compaction-state";
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => { resolve = r; });
+  return { promise, resolve };
+}
+
+describe("thread-compaction-state", () => {
+  beforeEach(() => __resetCompactionAttemptsForTests());
+  afterEach(() => vi.useRealTimers());
+
+  it("registers the attempt synchronously and releases it when it settles", async () => {
+    const gate = deferred<string>();
+    const run = runTrackedCompaction("t1", "manual", 5, () => gate.promise);
+    expect(isCompactionRunning("t1")).toBe(true);
+    expect(isCompactionRunning("t1", "manual")).toBe(true);
+    expect(getCompactionAttempt("t1", "manual")?.boundarySeq).toBe(5);
+    gate.resolve("ok");
+    await expect(run).resolves.toBe("ok");
+    expect(isCompactionRunning("t1")).toBe(false);
+  });
+
+  it("releases the attempt when the run throws", async () => {
+    await expect(runTrackedCompaction("t1", "auto", 1, async () => { throw new Error("boom"); })).rejects.toThrow("boom");
+    expect(isCompactionRunning("t1")).toBe(false);
+  });
+
+  it("times out, rejects, and stops the attempt from being current", async () => {
+    vi.useFakeTimers();
+    let seen: CompactionAttempt | null = null;
+    const run = runTrackedCompaction("t1", "refresh", null, (a) => { seen = a; return new Promise<void>(() => {}); }, 1_000);
+    const settled = expect(run).rejects.toBeInstanceOf(CompactionTimeoutError);
+    expect(seen!.isCurrent()).toBe(true);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await settled;
+    expect(seen!.isCurrent()).toBe(false);
+    expect(isCompactionRunning("t1")).toBe(false);
+  });
+
+  it("reports the most significant compaction first", () => {
+    const hold = () => new Promise<void>(() => {});
+    void runTrackedCompaction("t1", "refresh", null, hold);
+    void runTrackedCompaction("t1", "auto", 3, hold);
+    expect(currentCompaction("t1")?.kind).toBe("auto");
+    void runTrackedCompaction("t1", "manual", 4, hold);
+    expect(currentCompaction("t1")?.kind).toBe("manual");
+    expect(currentCompaction("t2")).toBeNull();
+  });
+
+  it("invalidates an attempt replaced by a newer one of the same kind", async () => {
+    let first: CompactionAttempt | null = null;
+    const gate = deferred<void>();
+    const a = runTrackedCompaction("t1", "auto", 1, (att) => { first = att; return gate.promise; });
+    const b = runTrackedCompaction("t1", "auto", 2, () => new Promise<void>(() => {}));
+    expect(first!.isCurrent()).toBe(false);
+    gate.resolve();
+    await a;
+    // Settling the stale attempt must not release the newer one.
+    expect(getCompactionAttempt("t1", "auto")?.boundarySeq).toBe(2);
+    void b;
+  });
+
+  it("shares state across module instances", async () => {
+    void runTrackedCompaction("t1", "manual", 9, () => new Promise<void>(() => {}));
+    vi.resetModules();
+    const fresh = await import("./thread-compaction-state");
+    expect(fresh.isCompactionRunning("t1", "manual")).toBe(true);
+  });
+});

package/lib/agents/thread-compaction-state.ts

@@ -0,0 +1,121 @@
+import { getConfig } from "@/lib/env/config";
+import { getOrCreateGlobal } from "@/lib/utils/global-state";
+
+// Every compaction is bound to its thread: one attempt per kind per thread,
+// held in process-global state so each route bundle sees the same attempts
+// (the compact route and the thread GET route must agree on "compacting"),
+// and bounded by a deadline so a stalled provider can't leave a thread
+// "compacting" until the next restart.
+
+export type CompactionKind = "manual" | "auto" | "refresh";
+
+export interface CompactionAttempt {
+  readonly threadId: string;
+  readonly kind: CompactionKind;
+  readonly boundarySeq: number | null;
+  readonly startedAt: number;
+  readonly deadlineAt: number;
+  /** False once the attempt timed out or was replaced; it must not commit. */
+  isCurrent(): boolean;
+}
+
+export class CompactionTimeoutError extends Error {
+  constructor(threadId: string, kind: CompactionKind, timeoutMs: number) {
+    super(`${kind} compaction for thread ${threadId} timed out after ${timeoutMs} ms`);
+    this.name = "CompactionTimeoutError";
+  }
+}
+
+const attempts = getOrCreateGlobal(
+  "__jarela_thread_compaction_attempts",
+  () => new Map<string, Map<CompactionKind, CompactionAttempt>>(),
+);
+
+function slotFor(threadId: string): Map<CompactionKind, CompactionAttempt> {
+  let slot = attempts.get(threadId);
+  if (!slot) { slot = new Map(); attempts.set(threadId, slot); }
+  return slot;
+}
+
+function release(attempt: CompactionAttempt): void {
+  const slot = attempts.get(attempt.threadId);
+  if (slot?.get(attempt.kind) !== attempt) return;
+  slot.delete(attempt.kind);
+  if (slot.size === 0) attempts.delete(attempt.threadId);
+}
+
+export function getCompactionAttempt(threadId: string, kind: CompactionKind): CompactionAttempt | null {
+  return attempts.get(threadId)?.get(kind) ?? null;
+}
+
+export function isCompactionRunning(threadId: string, kind?: CompactionKind): boolean {
+  const slot = attempts.get(threadId);
+  if (!slot) return false;
+  return kind ? slot.has(kind) : slot.size > 0;
+}
+
+const KIND_PRIORITY: readonly CompactionKind[] = ["manual", "auto", "refresh"];
+
+/** The most significant compaction running on the thread, if any. */
+export function currentCompaction(threadId: string): CompactionAttempt | null {
+  const slot = attempts.get(threadId);
+  if (!slot) return null;
+  for (const kind of KIND_PRIORITY) {
+    const attempt = slot.get(kind);
+    if (attempt) return attempt;
+  }
+  return null;
+}
+
+/**
+ * Register a compaction on the thread synchronously, run it, and release it
+ * when it settles or its deadline passes. On timeout the attempt stops being
+ * current — pass it to compactThreadWarmContext so a late result is dropped
+ * instead of committed — and the promise rejects with CompactionTimeoutError.
+ * A newer attempt of the same kind replaces (and invalidates) an older one.
+ */
+export function runTrackedCompaction<T>(
+  threadId: string,
+  kind: CompactionKind,
+  boundarySeq: number | null,
+  run: (attempt: CompactionAttempt) => Promise<T>,
+  timeoutMs: number = getConfig().compactionTimeoutMs,
+): Promise<T> {
+  const startedAt = Date.now();
+  let current = true;
+  const attempt: CompactionAttempt = {
+    threadId,
+    kind,
+    boundarySeq,
+    startedAt,
+    deadlineAt: startedAt + timeoutMs,
+    isCurrent: () => current && attempts.get(threadId)?.get(kind) === attempt,
+  };
+  slotFor(threadId).set(kind, attempt);
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      current = false;
+      release(attempt);
+      reject(new CompactionTimeoutError(threadId, kind, timeoutMs));
+    }, timeoutMs);
+    (timer as { unref?: () => void }).unref?.();
+  });
+
+  let work: Promise<T>;
+  try {
+    work = run(attempt);
+  } catch (err) {
+    work = Promise.reject(err);
+  }
+  return Promise.race([work, deadline]).finally(() => {
+    if (timer) clearTimeout(timer);
+    current = false;
+    release(attempt);
+  });
+}
+
+export function __resetCompactionAttemptsForTests(): void {
+  attempts.clear();
+}