@remnic/core 9.69.39 → 9.69.41

package/src/activity/vault-frontmatter.ts

@@ -37,3 +37,134 @@ export function applyVaultFrontmatter(
     .map((key) => `${key}: ${merged.get(key)}`)
     .join("\n");
 }
+
+/**
+ * Frontmatter property boundary for the vault publisher (issue #2917).
+ *
+ * Property values written into note frontmatter must be single-line
+ * plain YAML scalars (or lists of them) whose rendered `key: value` line
+ * cannot change shape or inject keys when a YAML parser reads the note
+ * back. Validation is pure and total; the publisher runs it before any
+ * note byte is read or written, so a rejection can never leave a
+ * half-merged note behind.
+ */
+
+/** A supported property value: one plain scalar, or a list of them. */
+export type VaultPropertyValue = string | readonly string[];
+
+export const VAULT_PROPERTY_KEY_MAX_CHARS = 64;
+export const VAULT_PROPERTY_SCALAR_MAX_CHARS = 200;
+export const VAULT_PROPERTY_LIST_MAX_ITEMS = 20;
+export const VAULT_PROPERTY_TOTAL_MAX_CHARS = 2_000;
+
+// C0 controls, DEL, and C1 controls. Covers \n, \r, \t — a newline is the
+// frontmatter-injection primitive (`v\ninjected: yes` becomes a new key).
+const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]/;
+// Characters that make the first character a YAML indicator. `-`, `?`,
+// and `:` only indicate when followed by a space, so `-5` stays a plain
+// scalar while `- 5` does not.
+const INDICATOR_CHARS = ",[]{}#&*!|>'\"%@`";
+const INJECTION_RE = /: | #/;
+// Flow-collection delimiters. Lists render as `[a, b]`; a bare delimiter
+// inside an item splits or closes the sequence on re-read.
+const FLOW_ITEM_DELIM_RE = /[[\]{},]/;
+
+export type ValidateVaultPropertyResult = { ok: true } | { ok: false; reason: string };
+
+/** Render a validated value the way `mergeFrontmatterKeys` writes it. */
+export function renderVaultPropertyValue(value: VaultPropertyValue): string {
+  return typeof value === "string" ? value : `[${value.join(", ")}]`;
+}
+
+function hasLeadingYamlIndicator(text: string): boolean {
+  const first = text[0];
+  if (first === undefined) return false;
+  return INDICATOR_CHARS.includes(first) || ("-?:".includes(first) && text[1] === " ");
+}
+
+function validateScalar(value: string, label: string): ValidateVaultPropertyResult {
+  if (value.length === 0) {
+    return { ok: false, reason: `${label} must not be empty` };
+  }
+  if (value.length > VAULT_PROPERTY_SCALAR_MAX_CHARS) {
+    return { ok: false, reason: `${label} exceeds ${VAULT_PROPERTY_SCALAR_MAX_CHARS} characters` };
+  }
+  if (CONTROL_RE.test(value)) {
+    return { ok: false, reason: `${label} must not contain control characters or line breaks` };
+  }
+  if (value !== value.trim()) {
+    return { ok: false, reason: `${label} must not carry leading or trailing whitespace` };
+  }
+  if (hasLeadingYamlIndicator(value)) {
+    return { ok: false, reason: `${label} must be a plain scalar (leading "${value[0]}" changes its YAML shape)` };
+  }
+  if (INJECTION_RE.test(value)) {
+    return { ok: false, reason: `${label} must not contain ": " or " #"` };
+  }
+  if (value.endsWith(":")) {
+    return { ok: false, reason: `${label} must not end with ":"` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Validate the final (already-prefixed) property set a publish would
+ * write: key shape, per-value scalar/list shape, per-value bounds, and
+ * the total rendered size across every entry.
+ */
+export function validateVaultProperties(
+  entries: ReadonlyArray<{ key: string; value: VaultPropertyValue }>,
+): ValidateVaultPropertyResult {
+  let total = 0;
+  for (const { key, value } of entries) {
+    if (key.length === 0) {
+      return { ok: false, reason: "property keys must not be empty" };
+    }
+    if (key.length > VAULT_PROPERTY_KEY_MAX_CHARS) {
+      return { ok: false, reason: `property key exceeds ${VAULT_PROPERTY_KEY_MAX_CHARS} characters` };
+    }
+    if (
+      CONTROL_RE.test(key) ||
+      key !== key.trim() ||
+      key.includes(":") ||
+      key.includes("#") ||
+      hasLeadingYamlIndicator(key)
+    ) {
+      return { ok: false, reason: `property key ${JSON.stringify(key)} is not a plain mapping key` };
+    }
+    if (typeof value === "string") {
+      const scalar = validateScalar(value, `property ${key}`);
+      if (!scalar.ok) return scalar;
+    } else {
+      if (!Array.isArray(value) || value.length === 0) {
+        return { ok: false, reason: `property ${key} must be a scalar string or a non-empty list of scalar strings` };
+      }
+      if (value.length > VAULT_PROPERTY_LIST_MAX_ITEMS) {
+        return { ok: false, reason: `property ${key} exceeds ${VAULT_PROPERTY_LIST_MAX_ITEMS} list items` };
+      }
+      for (const item of value) {
+        if (typeof item !== "string") {
+          return { ok: false, reason: `property ${key} must be a scalar string or a list of scalar strings` };
+        }
+        const scalar = validateScalar(item, `property ${key} list item`);
+        if (!scalar.ok) return scalar;
+        // Lists render in flow form `[a, b]`; a bare delimiter inside an
+        // item would split or close the sequence on re-read.
+        if (FLOW_ITEM_DELIM_RE.test(item)) {
+          return {
+            ok: false,
+            reason: `property ${key} list item must not contain flow delimiters "[", "]", "{", "}", or ","`,
+          };
+        }
+      }
+    }
+    total += key.length + 2 + renderVaultPropertyValue(value).length;
+    if (total > VAULT_PROPERTY_TOTAL_MAX_CHARS) {
+      return {
+        ok: false,
+        reason: `frontmatter properties exceed the ${VAULT_PROPERTY_TOTAL_MAX_CHARS}-character total`,
+      };
+    }
+  }
+  return { ok: true };
+}

package/src/activity/vault-publish.ts

@@ -261,6 +261,12 @@ export function parseAtxHeading(line: string): { level: number; text: string } |
   return { level, text: line.slice(start, end) };
 }
 
+/** True when `## ${name}` parses back to the same heading text. */
+export function headingSurvivesRoundTrip(name: string): boolean {
+  const parsed = parseAtxHeading(`## ${name}`);
+  return parsed !== null && parsed.text === name;
+}
+
 export function publishVaultRegion(input: {
   vaultPath: string;
   relativeFile: string;

package/src/activity/vault-publisher.test.ts

@@ -879,3 +879,175 @@ test("a concurrent editor save between read and rename aborts the publish and ke
     setVaultPublisherTestHooks(null);
   }
 });
+
+// ── Input-boundary regressions (issue #2917) ────────────────────────────
+// Every rejection below must fire before any file byte is read or written.
+
+test("a whitespace-padded section name is rejected, not silently trimmed (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        sections: [{ name: " timeline ", content: "fresh recap" }],
+      }),
+    /is not a valid region name/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+});
+
+test("a heading-strategy section name that cannot round-trip through the heading parser is rejected (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  // `## Timeline #` parses back as `Timeline` (closing hash sequence), so
+  // the region could never be matched on any publish.
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        strategy: "heading",
+        sections: [{ name: "Timeline #", content: "fresh recap" }],
+      }),
+    /not matchable by the heading parser/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+});
+
+test("a newline-bearing frontmatter value is rejected before any file mutation (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  const mtime = statSync(notePath).mtimeMs;
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        sections: [
+          {
+            name: "timeline",
+            content: "fresh recap",
+            properties: { focus: "220\ninjected: yes" },
+          },
+        ],
+        propertiesMode: "frontmatter",
+      }),
+    /control characters or line breaks/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+  assert.equal(statSync(notePath).mtimeMs, mtime, "no write attempt was made");
+});
+
+test("an oversize or injection-shaped frontmatter value is rejected before any file mutation (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  for (const value of ["x".repeat(201), "[flow]", "a #comment", " leading-space"] as const) {
+    assert.throws(
+      () =>
+        publishVaultNote({
+          vaultPath: vault,
+          notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+          date: DATE,
+          sections: [{ name: "timeline", content: "fresh recap", properties: { focus: value } }],
+          propertiesMode: "frontmatter",
+        }),
+      RangeError,
+      `value ${JSON.stringify(value)} must be rejected at the boundary`,
+    );
+  }
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+});
+
+test("a valid list property publishes as a flow list in frontmatter (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const status = publishVaultNote({
+    vaultPath: vault,
+    notePathTemplate: "Daily Notes/{yyyy}/{MM}/{yyyy}-{MM}-{dd}.md",
+    date: DATE,
+    sections: [{ name: "timeline", content: "fresh recap", properties: { cards: ["a", "b"] } }],
+    propertiesMode: "frontmatter",
+  });
+  const after = readFileSync(notePath, "utf8");
+  assert.match(after, /^remnic_cards: \[a, b\]$/m);
+});
+
+test("frontmatter property totals are bounded across sections (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  // Each value is under the per-scalar cap; the SUM crosses the total.
+  const big = "v".repeat(200);
+  const properties = Object.fromEntries(
+    Array.from({ length: 12 }, (_, i) => [`k${i}`, big]),
+  );
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        sections: [
+          { name: "timeline", content: "fresh recap", properties },
+        ],
+        propertiesMode: "frontmatter",
+      }),
+    /character total/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+});
+
+test("a prefix that makes the final key start with a YAML indicator is rejected before any file mutation (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  const mtime = statSync(notePath).mtimeMs;
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        sections: [{ name: "timeline", content: "fresh recap", properties: { focus: "220" } }],
+        propertiesMode: "frontmatter",
+        propertiesPrefix: "[",
+      }),
+    /not a plain mapping key/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+  assert.equal(statSync(notePath).mtimeMs, mtime, "no write attempt was made");
+});
+
+test("a list item carrying a flow delimiter is rejected before any file mutation (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  const before = readFileSync(notePath, "utf8");
+  const mtime = statSync(notePath).mtimeMs;
+  assert.throws(
+    () =>
+      publishVaultNote({
+        vaultPath: vault,
+        notePathTemplate: "{yyyy}-{MM}-{dd}.md",
+        date: DATE,
+        sections: [{ name: "timeline", content: "fresh recap", properties: { cards: ["a{"] } }],
+        propertiesMode: "frontmatter",
+      }),
+    /flow delimiter/,
+  );
+  assert.equal(readFileSync(notePath, "utf8"), before, "the note is untouched");
+  assert.equal(statSync(notePath).mtimeMs, mtime, "no write attempt was made");
+});
+
+test("a valid prefix still publishes a plain final key (#2917)", () => {
+  const { vault, notePath } = makeVault();
+  publishVaultNote({
+    vaultPath: vault,
+    notePathTemplate: "Daily Notes/{yyyy}/{MM}/{yyyy}-{MM}-{dd}.md",
+    date: DATE,
+    sections: [{ name: "timeline", content: "fresh recap", properties: { focus: "220" } }],
+    propertiesMode: "frontmatter",
+    propertiesPrefix: "x_",
+  });
+  assert.match(readFileSync(notePath, "utf8"), /^x_focus: 220$/m);
+});

