@remnic/core 9.69.39 → 9.69.41

package/src/activity/config.test.ts

@@ -366,3 +366,64 @@ test("an enabled vault rejects relative or whitespace-only vaultPath at config l
   const inert = parseActivityConfig({ timeline: { vault: { enabled: false, vaultPath: "." } } });
   assert.equal(inert.timeline.vault.vaultPath, ".");
 });
+
+test("insertUnderHeading must be a trimmed single-line heading (#2917)", () => {
+  for (const insertUnderHeading of ["   ", "  Journal  ", "Journal\nExtra"]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { vault: { insertUnderHeading } } }),
+      /insertUnderHeading must be a non-empty trimmed single-line heading/,
+      `value ${JSON.stringify(insertUnderHeading)} must be rejected`,
+    );
+  }
+  const ok = parseActivityConfig({ timeline: { vault: { insertUnderHeading: "Journal" } } });
+  assert.equal(ok.timeline.vault.insertUnderHeading, "Journal");
+});
+
+test("readback.journalSection must be a trimmed single-line heading (#2917)", () => {
+  for (const journalSection of ["  Journal  ", "Journal\r\nExtra"]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { vault: { readback: { journalSection } } } }),
+      /journalSection must be a non-empty trimmed single-line heading/,
+    );
+  }
+  const ok = parseActivityConfig({ timeline: { vault: { readback: { journalSection: "Journal" } } } });
+  assert.equal(ok.timeline.vault.readback.journalSection, "Journal");
+});
+
+test("heading-strategy section names that cannot round-trip are rejected at config load (#2917)", () => {
+  // `## Timeline #` parses back as `Timeline`. Accepted at load, every
+  // publish would throw before producing a status.
+  assert.throws(
+    () =>
+      parseActivityConfig({
+        timeline: {
+          vault: { sectionStrategy: "heading", publish: { timeline: { section: "Timeline #" } } },
+        },
+      }),
+    /publish\.timeline\.section must survive a heading render-and-parse round trip/,
+  );
+  const ok = parseActivityConfig({
+    timeline: {
+      vault: { sectionStrategy: "heading", publish: { timeline: { section: "Timeline" } } },
+    },
+  });
+  assert.equal(ok.timeline.vault.publish.timeline.section, "Timeline");
+});
+
+test("marker-strategy still accepts a section name that would fail heading round-trip (#2917)", () => {
+  const ok = parseActivityConfig({
+    timeline: {
+      vault: { sectionStrategy: "markers", publish: { timeline: { section: "Timeline #" } } },
+    },
+  });
+  assert.equal(ok.timeline.vault.publish.timeline.section, "Timeline #");
+});
+
+test("insertUnderHeading that cannot round-trip is rejected at config load (#2917)", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { vault: { insertUnderHeading: "Timeline #" } } }),
+    /insertUnderHeading must survive a heading render-and-parse round trip/,
+  );
+  const ok = parseActivityConfig({ timeline: { vault: { insertUnderHeading: "Journal" } } });
+  assert.equal(ok.timeline.vault.insertUnderHeading, "Journal");
+});

package/src/activity/config.ts

@@ -2,10 +2,11 @@ import path from "node:path";
 
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
-import { applyLegacyJournalHeading } from "./journal-heading.js";
+import { applyLegacyJournalHeading, normalizeJournalHeading } from "./journal-heading.js";
 import { checkVaultJournalPrerequisites } from "./journal-vault-prereq.js";
 import { resolveJournalSource } from "./journal-source.js";
 import { validateVaultNoteTemplate } from "./vault-path.js";
+import { headingSurvivesRoundTrip } from "./vault-publish.js";
 import { validateRegionName } from "./vault-region.js";
 import { TIMELINE_ANALYSIS_DEFAULT_TIMEOUT_MS } from "./timeline/analysis.js";
 import { ANALYSIS_METADATA_MAX_FIELD_LENGTH, isAnalysisIdentifier } from "./timeline/analysis-metadata.js";
