@remnic/core 10.0.48 → 10.0.50

package/src/briefing-abort.test.ts

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test, { type TestContext } from "node:test";
+import { abortError } from "./abort-error.js";
+import fs from "node:fs/promises";
+import { syncBuiltinESMExports } from "node:module";
+import { AccessObserveWriteSurface } from "./access-observe-write-surface.js";
+import { Orchestrator } from "./orchestrator.js";
+import { buildBriefing, type ParsedBriefingWindow } from "./briefing.js";
+import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
+import { StorageManager } from "./storage.js";
+import type { WindowedMemoryReadOptions, WindowedMemoryReadResult } from "./storage/windowed-memory-read.js";
+import type { EntityFile, MemoryFile } from "./types.js";
+
+const WINDOW: ParsedBriefingWindow = {
+  from: new Date("2026-04-10T00:00:00.000Z"),
+  to: new Date("2026-04-11T00:00:00.000Z"),
+  label: "test-window",
+};
+const MEMORY: MemoryFile = {
+  path: "/synthetic/mem.md",
+  frontmatter: {
+    id: "synthetic-mem",
+    category: "fact",
+    created: "2026-04-10T01:00:00.000Z",
+    updated: "2026-04-10T02:00:00.000Z",
+    source: "test",
+    confidence: 0.9,
+    confidenceTier: "explicit",
+    tags: [],
+  },
+  content: "synthetic briefing memory",
+};
+const ENTITY: EntityFile = {
+  name: "SyntheticEntity",
+  type: "project",
+  updated: "2026-04-10T03:00:00.000Z",
+  facts: ["synthetic fact"],
+  timeline: [],
+  relationships: [],
+  activity: [],
+  aliases: [],
+};
+
+function makeStorage(t: TestContext): StorageManager {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "remnic-briefing-abort-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const storage = new StorageManager(dir);
+  t.mock.method(storage, "readMemoriesWindow", async (_options: WindowedMemoryReadOptions) => ({
+    memories: [MEMORY],
+    filePaths: [MEMORY.path],
+  }));
+  t.mock.method(storage, "readAllEntityFiles", async (_options?: CorpusReadOptions) => [ENTITY]);
+  return storage;
+}
+
+function makeStallingStorage(t: TestContext) {
+  const storage = makeStorage(t);
+  const fallback = Promise.withResolvers<void>();
+  // The fallback releases broken signal plumbing too, so the regression cannot hang.
+  t.mock.method(
+    storage,
+    "readMemoriesWindow",
+    (options: WindowedMemoryReadOptions): Promise<WindowedMemoryReadResult> => {
+      const signal = options.abortSignal;
+      if (!signal) return fallback.promise.then(() => ({ memories: [], filePaths: [] }));
+      const read = Promise.withResolvers<WindowedMemoryReadResult>();
+      const onAbort = () => read.reject(abortError("corpus read aborted"));
+      if (signal.aborted) {
+        onAbort();
+        return read.promise;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+      void fallback.promise.then(() => {
+        signal.removeEventListener("abort", onAbort);
+        read.resolve({ memories: [], filePaths: [] });
+      });
+      return read.promise;
+    }
+  );
+  return { storage, releaseFallback: fallback.resolve };
+}
+
+test("buildBriefing rejects with an AbortError when the caller's cancel signal fires mid-read", async (t) => {
+  const { storage, releaseFallback } = makeStallingStorage(t);
+  const controller = new AbortController();
+  const call = buildBriefing({ storage, window: WINDOW, allowLlm: false, abortSignal: controller.signal });
+  controller.abort();
+  releaseFallback();
+  await assert.rejects(call, { name: "AbortError", message: /abort|cancel/i });
+});
+
+test("buildBriefing rejects when the caller's cancel signal is already aborted", async (t) => {
+  const { storage, releaseFallback } = makeStallingStorage(t);
+  const controller = new AbortController();
+  controller.abort();
+  const call = buildBriefing({ storage, window: WINDOW, allowLlm: false, abortSignal: controller.signal });
+  releaseFallback();
+  await assert.rejects(call, { name: "AbortError" });
+});
+
+test("a cancelled briefing does not drain the correction-notification queue", async (t) => {
+  const storage = makeStorage(t);
+  const queueDir = path.join(storage.dir, "state", "corrections");
+  mkdirSync(queueDir, { recursive: true });
+  const queueFile = path.join(queueDir, "notifications.jsonl");
+  writeFileSync(
+    queueFile,
+    `${JSON.stringify({ planId: "synthetic-plan", summary: "synthetic correction", undoCommand: "remnic correct plan synthetic-plan", createdAt: "2026-04-10T04:00:00.000Z" })}\n`
+  );
+  const controller = new AbortController();
+  const call = buildBriefing({
+    storage,
+    window: WINDOW,
+    abortSignal: controller.signal,
+    // Cancel after reads, just before the queue-draining phase.
+    followupGenerator: async () => {
+      controller.abort();
+      return [];
+    },
+  });
+  await assert.rejects(call, { name: "AbortError" });
+  assert.ok(existsSync(queueFile), "a cancelled briefing must not consume correction notifications");
+});
+
+test("buildBriefing returns a non-empty briefing when nothing is cancelled", async (t) => {
+  const result = await buildBriefing({ storage: makeStorage(t), window: WINDOW, allowLlm: false });
+  assert.equal(result.sections.activeThreads.length, 1);
+  assert.equal(result.sections.recentEntities.length, 1);
+  assert.ok(result.markdown.length > 0);
+  assert.deepEqual(result.window, { from: "2026-04-10T00:00:00.000Z", to: "2026-04-11T00:00:00.000Z" });
+});
+
+test("an HTTP/MCP briefing cancelled during the location read keeps the notification queue", async (t) => {
+  const storage = makeStorage(t);
+  const queueDir = path.join(storage.dir, "state", "corrections");
+  mkdirSync(queueDir, { recursive: true });
+  const queueFile = path.join(queueDir, "notifications.jsonl");
+  writeFileSync(
+    queueFile,
+    `${JSON.stringify({ planId: "synthetic-plan", summary: "synthetic correction", undoCommand: "remnic correct plan synthetic-plan", createdAt: "2026-04-10T04:00:00.000Z" })}\n`
+  );
+  const controller = new AbortController();
+  const read: (file: string, encoding: "utf-8") => Promise<string> = fs.readFile;
+  t.mock.method(fs, "readFile", async (file: string) => {
+    if (file.endsWith(path.join("state", "locations", "sync.json"))) controller.abort(abortError("deadline"));
+    return read(file, "utf-8");
+  });
+  syncBuiltinESMExports();
+  t.after(() => {
+    t.mock.restoreAll();
+    syncBuiltinESMExports();
+  });
+  // Object.create yields untyped values, so no assertion is needed: briefing() reads only these members.
+  const orchestrator: Orchestrator = Object.assign(Object.create(Orchestrator.prototype), {
+    config: {
+      briefing: { enabled: true, defaultWindow: "24h", defaultFormat: "markdown", maxFollowups: 0, llmFollowups: false },
+      location: { enabled: true, tagging: { enabled: true }, timezone: "UTC" },
+    },
+    getStorage: async () => storage,
+  });
+  const surface = new AccessObserveWriteSurface(
+    Object.assign(Object.create(null), { orchestrator, resolveReadableNamespace: () => "default" }),
+  );
+
+  await assert.rejects(
+    surface.briefing({ includeLocation: true, abortSignal: controller.signal }),
+    { name: "AbortError" },
+  );
+  assert.ok(existsSync(queueFile), "a briefing cancelled during the location read must not consume notifications");
+});

package/src/briefing-deadline.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Issue #3139 — the briefing's default deadline.
+ *
+ * The budget is a server-side limit, not a client cancellation: exhausting it
+ * must surface as an explicit TimeoutError, never as an empty result.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  BRIEFING_DEADLINE_MS,
+  BriefingTimeoutError,
+  withBriefingDeadline,
+} from "./briefing-deadline.js";
+
+test("withBriefingDeadline rejects with a TimeoutError when the default budget is exhausted", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+
+  const pending = withBriefingDeadline(
+    () => Promise.withResolvers<never>().promise,
+  );
+
+  t.mock.timers.tick(BRIEFING_DEADLINE_MS);
+
+  await assert.rejects(pending, (err) => {
+    assert.ok(
+      err instanceof BriefingTimeoutError,
+      "budget exhaustion must surface as a timeout",
+    );
+    assert.equal(err.name, "TimeoutError");
+    assert.equal(err.deadlineMs, BRIEFING_DEADLINE_MS);
+    return true;
+  });
+});
+
+test("withBriefingDeadline clears its timer once the run settles", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  let observed: AbortSignal | undefined;
+
+  const result = await withBriefingDeadline(async (signal) => {
+    observed = signal;
+    return "briefing";
+  });
+
+  assert.equal(result, "briefing");
+  t.mock.timers.tick(BRIEFING_DEADLINE_MS);
+  assert.equal(
+    observed?.aborted,
+    false,
+    "the budget timer must be cleared when the run settles, not left to fire afterwards",
+  );
+});
+
+test("withBriefingDeadline preserves work failures and clears their timer", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  const failure = new Error("synthetic work failure");
+  const signals: AbortSignal[] = [];
+
+  const pending = withBriefingDeadline(async (signal) => {
+    signals.push(signal);
+    throw failure;
+  });
+
+  await assert.rejects(pending, (err) => err === failure);
+  assert.equal(signals.length, 1);
+  t.mock.timers.tick(BRIEFING_DEADLINE_MS);
+  assert.equal(signals[0].aborted, false);
+});
+
+test("withBriefingDeadline normalizes arbitrary caller cancellation to AbortError", async () => {
+  const controller = new AbortController();
+  const pending = withBriefingDeadline(
+    () => Promise.withResolvers<never>().promise,
+    controller.signal,
+  );
+  controller.abort(new Error("synthetic caller cancellation"));
+
+  await assert.rejects(pending, (err) => {
+    assert.ok(err instanceof Error);
+    assert.equal(err.name, "AbortError");
+    return true;
+  });
+});