package/src/activity/vault-publisher.ts

@@ -19,7 +19,12 @@ import { chmodSync, chownSync, lstatSync, mkdirSync, readFileSync, realpathSync,
 import path from "node:path";
 
 import { expandTildePath } from "../utils/path.js";
-import { applyManagedRegion, fileLines } from "./vault-publish.js";
+import { applyManagedRegion, fileLines, headingSurvivesRoundTrip } from "./vault-publish.js";
+import {
+  renderVaultPropertyValue,
+  validateVaultProperties,
+  type VaultPropertyValue,
+} from "./vault-frontmatter.js";
 import { insertMarkersUnderHeading } from "./vault-insert.js";
 import { validateRegionName } from "./vault-region.js";
 import { assertBeginEndPair } from "./vault-region-pair.js";
@@ -37,8 +42,8 @@ export interface VaultSectionPublish {
   name: string;
   /** Rendered artifact body the region owns. */
   content: string;
-  /** Unprefixed stats, e.g. `{ focus_minutes: "220" }`; keys get the configured prefix. */
-  properties?: Readonly<Record<string, string>>;
+  /** Unprefixed stats, e.g. `{ focus_minutes: "220" }`; keys get the configured prefix. Values are plain single-line scalars or lists of them (vault-frontmatter.ts). */
+  properties?: Readonly<Record<string, VaultPropertyValue>>;
   /** When present, a provenance footer line is appended inside the region. */
   provenance?: VaultSectionProvenance;
 }
@@ -97,6 +102,48 @@ export function publishVaultNote(input: PublishVaultNoteInput): VaultPublishStat
     }
   }
 
