@remnic/core 9.69.39 → 9.69.41

package/src/source-attribution.ts

@@ -482,6 +482,78 @@ export function lastCitationMarkerForTemplate(
   return last;
 }
 
+/**
+ * True when a template can be matched and stripped later. All-placeholder
+ * templates such as `{agent}{sessionId}` have no literal anchors.
+ */
+export function citationTemplateIsDetectable(template: string): boolean {
+  if (typeof template !== "string" || template.length === 0) return false;
+  if (template === DEFAULT_CITATION_FORMAT) return true;
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  if (!PLACEHOLDER_REGEX.test(template)) {
+    PLACEHOLDER_REGEX.lastIndex = 0;
+    return true;
+  }
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  return templateMatcher(template) !== null;
+}
+
+/**
+ * Templates the merge path may lift, preserve, or strip: the default
+ * format, the current format when it is detectable, then any prior
+ * configured formats the caller still holds. Undetectable shapes are
+ * dropped so we never hash or attach a marker we cannot re-match.
+ */
+export function citationTemplatesToRecognize(
+  primary: string | undefined,
+  extra: readonly string[] = [],
+): string[] {
+  const out: string[] = [];
+  const add = (template: string | undefined): void => {
+    if (typeof template !== "string" || template.length === 0) return;
+    if (!citationTemplateIsDetectable(template)) return;
+    if (!out.includes(template)) out.push(template);
+  };
+  add(DEFAULT_CITATION_FORMAT);
+  add(primary);
+  for (const template of extra) add(template);
+  return out;
+}
+
+/**
+ * Prior formats the caller still holds, if any. Absent or malformed
+ * history is ignored — fail safe, do not invent templates.
+ */
+export function citationTemplatesForMerge(config: {
+  inlineSourceAttributionFormat?: string;
+  inlineSourceAttributionFormatHistory?: unknown;
+}): string[] {
+  const raw = config.inlineSourceAttributionFormatHistory;
+  const extra = Array.isArray(raw)
+    ? raw.filter((value): value is string => typeof value === "string" && value.length > 0)
+    : [];
+  return citationTemplatesToRecognize(config.inlineSourceAttributionFormat, extra);
+}
+
+export function lastRecognizedCitationMarker(
+  text: string,
+  templates: readonly string[],
+): string | null {
+  for (const template of templates) {
+    const marker = lastCitationMarkerForTemplate(text, template);
+    if (marker) return marker;
+  }
+  return null;
+}
+
+export function stripRecognizedCitations(text: string, templates: readonly string[]): string {
+  let out = text;
+  for (const template of templates) {
+    out = stripCitationForTemplate(out, template);
+  }
+  return out;
+}
+
 /**
  * Attach an inline citation to fact text.
  *

package/src/storage/cas-revision-store.test.ts

@@ -226,6 +226,7 @@ test("an evidenced gated recovery defers a reserve-only marker to the path-locke
       status: "present",
       revision: b.pendingRevision,
       committedDigest: store.digestContent("landed bytes"),
+      committedSemanticFingerprint: store.digestContent("landed bytes"),
     });
   });
 });
@@ -258,6 +259,7 @@ test("recoverPendingRevision publishes a crashed reservation whose write landed
       status: "present",
       revision: b.pendingRevision,
       committedDigest: store.digestContent("new durable bytes"),
+      committedSemanticFingerprint: store.digestContent("new durable bytes"),
     });
     assert.equal(await store.recoverPendingRevision(target), "committed", "idempotent");
   });
@@ -361,6 +363,7 @@ test("beginRevisionTransaction with expectedContent persists expectedDigest in p
       status: "present",
       revision: txn2.pendingRevision,
       committedDigest: store.digestContent(expectedContent),
+      committedSemanticFingerprint: store.digestContent(expectedContent),
     });
   });
 });
@@ -425,6 +428,7 @@ test("legacy pending shards without writeLanded treat expectedDigest as already
       status: "present",
       revision: "2026-08-01T00:00:00.000Z",
       committedDigest: expectedDigest,
+      committedSemanticFingerprint: expectedDigest,
     });
   });
 });

package/src/storage/cas-revision-store.ts

@@ -35,6 +35,15 @@ type CasRevisionShard = {
   writeLanded?: boolean;
   /** #2813 (P1 B): sha256 hex digest of the durable memory file when committed. */
   committedDigest?: string | null;