package/src/briefing-deadline.ts

@@ -0,0 +1,33 @@
+import { isAbortError, raceAbort } from "./abort-error.js";
+
+export const BRIEFING_DEADLINE_MS = 30_000;
+
+export class BriefingTimeoutError extends Error {
+  constructor(readonly deadlineMs: number) {
+    super(`briefing timed out after ${deadlineMs}ms`);
+    this.name = "TimeoutError";
+  }
+}
+
+export async function withBriefingDeadline<T>(
+  run: (signal: AbortSignal) => Promise<T>,
+  abortSignal?: AbortSignal
+): Promise<T> {
+  const controller = new AbortController();
+  const signal = abortSignal ? AbortSignal.any([abortSignal, controller.signal]) : controller.signal;
+  const timer = setTimeout(
+    () => controller.abort(new BriefingTimeoutError(BRIEFING_DEADLINE_MS)),
+    BRIEFING_DEADLINE_MS
+  );
+  try {
+    signal.throwIfAborted();
+    return await raceAbort(run(signal), signal, "briefing aborted");
+  } catch (err) {
+    // raceAbort normalizes cancellation; retain the distinct deadline reason.
+    const reason: unknown = signal.reason;
+    if (signal.aborted && (reason instanceof BriefingTimeoutError || isAbortError(reason))) throw reason;
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/briefing-window-abort.test.ts

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { safeReadMemories } from "./briefing-window.js";
+import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
+import type { MemoryFile } from "./types.js";
+
+test("caller cancellation reaches the signal-aware legacy briefing scan", async () => {
+  const controller = new AbortController();
+  const started = Promise.withResolvers<AbortSignal>();
+  const release = Promise.withResolvers<void>();
+  const reader = {
+    supportsAbortSignal: true,
+    async readAllMemories(options?: CorpusReadOptions): Promise<MemoryFile[]> {
+      assert.ok(options?.abortSignal);
+      started.resolve(options.abortSignal);
+      await release.promise;
+      options.abortSignal.throwIfAborted();
+      return [];
+    },
+  };
+  const result = safeReadMemories(
+    reader,
+    {
+      from: new Date("2026-04-10T00:00:00.000Z"),
+      to: new Date("2026-04-11T00:00:00.000Z"),
+      label: "yesterday",
+    },
+    { signal: controller.signal }
+  ).then(
+    () => ({ ok: true as const }),
+    (error) => ({ ok: false as const, error })
+  );
+  try {
+    const scanSignal = await started.promise;
+    assert.equal(scanSignal.aborted, false);
+    controller.abort();
+    release.resolve();
+    const outcome = await result;
+    assert.equal(outcome.ok, false, "a cancelled scan must reject, not return an empty corpus");
+    assert.ok(outcome.error instanceof Error);
+    assert.equal(outcome.error.name, "AbortError");
+    assert.equal(scanSignal.aborted, true, "the underlying scan must stop too");
+  } finally {
+    release.resolve();
+    await result;
+  }
+});

package/src/briefing-window.ts

@@ -1,11 +1,12 @@
 import { log } from "./logger.js";
-import type { MemoryFile } from "./types.js";
+import type { EntityFile, MemoryFile } from "./types.js";
 import { isAbortError } from "./abort-error.js";
 import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
 import type { ParsedBriefingWindow } from "./briefing.js";
+import type { WindowedMemoryReadOptions } from "./storage/windowed-memory-read.js";
 
 type BriefingMemoryReader = {
-  readMemoriesWindow?: (options: { updatedAfter?: Date }) => Promise<{ memories: MemoryFile[] }>;
+  readMemoriesWindow?: (options: WindowedMemoryReadOptions) => Promise<{ memories: MemoryFile[] }>;
   readAllMemories: ((options?: CorpusReadOptions) => Promise<MemoryFile[]>) & {
     supportsAbortSignal?: boolean;
   };
@@ -30,6 +31,12 @@ export const BRIEFING_FULL_READ_FALLBACK_MS = 30_000;
 export interface SafeReadMemoriesOptions {
   /** Test seam overriding {@link BRIEFING_FULL_READ_FALLBACK_MS}. */
   fallbackDeadlineMs?: number;
+  /**
+   * Caller cancellation. The signal reaches the storage read so it stops at
+   * its next boundary, and a cancelled read is rethrown rather than degraded
+   * into an empty corpus (issue #3139).
+   */
+  signal?: AbortSignal;
 }
 
 type BriefingReadMode = "windowed" | "full-read-fallback";
@@ -138,6 +145,12 @@ export async function safeReadMemories(
     resultCount = memories.length;
     return memories;
   } catch (err) {
+    if (isAbortError(err) && options.signal?.aborted) {
+      // Caller cancellation is not a read failure: rethrow it so the briefing
+      // rejects instead of degrading into an empty corpus (issue #3139). The
+      // own fallback deadline is reported as BriefingReadTimedOut below.
+      throw err;
+    }
     if (err instanceof BriefingReadTimedOut) {
       outcome = "timeout";
       bestEffortLog(
@@ -174,7 +187,9 @@ async function readBriefingMemories(
   // the full corpus on cache misses; keep the full-read fallback for custom
   // StorageManager-compatible callers that predate readMemoriesWindow().
   if (mode === "windowed") {
-    const result = await storage.readMemoriesWindow!({ updatedAfter: window.from });
+    const readOptions: WindowedMemoryReadOptions = { updatedAfter: window.from };
+    if (options.signal) readOptions.abortSignal = options.signal;
+    const result = await storage.readMemoriesWindow!(readOptions);
     return result.memories;
   }
   // Refuse legacy adapters that do not explicitly declare cancellation support (#2827).
@@ -195,12 +210,13 @@ async function readBriefingMemories(
     deadlineFired = true;
     controller.abort();
   }, deadlineMs);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
   try {
     // Direct await, no Promise.race: the signal IS the deadline. A
     // signal-aware read settles on abort (AbortError at its next scan
     // boundary, #2307), so nothing is left scanning in the background once
     // this function returns.
-    const memories = await storage.readAllMemories({ abortSignal: controller.signal });
+    const memories = await storage.readAllMemories({ abortSignal: signal });
     if (deadlineFired) {
       // A double that resolves partial rows instead of rejecting on abort
       // must not have them served as a complete corpus.
@@ -214,3 +230,16 @@ async function readBriefingMemories(
     clearTimeout(timer);
   }
 }
+
+export async function safeReadEntities(
+  storage: { readAllEntityFiles(options?: CorpusReadOptions): Promise<EntityFile[]> },
+  signal: AbortSignal,
+): Promise<EntityFile[]> {
+  try {
+    return await storage.readAllEntityFiles({ abortSignal: signal });
+  } catch (err) {
+    if (isAbortError(err) && signal.aborted) throw err;
+    log.warn(`briefing: readAllEntityFiles failed: ${err}`);
+    return [];
+  }
+}

package/src/briefing.ts

@@ -19,12 +19,14 @@ import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { log } from "./logger.js";
+import { isAbortError, throwIfAborted } from "./abort-error.js";
+import { withBriefingDeadline } from "./briefing-deadline.js";
 import { withBriefingFollowupTimeout } from "./briefing-followup-timeout.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import { drainPassiveCorrectionNotifications } from "./correction/passive-correction-notifications.js";
 import { excludeSupportPassportPrivateMemories } from "./support-passport/card-projection.js";
 import { normalizeEntityName, StorageManager } from "./storage.js";
-import { safeReadMemories } from "./briefing-window.js";
+import { safeReadEntities, safeReadMemories } from "./briefing-window.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import type {
   BriefingActiveThread,
@@ -817,6 +819,8 @@ export interface BuildBriefingOptions {
   followupGenerator?: BriefingFollowupGenerator;
   /** Injected "now" — makes tests deterministic. */
   now?: Date;
+  /** Caller cancellation must not consume correction notifications. */
+  abortSignal?: AbortSignal;
 }
 
 const MAX_ACTIVE_THREADS = 8;
@@ -830,15 +834,23 @@ const MAX_OPEN_COMMITMENTS = 8;
  * omitted and `followupsUnavailableReason` is set.
  */
 export async function buildBriefing(options: BuildBriefingOptions): Promise<BriefingResult> {
+  return withBriefingDeadline(
+    (signal) => buildBriefingWithSignal(options, signal),
+    options.abortSignal,
+  );
+}
+
+async function buildBriefingWithSignal(options: BuildBriefingOptions, signal: AbortSignal): Promise<BriefingResult> {
   const now = options.now ?? new Date();
   const window = options.window ?? defaultWindow(now);
   const maxFollowups = clampFollowups(options.maxFollowups);
   const focus = options.focus ?? null;
 
   const [allMemories, allEntities] = await Promise.all([
-    safeReadMemories(options.storage, window).then(excludeSupportPassportPrivateMemories),
-    safeReadEntities(options.storage),
+    safeReadMemories(options.storage, window, { signal }).then(excludeSupportPassportPrivateMemories),
+    safeReadEntities(options.storage, signal),
   ]);
+  throwIfAborted(signal, "briefing aborted");
 
   const memoriesInWindow = filterMemoriesByWindow(allMemories, window);
   const focusedMemories = focus
@@ -852,6 +864,7 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
   const calendarLoadResult = options.calendarSource
     ? await loadTodayCalendar(options.calendarSource, now)
     : undefined;
+  throwIfAborted(signal, "briefing aborted");
 
   const calendarSourceErrors: BriefingCalendarSourceError[] =
     calendarLoadResult?.error ? [calendarLoadResult.error] : [];
@@ -904,18 +917,20 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
       log.warn(`briefing: ${followupsUnavailableReason}`);
     }
   }
+  throwIfAborted(signal, "briefing aborted");
 
   const sections: BriefingSections = {
     ...sectionsBase,
     suggestedFollowups: followups,
   };
 
-  // Drain auto-applied passive-correction notifications (issue #1581). The
-  // queue is cleared on read, so each notification surfaces in exactly one
-  // briefing. Fail-open: a drain error never blocks the briefing.
+  // Drain auto-applied passive-correction notifications (issue #1581): cleared on read,
+  // so each surfaces in exactly one briefing. Fail-open except cancellation, which must
+  // not consume notifications nobody receives.
+  throwIfAborted(signal, "briefing aborted");
   let correctionNotifications: BriefingResult["correctionNotifications"];
   try {
-    const drained = await drainPassiveCorrectionNotifications(options.storage.dir);
+    const drained = await drainPassiveCorrectionNotifications(options.storage.dir, signal);
     if (drained.length > 0) {
       correctionNotifications = drained.map((n) => ({
         planId: n.planId,
@@ -925,6 +940,7 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
       }));
     }
   } catch (err) {
+    if (isAbortError(err)) throw err;
     log.debug(`briefing: correction notification drain failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
   }
 
@@ -977,15 +993,6 @@ function defaultWindow(now: Date): ParsedBriefingWindow {
   return { from: new Date(now.getTime() - DAY_MS), to: now, label: "yesterday" };
 }
 
-async function safeReadEntities(storage: StorageManager): Promise<EntityFile[]> {
-  try {
-    return await storage.readAllEntityFiles();
-  } catch (err) {
-    log.warn(`briefing: readAllEntityFiles failed: ${err}`);
-    return [];
-  }
-}
-
 function memoryTimestamp(memory: MemoryFile): number {
   const raw = memory.frontmatter.updated || memory.frontmatter.created;
   if (!raw) return 0;

package/src/capture-write-lock-scope.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { scopedCaptureWriteLockLimits, withCaptureWriteLockBackoff } from "./capture-write-lock-scope.js";
+
+const limits = { initialDelayMs: 20, maxDelayMs: 50, deadlineMs: 8_000 };
+const expected = {
+  captureWriteLockInitialDelayMs: 20,
+  captureWriteLockMaxDelayMs: 50,
+  captureWriteLockDeadlineMs: 8_000,
+};
+
+test("capture backoff scope belongs only to its storage and restores nested state after rejection", async () => {
+  const storage = { dir: "synthetic-shared-root" };
+  const other = { dir: storage.dir };
+  const result = await withCaptureWriteLockBackoff(storage, limits, async () => {
+    await Promise.resolve();
+    assert.deepEqual(scopedCaptureWriteLockLimits(storage), expected);
+    assert.equal(scopedCaptureWriteLockLimits(other), undefined);
+    await assert.rejects(
+      withCaptureWriteLockBackoff(other, { ...limits, deadlineMs: 4_000 }, async () => {
+        assert.equal(scopedCaptureWriteLockLimits(other)?.captureWriteLockDeadlineMs, 4_000);
+        assert.equal(scopedCaptureWriteLockLimits(storage), undefined);
+        throw new Error("peer apply failed");
+      }),
+      /peer apply failed/
+    );
+    return scopedCaptureWriteLockLimits(storage);
+  });
+  assert.deepEqual(result, expected);
+  assert.equal(scopedCaptureWriteLockLimits(storage), undefined);
+  assert.equal(scopedCaptureWriteLockLimits(other), undefined);
+});

package/src/capture-write-lock-scope.ts

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CaptureWriteLockBackoffLimits, CaptureWriteLockLimitSource } from "./capture-write-lock-backoff.js";
+import type { StorageManager } from "./storage.js";
+
+type CaptureLockOwner = Pick<StorageManager, "dir">;
+
+const captureScope = new AsyncLocalStorage<{ storage: CaptureLockOwner; limits: CaptureWriteLockLimitSource }>();
+
+export function withCaptureWriteLockBackoff<T>(
+  storage: CaptureLockOwner,
+  limits: CaptureWriteLockBackoffLimits,
+  run: () => Promise<T>
+): Promise<T> {
+  return captureScope.run(
+    {
+      storage,
+      limits: {
+        captureWriteLockInitialDelayMs: limits.initialDelayMs,
+        captureWriteLockMaxDelayMs: limits.maxDelayMs,
+        captureWriteLockDeadlineMs: limits.deadlineMs,
+      },
+    },
+    run
+  );
+}
+
+export function scopedCaptureWriteLockLimits(storage: CaptureLockOwner): CaptureWriteLockLimitSource | undefined {
+  const scope = captureScope.getStore();
+  return scope?.storage === storage ? scope.limits : undefined;
+}

package/src/correction/passive-correction-notifications-abort.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import { syncBuiltinESMExports } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  drainPassiveCorrectionNotifications,
+  enqueuePassiveCorrectionNotification,
+} from "./passive-correction-notifications.js";
+
+// Issue #3139 review: a briefing cancelled mid-drain must leave the queue
+// intact, because the caller never receives what the drain consumed.
+test("a drain cancelled after reading keeps the notification queue", async (t) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "remnic-3139-drain-"));
+  t.after(() => fs.rm(dir, { recursive: true, force: true }));
+  await enqueuePassiveCorrectionNotification(dir, {
+    planId: "plan-1",
+    summary: "kept",
+    undoCommand: "undo",
+    createdAt: new Date(0).toISOString(),
+  });
+  const controller = new AbortController();
+  const read: (file: string, encoding: "utf-8") => Promise<string> = fs.readFile;
+  t.mock.method(fs, "readFile", async (file: string) => {
+    const content = await read(file, "utf-8");
+    controller.abort(new Error("deadline"));
+    return content;
+  });
+  syncBuiltinESMExports();
+  t.after(() => {
+    t.mock.restoreAll();
+    syncBuiltinESMExports();
+  });
+
+  await assert.rejects(drainPassiveCorrectionNotifications(dir, controller.signal), { name: "AbortError" });
+
+  t.mock.restoreAll();
+  syncBuiltinESMExports();
+  const kept = await drainPassiveCorrectionNotifications(dir);
+  assert.equal(kept.length, 1, "the cancelled drain must not consume the queue");
+});

package/src/correction/passive-correction-notifications.ts

@@ -14,6 +14,7 @@
 
 import { mkdir, readFile, rename, writeFile, unlink } from "node:fs/promises";
 import path from "node:path";
+import { throwIfAborted } from "../abort-error.js";
 import { serializeMutations } from "../utils/serialize-mutations.js";
 
 // ---------------------------------------------------------------------------
@@ -84,6 +85,7 @@ export async function enqueuePassiveCorrectionNotification(
  */
 export async function drainPassiveCorrectionNotifications(
   storageDir: string,
+  signal?: AbortSignal,
 ): Promise<PassiveCorrectionNotification[]> {
   const filePath = notificationsPath(storageDir);
   return serializeMutations(`passive-notification:${filePath}`, async () => {
@@ -96,6 +98,8 @@ export async function drainPassiveCorrectionNotifications(
       throw err;
     }
 
+    // Cancellation after the read must keep the queue: the caller never receives these.
+    throwIfAborted(signal, "briefing aborted");
     const notifications: PassiveCorrectionNotification[] = [];
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();