@remnic/core 9.69.39 → 9.69.40

package/src/access-category-alias.test.ts

@@ -151,6 +151,18 @@ test("#2829 retainedCategoryAlias reads the transform-minted spelling from a raw
   assert.equal(categoryAliasCoercion(undefined), undefined);
 });
 
+test("#2889 retainedCategoryAlias recovers the spelling from a single-parse envelope's category", () => {
+  // Single-parse callers (CLI store command, direct op.run) hand the op the
+  // raw envelope: the alias sits on `category`, no `rawCategory` exists yet.
+  assert.equal(retainedCategoryAlias({ content: "x", category: "project_state" }), "project_state");
+  assert.equal(retainedCategoryAlias({ content: "x", category: "project-state" }), "project-state");
+  // Canonical and near-miss categories never mint a retained spelling.
+  assert.equal(retainedCategoryAlias({ content: "x", category: "fact" }), undefined);
+  assert.equal(retainedCategoryAlias({ content: "x", category: "projection" }), undefined);
+  assert.equal(retainedCategoryAlias({ content: "x" }), undefined);
+  // A transform-minted rawCategory outranks the raw category spelling.
+  assert.equal(retainedCategoryAlias({ category: "project_update", rawCategory: "project" }), "project");
+});
 // ---------------------------------------------------------------------------
 // Type-level regressions (enforced by tsc via check-types)
 // ---------------------------------------------------------------------------
@@ -303,6 +315,10 @@ function makePersistService(memoryDir: string): PersistProbe {
       writes.push({ category, content });
       return { id: `mem-${writes.length}`, duplicateOf: undefined };
     },
+    // The suggestion review-queue path re-reads and re-stamps the queued
+    // memory (explicit-capture.ts queueExplicitCaptureForReview).
+    getMemoryById: async (id: string) => ({ id, status: "active" }),
+    writeMemoryFrontmatter: async () => {},
   });
   return { service: new EngramAccessService(orch), writes };
 }
@@ -410,6 +426,83 @@ test("#2829 peek idempotency ignores the retained spelling", async () => {
   });
 });
 
+test("#2889 single-pass op.run retains the alias through canonical validation and replay", async () => {
+  // The CLI store command's path (PR #2866 review): the raw envelope carries
+  // the alias on `category` and op.run performs the ONLY schema parse. The
+  // boundary must still retain the spelling, and a same-key replay with a
+  // different accepted spelling must report THIS caller's alias while the
+  // stored result stays canonical and untouched.
+  await withPersistService(async ({ service, writes }) => {
+    const base = {
+      content: "single-pass aliased idempotent write",
+      confidence: 0.9,
+      tags: [] as string[],
+      idempotencyKey: "k-2889",
+    };
+    const first = await memoryStoreOperation.run(
+      { ...base, category: "project_state" },
+      { service },
+    );
+    assert.equal(first.result.status, "stored");
+    assert.deepEqual(first.result.categoryCoercion, { from: "project_state", to: "fact" });
+    assert.equal(writes.length, 1);
+    assert.equal(writes[0]?.category, "fact", "the persisted memory stays canonical");
+
+    const second = await memoryStoreOperation.run(
+      { ...base, category: "project-state" },
+      { service },
+    );
+    assert.equal(second.result.idempotencyReplay, true, "alias spellings share the canonical fingerprint");
+    assert.deepEqual(second.result.categoryCoercion, { from: "project-state", to: "fact" });
+    assert.equal(first.result.categoryCoercion?.from, "project_state", "the replay never mutates the stored note");
+    assert.equal(writes.length, 1, "the replay persists nothing");
+
+    const third = await memoryStoreOperation.run(
+      { ...base, category: "fact" },
+      { service },
+    );
+    assert.equal(third.result.idempotencyReplay, true);
+    assert.equal("categoryCoercion" in third.result, false, "a canonical replay reports no coercion");
+    assert.equal(writes.length, 1);
+  });
+});
+
+test("#2889 a single-pass dry run reports the coercion note and persists nothing", async () => {
+  await withPersistService(async ({ service, writes }) => {
+    const output = await memoryStoreOperation.run(
+      { content: "single-pass dry-run alias", category: "project_update", confidence: 0.9, tags: [], dryRun: true },
+      { service },
+    );
+    assert.equal(output.result.status, "validated");
+    assert.deepEqual(output.result.categoryCoercion, { from: "project_update", to: "fact" });
+    assert.equal(writes.length, 0);
+  });
+});
+
+test("#2889 suggestion_submit reports the coercion and queues the canonical category", async () => {
+  await withPersistService(async ({ service, writes }) => {
+    const aliased = await service.suggestionSubmit({
+      content: "suggested aliased fact",
+      category: "fact",
+      confidence: 0.9,
+      tags: [],
+      rawCategory: "project_update",
+    });
+    assert.equal(aliased.status, "queued_for_review");
+    assert.deepEqual(aliased.categoryCoercion, { from: "project_update", to: "fact" });
+    assert.equal(writes.length, 1);
+    assert.equal(writes[0]?.category, "fact", "the queued review memory stays canonical");
+
+    const canonical = await service.suggestionSubmit({
+      content: "suggested canonical fact",
+      category: "preference",
+      confidence: 0.9,
+      tags: [],
+    });
+    assert.equal(canonical.status, "queued_for_review");
+    assert.equal("categoryCoercion" in canonical, false, "a no-alias submit reports no coercion");
+  });
+});
 // ---------------------------------------------------------------------------
 // Quarantine — the parked payload keeps the raw spelling for replay
 // ---------------------------------------------------------------------------