+
+  // Issue #2917: input boundaries are total and run BEFORE any note byte
+  // is read or written, so a rejection can never leave a half-merged
+  // note behind.
+
+  // The heading strategy matches a section by scanning note headings with
+  // the shared ATX parser (`applyHeadingRegion`/`insertMarkersUnderHeading`).
+  // A name whose rendered heading parses back to something else — a
+  // trailing `#` run is stripped as a closing sequence (`## Timeline #`
+  // reads as `Timeline`) — can never be matched, so every publish would
+  // no-op or mis-scope. Reject it here rather than at match time.
+  const headingsToProbe =
+    strategy === "heading" ? input.sections.map((section) => section.name) : [];
+  if (typeof input.insertUnderHeading === "string" && input.insertUnderHeading.length > 0) {
+    headingsToProbe.push(input.insertUnderHeading);
+  }
+  for (const headingName of headingsToProbe) {
+    if (!headingSurvivesRoundTrip(headingName)) {
+      throw new RangeError(
+        `Section name ${JSON.stringify(headingName)} is not matchable by the heading parser; it must survive a render-and-parse round trip.`,
+      );
+    }
+  }
+
+  // Property values land in note frontmatter or inline fields; validate
+  // their shape and bounds (vault-frontmatter.ts) against the final
+  // prefixed keys, in every mode, before any file access.
+  const propertyEntries: Array<{ key: string; value: VaultPropertyValue }> = [];
+  for (const section of input.sections) {
+    if (!section.properties) continue;
+    for (const key of Object.keys(section.properties)) {
+      const value = section.properties[key];
+      if (value === undefined) continue;
+      propertyEntries.push({ key: `${prefix}${key}`, value });
+    }
+  }
+  if (propertyEntries.length > 0) {
+    const checked = validateVaultProperties(propertyEntries);
+    if (!checked.ok) {
+      throw new RangeError(`Vault publish properties rejected: ${checked.reason}.`);
+    }
+  }
   const relative = resolveVaultNotePath(input.notePathTemplate, input.date);
   const result = publishRelative(input, relative, { strategy, propertiesMode, prefix });
   return summarizeVaultPublish(result);
