@remnic/core 10.0.49 → 10.0.51

package/src/access-http.test.ts

@@ -15,11 +15,13 @@ import {
   EngramAccessInputError,
   type EngramAccessRecallRequest,
   type EngramAccessService,
+  type EngramAccessBriefingRequest,
 } from "./access-service.js";
 import {
   tokenCapabilityStore,
   type TokenCapabilities,
 } from "./access-token-capabilities.js";
+import { BriefingTimeoutError } from "./briefing-deadline.js";
 import { parseConfig } from "./config.js";
 import { readPair, writePair } from "./contradiction/contradiction-review.js";
 import { createChatSession } from "./chat/chat-session.js";
@@ -859,17 +861,23 @@ test("HTTP briefing endpoint dispatches through the briefing operation", async (
     assert.equal(body.format, "markdown");
     assert.equal(body.markdown, "# Briefing");
     assert.deepEqual(body.json.sections.activeThreads, []);
-    assert.deepEqual(calls, [
-      {
-        since: "24h",
-        focus: undefined,
-        includeLocation: undefined,
-        namespace: "team",
-        format: "markdown",
-        maxFollowups: 5,
-        principal: "panel-user",
-      },
-    ]);
+    assert.equal(calls.length, 1);
+    // SAFETY: the registered handler builds this request after validating the HTTP body; assertions below check its values.
+    const captured = calls[0] as EngramAccessBriefingRequest;
+    const { abortSignal, ...briefingRequest } = captured;
+    assert.ok(
+      abortSignal instanceof AbortSignal,
+      "the briefing request carries the HTTP request lifetime signal",
+    );
+    assert.deepEqual(briefingRequest, {
+      since: "24h",
+      focus: undefined,
+      includeLocation: undefined,
+      namespace: "team",
+      format: "markdown",
+      maxFollowups: 5,
+      principal: "panel-user",
+    });
 
     const invalid = await fetch(
       `http://127.0.0.1:${status.port}/engram/v1/briefing`,
@@ -890,6 +898,27 @@ test("HTTP briefing endpoint dispatches through the briefing operation", async (
   }
 });
 
+test("HTTP briefing endpoint answers 504 briefing_timeout when the request budget is exhausted", async () => {
+  const service: EngramAccessService = Object.assign(Object.create(null), {
+    briefing: async () => {
+      throw new BriefingTimeoutError(30_000);
+    },
+  });
+  const server = new EngramAccessHttpServer({ service, port: 0, authToken: "test-token", adminConsoleEnabled: false });
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/briefing`, {
+      method: "POST",
+      headers: { authorization: "Bearer test-token", "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    assert.equal(response.status, 504);
+    assert.deepEqual(await response.json(), { error: "briefing timed out after 30000ms", code: "briefing_timeout" });
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP contradiction scan uses writable namespace resolver", async () => {
   const resolverCalls: Array<{
     namespace: string | undefined;
@@ -2136,7 +2165,7 @@ test("HTTP offline snapshot rejects out-of-range baseline mtimes as validation e
     assert.equal(response.status, 400);
     assert.equal(body.code, "validation_error");
     assert.equal(body.details?.[0]?.field, "baseFiles.0.mtimeMs");
-    assert.match(body.details?.[0]?.message ?? "", /less than or equal/);
+    assert.match(body.details?.[0]?.message ?? "", /<=8640000000000000/);
     assert.equal(calls, 0);
   } finally {
     await server.stop();

package/src/access-http.ts

@@ -10,6 +10,7 @@ import { log } from "./logger.js";
 import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { WriteRateLimiter, type WriteRateLimitReservation } from "./write-rate-limiter.js";
 import { abortError, isAbortError } from "./abort-error.js";
+import { BriefingTimeoutError } from "./briefing-deadline.js";
 import { EngramAccessForbiddenError } from "./access-errors.js";
 import {
   EngramAccessInputError,
@@ -500,6 +501,10 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       res.once("close", abortDisconnectedRequest);
       correlationIdStore.run(correlationId, () => {
         void this.handle(req, res, correlationId, abortController.signal).catch((err) => {
+          if (err instanceof BriefingTimeoutError) {
+            this.respondJson(res, 504, { error: err.message, code: "briefing_timeout" });
+            return;
+          }
           if (isAbortError(err)) {
             if (!res.destroyed && !res.writableEnded) {
               res.end();
@@ -1979,6 +1984,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
         service: this.service,
         principal: this.resolveRequestPrincipal(req),
         respondJson: (status, payload) => this.respondJson(res, status, payload),
+        abortSignal,
       });
       return;
     }

package/src/access-observe-write-category.ts

@@ -15,7 +15,7 @@ import {
 } from "./access-schema.js";
 
 export { reapplyCategoryCoercion };
-export { applyBriefingLocationContext } from "./location/tagging.js";
+export { buildWithBriefingLocation } from "./location/tagging.js";
 
 export function splitCanonicalWriteRequest<T extends { rawCategory?: string; category?: string }>(
   request: T,

package/src/access-observe-write-surface.ts

@@ -29,8 +29,9 @@ import {
   type MemoryScopePlan,
   NamespaceNotWritableError,
 } from "./access-service.js";
-import { applyBriefingLocationContext, reapplyCategoryCoercion, splitCanonicalWriteRequest } from "./access-observe-write-category.js";
+import { buildWithBriefingLocation, reapplyCategoryCoercion, splitCanonicalWriteRequest } from "./access-observe-write-category.js";
 import { abortError } from "./abort-error.js";
+import { withBriefingDeadline } from "./briefing-deadline.js";
 import { extractionForceFlush } from "./access-extraction-force-flush.js";
 import { ObserveTranscriptPersister, observeTranscriptSessionKey } from "./access-observe-transcript.js";
 import { FileCalendarSource, buildBriefing, parseBriefingFocus, parseBriefingWindow } from "./briefing.js";
@@ -410,7 +411,6 @@ export class AccessObserveWriteSurface {
     }
 
     const namespace = this.deps.resolveReadableNamespace(request.namespace, request.principal);
-    const storage = await this.deps.orchestrator.getStorage(namespace);
 
     const token =
       typeof request.since === "string" && request.since.trim().length > 0
@@ -457,23 +457,28 @@ export class AccessObserveWriteSurface {
       ? new FileCalendarSource(config.briefing.calendarSource)
       : undefined;
 
-    const result = await applyBriefingLocationContext(await buildBriefing({
-      storage,
-      namespace,
-      window,
-      focus,
-      calendarSource,
-      maxFollowups,
-      allowLlm: config.briefing.llmFollowups,
-      openaiApiKey: config.openaiApiKey,
-      openaiBaseUrl: config.openaiBaseUrl,
-      model: config.model,
-      // Without a direct OpenAI key, route follow-ups through the configured
-      // LLM chain (gateway model source or local LLM) — same fallback every
-      // other LLM feature uses. A configured key keeps its precedence so
-      // existing deployments are unchanged.
-      followupGenerator: config.openaiApiKey ? undefined : this.deps.orchestrator.briefingChainFollowupGenerator,
-    }), request.includeLocation, storage.dir, window.from.toISOString(), config.location);
+    // Storage acquisition and the briefing body share one request budget.
+    const result = await withBriefingDeadline(async (signal) => {
+      const storage = await this.deps.orchestrator.getStorage(namespace);
+      return buildWithBriefingLocation(request.includeLocation, storage.dir, window.from.toISOString(), config.location, () => buildBriefing({
+        storage,
+        namespace,
+        window,
+        focus,
+        calendarSource,
+        maxFollowups,
+        allowLlm: config.briefing.llmFollowups,
+        openaiApiKey: config.openaiApiKey,
+        openaiBaseUrl: config.openaiBaseUrl,
+        model: config.model,
+        // Without a direct OpenAI key, route follow-ups through the configured
+        // LLM chain (gateway model source or local LLM) — same fallback every
+        // other LLM feature uses. A configured key keeps its precedence so
+        // existing deployments are unchanged.
+        followupGenerator: config.openaiApiKey ? undefined : this.deps.orchestrator.briefingChainFollowupGenerator,
+        abortSignal: signal,
+      }));
+    }, request.abortSignal);
 
     return {
       format,

package/src/access-operations-batch.ts

@@ -23,7 +23,7 @@ import {
   retainedCategoryAlias,
   suggestionSubmitRequestSchema,
 } from "./access-schema.js";
-import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError, type EngramAccessService, type EngramAccessBriefingRequest } from "./access-service.js";
 import { enforceNamespaceAllowList, tokenCapabilityStore } from "./access-token-capabilities.js";
 import { projectTagProjectId } from "./coding/coding-namespace.js";
 import {
@@ -381,7 +381,23 @@ defineOperation({ name: "memory_promote", description: "Promote memory.", schema
 defineOperation({ name: "memory_outcome", description: "Record outcome.", schema: strictSchema({ memoryId: S.str, outcome: S.str, namespace: S.str, sessionKey: S.str, timestamp: S.str }), handler: async (input, ctx) => { const o = optStr(input.outcome); if (o !== "success" && o !== "failure") throw new EngramAccessInputError("memory_outcome: outcome must be \"success\" or \"failure\"; got " + JSON.stringify(o)); return { result: await ctx.service.memoryOutcome({ memoryId: optStr(input.memoryId) ?? "", outcome: o, namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey), timestamp: optStr(input.timestamp), principal: ctx.authenticatedPrincipal }) }; } });
 defineOperation({ name: "memory_action_apply", description: "Apply action.", schema: strictSchema({ action: S.str, outcome: S.str, reason: S.str, memoryId: S.str, namespace: S.str, sessionKey: S.str, content: S.str, category: S.str, linkTargetId: S.str, linkType: S.str, linkStrength: S.num, artifactType: S.str, execute: S.bool, sourcePrompt: S.str, dryRun: S.bool }), handler: async (input, ctx) => ({ result: await ctx.service.memoryActionApply({ action: optStr(input.action) ?? "", outcome: optStr(input.outcome), reason: optStr(input.reason), memoryId: optStr(input.memoryId) ?? "", namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey), content: optStr(input.content), category: optStr(input.category), linkTargetId: optStr(input.linkTargetId), linkType: optStr(input.linkType), linkStrength: optNum(input.linkStrength), artifactType: optStr(input.artifactType), execute: optBool(input.execute), sourcePrompt: optStr(input.sourcePrompt), dryRun: input.dryRun === true, principal: ctx.authenticatedPrincipal }) }) });
 defineOperation({ name: "context_checkpoint", description: "Context checkpoint.", schema: strictSchema({ sessionKey: S.str, context: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.contextCheckpoint({ sessionKey: optStr(input.sessionKey) ?? "", context: optStr(input.context) ?? "", namespace: optStr(input.namespace), principal: ctx.authenticatedPrincipal }) }) });
-defineOperation({ name: "briefing", description: "Daily briefing.", schema: strictSchema({ since: S.str, focus: S.str, namespace: S.str, includeLocation: S.bool, format: S.str, maxFollowups: S.num }), handler: async (input, ctx) => { const rf = optStr(input.format); const fe = validateBriefingFormat(rf); if (fe) throw new EngramAccessInputError(fe); return { result: await ctx.service.briefing({ since: optStr(input.since), focus: optStr(input.focus), namespace: optStr(input.namespace), includeLocation: optBool(input.includeLocation), format: rf as "json" | "markdown" | undefined, maxFollowups: optNum(input.maxFollowups), principal: ctx.authenticatedPrincipal }) }; } });
+defineOperation({
+  name: "briefing", description: "Daily briefing.",
+  schema: strictSchema({ since: S.str, focus: S.str, namespace: S.str, includeLocation: S.bool, format: S.str, maxFollowups: S.num }),
+  handler: async (input, ctx) => {
+    const rf = optStr(input.format);
+    const fe = validateBriefingFormat(rf);
+    if (fe) throw new EngramAccessInputError(fe);
+    // SAFETY: validateBriefingFormat rejects every format except json, markdown, or undefined.
+    const request: EngramAccessBriefingRequest = {
+      since: optStr(input.since), focus: optStr(input.focus), namespace: optStr(input.namespace),
+      includeLocation: optBool(input.includeLocation), format: rf as "json" | "markdown" | undefined,
+      maxFollowups: optNum(input.maxFollowups), principal: ctx.authenticatedPrincipal,
+    };
+    if (ctx.abortSignal) request.abortSignal = ctx.abortSignal;
+    return { result: await ctx.service.briefing(request) };
+  },
+});
 
 // === CONTRADICTION/REVIEW ===
 defineOperation({ name: "review_list", description: "List review pairs.", schema: strictSchema({ filter: S.str, namespace: S.str, limit: S.num }),

package/src/access-schema.ts

@@ -369,11 +369,7 @@ export function reapplyCategoryCoercion<T extends object>(
 const categoryWireSchema = z.enum(
   [...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT],
   {
-    errorMap: () => ({
-      message:
-        `category must be one of: ${[...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT].join(", ")}; ` +
-        'for project state/facts use "fact"',
-    }),
+    error: `category must be one of: ${[...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT].join(", ")}; for project state/facts use "fact"`,
   },
 );
 
@@ -454,7 +450,7 @@ export const reviewDispositionRequestSchema = z.object({
 export const trustZonePromoteRequestSchema = z.object({
   recordId: z.string().trim().min(1, "recordId is required"),
   targetZone: z.enum(["working", "trusted"], {
-    errorMap: () => ({ message: "targetZone must be 'working' or 'trusted'" }),
+    error: "targetZone must be 'working' or 'trusted'",
   }),
   promotionReason: z.string().trim().min(1, "promotionReason is required"),
   recordedAt: z.string().trim().optional(),
@@ -662,16 +658,13 @@ export const offlineSyncSnapshotRequestSchema = z.object({
     .optional(),
 });
 
-export const offlineSyncApplyRequestSchema = z
-  .object({
-    namespace: namespaceSchema,
-    changeset: z.unknown(),
-    returnCurrentFiles: z.boolean().optional(),
-  })
-  .refine((value) => value.changeset !== undefined && value.changeset !== null, {
-    message: "changeset is required",
-    path: ["changeset"],
-  });
+export const offlineSyncApplyRequestSchema = z.object({
+  namespace: namespaceSchema,
+  // zod 4: refine messages cannot override its synthesized nonoptional check,
+  // so presence is enforced on the field itself.
+  changeset: z.custom<unknown>((value) => value !== undefined && value !== null, "changeset is required"),
+  returnCurrentFiles: z.boolean().optional(),
+});
 
 export const offlineSyncFilesRequestSchema = z.object({
   namespace: namespaceSchema,
@@ -693,8 +686,11 @@ export const offlineSyncFileContentRequestSchema = z.object({
 // Action confidence
 // ---------------------------------------------------------------------------
 
+// Outer .optional() keeps the inferred property optional: a transform-typed
+// property becomes required-with-undefined under zod 4 inference, breaking
+// object literals that legitimately omit the key.
 const nullableOptional = <T extends z.ZodTypeAny>(schema: T) =>
-  schema.optional().nullable().transform((value) => value ?? undefined);
+  schema.nullable().transform((value) => value ?? undefined).optional();
 
 const actionConfidenceRuleSchema = z
   .object({

package/src/access-service.ts

@@ -507,6 +507,11 @@ export interface EngramAccessBriefingRequest extends LocationContextRequestOptio
   maxFollowups?: number;
   /** Caller principal for namespace access checks. Transport-bound — never from untrusted payloads. */
   principal?: string;
+  /**
+   * Transport request lifetime. When it aborts, the briefing stops and
+   * rejects with that AbortError instead of running on (issue #3139).
+   */
+  abortSignal?: AbortSignal;
 }
 
 /** Response for `remnic_briefing`. */

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;
+  }
+});