package/src/access-offline-manifest.ts

@@ -57,11 +57,17 @@ export interface ServerIdentityCacheEntry {
 export function planServerIdentityCacheWrite(input: {
   persisted: ReadonlyMap<string, ServerIdentityCacheEntry>;
   yieldedPaths: ReadonlySet<string>;
+  /** Paths the walk saw but never yielded (removed by the exclusion
+   * callback). Not deleted — pruning them would drop their persisted
+   * classification and force a re-classify on every later cycle. */
+  retainedPaths?: ReadonlySet<string>;
   streamCompleted: boolean;
   cacheDirty: boolean;
 }): { shouldWrite: boolean; entries: ServerIdentityCacheEntry[] } {
   const entries = input.streamCompleted
-    ? [...input.persisted.values()].filter((entry) => input.yieldedPaths.has(entry.path))
+    ? [...input.persisted.values()].filter(
+        (entry) => input.yieldedPaths.has(entry.path) || input.retainedPaths?.has(entry.path)
+      )
     : [...input.persisted.values()];
   return { shouldWrite: input.cacheDirty || entries.length !== input.persisted.size, entries };
 }
@@ -147,7 +153,7 @@ async function withServerIdentityCacheWriteLock(cachePath: string, write: () =>
 
 /** Union of the entries being written and the current on-disk set; on conflict
  * the write wins (it reflects the newer run). Callers hold the write lock. */
-async function mergeServerIdentityCacheEntries(
+export async function mergeServerIdentityCacheEntries(
   fs: typeof import("node:fs/promises"),
   cachePath: string,
   entries: readonly ServerIdentityCacheEntry[],
@@ -178,6 +184,9 @@ async function mergeServerIdentityCacheEntries(
                   ? { identityResolutionVersion: entry.identityResolutionVersion }
                   : {}),
               }),
+          ...(entry.statIdentity !== undefined && entry.excluded !== undefined
+            ? { statIdentity: entry.statIdentity, excluded: entry.excluded }
+            : {}),
         });
       }
     }
@@ -187,6 +196,34 @@ async function mergeServerIdentityCacheEntries(
   return [...merged.values()];
 }
 