@@ -376,6 +377,23 @@ export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultCon
   const noteTemplate = optionalNonEmptyString(vault.noteTemplate, "activity.timeline.vault.noteTemplate") ?? "";
   const insertUnderHeading =
     optionalNonEmptyString(vault.insertUnderHeading, "activity.timeline.vault.insertUnderHeading") ?? "";
+  // The configured insertion heading is matched against parsed note
+  // headings, so a blank, padded, or multi-line value can never match
+  // (issue #2917). Reuse the journal work's canonical heading validator —
+  // no second parser — and require the trimmed form like publish sections.
+  if (insertUnderHeading.length > 0) {
+    const heading = normalizeJournalHeading(insertUnderHeading);
+    if (!heading.ok || heading.heading !== insertUnderHeading) {
+      throw new RangeError(
+        "activity.timeline.vault.insertUnderHeading must be a non-empty trimmed single-line heading",
+      );
+    }
+    if (!headingSurvivesRoundTrip(insertUnderHeading)) {
+      throw new RangeError(
+        "activity.timeline.vault.insertUnderHeading must survive a heading render-and-parse round trip",
+      );
+    }
+  }
 
   if (typeof vault.sectionStrategy !== "undefined" && typeof vault.sectionStrategy !== "string") {
     throw new TypeError("activity.timeline.vault.sectionStrategy must be a string");
@@ -423,6 +441,15 @@ export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultCon
   }
 
   const publish = parseVaultPublishBlock(vault.publish, weeklyNotePath);
+  if (sectionStrategy === "heading") {
+    for (const kind of ["timeline", "standup", "weekly", "locations"] as const) {
+      if (!headingSurvivesRoundTrip(publish[kind].section)) {
+        throw new RangeError(
+          `activity.timeline.vault.publish.${kind}.section must survive a heading render-and-parse round trip`,
+        );
+      }
+    }
+  }
   const wikilinksRaw = vault.wikilinks;
   const wikilinks =
     wikilinksRaw === undefined
@@ -439,6 +466,18 @@ export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultCon
     (readbackRaw as Record<string, unknown> | undefined)?.journalSection,
     "activity.timeline.vault.readback.journalSection",
   );
+  // Readback matches the section by parsed heading text, so a padded or
+  // multi-line journalSection can never match and would silently read back
+  // an empty journal (issue #2917). Same canonical validator as the legacy
+  // journal.heading alias.
+  if (readbackJournalSection !== undefined && readbackJournalSection.length > 0) {
+    const heading = normalizeJournalHeading(readbackJournalSection);
+    if (!heading.ok || heading.heading !== readbackJournalSection) {
+      throw new RangeError(
+        "activity.timeline.vault.readback.journalSection must be a non-empty trimmed single-line heading",
+      );
+    }
+  }
   const readback = {
     journalSection: readbackJournalSection ?? "",
   };

package/src/activity/timeline/analysis-provider.ts

@@ -25,6 +25,7 @@ export interface TimelineAnalysisLocalLlm {
       operation?: string;
       redactProviderErrors?: boolean;
       model?: string;
+      failureDiag?: { lastError?: unknown };
     },
   ): Promise<{ content: string } | null>;
 }
@@ -40,6 +41,7 @@ export interface TimelineAnalysisRemoteLlm {
       modelChain?: { primary?: string; fallbacks?: string[] };
       includeDefaultModelFallback?: boolean;
       redactProviderErrors?: boolean;
+      failureDiag?: { lastError?: unknown };
     },
   ): Promise<{ content: string } | null>;
 }
@@ -99,6 +101,7 @@ export function timelineAnalysisCompleteFromClients(input: {
           "timeline analysis local provider is not configured",
         );
       }
