@remnic/core 10.0.92 → 10.0.93

package/src/local-llm-shutdown.test.ts

@@ -0,0 +1,194 @@
+// Shutdown-signal behavioral tests for LocalLlmClient: a daemon stop must
+// abort in-flight chat requests at once (the abort reaches the transport),
+// must not start another attempt once aborted, and must not sit out the
+// retry backoff after abort. Uses the globalThis.fetch seam from
+// local-llm-qos.test.ts with a hanging transport so the real retry loop is
+// exercised, not a mock of it.
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { LocalLlmClient } from "./local-llm.js";
+import { initLogger, resetLogger, type LoggerBackend } from "./logger.js";
+
+/** Captured log lines with the logger's "remnic: " prefix stripped. */
+interface CapturedLog {
+  lines: string[];
+}
+
+function createConfig(memoryDir: string) {
+  return parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: `${memoryDir}/workspace`,
+    localLlmEnabled: true,
+    localLlmModel: "test-local-model",
+    localLlmUrl: "http://127.0.0.1:9",
+    // Mirror the production daemon: a 10-minute budget with 2 attempts, so
+    // an unhonored abort would outlive any sane test deadline.
+    localLlmTimeoutMs: 600_000,
+    localLlmRetry5xxCount: 1,
+    localLlmRetryBackoffMs: 30_000,
+    localLlmHeaders: {},
+    localLlm400TripThreshold: 3,
+    localLlm400CooldownMs: 60_000,
+    localLlmReasoningEffort: "none",
+    debug: false,
+  });
+}
+
+interface HangingFetchSpec {
+  calls: { signal: AbortSignal | undefined }[];
+  sawAbort: boolean;
+  /** Reject with AbortError after delayMs (timeout simulation); default hangs forever. */
+  timeoutAfterMs?: number;
+  /** Resolves when the transport stub is entered (request is in flight). */
+  entered: Promise<void>;
+}
+
+function installHangingFetch(spec: HangingFetchSpec): () => void {
+  const { promise: entered, resolve: markEntered } = Promise.withResolvers<void>();
+  spec.entered = entered;
+  const originalFetch = globalThis.fetch;
+  // SAFETY: the transport passes a string URL and an init with a signal;
+  // this async stub matches that call shape exactly.
+  globalThis.fetch = (async (url: string, init?: { signal?: AbortSignal }) => {
+    void url;
+    const signal = init?.signal;
+    spec.calls.push({ signal });
+    markEntered();
+    const { promise, reject } = Promise.withResolvers<Response>();
+    // A real transport rejects with AbortError when its signal aborts
+    // (undici behavior); the stub must honor it the same way or the client
+    // loop cannot observe the abort.
+    const onAbort = (): void => {
+      spec.sawAbort = true;
+      reject(new DOMException("This operation was aborted", "AbortError"));
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+    if (spec.timeoutAfterMs !== undefined) {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        reject(new DOMException("This operation was aborted", "AbortError"));
+      }, spec.timeoutAfterMs);
+      timer.unref?.();
+    }
+    return await promise;
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = originalFetch;
+  };
+}
+
+/** Polls a real runtime condition (a log line, a stub entry) instead of a
+ *  guessed fixed sleep: the condition, not a duration, gates progress. */
+async function waitFor(
+  predicate: () => boolean,
+  description: string,
+  timeoutMs = 5_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error(`condition not met: ${description}`);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+async function withTestDeadline<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  const { promise: deadline, reject } = Promise.withResolvers<never>();
+  const timer = setTimeout(() => reject(new Error(`${label}: test deadline exceeded (${timeoutMs}ms)`)), timeoutMs);
+  timer.unref?.();
+  try {
+    return await Promise.race([promise, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function installRecordingLogger(): CapturedLog {
+  const lines: string[] = [];
+  const body = (msg: string) => msg.replace(/^remnic: /, "");
+  const backend: LoggerBackend = {
+    info: (msg) => lines.push(body(msg)),
+    warn: (msg) => lines.push(body(msg)),
+    error: (msg) => lines.push(body(msg)),
+  };
+  initLogger(backend, false, { timestamps: false });
+  return { lines };
+}
+
+function quietLogger(): void {
+  initLogger({ info() {}, warn() {}, error() {}, debug() {} }, false);
+}
+
+test("aborting the client shutdown signal aborts an in-flight request and reaches the transport stub", async () => {
+  quietLogger();
+  const spec: HangingFetchSpec = { calls: [], sawAbort: false, entered: Promise.resolve() };
+  const restoreFetch = installHangingFetch(spec);
+  try {
+    const controller = new AbortController();
+    const client = new LocalLlmClient(createConfig("/tmp/remnic-llm-shutdown-inflight"), undefined, controller.signal);
+    // SAFETY: availability is stubbed at the established field seam (same as
+    // local-llm-qos.test.ts) so the retry loop, not the network probe, runs.
+    const seams = client as any;
+    seams.isAvailable = true;
+    seams.lastHealthCheck = Date.now();
+
+    const pending = client.chatCompletion(
+      [{ role: "user", content: "shutdown abort in flight" }],
+      { operation: "extraction" },
+    );
+
+    await spec.entered;
+    controller.abort();
+
+    const result = await withTestDeadline(pending, 2_000, "in-flight abort");
+    assert.equal(result, null);
+    assert.equal(spec.calls.length, 1, "no second attempt may start after abort");
+    assert.equal(spec.sawAbort, true, "the abort signal must reach the transport stub");
+    assert.equal(spec.calls[0]?.signal?.aborted, true);
+  } finally {
+    restoreFetch();
+    resetLogger();
+  }
+});
+
+test("an abort during retry backoff ends the loop without sleeping it out or starting another attempt", async () => {
+  const { lines } = installRecordingLogger();
+  const spec: HangingFetchSpec = { calls: [], sawAbort: false, timeoutAfterMs: 20, entered: Promise.resolve() };
+  const restoreFetch = installHangingFetch(spec);
+  try {
+    const controller = new AbortController();
+    const client = new LocalLlmClient(createConfig("/tmp/remnic-llm-shutdown-backoff"), undefined, controller.signal);
+    // SAFETY: availability is stubbed at the established field seam (same as
+    // local-llm-qos.test.ts) so the retry loop, not the network probe, runs.
+    const seams = client as any;
+    seams.isAvailable = true;
+    seams.lastHealthCheck = Date.now();
+
+    const pending = client.chatCompletion(
+      [{ role: "user", content: "shutdown abort during backoff" }],
+      { operation: "extraction" },
+    );
+
+    // Sync point: the retry loop is in its 30s backoff when the backoff
+    // warn line lands; abort there.
+    await waitFor(
+      () => lines.some((line) => line.includes("retrying after 30000ms")),
+      "attempt 1 to fail and backoff to start",
+    );
+    controller.abort();
+
+    const startedAtMs = Date.now();
+    const result = await withTestDeadline(pending, 2_000, "backoff abort");
+    assert.equal(result, null);
+    assert.ok(Date.now() - startedAtMs < 1_500, "backoff must not be slept out after abort");
+    assert.equal(spec.calls.length, 1, "no second attempt may start after abort");
+  } finally {
+    restoreFetch();
+    resetLogger();
+  }
+});

package/src/local-llm.ts

@@ -20,6 +20,7 @@ import {
   type ProbeFetchResult,
   normalizeBackendTripReason,
   waitForRetryBackoff,
+  combineClientAbortSignals,
   SingleFlightProbe,
   type LocalLlmChatCompletionOptions,
   type LocalLlmChatCompletionResult,
@@ -201,10 +202,14 @@ export class LocalLlmClient {
   private static readonly HEALTH_CHECK_INTERVAL_MS = 60000; // 1 minute
   private static readonly LMS_CACHE_INTERVAL_MS = 30000; // 30 seconds
   private readonly chatTransport = new ChatTransport();
+  /** Orchestrator-owned stop signal: aborts every in-flight and queued
+   *  request (and their retry backoffs) the moment teardown begins. */
+  private readonly shutdownSignal: AbortSignal | undefined;
 
-  constructor(config: PluginConfig, modelRegistry?: ModelRegistry) {
+  constructor(config: PluginConfig, modelRegistry?: ModelRegistry, shutdownSignal?: AbortSignal) {
     this.config = config;
     this.modelRegistry = modelRegistry;
+    this.shutdownSignal = shutdownSignal;
   }
 
   /**
@@ -829,7 +834,7 @@ export class LocalLlmClient {
 
   private async runQueuedRequest(next: LocalLlmQueuedRequest): Promise<void> {
     try {
-      if (next.options.signal?.aborted) {
+      if (combineClientAbortSignals(next.options.signal, this.shutdownSignal)?.aborted) {
         next.resolve(null);
         return;
       }
@@ -879,8 +884,9 @@ export class LocalLlmClient {
     }
 
     try {
-      if (options.signal?.aborted) return null;
-      const isAvailable = await this.checkAvailability(options.signal);
+      const signal = combineClientAbortSignals(options.signal, this.shutdownSignal);
+      if (signal?.aborted) return null;
+      const isAvailable = await this.checkAvailability(signal);
       if (!isAvailable) {
         log.debug(
           `local LLM: checkAvailability returned false for ${this.config.localLlmUrl}`,
@@ -977,7 +983,7 @@ export class LocalLlmClient {
         response = null;
         responseBody = "";
         // Wait out the shared endpoint backoff, then take a concurrency slot.
-        const gate = await rateLimit.beforeAttempt(options.signal);
+        const gate = await rateLimit.beforeAttempt(signal);
         if (gate.kind === "skip") {
           log.warn(gate.reason === "queue"
             ? `local LLM concurrency queue exceeded the ${effectiveTimeoutMs}ms request budget; skipping request (op=${operation})`
@@ -989,24 +995,25 @@ export class LocalLlmClient {
         if (gate.kind === "aborted") return null;
         const attemptAbort = new AbortController();
         const onCallerAbort = (): void => {
-          attemptAbort.abort(options.signal?.reason);
+          attemptAbort.abort(signal?.reason);
         };
-        if (options.signal) {
-          if (options.signal.aborted) {
+        if (signal) {
+          if (signal.aborted) {
             onCallerAbort();
           } else {
-            options.signal.addEventListener("abort", onCallerAbort, { once: true });
+            signal.addEventListener("abort", onCallerAbort, { once: true });
           }
         }
         const attemptTimeout = setTimeout(() => attemptAbort.abort(), effectiveTimeoutMs);
+        const postAttempt = (bodyJson: string): Promise<Response> => this.chatTransport.post({
+          url: chatUrl,
+          headers: this.buildRequestHeaders({ "Content-Type": "application/json" }),
+          body: bodyJson,
+          signal: attemptAbort.signal,
+          budgetMs: this.config.localLlmTimeoutMs,
+        });
         try {
-          response = await this.chatTransport.post({
-            url: chatUrl,
-            headers: this.buildRequestHeaders({ "Content-Type": "application/json" }),
-            body: requestBodyJson,
-            signal: attemptAbort.signal,
-            budgetMs: this.config.localLlmTimeoutMs,
-          });
+          response = await postAttempt(requestBodyJson);
           responseBody = await response.text();
           if (
             response.status === 400 &&
@@ -1019,18 +1026,12 @@ export class LocalLlmClient {
             requestBodyJson = JSON.stringify(requestBody);
             log.debug("local LLM rejected native JSON schema; retrying without it");
             response = null;
-            response = await this.chatTransport.post({
-              url: chatUrl,
-              headers: this.buildRequestHeaders({ "Content-Type": "application/json" }),
-              body: requestBodyJson,
-              signal: attemptAbort.signal,
-              budgetMs: this.config.localLlmTimeoutMs,
-            });
+            response = await postAttempt(requestBodyJson);
             responseBody = await response.text();
           }
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
-          if (options.signal?.aborted) {
+          if (signal?.aborted) {
             response = null;
             lastAbortError = error;
             break;
@@ -1046,12 +1047,12 @@ export class LocalLlmClient {
             log.warn(
               `local LLM request aborted: op=${operation} attempt=${attempt}/${maxAttempts} timeoutMs=${effectiveTimeoutMs} model=${this.config.localLlmModel}; retrying after ${backoffMs}ms`,
             );
-            if (!(await waitForRetryBackoff(backoffMs, options.signal))) return null;
+            if (!(await waitForRetryBackoff(backoffMs, signal))) return null;
             continue;
           }
         } finally {
           clearTimeout(attemptTimeout);
-          options.signal?.removeEventListener("abort", onCallerAbort);
+          signal?.removeEventListener("abort", onCallerAbort);
           gate.release();
         }
 
@@ -1085,7 +1086,7 @@ export class LocalLlmClient {
         log.warn(
           `local LLM request got ${response.status}; retrying (attempt ${attempt + 1}/${maxAttempts}) after ${backoffMs}ms`,
         );
-        if (!(await waitForRetryBackoff(backoffMs, options.signal))) return null;
+        if (!(await waitForRetryBackoff(backoffMs, signal))) return null;
       }
       log.debug(
         `local LLM: received response, status=${response?.status}, ok=${response?.ok}`,
@@ -1401,13 +1402,14 @@ export class LocalLlmClient {
     }
     if (options.priority) {
       const priority = options.priority;
+      const signal = combineClientAbortSignals(options.signal, this.shutdownSignal);
       return await new Promise<LocalLlmChatCompletionResult | null>((resolve) => {
         let settled = false;
         let onAbort: (() => void) | undefined;
         const finish = (value: LocalLlmChatCompletionResult | null): void => {
           if (settled) return;
           settled = true;
-          if (onAbort) options.signal?.removeEventListener("abort", onAbort);
+          if (onAbort) signal?.removeEventListener("abort", onAbort);
           resolve(value);
         };
         const queued: LocalLlmQueuedRequest = {
@@ -1424,8 +1426,8 @@ export class LocalLlmClient {
           finish(null);
         };
         this.requestQueues[priority].push(queued);
-        if (options.signal?.aborted) onAbort();
-        else if (options.signal) options.signal.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+        else if (signal) signal.addEventListener("abort", onAbort, { once: true });
         this.scheduleQueueDrain();
       });
     }

package/src/orchestration/extraction-run.ts

@@ -113,6 +113,10 @@ export interface ExtractionRunCoordinatorDeps {
    * threshold and honors a foreground-opened breaker (review round).
    */
   providerBreaker?: ProviderCircuitBreaker;
+  /** Orchestrator-owned stop signal, combined into every extraction run's
+   *  abort signal: queued tasks never start and in-flight runs abort the
+   *  moment destroy() begins. Absent for standalone coordinators (tests). */
+  shutdownSignal?: AbortSignal;
 }
 
 // Recall/extraction abort helpers live in orchestrator-helpers.ts since
@@ -692,11 +696,16 @@ export class ExtractionRunCoordinator {
       typeof deadlineMs === "number" && Number.isFinite(deadlineMs)
         ? new AbortController()
         : undefined;
+    const shutdownSignal = this.deps.shutdownSignal;
+    const callerAbortSignal =
+      options.abortSignal && shutdownSignal
+        ? AbortSignal.any([options.abortSignal, shutdownSignal])
+        : (options.abortSignal ?? shutdownSignal);
     const extractionAbortSignal = extractionDeadlineController
-      ? options.abortSignal
-        ? AbortSignal.any([options.abortSignal, extractionDeadlineController.signal])
+      ? callerAbortSignal
+        ? AbortSignal.any([callerAbortSignal, extractionDeadlineController.signal])
         : extractionDeadlineController.signal
-      : options.abortSignal;
+      : callerAbortSignal;
     let extractionDeadlineTimer: NodeJS.Timeout | undefined;
     const clearExtractionDeadlineTimer = (): void => {
       if (extractionDeadlineTimer) {

package/src/orchestration/fact-dedup-window.ts

@@ -1,6 +1,10 @@
 import path from "node:path";
 import { serializeMutations, withHeldFileLock } from "../utils/serialize-mutations.js";
-import { ContentHashIndex, type StorageManager } from "../index.js";
+// Import from the real modules, NOT the ../index.js barrel: a barrel edge
+// from orchestration code that explicit-capture.ts imports re-orders module
+// initialization and leaves access-boundary's registry in TDZ (#3354).
+import { ContentHashIndex } from "../storage/content-hash-index.js";
+import type { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
 import { normalizeStoredHashSource } from "./extraction-persist-citation.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";

package/src/orchestrator-connector-dedup.test.ts

@@ -1331,8 +1331,10 @@ test("#1909 round 11: the restart rebuild reflects the current corpus (archived
 test("#1909 round 11 finding 2: destroy() flushes the debounced buffer BEFORE catalog touches", async () => {
   // The buffer save fires a coalesced namespace-catalog touch; if catalog touches
   // were flushed first, that shutdown-time touch would queue after and be lost.
-  // destroy() must flush the buffer first so its touch folds into the catalog
-  // flush and both settle before destroy() returns.
+  // destroy() flushes the buffer before the extraction drain and again after it
+  // (post-drain removals); every buffer flush must run before the one catalog
+  // flush so each shutdown-time touch folds into it and settles before destroy()
+  // returns.
   const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-destroy-order-"));
   const config = parseConfig({
     openaiApiKey: "sk-test",
@@ -1363,10 +1365,12 @@ test("#1909 round 11 finding 2: destroy() flushes the debounced buffer BEFORE ca
 
   await priv.destroy();
   assert.deepEqual(
-    order,
-    ["buffer", "catalog"],
-    "buffer flush must run before the catalog-touch flush on shutdown",
+    order.filter((step) => step === "catalog"),
+    ["catalog"],
+    "the catalog-touch flush runs exactly once",
   );
+  assert.equal(order.at(-1), "catalog", "no buffer flush may run after the catalog-touch flush");
+  assert.ok(order.includes("buffer"), "destroy() flushes the buffer");
 });
 test("#1909 round 14: destroy() surfaces a buffer flush failure and still completes teardown", async () => {
   // Graceful-shutdown durability contract: a failed shutdown buffer flush must

package/src/orchestrator.ts

@@ -739,6 +739,9 @@ export class Orchestrator {
   private _dependencyPropagationRecovery: Promise<void> | null = null;
   private destroyed = false;
   private acceptingEntityMigrationMaintenance = true;
+  /** Aborted at the start of destroy(); stops every local-LLM client and extraction task at once. */
+  private readonly shutdownController = new AbortController();
+  readonly shutdownSignal: AbortSignal = this.shutdownController.signal;
 
   private get dependencyPropagationDelivery(): DependencyPropagationDelivery {
     if (this.destroyed) throw new Error("orchestrator has been destroyed");
@@ -770,9 +773,8 @@ export class Orchestrator {
     return this._providerBreaker;
   }
 
-  /** The run-coordinator deps bundle, parameterized by its buffer accessor so
-   * an isolated claim-backed drain can bind its own SmartBuffer (the daemon
-   * backlog scheduler) while live extraction keeps `this.buffer`. */
+  /** The run-coordinator deps bundle, parameterized by its buffer accessor:
+   * an isolated claim-backed drain binds its own SmartBuffer (backlog scheduler). */
   private extractionRunDeps(getBuffer: () => SmartBuffer): ExtractionRunCoordinatorDeps {
     return {
       config: this.config,
@@ -795,9 +797,26 @@ export class Orchestrator {
       runTierMigrationCycle: (storage, trigger, options) => this.runTierMigrationCycle(storage, trigger, options),
       recordProcessedExtractionFingerprint: (storage, fingerprint, preloadedMeta) =>
         this.recordProcessedExtractionFingerprint(storage, fingerprint, preloadedMeta),
+      shutdownSignal: this.shutdownSignal,
     };
   }
 
+  /** Fast-tier client: low latency at all costs, thinking always suppressed. */
+  private buildFastLlm(config: PluginConfig): LocalLlmClient {
+    const client = new LocalLlmClient(
+      {
+        ...config,
+        localLlmModel: config.localLlmFastModel || config.localLlmModel,
+        localLlmUrl: config.localLlmFastUrl,
+        localLlmTimeoutMs: config.localLlmFastTimeoutMs,
+      },
+      this.modelRegistry,
+      this.shutdownSignal,
+    );
+    client.disableThinking = true;
+    return client;
+  }
+
   private get extractionRunCoordinator(): ExtractionRunCoordinator {
     if (!this._extractionRunCoordinator) {
       this._extractionRunCoordinator = new ExtractionRunCoordinator(this.extractionRunDeps(() => this.buffer));
@@ -983,6 +1002,8 @@ export class Orchestrator {
    * commands should call it before returning to let Node exit naturally.
    */
   async destroy(): Promise<void> {
+    // First, always: every client and extraction task holds this signal.
+    this.shutdownController.abort();
     this.acceptingEntityMigrationMaintenance = false;
     this._orchestratorInitCoordinator?.retireStartupEpoch();
     this.abortDeferredInit();
@@ -996,23 +1017,29 @@ export class Orchestrator {
     await this.maintenanceScheduler.dispose();
     await this._dependencyPropagationRecovery;
     this._dependencyPropagationRecovery = null;
+    // Persist unsent turns BEFORE the extraction drain: buffered turns must
+    // already be on disk when shutdown abandons or bounds the drain's wait.
+    let bufferFlushError: unknown;
+    try {
+      await this.buffer.flushPendingSave({ throwOnFailure: true });
+    } catch (err) {
+      bufferFlushError = err;
+    }
     const extractionDrainError = await drainExtractionAndShutdownDependencyPropagation(
       this.extractionQueueCoordinator,
       this._dependencyPropagationDelivery,
     );
+    // After the drain, never before: an extraction already in its persist
+    // stage reads dependencyPropagationDelivery, and this flag gates that
+    // getter ("orchestrator has been destroyed").
     this.destroyed = true;
     this._dependencyPropagationDelivery = undefined;
+    // Persist post-drain removals; a failed write stays pending for next boot.
+    await this.buffer.flushPendingSave().catch(() => undefined);
     await drainRecallWrites(this);
     await this.persistenceIndexCoordinator
       .drainContentHashReconcileRetries()
       .catch((err) => log.warn(`content-hash reconcile drain failed during destroy: ${err}`));
-    // Save buffered turns before catalog flush; rethrow save failures after teardown.
-    let bufferFlushError: unknown;
-    try {
-      await this.buffer.flushPendingSave({ throwOnFailure: true });
-    } catch (err) {
-      bufferFlushError = err;
-    }
     try {
       // Flush catalog touches before backend disposal.
       await this.namespaceCatalog.flushPendingTouches().catch(() => undefined);
@@ -1668,35 +1695,16 @@ export class Orchestrator {
       config.gatewayConfig,
       this.modelRegistry,
       this.transcript,
+      this.shutdownSignal,
     );
     this.judgeVerdictCache = createVerdictCache();
     this.judgeDeferCounts = createDeferCountMap();
-    this.localLlm = new LocalLlmClient(config, this.modelRegistry);
-    // Issue #548: the main local-LLM client is used by extraction,
-    // consolidation, and other structured-output tasks that gain
-    // nothing from chain-of-thought reasoning.  Apply the operator's
-    // configured preference (default true) so thinking-capable models
-    // skip reasoning tokens and avoid the common 60s extraction
-    // timeout.  Operators can set `localLlmDisableThinking: false`
-    // when they want thinking enabled for narrative paths.
+    this.localLlm = new LocalLlmClient(config, this.modelRegistry, this.shutdownSignal);
+    // Operator-controlled thinking suppression for structured-output ops;
+    // full rationale on THINKING_SUPPRESSED_OPERATIONS in local-llm.ts (issue #548).
     this.localLlm.disableThinking = config.localLlmDisableThinking;
     this.fastLlm = resolvePipelineProcessingCapabilities(this.config).localLlmFast
-      ? (() => {
-          const client = new LocalLlmClient(
-            {
-              ...config,
-              localLlmModel: config.localLlmFastModel || config.localLlmModel,
-              localLlmUrl: config.localLlmFastUrl,
-              localLlmTimeoutMs: config.localLlmFastTimeoutMs,
-            },
-            this.modelRegistry,
-          );
-          // Fast-tier always suppresses thinking — the contract of
-          // `fastLlm` is "low latency at all costs" and that is
-          // independent of the main-client config.
-          client.disableThinking = true;
-          return client;
-        })()
+      ? this.buildFastLlm(config)
       : this.localLlm;
     this.semanticConsolidationCoordinator = new SemanticConsolidationCoordinator({
       config,
@@ -1715,11 +1723,7 @@ export class Orchestrator {
         )
       : null;
     if (config.modelSource === "gateway") {
-      log.debug(
-        `orchestrator: gateway model source active` +
-          (config.gatewayAgentId ? ` (primary: ${config.gatewayAgentId})` : "") +
-          (config.fastGatewayAgentId ? ` (fast: ${config.fastGatewayAgentId})` : ""),
-      );
+      log.debug(`orchestrator: gateway model source active (primary: ${config.gatewayAgentId ?? "none"}, fast: ${config.fastGatewayAgentId ?? "none"})`);
     }
     this.extraction = new ExtractionEngine(
       config,
@@ -1973,18 +1977,11 @@ export class Orchestrator {
     };
   }
 
-  /**
-   * Build a briefing follow-up generator backed by the configured LLM chain
-   * (gateway model source or local LLM). Returns `undefined` when no chain
-   * is available so `buildBriefing` can surface a clear unavailable reason
-   * instead of failing at call time. Used by the access service and CLI as
-   * the fallback when no direct `openaiApiKey` is configured, so briefing
-   * follow-ups ride the same routing as every other fast-tier LLM feature.
-   */
+  /** Briefing follow-up generator over the configured LLM chain, or
+   * `undefined` when no chain is available (see buildBriefing). */
   get briefingChainFollowupGenerator(): BriefingFollowupGenerator | undefined {
-    // Plugin mode gates on `localLlmEnabled` alone: `LocalLlmClient.chatCompletion`
-    // returns null when the master switch is off, so `localLlmFastEnabled` by
-    // itself cannot serve requests (Cursor review on PR #1463).
+    // Plugin mode gates on `localLlmEnabled` alone: chatCompletion returns
+    // null when the master switch is off (Cursor review on PR #1463).
     const chainAvailable =
       this.config.modelSource === "gateway"
         ? this._fastGatewayLlm?.isAvailable(

package/src/storage/content-hash-index.ts

@@ -3,7 +3,7 @@
 // rebuild saves plus the deferred durable-retry machinery. storage.ts imports
 // these back and re-exports the class + companion types that were previously
 // part of its public API.
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir, stat, utimes } from "node:fs/promises";
 import path from "node:path";
 import { computeContentHash, normalizeContent } from "../content-hash.js";
 import { log } from "../logger.js";
@@ -291,6 +291,25 @@ export class ContentHashIndex {
     );
   }
 
+  /**
+   * Change the durable file's mtime without touching its content. A publish
+   * that throws or stays deferred leaves the file as it was, so a peer that
+   * already synced it keeps answering authoritative MISSes for deltas this
+   * instance holds only in memory (#3355). A new stamp makes every holder of the
+   * old fingerprint, this instance included, fail the freshness check and
+   * confirm against the corpus. Best effort: a file that cannot be stamped
+   * leaves the callers' existing retry and rebuild paths as the only repair.
+   */
+  private async invalidatePeerFreshness(): Promise<void> {
+    try {
+      const { mtimeMs } = await stat(this.filePath);
+      const bumped = new Date(Math.max(Date.now(), mtimeMs + 1));
+      await utimes(this.filePath, bumped, bumped);
+    } catch (err) {
+      log.debug(`content-hash index: could not invalidate peer freshness of ${this.filePath}: ${err}`);
+    }
+  }
+
   /** Check if content already exists in the index. */
   has(content: string): boolean {
     return this.hashes.has(ContentHashIndex.computeHash(content));
@@ -473,9 +492,15 @@ export class ContentHashIndex {
             `content-hash index: lock not acquired for ${this.filePath}; deferring reconcile save (dirty retained, scheduling durable retry)`
           );
           this.scheduleReconcileRetry();
+          await this.invalidatePeerFreshness();
           return;
         }
-        await publish();
+        try {
+          await publish();
+        } catch (err) {
+          await this.invalidatePeerFreshness();
+          throw err;
+        }
         if (this.dirty) {
           // A concurrent add()/remove() landed during publish's disk awaits, so
           // deltas remain unpersisted (PR #2016 thread SD7Tj). Arm a bounded