+/** Record classifications for files the walk excluded (the exclusion callback
+ * returned true, so they were never yielded): they were seen this walk, so
+ * their entries must persist and must not be pruned as deleted. Mirrors the
+ * per-yield classification application for never-yielded paths. */
+export function retainExcludedClassifications(input: {
+  persisted: Map<string, ServerIdentityCacheEntry>;
+  classifications: ReadonlyMap<string, { statIdentity: string; excluded: boolean }>;
+  yieldedPaths: ReadonlySet<string>;
+}): { retained: Set<string>; changed: boolean } {
+  const retained = new Set<string>();
+  let changed = false;
+  for (const [pathName, classification] of input.classifications) {
+    if (input.yieldedPaths.has(pathName)) continue;
+    retained.add(pathName);
+    const entry = input.persisted.get(pathName) ?? { path: pathName, sha256: "" };
+    if (entry.statIdentity === classification.statIdentity && entry.excluded === classification.excluded) {
+      continue;
+    }
+    input.persisted.set(pathName, {
+      ...entry,
+      statIdentity: classification.statIdentity,
+      excluded: classification.excluded,
+    });
+    changed = true;
+  }
+  return { retained, changed };
+}
+
 export async function createOfflineSyncManifestStream(
   orchestrator: Orchestrator,
   namespace: string,
@@ -227,10 +264,12 @@ export async function createOfflineSyncManifestStream(
       // near-cold rebuild on the next request.
       const persistedEntries = new Map(identityCache);
       const yieldedPaths = new Set<string>();
+      const retainedPaths = new Set<string>();
       const flush = async (): Promise<void> => {
         const { shouldWrite, entries } = planServerIdentityCacheWrite({
           persisted: persistedEntries,
           yieldedPaths,
+          retainedPaths,
           streamCompleted,
           cacheDirty,
         });
@@ -334,6 +373,17 @@ export async function createOfflineSyncManifestStream(
         }
         streamCompleted = true;
       } finally {
+        // Files the exclusion callback removed from the snapshot were seen
+        // this walk but never yielded: persist their classifications so the
+        // next cycle skips the read+parse, and keep them out of the
+        // deleted-path prune.
+        const retained = retainExcludedClassifications({
+          persisted: persistedEntries,
+          classifications: classificationUpdates,
+          yieldedPaths,
+        });
+        for (const pathName of retained.retained) retainedPaths.add(pathName);
+        if (retained.changed) cacheDirty = true;
         await flush();
       }
     })(),

package/src/access-schema.ts

@@ -323,13 +323,18 @@ export function categoryAliasCoercion(rawCategory: string | undefined): Category
 /**
  * Recover the retained alias spelling from a pre-parse raw envelope: the
  * `rawCategory` minted by a previous parse of the same schema (the HTTP/MCP
- * validate-then-dispatch double pass) or an as-yet-untransformed alias
- * `category` (single-parse callers like the CLI store command).
+ * validate-then-dispatch double pass), or — for single-parse callers like the
+ * CLI store command — the as-yet-untransformed alias still sitting on
+ * `category` (issue #2889). A minted `rawCategory` always wins: it names the
+ * spelling the transform actually canonicalized.
  */
 export function retainedCategoryAlias(rawInput: unknown): MemoryCategoryAlias | undefined {
   if (!rawInput || typeof rawInput !== "object") return undefined;
-  const spelling = (rawInput as Record<string, unknown>).rawCategory;
-  return typeof spelling === "string" && isMemoryCategoryAlias(spelling) ? spelling : undefined;
+  const envelope = rawInput as Record<string, unknown>;
+  const minted = envelope.rawCategory;
+  if (typeof minted === "string" && isMemoryCategoryAlias(minted)) return minted;
+  const category = envelope.category;
+  return typeof category === "string" && isMemoryCategoryAlias(category) ? category : undefined;
 }
 
 /**

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,
         {