+      const failureDiag: { lastError?: unknown } = {};
       const result = await localLlm.chatCompletion(messages, {
         temperature: 0,
         maxTokens: 2048,
@@ -106,10 +109,11 @@ export function timelineAnalysisCompleteFromClients(input: {
         operation: "timeline-analysis",
         redactProviderErrors: true,
         model,
+        failureDiag,
       });
       if (result === null) {
         throw new TimelineAnalysisProviderError(
-          "provider_unavailable",
+          classifyAnalysisProviderError(failureDiag.lastError),
           "timeline analysis local provider returned no completion",
         );
       }
@@ -121,6 +125,7 @@ export function timelineAnalysisCompleteFromClients(input: {
         "timeline analysis remote provider is not configured",
       );
     }
+    const failureDiag: { lastError?: unknown } = {};
     const result = await remoteLlm.chatCompletion(messages, {
       temperature: 0,
       maxTokens: 2048,
@@ -128,10 +133,11 @@ export function timelineAnalysisCompleteFromClients(input: {
       modelChain: { primary: `${provider}/${model}` },
       includeDefaultModelFallback: false,
       redactProviderErrors: true,
+      failureDiag,
     });
     if (result === null) {
       throw new TimelineAnalysisProviderError(
-        "provider_unavailable",
+        classifyAnalysisProviderError(failureDiag.lastError),
         `timeline analysis provider "${provider}" is not configured`,
       );
     }

package/src/activity/timeline/analysis-run.test.ts

@@ -417,3 +417,85 @@ test("adapter pins the call-time provider verbatim with no chain fallback", asyn
   });
   assert.deepEqual(seen, ["anthropic/claude-4_1"]);
 });
+
+test("remote failureDiag preserves a rate-limited failure as retryable (issue #2891)", async () => {
+  const cards = sampleCards();
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (_messages, options) => {
+      assert.ok(options.failureDiag, "adapter must pass a failureDiag out-box");
+      options.failureDiag.lastError = Object.assign(new Error("provider throttled"), { status: 429 });
+      return null;
+    },
+  };
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.failure?.kind, "rate_limited");
+  assert.equal(result.failure?.retryable, true);
+  assert.equal(result.failure?.preservesDeterministic, true);
+  assert.equal(result.cards, cards);
+});
+
+test("local failureDiag preserves a rate-limited failure (issue #2891)", async () => {
+  const localLlm: TimelineAnalysisLocalLlm = {
+    chatCompletion: async (_messages, options) => {
+      assert.ok(options.failureDiag, "adapter must pass a failureDiag out-box");
+      options.failureDiag.lastError = Object.assign(new Error("local backend throttled"), { status: 429 });
+      return null;
+    },
+  };
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: { enabled: true, provider: "local", model: "local-test" },
+    deps: { localLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.failure?.kind, "rate_limited");
+  assert.equal(result.failure?.retryable, true);
+});
+
+test("failureDiag without a rate limit still classifies as provider_unavailable", async () => {
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (_messages, options) => {
+      options.failureDiag!.lastError = Object.assign(new Error("server error"), { status: 500 });
+      return null;
+    },
+  };
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.failure?.kind, "provider_unavailable");
+  assert.equal(result.failure?.retryable, true);
+});
+
+test("a null completion with no recorded cause keeps the generic kind", async () => {
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async () => null,
+  };
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.failure?.kind, "provider_unavailable");
+  assert.equal(result.failure?.retryable, true);
+});

package/src/activity/timeline/publish-cli.test.ts

@@ -167,3 +167,33 @@ test("range and search reject publish-only flags instead of ignoring them", asyn
   assert.equal(searchCode, 1);
   assert.match(searchSink.err, /unknown flag --dry-run \(valid: --from, --limit, --query, --to\)/);
 });
+
+test("an explicitly empty --date is invalid, not treated as absent (#2917)", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--date", ""],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /Invalid --date ""/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "no note is published on an empty --date");
+});
+
+test("publish rejects extra positional arguments instead of discarding them (#2917)", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "extra-arg", "--date", DATE],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /takes no positional arguments/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "no note is published on excess syntax");
+});

package/src/activity/timeline/publish-cli.ts