+  /** #2870: sha256 of the durable file's canonical SEMANTIC text — the
+   * file with the access-telemetry frontmatter keys (`accessCount:`,
+   * `lastAccessed:`) stripped, the same exclusion set
+   * `invalidationCommitFingerprint` applies to parsed records. Promotion
+   * binds to THIS, never to the byte digest: an access-tracking flush
+   * rewrites exactly those two lines without minting a receipt
+   * (`isSemanticFrontmatterChange` is false), and must not invalidate a
+   * valid promotion. null means the file was absent at commit. */
+  committedSemanticFingerprint?: string | null;
 };
 
 type CasRevisionMetadata = {
@@ -51,7 +60,7 @@ type CasRevisionMetadata = {
  *   `readRevision` collapses this into `undefined`; callers that transact
  *   on receipt identity MUST refuse instead. */
 export type CasRevisionReadStatus =
-  | { status: "present"; revision: string; committedDigest?: string }
+  | { status: "present"; revision: string; committedDigest?: string; committedSemanticFingerprint?: string }
   | { status: "absent" }
   | { status: "unavailable"; reason: string };
 
@@ -78,7 +87,7 @@ export interface CasRevisionTransaction {
 type CasShardView =
   | { kind: "missing" }
   | { kind: "foreign" }
-  | { kind: "committed"; revision: string; committedDigest?: string; foreign: boolean }
+  | { kind: "committed"; revision: string; committedDigest?: string; committedSemanticFingerprint?: string; foreign: boolean }
   | {
       kind: "pending";
       revision: string;
@@ -89,6 +98,29 @@ type CasShardView =
       writeLanded?: boolean;
     };
 
+const ACCESS_TELEMETRY_FRONTMATTER_KEY = /^(?:accessCount|lastAccessed):/;
+
+/**
+ * #2870: canonical SEMANTIC text of a durable memory file — the file with
+ * the access-telemetry frontmatter keys (`accessCount:`, `lastAccessed:`)
+ * removed. This is the file-level twin of `invalidationCommitFingerprint`
+ * (deletion-revision-store.ts): the same exclusion set, computed without
+ * parsing, so the CAS receipt can record it at commit time from the same
+ * bytes the digests come from. Only TOP-LEVEL frontmatter lines are
+ * stripped — serialized frontmatter is flat `key: value` lines, and nested
+ * blocks (links:) are indented and never match. A file without a leading
+ * frontmatter block is returned unchanged.
+ */
+export function canonicalSemanticFileText(raw: string): string {
+  const lines = raw.split("\n");
+  if (lines[0] !== "---") return raw;
+  const closing = lines.indexOf("---", 1);
+  if (closing === -1) return raw;
+  const frontmatter = lines
+    .slice(1, closing)
+    .filter((line) => !ACCESS_TELEMETRY_FRONTMATTER_KEY.test(line));
+  return [...lines.slice(0, 1), ...frontmatter, ...lines.slice(closing)].join("\n");
+}
 const CAS_REVISION_LOCK_STALE_MS = 60_000;
 const CAS_REVISION_LOCK_MAX_WAIT_MS = 120_000;
 const SHA256_HEX = /^[0-9a-f]{64}$/;
@@ -252,6 +284,10 @@ export class CasRevisionStore {
       const foreign = root.path !== relativePath;
       const committedDigest =
         typeof root.committedDigest === "string" ? root.committedDigest : undefined;
+      const committedSemanticFingerprint =
+        typeof root.committedSemanticFingerprint === "string"
+          ? root.committedSemanticFingerprint
+          : undefined;
       return root.state === "pending"
         ? {
             kind: "pending",
@@ -262,7 +298,13 @@ export class CasRevisionStore {
             expectedDigest: root.expectedDigest as string | null | undefined,
             ...(typeof root.writeLanded === "boolean" ? { writeLanded: root.writeLanded } : {}),
           }
-        : { kind: "committed", revision: root.revision, committedDigest, foreign };
+        : {
+            kind: "committed",
+            revision: root.revision,
+            committedDigest,
+            committedSemanticFingerprint,
+            foreign,
+          };
     }
     // Pre-two-phase shard: a full-shape match reads as committed; anything
     // else keeps the legacy fall-through (legacy metadata, then absence).
@@ -274,14 +316,26 @@ export class CasRevisionStore {
     ) {
       const committedDigest =
         typeof root.committedDigest === "string" ? root.committedDigest : undefined;
-      return { kind: "committed", revision: root.revision, committedDigest, foreign: false };
+      const committedSemanticFingerprint =
+        typeof root.committedSemanticFingerprint === "string"
+          ? root.committedSemanticFingerprint
+          : undefined;
+      return {
+        kind: "committed",
+        revision: root.revision,
+        committedDigest,
+        committedSemanticFingerprint,
+        foreign: false,
+      };
     }
     return { kind: "foreign" };
   }
 
-  private async readStandingRevision(relativePath: string): Promise<string | undefined> {
+  private async readStandingRevision(relativePath: string): Promise<
+    { revision: string; committedDigest?: string; committedSemanticFingerprint?: string } | undefined
+  > {
     try {
-      return (await this.readStandingRevisionStrict(relativePath))?.revision;
+      return await this.readStandingRevisionStrict(relativePath);
     } catch (error) {
       log.warn(`CasRevisionStore failed to read standing revision for ${relativePath}: ${error}`);
       return undefined;
@@ -299,7 +353,9 @@ export class CasRevisionStore {
    * refuse instead of mistaking the failure for absence. */
   private async readStandingRevisionStrict(
     relativePath: string,
-  ): Promise<{ revision: string; committedDigest?: string } | undefined> {
+  ): Promise<
+    { revision: string; committedDigest?: string; committedSemanticFingerprint?: string } | undefined
+  > {
     const { shardPath } = await this.getSafeShardInfo(relativePath);
     const view = await this.readShardView(shardPath, relativePath);
     if (view.kind === "pending") {
@@ -308,7 +364,11 @@ export class CasRevisionStore {
       );
     }
     if (view.kind === "committed" && !view.foreign) {
-      return { revision: view.revision, committedDigest: view.committedDigest };
+      return {
+        revision: view.revision,
+        committedDigest: view.committedDigest,
+        committedSemanticFingerprint: view.committedSemanticFingerprint,
+      };
     }
     const legacyMap = await this.readLegacyMetadata();
     const legacyRev = legacyMap.get(relativePath);
@@ -326,6 +386,7 @@ export class CasRevisionStore {
       baselineDigest?: string | null;
       expectedDigest?: string | null;
       committedDigest?: string | null;
+      committedSemanticFingerprint?: string | null;
       writeLanded?: boolean;
     },
   ): Promise<void> {
@@ -335,6 +396,9 @@ export class CasRevisionStore {
       if (evidence?.committedDigest !== undefined) {
         payload.committedDigest = evidence.committedDigest;
       }
+      if (evidence?.committedSemanticFingerprint !== undefined) {
+        payload.committedSemanticFingerprint = evidence.committedSemanticFingerprint;
+      }
     } else {
       payload = { version: 1, path: relativePath, revision, state };
       if (previous !== undefined) payload.previous = previous;
@@ -401,7 +465,7 @@ export class CasRevisionStore {
   async readRevision(filePath: string): Promise<string | undefined> {
     try {
       const relativePath = await this.resolveRelativePath(filePath);
-      return await this.readStandingRevision(relativePath);
+      return (await this.readStandingRevision(relativePath))?.revision;
     } catch (error) {
       log.warn(`CasRevisionStore.readRevision failed for ${filePath}: ${error}`);
       return undefined;
@@ -426,6 +490,9 @@ export class CasRevisionStore {
             ...(standing.committedDigest !== undefined
               ? { committedDigest: standing.committedDigest }
               : {}),
+            ...(standing.committedSemanticFingerprint !== undefined
+              ? { committedSemanticFingerprint: standing.committedSemanticFingerprint }
+              : {}),
           };
     } catch (error) {
       return { status: "unavailable", reason: error instanceof Error ? error.message : String(error) };
@@ -477,19 +544,34 @@ export class CasRevisionStore {
   }
 
   public async digestDurableFile(filePath: string): Promise<string | null> {
+    const bytes = await this.readDurableBytes(filePath);
+    return bytes === null ? null : createHash("sha256").update(bytes).digest("hex");
+  }
+
+  /** #2870: canonical SEMANTIC fingerprint of the durable file — its text
+   * with the access-telemetry frontmatter keys stripped
+   * ({@link canonicalSemanticFileText}), hashed. Null means the file was
+   * absent. A fingerprint, never memory content. */
+  public async semanticFingerprintDurableFile(filePath: string): Promise<string | null> {
+    const bytes = await this.readDurableBytes(filePath);
+    return bytes === null
+      ? null
+      : createHash("sha256").update(canonicalSemanticFileText(bytes.toString("utf8"))).digest("hex");
+  }
+
+  private async readDurableBytes(filePath: string): Promise<Buffer | null> {
     const relativePath = await this.resolveRelativePath(filePath);
     const baseDir = path.resolve(this.baseDir);
     const target = await resolveSafeStoragePath(baseDir, relativePath);
-    let bytes: Buffer;
     try {
-      bytes = await readFile(target);
+      return await readFile(target);
     } catch (error) {
       if (isErrnoCode(error, "ENOENT")) return null;
       throw new Error(
         `CAS revision evidence: durable memory file ${relativePath} is unreadable: ${error instanceof Error ? error.message : String(error)}`,
       );
     }
-    return createHash("sha256").update(bytes).digest("hex");
+
   }
 
   /** #2807: mark the reserved write as landed. Verifies a pre-recorded
@@ -531,8 +613,14 @@ export class CasRevisionStore {
         if (outcome === "commit") {
           const committedDigest =
             view.expectedDigest ?? (await this.digestDurableFile(relativePath));
+          // #2870: publish the canonical semantic fingerprint alongside the
+          // byte digest so promotion can bind semantic identity without
+          // refusing on access-only telemetry flushes.
+          const committedSemanticFingerprint =
+            await this.semanticFingerprintDurableFile(relativePath);
           await this.writeShard(shardPath, relativePath, token, lock, "committed", undefined, {
             committedDigest,
+            committedSemanticFingerprint,
           });
         } else if (view.previous !== undefined) {
           await this.writeShard(shardPath, relativePath, view.previous, lock, "committed");
@@ -577,8 +665,11 @@ export class CasRevisionStore {
       if (fileWriteLanded) {
         const committedDigest =
           view.expectedDigest ?? (await this.digestDurableFile(relativePath));
+        const committedSemanticFingerprint =
+          await this.semanticFingerprintDurableFile(relativePath);
         await this.writeShard(shardPath, relativePath, view.revision, lock, "committed", undefined, {
           committedDigest,
+          committedSemanticFingerprint,
         });
       } else if (view.previous !== undefined) {
         await this.writeShard(shardPath, relativePath, view.previous, lock, "committed");
@@ -623,6 +714,7 @@ export class CasRevisionStore {
       if (view.expectedDigest !== undefined && currentDigest === view.expectedDigest) {
         await this.writeShard(shardPath, relativePath, view.revision, lock, "committed", undefined, {
           committedDigest: view.expectedDigest,
+          committedSemanticFingerprint: await this.semanticFingerprintDurableFile(relativePath),
         });
         return "committed";
       }

package/src/storage-frontmatter-cas.test.ts

@@ -267,11 +267,13 @@ test("readCasRevisionStatus distinguishes present, absent, and unavailable recei
     assert.equal(await storage.writeMemoryFrontmatter(memory, { status: "archived" }), true);
     const standing = await storage.readCasRevision(memory.path);
     assert.ok(standing);
-    assert.deepEqual(await storage.readCasRevisionStatus(memory.path), {
-      status: "present",
-      revision: standing,
-      committedDigest: createHash("sha256").update(await readFile(memory.path)).digest("hex"),
-    });
+    const archived = await storage.readCasRevisionStatus(memory.path);
+    assert.equal(archived.status, "present");
+    assert.equal(archived.revision, standing);
+    assert.equal(
+      archived.status === "present" ? archived.committedDigest : undefined,
+      createHash("sha256").update(await readFile(memory.path)).digest("hex"),
+    );
 
     // A torn shard write: the receipt EXISTS but cannot be read. That is
     // unavailability — never absence — while the fail-open read keeps
@@ -554,11 +556,13 @@ test("a receipt publication failure after the memory write recovers from recorde
 
     // #2807: writeLanded recorded evidence, so the next unlocked read
     // publishes the reserved token with the intended file digest.
-    assert.deepEqual(await storage.readCasRevisionStatus(before.path), {
-      status: "present",
-      revision: reserved,
-      committedDigest: createHash("sha256").update(onDisk).digest("hex"),
-    });
+    const published = await storage.readCasRevisionStatus(before.path);
+    assert.equal(published.status, "present");
+    assert.equal(published.revision, reserved);
+    assert.equal(
+      published.status === "present" ? published.committedDigest : undefined,
+      createHash("sha256").update(onDisk).digest("hex"),
+    );
     assert.equal(
       await storage.updateMemory(created.id, "Second body after evidence recovery."),
       true,
@@ -676,13 +680,11 @@ test("restart after a crash between write and commit publishes the reserved rece
 
     const restarted = new StorageManager(dir);
     const landedBytes = await readFile(memory.path);
-    assert.deepEqual(
-      await restarted.readCasRevisionStatus(memory.path),
-      {
-        status: "present",
-        revision: reserved,
-        committedDigest: createHash("sha256").update(landedBytes).digest("hex"),
-      },
+    const restartedStatus = await restarted.readCasRevisionStatus(memory.path);
+    assert.ok(
+      restartedStatus.status === "present" &&
+        restartedStatus.revision === reserved &&
+        restartedStatus.committedDigest === createHash("sha256").update(landedBytes).digest("hex"),
       "the first read after restart publishes the reserved token from writeLanded evidence",
     );
     assert.equal(

package/src/summarizer.ts

@@ -223,7 +223,11 @@ export class HourlySummarizer {
     if (this.config.backgroundGeneration) {
       try {
         const text = await completeBackgroundGeneration(this.config, [
-          { role: "system", content: "You are a conversation summarization system. Output valid JSON only." },
+          {
+            role: "system",
+            content:
+              "You are a conversation summarization system. Summarize the following conversation transcript into 3-5 concise bullet points.\n\nGuidelines:\n- Focus on what was accomplished, decided, or discussed\n- Include specific topics, projects, or entities mentioned\n- Note any significant user requests or agent actions\n- Keep bullets brief but informative (1-2 sentences each)\n- Skip trivial greetings or meta-conversation\n- Use present tense for ongoing work, past for completed items\n\nRespond with valid JSON only, matching this schema:\n{\"bullets\": [\"bullet 1\", \"bullet 2\", \"bullet 3\"]}",
+          },
           { role: "user", content: `Summarize this conversation:\n\n${conversation}` },
         ]);
         const parsed = parseBackgroundGenerationJson(text, (value) => HourlySummarySchema.parse(value));

package/src/task-llm-config.test.ts

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { initLogger, resetLogger } from "./logger.js";
+import { parseTaskLlmConfig, resetTaskLlmLegacyWarningsForTest } from "./task-llm-config.js";
+
+function captureWarns(): string[] {
+  const warns: string[] = [];
+  initLogger(
+    {
+      info() {},
+      warn(msg) {
+        warns.push(msg);
+      },
+      error() {},
+    },
+    false,
+    { timestamps: false },
+  );
+  return warns;
+}
+
+test("taskLlmTimeoutMs wins over legacy localLlmTimeoutMs", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const parsed = parseTaskLlmConfig({
+    taskLlmTimeoutMs: 90_000,
+    localLlmTimeoutMs: 12_000,
+  });
+  assert.equal(parsed.timeoutMs, 90_000);
+  assert.equal(parsed.localTimeoutMs, 12_000);
+});
+
+test("taskLlmFallback wins over legacy localLlmFallback", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const parsed = parseTaskLlmConfig({
+    taskLlmFallback: false,
+    localLlmFallback: true,
+  });
+  assert.equal(parsed.fallback, false);
+});
+
+test("legacy localLlmTimeoutMs is read when taskLlmTimeoutMs is absent and warns once", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const warns = captureWarns();
+  try {
+    const first = parseTaskLlmConfig({ localLlmTimeoutMs: 45_000 });
+    const second = parseTaskLlmConfig({ localLlmTimeoutMs: 45_000 });
+    assert.equal(first.timeoutMs, 45_000);
+    assert.equal(second.timeoutMs, 45_000);
+    const legacyWarns = warns.filter((line) => line.includes("localLlmTimeoutMs is a legacy alias for taskLlmTimeoutMs"));
+    assert.equal(legacyWarns.length, 1);
+  } finally {
+    resetLogger();
+    resetTaskLlmLegacyWarningsForTest();
+  }
+});
+
+test("legacy localLlmFallback is read when taskLlmFallback is absent and warns once", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const warns = captureWarns();
+  try {
+    const first = parseTaskLlmConfig({ localLlmFallback: false });
+    const second = parseTaskLlmConfig({ localLlmFallback: false });
+    assert.equal(first.fallback, false);
+    assert.equal(second.fallback, false);
+    const legacyWarns = warns.filter((line) => line.includes("localLlmFallback is a legacy alias for taskLlmFallback"));
+    assert.equal(legacyWarns.length, 1);
+  } finally {
+    resetLogger();
+    resetTaskLlmLegacyWarningsForTest();
+  }
+});
+
+test("neither key uses defaults and does not warn", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const warns = captureWarns();
+  try {
+    const parsed = parseTaskLlmConfig({});
+    assert.equal(parsed.timeoutMs, 180_000);
+    assert.equal(parsed.localTimeoutMs, 180_000);
+    assert.equal(parsed.fallback, true);
+    assert.equal(warns.some((line) => line.includes("legacy alias")), false);
+  } finally {
+    resetLogger();
+    resetTaskLlmLegacyWarningsForTest();
+  }
+});
+
+test("present-with-undefined taskLlmTimeoutMs does not fall through to the legacy key", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const parsed = parseTaskLlmConfig({
+    taskLlmTimeoutMs: undefined,
+    localLlmTimeoutMs: 12_000,
+  });
+  assert.equal(parsed.timeoutMs, 180_000);
+  assert.equal(parsed.localTimeoutMs, 12_000);
+});
+
+test("taskLlmFallback coerces string false", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const parsed = parseTaskLlmConfig({ taskLlmFallback: "false" });
+  assert.equal(parsed.fallback, false);
+});
+
+test("parseConfig wires taskLlmTimeoutMs onto PluginConfig and keeps localLlmTimeoutMs independent", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const cfg = parseConfig({
+    taskLlmTimeoutMs: 90_000,
+    localLlmTimeoutMs: 12_000,
+    taskLlmFallback: false,
+  });
+  assert.equal(cfg.taskLlmTimeoutMs, 90_000);
+  assert.equal(cfg.localLlmTimeoutMs, 12_000);
+  assert.equal(cfg.localLlmFallback, false);
+  assert.equal(cfg.taskLlmFallback, false);
+});
+
+test("parseConfig legacy-only timeout still populates taskLlmTimeoutMs", () => {
+  resetTaskLlmLegacyWarningsForTest();
+  const cfg = parseConfig({ localLlmTimeoutMs: 600_000 });
+  assert.equal(cfg.taskLlmTimeoutMs, 600_000);
+  assert.equal(cfg.localLlmTimeoutMs, 600_000);
+});

package/src/task-llm-config.ts

@@ -0,0 +1,88 @@
+/**
+ * Honest names for the gateway/task LLM chain (issue #2967).
+ *
+ * `FallbackLlmClient` is the primary configured path in gateway mode, not a
+ * secondary recovery path. `taskLlmTimeoutMs` / `taskLlmFallback` are the
+ * current keys. `localLlmTimeoutMs` / `localLlmFallback` remain documented
+ * legacy aliases, read only when the corresponding new key is absent.
+ */
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { log } from "./logger.js";
+
+const DEFAULT_TIMEOUT_MS = 180_000;
+const MIN_TIMEOUT_MS = 1;
+const MAX_TIMEOUT_MS = 86_400_000;
+
+const warnedLegacy = new Set<string>();
+
+export function resetTaskLlmLegacyWarningsForTest(): void {
+  warnedLegacy.clear();
+}
+
+function warnLegacyOnce(legacyKey: string, currentKey: string, extra: string): void {
+  if (warnedLegacy.has(legacyKey)) return;
+  warnedLegacy.add(legacyKey);
+  log.warn(
+    `config: ${legacyKey} is a legacy alias for ${currentKey}; set ${currentKey} instead. ${legacyKey} still works when ${currentKey} is absent. ${extra}`,
+  );
+}
+
+function parseBoundedIntegerMs(value: unknown, fallback: number): number {
+  const coerced = coerceNumber(value);
+  if (coerced === undefined) return fallback;
+  return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.floor(coerced)));
+}
+
+function hasOwnKey(raw: Record<string, unknown>, key: string): boolean {
+  return Object.hasOwn(raw, key);
+}
+
+export interface ParsedTaskLlmConfig {
+  timeoutMs: number;
+  localTimeoutMs: number;
+  fallback: boolean;
+}
+
+/**
+ * Resolve task-LLM timeout and local→task fallback.
+ *
+ * New key wins when present (including present-with-`undefined`, which takes
+ * the default rather than falling through to the legacy key). Legacy keys are
+ * read only when the new key is absent, and warn once per process.
+ */
+export function parseTaskLlmConfig(cfg: Record<string, unknown>): ParsedTaskLlmConfig {
+  const localTimeoutMs = hasOwnKey(cfg, "localLlmTimeoutMs")
+    ? parseBoundedIntegerMs(cfg.localLlmTimeoutMs, DEFAULT_TIMEOUT_MS)
+    : DEFAULT_TIMEOUT_MS;
+
+  let timeoutMs: number;
+  if (hasOwnKey(cfg, "taskLlmTimeoutMs")) {
+    timeoutMs = parseBoundedIntegerMs(cfg.taskLlmTimeoutMs, DEFAULT_TIMEOUT_MS);
+  } else if (hasOwnKey(cfg, "localLlmTimeoutMs")) {
+    warnLegacyOnce(
+      "localLlmTimeoutMs",
+      "taskLlmTimeoutMs",
+      "localLlmTimeoutMs remains the local-endpoint timeout; without taskLlmTimeoutMs it also sizes the gateway/task chain.",
+    );
+    timeoutMs = localTimeoutMs;
+  } else {
+    timeoutMs = DEFAULT_TIMEOUT_MS;
+  }
+
+  let fallback: boolean;
+  if (hasOwnKey(cfg, "taskLlmFallback")) {
+    const coerced = coerceBool(cfg.taskLlmFallback, "taskLlmFallback");
+    fallback = coerced !== undefined ? coerced : true;
+  } else if (hasOwnKey(cfg, "localLlmFallback")) {
+    warnLegacyOnce(
+      "localLlmFallback",
+      "taskLlmFallback",
+      "taskLlmFallback is the current name for using the gateway/task chain when the local path fails.",
+    );
+    fallback = cfg.localLlmFallback !== false;
+  } else {
+    fallback = true;
+  }
+
+  return { timeoutMs, localTimeoutMs, fallback };
+}