@@ -262,13 +309,13 @@ function refuse(relative: string, outcome: "skipped" | "error", reason: string):
 
 function decorate(
   section: VaultSectionPublish,
-  prefixed: Record<string, string> | undefined,
+  prefixed: Record<string, VaultPropertyValue> | undefined,
   mode: string,
 ): string {
   const parts: string[] = [section.content];
   if (prefixed !== undefined && mode === "dataview-inline") {
     for (const [key, value] of Object.entries(prefixed)) {
-      parts.push(`${key}:: ${value}`);
+      parts.push(`${key}:: ${renderVaultPropertyValue(value)}`);
     }
   }
   if (section.provenance !== undefined) {
@@ -388,8 +435,8 @@ function looksLikeRemnicMarkerLine(trimmed: string): boolean {
 function frontmatterUpdates(
   sections: readonly VaultSectionPublish[],
   prefix: string,
-): Record<string, string> {
-  const updates: Record<string, string> = {};
+): Record<string, VaultPropertyValue> {
+  const updates: Record<string, VaultPropertyValue> = {};
   for (const section of sections) {
     if (!section.properties) continue;
     for (const [key, value] of Object.entries(section.properties)) {
@@ -406,14 +453,16 @@ function frontmatterUpdates(
  */
 export function mergeFrontmatterKeys(
   noteText: string,
-  updates: Readonly<Record<string, string>>,
+  updates: Readonly<Record<string, VaultPropertyValue>>,
 ): { ok: true; text: string } | { ok: false; reason: string } {
   const entries = Object.entries(updates);
   if (entries.length === 0) return { ok: true, text: noteText };
-  for (const [key] of entries) {
-    if (key.includes("\n") || key.includes("\r") || key.trim() !== key || key.length === 0) {
-      return { ok: false, reason: "invalid_property_key" };
-    }
+  // The writer re-validates the same boundary the publisher entry checked
+  // (issue #2917): this function is exported, so a direct caller must not
+  // be able to smuggle a newline-bearing or unbounded value into a note.
+  const checked = validateVaultProperties(entries.map(([key, value]) => ({ key, value })));
+  if (!checked.ok) {
+    return { ok: false, reason: "invalid_property" };
   }
 
   const eol = noteText.includes("\r\n") ? "\r\n" : "\n";
@@ -422,7 +471,12 @@ export function mergeFrontmatterKeys(
   const firstLine = firstLineEnd === -1 ? noteText : noteText.slice(0, firstLineEnd);
 
   if (!openRe.test(firstLine)) {
-    const block = ["---", ...entries.map(([key, value]) => `${key}: ${value}`), "---", ""].join(eol);
+    const block = [
+      "---",
+      ...entries.map(([key, value]) => `${key}: ${renderVaultPropertyValue(value)}`),
+      "---",
+      "",
+    ].join(eol);
     return { ok: true, text: block + eol + noteText };
   }
 
@@ -451,13 +505,13 @@ export function mergeFrontmatterKeys(
     if (rawKey !== rawKey.trimStart()) continue;
     const key = rawKey.trimEnd();
     if (!pending.has(key)) continue;
-    lines[i] = `${rawKey}: ${pending.get(key)}`;
+    lines[i] = `${rawKey}: ${renderVaultPropertyValue(pending.get(key)!)}`;
     pending.delete(key);
   }
   const insertAt = closeIdx;
   const added: string[] = [];
   for (const [key, value] of pending.entries()) {
-    added.push(`${key}: ${value}`);
+    added.push(`${key}: ${renderVaultPropertyValue(value)}`);
   }
   lines.splice(insertAt, 0, ...added);
   return { ok: true, text: lines.join(eol) };

package/src/activity/vault-region.test.ts

@@ -3,9 +3,14 @@ import test from "node:test";
 
 import { validateRegionName } from "./vault-region.js";
 
-test("validateRegionName trims a valid name", () => {
+test("validateRegionName accepts a valid name unchanged", () => {
   assert.deepEqual(validateRegionName("timeline"), { ok: true, name: "timeline" });
-  assert.deepEqual(validateRegionName("  weekly  "), { ok: true, name: "weekly" });
+});
+
+test("validateRegionName rejects whitespace-padded names instead of trimming them (#2917)", () => {
+  assert.deepEqual(validateRegionName("  weekly"), { ok: false, error: "invalid_name" });
+  assert.deepEqual(validateRegionName("weekly  "), { ok: false, error: "invalid_name" });
+  assert.deepEqual(validateRegionName("  weekly  "), { ok: false, error: "invalid_name" });
 });
 
 test("validateRegionName rejects empty and whitespace-only names", () => {

package/src/activity/vault-region.ts

@@ -8,6 +8,10 @@
  * or as name `A` with a `B:start` suffix) and a publisher that resolved
  * that ambiguity differently from the note's own markers would pair a
  * start with a later end and delete the user bytes in between.
+ *
+ * Whitespace-padded names are rejected, not trimmed (issue #2917): the
+ * old silent trim validated one name and wrote another, so markers and
+ * heading matches were computed against bytes the caller never saw.
  */
 
 export type ValidateRegionNameResult =
@@ -21,9 +25,9 @@ export function validateRegionName(name: string): ValidateRegionNameResult {
   if (name.includes("\n") || name.includes("\r") || name.includes("-->") || name.includes(":")) {
     return { ok: false, error: "invalid_name" };
   }
-  const trimmed = name.trim();
-  if (trimmed.length === 0) {
+  if (name.trim() !== name || name.trim().length === 0) {
     return { ok: false, error: "invalid_name" };
   }
-  return { ok: true, name: trimmed };
+  return { ok: true, name };
 }
+

package/src/background-generation-config.ts

@@ -1,4 +1,7 @@
+import { readFileSync } from "node:fs";
+
 import { isLoopbackHost } from "./runtime/http-transport.js";
+import { expandTildePath } from "./utils/path.js";
 
 export interface BackgroundGenerationConfig {
   /** Full chat-completions URL. Never used as the global OpenAI base URL. */
@@ -54,14 +57,13 @@ function parseBackgroundGenerationObject(
   if (typeof tokenRaw !== "string" || tokenRaw.length === 0) {
     throw new Error(`${keyName} must include a token`);
   }
-  const timeoutRaw = record.timeoutSeconds;
+  const timeoutRaw = record.timeoutSeconds ?? record.timeout_seconds;
   let timeoutSeconds = 120;
   if (timeoutRaw !== undefined) {
-    const parsed = typeof timeoutRaw === "number" ? timeoutRaw : Number(timeoutRaw);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
+    if (typeof timeoutRaw !== "number" || !Number.isFinite(timeoutRaw) || timeoutRaw <= 0) {
       throw new Error(`${keyName} timeoutSeconds must be a finite number > 0`);
     }
-    timeoutSeconds = parsed;
+    timeoutSeconds = timeoutRaw;
   }
   return {
     endpoint: parseBackgroundEndpoint(endpointRaw, `${keyName}.endpoint`),
@@ -72,8 +74,32 @@ function parseBackgroundGenerationObject(
 
 export function parseBackgroundGeneration(
   cfg: Record<string, unknown>,
+  expandEnv: (value: string) => string,
 ): BackgroundGenerationConfig | undefined {
+  const pathRaw = cfg.llmBridgeClientConfigPath;
+  let fromFile: BackgroundGenerationConfig | undefined;
+  if (pathRaw !== undefined && pathRaw !== null && pathRaw !== "") {
+    if (typeof pathRaw !== "string") {
+      throw new Error("llmBridgeClientConfigPath must be a string");
+    }
+    const expanded = expandTildePath(expandEnv(pathRaw.trim()));
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(expanded, "utf8"));
+    } catch {
+      throw new Error(`llmBridgeClientConfigPath could not be read: ${expanded}`);
+    }
+    fromFile = parseBackgroundGenerationObject(parsed, "llmBridgeClientConfigPath");
+  }
   const explicitRaw = cfg.backgroundGeneration;
-  if (explicitRaw === undefined || explicitRaw === null) return undefined;
-  return parseBackgroundGenerationObject(explicitRaw, "backgroundGeneration");
+  const fromExplicit =
+    explicitRaw === undefined || explicitRaw === null
+      ? undefined
+      : parseBackgroundGenerationObject(explicitRaw, "backgroundGeneration");
+  if (!fromFile && !fromExplicit) return undefined;
+  return {
+    endpoint: fromExplicit?.endpoint ?? fromFile!.endpoint,
+    token: fromExplicit?.token ?? fromFile!.token,
+    timeoutSeconds: fromExplicit?.timeoutSeconds ?? fromFile!.timeoutSeconds,
+  };
 }

package/src/background-generation.test.ts

@@ -83,11 +83,13 @@ test("HourlySummarizer uses backgroundGeneration and not openaiBaseUrl", async (
         timeoutSeconds: 12,
       },
     });
-    globalThis.fetch = (async (url) => {
+    let sentBody: string | undefined;
+    globalThis.fetch = (async (url, init) => {
       calls.push(String(url));
       if (String(url) !== "http://127.0.0.1:8765/v1/chat/completions") {
         return new Response("not the bridge", { status: 404 });
       }
+      sentBody = String(init?.body);
       return new Response(
         JSON.stringify({
           choices: [{ message: { content: '{"bullets":["bridge-only"]}' } }],
@@ -114,6 +116,13 @@ test("HourlySummarizer uses backgroundGeneration and not openaiBaseUrl", async (
     assert.deepEqual(summary?.bullets, ["bridge-only"]);
     assert.deepEqual(calls, ["http://127.0.0.1:8765/v1/chat/completions"]);
     assert.equal(config.openaiBaseUrl, "http://127.0.0.1:9999/v1");
+    // The bridge prompt must spell out the required JSON shape; without it a
+    // literal host model returns {"summary": "..."} and the schema rejects it.
+    const sent = JSON.parse(String(sentBody)) as {
+      messages: Array<{ role: string; content: string }>;
+    };
+    const system = sent.messages.find((message) => message.role === "system")?.content ?? "";
+    assert.match(system, /"bullets"/);
   } finally {
     globalThis.fetch = previousFetch;
     if (previousXdg === undefined) delete process.env.XDG_CONFIG_HOME;