@@ -51,6 +51,13 @@ export function runTimelinePublishCli(
     return 1;
   }
 
+  // An explicitly empty --date is invalid, not absent (issue #2917): ""
+  // can never be a day, and silently falling back to today would publish
+  // the wrong note. Only a missing --date means "today".
+  if (options.date !== undefined && (typeof options.date !== "string" || options.date.length === 0)) {
+    io.stderr.write(`Invalid --date ${JSON.stringify(options.date ?? "")}; expected YYYY-MM-DD.\n`);
+    return 1;
+  }
   // Timeline artifacts are grouped on the configured activity timezone's
   // calendar day, so "today" must be derived there — the host-local day
   // drifts by one near either timezone's midnight.

package/src/activity/timeline/query.ts

@@ -311,7 +311,14 @@ export async function runTimelineCliCommand(
         io.stderr.write("timeline publish requires the Remnic config — run `remnic doctor`\n");
         return 1;
       }
-      const publishFlags = parseFlags(rest, PUBLISH_FLAGS).flags;
+      const { flags: publishFlags, positional } = parseFlags(rest, PUBLISH_FLAGS);
+      // `publish` takes flags only (issue #2917): a stray positional used
+      // to be silently discarded while today's note published.
+      if (positional.length > 0) {
+        throw new TypeError(
+          `timeline publish takes no positional arguments (got ${JSON.stringify(positional.join(" "))})`,
+        );
+      }
       return runTimelinePublishCli(
         deps.config,
         {

package/src/activity/timeline/regenerate.test.ts

@@ -114,7 +114,6 @@ function priorEditsFromPrompt(prompt: string): unknown {
   return parsed.priorEdits;
 }
 
-
 test("disabled analysis persists deterministic cards and makes zero provider calls", async () => {
   await withStore(async (store, memoryDir) => {
     store.insertSnapshot(snapshot());
@@ -387,6 +386,54 @@ test("resolveTimelineLoadDates keeps a bounded window and expands an unbounded o
   assert.deepEqual(empty, ["2026-08-23"]);
 });
 
+test("resolveTimelineLoadDates loads the local day of a lone bound, never today (#2931)", () => {
+  const store = { snapshotCaptureExtent: () => null };
+  const base = { timezone: "UTC" as const, today: "2026-08-23", store, persistedDates: [] as string[] };
+
+  const loneTo = resolveTimelineLoadDates({
+    ...base,
+    window: { to: "2026-05-02T12:00:00.000Z" },
+  });
+  assert.deepEqual(loneTo, ["2026-05-02"], "a lone --to must load the day of the to instant, not today");
+
+  const loneFrom = resolveTimelineLoadDates({
+    ...base,
+    window: { from: "2026-05-02T12:00:00.000Z" },
+  });
+  assert.deepEqual(loneFrom, ["2026-05-02"], "a lone --from keeps loading its own day");
+
+  const futureTo = resolveTimelineLoadDates({
+    ...base,
+    window: { to: "2026-09-01T12:00:00.000Z" },
+  });
+  assert.deepEqual(futureTo, ["2026-09-01"], "a lone future --to loads that future day, not today");
+});
+
+test("resolveTimelineLoadDates resolves a lone --to day through the configured timezone (#2931)", () => {
+  const store = { snapshotCaptureExtent: () => null };
+  // 2026-08-20T23:30Z is 2026-08-21 13:30 in Kiritimati (UTC+14) but still
+  // 2026-08-20 in Adak (UTC-10): the same instant must load different local
+  // days under the two configured zones, proving the configured timezone —
+  // not UTC and not today — drives the resolution.
+  const east = resolveTimelineLoadDates({
+    window: { to: "2026-08-20T23:30:00.000Z" },
+    timezone: "Pacific/Kiritimati",
+    today: "2026-08-23",
+    store,
+    persistedDates: [],
+  });
+  assert.deepEqual(east, ["2026-08-21"]);
+
+  const west = resolveTimelineLoadDates({
+    window: { to: "2026-08-20T23:30:00.000Z" },
+    timezone: "America/Adak",
+    today: "2026-08-23",
+    store,
+    persistedDates: [],
+  });
+  assert.deepEqual(west, ["2026-08-20"]);
+});
+
 test("localDatesForUtcRange covers a multi-year span for unbounded search", () => {
   const dates = localDatesForUtcRange(
     Date.parse("2020-01-01T00:00:00.000Z"),
@@ -413,6 +460,88 @@ test("listPersistedTimelineDates lists only valid day files", async () => {
   }
 });
 
+test("a timezone change invalidates the cached day and re-analyzes (issue #2891)", async () => {
+  await withStore(async (store, memoryDir) => {
+    store.insertSnapshot(snapshot());
+    const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+    const analysis = parseActivityConfig({
+      timeline: { analysis: { enabled: true, provider: "openai", model: "gpt-test" } },
+    }).timeline.analysis;
+    const first = await regenerateTimelineDay({
+      date: DATE,
+      timezone: TZ,
+      memoryDir,
+      store,
+      timelineEnabled: true,
+      analysis,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(first.status, "ok");
+    assert.equal(remote.calls, 1);
+    const sameTz = await regenerateTimelineDay({
+      date: DATE,
+      timezone: TZ,
+      memoryDir,
+      store,
+      timelineEnabled: true,
+      analysis,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(sameTz.written, false);
+    assert.equal(remote.calls, 1);
+    const shifted = await regenerateTimelineDay({
+      date: DATE,
+      timezone: "America/New_York",
+      memoryDir,
+      store,
+      timelineEnabled: true,
+      analysis,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(shifted.status, "ok");
+    assert.equal(shifted.written, true);
+    assert.equal(shifted.analyzed, true);
+    assert.equal(remote.calls, 2);
+    const persisted = JSON.parse(await readFile(timelineDayPath(memoryDir, DATE), "utf8"));
+    assert.equal(persisted.timezone, "America/New_York");
+  });
+});
+
+test("an empty day cached under one timezone is rebuilt under another (issue #2891)", async () => {
+  await withStore(async (store, memoryDir) => {
+    const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+    const analysis = parseActivityConfig({
+      timeline: { analysis: { enabled: true, provider: "openai", model: "gpt-test" } },
+    }).timeline.analysis;
+    const first = await regenerateTimelineDay({
+      date: DATE,
+      timezone: TZ,
+      memoryDir,
+      store,
+      timelineEnabled: true,
+      analysis,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(first.status, "invalid_output");
+    assert.equal(first.analyzed, false);
+    assert.equal(remote.calls, 0);
+    const shifted = await regenerateTimelineDay({
+      date: DATE,
+      timezone: "America/New_York",
+      memoryDir,
+      store,
+      timelineEnabled: true,
+      analysis,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    // Zero observations under any timezone: still a rebuild, never the
+    // UTC-cached file served with the old day derivation.
+    assert.equal(shifted.written, true);
+    const persisted = JSON.parse(await readFile(timelineDayPath(memoryDir, DATE), "utf8"));
+    assert.equal(persisted.timezone, "America/New_York");
+  });
+});
+
 test("a correction for another day does not change this day's hash, cache, or provider input", async () => {
   await withStore(async (store, memoryDir) => {
     store.insertSnapshot(snapshot());
@@ -502,4 +631,3 @@ test("a same-day correction updates hash, cards, and priorEdits", async () => {
     assert.notEqual(persistedSourceHash(await readFile(timelineDayPath(memoryDir, DATE), "utf8")), firstHash);
   });
 });
-

package/src/activity/timeline/regenerate.ts

@@ -143,9 +143,10 @@ export function listPersistedTimelineDates(memoryDir: string): string[] {
 
 /**
  * Local days a CLI window must load. Bounded windows keep the explicit
- * from/to span. An unbounded search loads every day the snapshot store or a
- * persisted day file covers (plus today), so historical cards enter the
- * search pool instead of only the current day.
+ * from/to span; a window with a single bound loads the local day containing
+ * that instant (never today). An unbounded search loads every day the
+ * snapshot store or a persisted day file covers (plus today), so historical
+ * cards enter the search pool instead of only the current day.
  */
 export function resolveTimelineLoadDates(input: {
   window: { from?: string; to?: string };
@@ -156,8 +157,9 @@ export function resolveTimelineLoadDates(input: {
 }): string[] {
   const { window, timezone, today, store, persistedDates } = input;
   if (window.from !== undefined || window.to !== undefined) {
-    const fromMs = window.from === undefined ? Date.now() : Date.parse(window.from);
-    const toMs = window.to === undefined ? fromMs + 1 : Date.parse(window.to);
+    const parsedTo = window.to === undefined ? Number.NaN : Date.parse(window.to);
+    const fromMs = window.from === undefined ? parsedTo : Date.parse(window.from);
+    const toMs = window.to === undefined ? fromMs + 1 : parsedTo;
     if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return [];
     return localDatesForUtcRange(fromMs, toMs > fromMs ? toMs : fromMs + 1, timezone);
   }
@@ -191,12 +193,18 @@ function resolveClients(input: RegenerateTimelineDayInput): TimelineAnalysisClie
 }
 
 function sourceHash(input: {
+  timezone: string;
   observations: readonly TimelineObservation[];
   analysis: ActivityTimelineAnalysisConfig;
   corrections: readonly TimelineCorrection[];
 }): string {
   return hashActivityBody(
     JSON.stringify({
+      // The timezone is a day-window determinant (it bounds which
+      // observations the day sees), so it belongs to the source identity:
+      // identical observations under a different timezone must not reuse
+      // the cached day (issue #2891).
+      timezone: input.timezone,
       observations: input.observations.map((observation) => ({
         id: observation.id,
         contentHash: observation.contentHash,
@@ -310,7 +318,7 @@ async function regenerateUncached(input: RegenerateTimelineDayInput): Promise<Re
     const rawCards = buildTimelineDay({ date, timezone, observations }).cards;
     corrections = correctionsForCards(rawCards, corrections);
     const built = applyTimelineCorrections(rawCards, corrections);
-    const hash = sourceHash({ observations, analysis: input.analysis, corrections });
+    const hash = sourceHash({ timezone, observations, analysis: input.analysis, corrections });
     const prior = readPersisted(filePath);
     if (prior !== null && prior.sourceHash === hash && isCachedDayFinal(prior.status, input.analysis.enabled)) {
       return toResult(filePath, false, false, prior);

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

@@ -1,7 +1,14 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { applyVaultFrontmatter } from "./vault-frontmatter.js";
+import {
+  applyVaultFrontmatter,
+  renderVaultPropertyValue,
+  validateVaultProperties,
+  VAULT_PROPERTY_LIST_MAX_ITEMS,
+  VAULT_PROPERTY_SCALAR_MAX_CHARS,
+  VAULT_PROPERTY_TOTAL_MAX_CHARS,
+} from "./vault-frontmatter.js";
 
 test("applyVaultFrontmatter merges listed keys and sorts", () => {
   const merged = applyVaultFrontmatter("zeta: old\nalpha: keep\n", {
@@ -26,3 +33,94 @@ test("applyVaultFrontmatter leaves the original body unchanged when updates are
   const existing = "zeta: 1\n# comment stays\nalpha: 2\n";
   assert.equal(applyVaultFrontmatter(existing, {}), existing);
 });
+
+test("accepts a plain scalar and renders it verbatim (#2917)", () => {
+  assert.deepEqual(validateVaultProperties([{ key: "remnic_focus", value: "220" }]), { ok: true });
+  assert.equal(renderVaultPropertyValue("220"), "220");
+});
+
+test("accepts a list of plain scalars and renders a flow list (#2917)", () => {
+  assert.deepEqual(validateVaultProperties([{ key: "remnic_cards", value: ["a", "b"] }]), { ok: true });
+  assert.equal(renderVaultPropertyValue(["a", "b"]), "[a, b]");
+});
+
+test("rejects newline and control characters — the injection primitives (#2917)", () => {
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: "v\ninjected: yes" }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: "v\rinjected: yes" }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: "v\ttab" }]).ok, false);
+});
+
+test("rejects values whose YAML shape would change on re-read (#2917)", () => {
+  for (const value of [" padded", "padded ", "[seq]", "{map}", "#comment", "- item", "a #c", "ends:", "a: b"]) {
+    assert.equal(
+      validateVaultProperties([{ key: "remnic_x", value }]).ok,
+      false,
+      `value ${JSON.stringify(value)} must be rejected`,
+    );
+  }
+});
+
+test("a negative number stays a plain scalar (#2917)", () => {
+  assert.deepEqual(validateVaultProperties([{ key: "remnic_delta", value: "-5" }]), { ok: true });
+});
+
+test("rejects unsupported value shapes (#2917)", () => {
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: 42 as unknown as string }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: null as unknown as string }]).ok, false);
+  assert.equal(
+    validateVaultProperties([{ key: "remnic_x", value: { nested: true } as unknown as string }]).ok,
+    false,
+  );
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: [] as unknown as string[] }]).ok, false);
+});
+
+test("rejects oversize scalars, lists, keys, and totals (#2917)", () => {
+  assert.equal(
+    validateVaultProperties([{ key: "remnic_x", value: "v".repeat(VAULT_PROPERTY_SCALAR_MAX_CHARS + 1) }]).ok,
+    false,
+  );
+  assert.equal(validateVaultProperties([{ key: "x".repeat(65), value: "v" }]).ok, false);
+  const tooMany = Array.from({ length: VAULT_PROPERTY_LIST_MAX_ITEMS + 1 }, (_, i) => `item-${i}`);
+  assert.equal(validateVaultProperties([{ key: "remnic_x", value: tooMany }]).ok, false);
+  const entries = Array.from({ length: 30 }, (_, i) => ({
+    key: `remnic_k${i}`,
+    value: "v".repeat(100),
+  }));
+  assert.equal(
+    validateVaultProperties(entries).ok,
+    false,
+    `30 × 100+ chars must exceed the ${VAULT_PROPERTY_TOTAL_MAX_CHARS}-char total`,
+  );
+});
+
+test("rejects malformed keys (#2917)", () => {
+  assert.equal(validateVaultProperties([{ key: "remnic x:", value: "v" }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: " padded", value: "v" }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: "remnic#x", value: "v" }]).ok, false);
+  assert.equal(validateVaultProperties([{ key: "", value: "v" }]).ok, false);
+});
+
+test("rejects a final key that starts with a YAML indicator (#2917)", () => {
+  // Prefix "[" + key "focus" is the review case: the written line would
+  // be `[focus: 220`, which is not a mapping entry.
+  for (const key of ["[focus", "{focus", "*focus", "&focus", "!focus", "%focus"]) {
+    assert.equal(
+      validateVaultProperties([{ key, value: "220" }]).ok,
+      false,
+      `key ${JSON.stringify(key)} must be rejected`,
+    );
+  }
+  assert.deepEqual(validateVaultProperties([{ key: "remnic_focus", value: "220" }]), { ok: true });
+  assert.deepEqual(validateVaultProperties([{ key: "x_focus", value: "220" }]), { ok: true });
+});
+
+test("rejects flow delimiters inside list scalar items (#2917)", () => {
+  for (const item of ["a{", "a}", "a[", "a]", "a,b"]) {
+    assert.equal(
+      validateVaultProperties([{ key: "remnic_cards", value: [item] }]).ok,
+      false,
+      `list item ${JSON.stringify(item)} must be rejected`,
+    );
+  }
+  assert.deepEqual(validateVaultProperties([{ key: "remnic_cards", value: ["a", "b"] }]), { ok: true });
+});