@vellumai/assistant 0.7.2 → 0.8.0

package/src/memory/v2/consolidation-job.ts

@@ -15,8 +15,8 @@
  * substitute in.
  *
  * Lifecycle:
- *   1. Bail if the `memory-v2-enabled` feature flag is off (the worker may
- *      have claimed a stale row at flag-flip time).
+ *   1. Bail if `config.memory.v2.enabled` is false (the worker may have
+ *      claimed a stale row from before v2 was disabled).
  *   2. Acquire a single-process lock at `memory/.v2-state/consolidation.lock`
  *      so two overlapping schedule windows can't fight over the same files.
  *      The lock contains the holder's PID + timestamp so a crashed run leaves
@@ -53,12 +53,12 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../../daemon/trust-context.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { isProcessAlive } from "../../util/process-liveness.js";
 import { bootstrapConversation } from "../conversation-bootstrap.js";
 import { deleteConversation } from "../conversation-crud.js";
 import {
@@ -84,11 +84,11 @@ const FOLLOW_UP_JOB_TYPES: readonly MemoryJobType[] = [
 
 /**
  * Job handler. See file header for the full lifecycle. Returns a discriminated
- * union so tests can assert on the path taken (flag-off / locked / empty /
+ * union so tests can assert on the path taken (disabled / locked / empty /
  * invoked) without having to spy on the filesystem.
  */
 export type ConsolidationOutcome =
-  | { kind: "flag_off" }
+  | { kind: "disabled" }
   | { kind: "locked"; holder: string }
   | { kind: "empty_buffer" }
   | { kind: "wake_failed"; reason?: string }
@@ -103,9 +103,9 @@ export async function memoryV2ConsolidateJob(
   _job: MemoryJob,
   config: AssistantConfig,
 ): Promise<ConsolidationOutcome> {
-  if (!isAssistantFeatureFlagEnabled("memory-v2-enabled", config)) {
-    log.debug("memory-v2-enabled flag off; consolidation skipped");
-    return { kind: "flag_off" };
+  if (!config.memory.v2.enabled) {
+    log.debug("memory.v2.enabled is false; consolidation skipped");
+    return { kind: "disabled" };
   }
 
   const memoryDir = join(getWorkspaceDir(), "memory");
@@ -240,14 +240,20 @@ function readBufferContent(bufferPath: string): string {
 /**
  * Atomically create the lock file with `wx` (O_CREAT | O_EXCL) flags. Returns
  * `null` on success, or the current holder string (file contents, typically
- * `pid timestamp`) when the file already exists — the holder is surfaced for
- * log diagnostics so operators can identify a stuck lock without re-reading.
+ * `pid timestamp`) when the file already exists and the holder is still alive.
  *
- * Crash recovery: if the prior daemon died with the lock held, the file will
- * still be on disk on the next start. PR 20 keeps the lock simple per the
- * plan instructions; a future iteration can probe liveness via `kill(pid, 0)`
- * the way `snapshot-lock.ts` does. Until then, an operator can clear a
- * stale lock by removing the file.
+ * Stale-lock takeover: if the file exists but its holder PID is not running,
+ * unlink the stale file and retry the create exactly once. This recovers
+ * automatically from a crashed daemon that died with the lock held —
+ * otherwise every subsequent scheduled consolidation would skip with `locked`
+ * indefinitely until an operator manually removed the file.
+ *
+ * The simple takeover-then-retry is safe here (unlike `snapshot-lock.ts`'s
+ * full rename-aside dance) because only the assistant's jobs worker calls
+ * this lock, and at most one assistant process runs per workspace at any
+ * time. A holder with an unparseable / empty payload is treated as stale —
+ * the only writers ever produce a `<pid> <timestamp>` line, so an
+ * unparseable file is corruption from a partial write that crashed.
  */
 function tryAcquireLock(lockPath: string): string | null {
   // The workspace migration seeds `memory/.v2-state/`, but tests and
@@ -255,9 +261,40 @@ function tryAcquireLock(lockPath: string): string | null {
   // is idempotent, so the call is cheap when the dir already exists.
   mkdirSync(dirname(lockPath), { recursive: true });
 
+  const firstHolder = tryCreate(lockPath);
+  if (firstHolder === null) return null;
+  if (!isHolderStale(firstHolder)) return firstHolder;
+
+  log.info(
+    { lockPath, holder: firstHolder },
+    "consolidation: taking over stale lock (holder not running)",
+  );
+  try {
+    unlinkSync(lockPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      log.warn(
+        { err, lockPath },
+        "consolidation: failed to unlink stale lock; reporting as locked",
+      );
+      return firstHolder;
+    }
+  }
+  // After unlink, the next `wx` create should succeed. If a third party
+  // raced in and re-acquired (vanishingly unlikely with one writer per
+  // workspace), surface their holder string rather than overwriting.
+  return tryCreate(lockPath);
+}
+
+/**
+ * Atomically create the lock file. Returns `null` on success, or the holder
+ * string read from the file when it already exists (`"unknown"` if the read
+ * itself fails). Rethrows any non-EEXIST errno from `openSync`.
+ */
+function tryCreate(lockPath: string): string | null {
   let fd: number;
   try {
-    // `wx` = create-if-not-exists, fail with EEXIST if it does.
     fd = openSync(lockPath, "wx");
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
@@ -267,13 +304,10 @@ function tryAcquireLock(lockPath: string): string | null {
       return "unknown";
     }
   }
-
-  // Best-effort PID + timestamp payload so a stale lock can be diagnosed.
-  // The worker only cares that the file exists; the contents are advisory.
   try {
     writeSync(fd, `${process.pid} ${Date.now()}\n`);
   } catch {
-    // best-effort
+    // best-effort — payload is advisory, the file's existence is the lock
   } finally {
     try {
       closeSync(fd);
@@ -284,6 +318,21 @@ function tryAcquireLock(lockPath: string): string | null {
   return null;
 }
 
+/**
+ * A holder string is stale when its PID parses to a non-running process.
+ * The payload format is `<pid> <timestamp>` (see `tryCreate`'s write), but
+ * an unparseable / empty / `"unknown"` payload is also treated as stale:
+ * the only writer is `tryCreate` itself, so corruption indicates a partial
+ * write from a crashed prior holder rather than a live writer mid-flush.
+ */
+function isHolderStale(holder: string): boolean {
+  const match = /^\d+/.exec(holder);
+  if (!match) return true;
+  const pid = Number.parseInt(match[0], 10);
+  if (!Number.isFinite(pid) || pid <= 0) return true;
+  return !isProcessAlive(pid);
+}
+
 /**
  * Idempotent unlink of the lock file. Called from the `finally` block so a
  * crash in the wake path doesn't leave the lock stranded. ENOENT is swallowed

package/src/memory/v2/injection.ts

@@ -29,21 +29,18 @@ import { getWorkspaceDir } from "../../util/platform.js";
 import type { DrizzleDb } from "../db-connection.js";
 import {
   type MemoryV2ConceptRowRecord,
-  type MemoryV2SkillRowRecord,
   recordMemoryV2ActivationLog,
 } from "../memory-v2-activation-log-store.js";
 import {
   computeOwnActivation,
-  computeSkillActivation,
   selectCandidates,
   selectInjections,
-  selectSkillInjections,
   spreadActivation,
 } from "./activation.js";
 import { hydrate, save } from "./activation-store.js";
 import { getEdgeIndex } from "./edge-index.js";
 import { readPage, renderPageContent } from "./page-store.js";
-import { getAllSkillIds, getSkillCapability } from "./skill-store.js";
+import { getSkillCapability, isSkillSlug } from "./skill-store.js";
 import type { ActivationState, EverInjectedEntry } from "./types.js";
 
 const log = getLogger("memory-v2-injection");
@@ -84,6 +81,7 @@ export interface InjectMemoryV2BlockParams {
    */
   mode?: InjectMemoryV2Mode;
   config: AssistantConfig;
+  signal?: AbortSignal;
 }
 
 export interface InjectMemoryV2BlockResult {
@@ -127,30 +125,36 @@ export async function injectMemoryV2Block(
     nowText,
     messageId,
     config,
+    signal,
   } = params;
 
   const workspaceDir = getWorkspaceDir();
 
   // (1) Hydrate. Missing rows are normal at conversation start — proceed
   // with an effective empty prior state so the first turn can still inject.
+  throwIfAborted(signal);
   const priorState = await hydrate(database, conversationId);
 
   // (2) Topology. `getEdgeIndex` walks concept-page frontmatter and caches
   // the result module-locally; an empty workspace yields an empty index.
+  throwIfAborted(signal);
   const edgeIndex = await getEdgeIndex(workspaceDir);
 
   // (3) Candidate set: prior-state survivors above epsilon ∪ ANN top-50.
   // `selectCandidates` also returns `fromPrior` / `fromAnn` provenance sets so
   // telemetry can attribute each candidate back to its source.
+  throwIfAborted(signal);
   const { candidates, fromPrior, fromAnn } = await selectCandidates({
     priorState,
     userText: userMessage,
     assistantText: assistantMessage,
     nowText,
     config,
+    signal,
   });
 
   // (4) Own activation: A_o = d·prev + c_user·sim_u + c_a·sim_a + c_now·sim_n.
+  throwIfAborted(signal);
   const { activation: ownActivation, breakdown: ownBreakdown } =
     await computeOwnActivation({
       candidates,
@@ -159,9 +163,11 @@ export async function injectMemoryV2Block(
       assistantText: assistantMessage,
       nowText,
       config,
+      signal,
     });
 
   // (5) Spreading activation across the edge graph (k, hops from config).
+  throwIfAborted(signal);
   const { k, hops, top_k, epsilon } = config.memory.v2;
   const { final: finalActivation, contribution: spreadContribution } =
     spreadActivation(ownActivation, edgeIndex, k, hops);
@@ -182,25 +188,6 @@ export async function injectMemoryV2Block(
   });
   const slugsToRender = mode === "context-load" ? topNow : toInject;
 
-  // (6b) Skill pipeline — a sibling pipeline to the concept-page one above.
-  // Skills are stateless (no decay, no spread, no `everInjected` dedup) and
-  // the catalog is small, so every known skill is scored every turn. The
-  // top-K injection slate is re-presented every turn so the agent can drop
-  // and pick skills up freely; the inspector renders the full ranked list.
-  const skillCandidates = new Set(getAllSkillIds());
-  const { activation: skillActivation, breakdown: skillBreakdown } =
-    await computeSkillActivation({
-      candidates: skillCandidates,
-      userText: userMessage,
-      assistantText: assistantMessage,
-      nowText,
-      config,
-    });
-  const { topNow: topSkillIds } = selectSkillInjections({
-    A: skillActivation,
-    topK: config.memory.v2.top_k_skills,
-  });
-
   // Build the next persisted state regardless of whether we render anything:
   // even on a "no new injection" turn, prior-state activations decay via the
   // candidate-set carry-forward and need to be rewritten so `epsilon`-trimmed
@@ -215,8 +202,10 @@ export async function injectMemoryV2Block(
   // just rendered all of them); on per-turn it's just the newly added slugs.
   // We append rather than reset so that compaction-driven eviction
   // (`evictCompactedTurns`) is the only path that can re-enable a previously-
-  // injected slug. Skills do NOT enter `everInjected` — they are stateless
-  // and re-presented every turn.
+  // injected slug. Skill slugs (`skills/<id>`) participate in this dedup just
+  // like concept slugs — once attached on a turn, the cached attachment lives
+  // on that user message and the agent keeps seeing it across subsequent turns
+  // until compaction evicts the turn.
   const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
   const newlyInjected = slugsToRender.filter(
     (slug) => !everInjectedSet.has(slug),
@@ -243,7 +232,6 @@ export async function injectMemoryV2Block(
   const { block, missingSlugs } = await renderInjectionBlock(
     workspaceDir,
     slugsToRender,
-    topSkillIds,
   );
   const missingSlugSet = new Set(missingSlugs);
   if (missingSlugs.length > 0) {
@@ -262,7 +250,6 @@ export async function injectMemoryV2Block(
   // block memory injection.
   const toInjectSet = new Set(toInject);
   const renderedSet = new Set(slugsToRender);
-  const topSkillIdSet = new Set(topSkillIds);
   const conceptRows: MemoryV2ConceptRowRecord[] = [...candidates].map(
     (slug) => {
       const breakdown = ownBreakdown.get(slug);
@@ -301,6 +288,9 @@ export async function injectMemoryV2Block(
         simUser: breakdown?.simUser ?? 0,
         simAssistant: breakdown?.simAssistant ?? 0,
         simNow: breakdown?.simNow ?? 0,
+        simUserRerankBoost: breakdown?.simUserRerankBoost ?? 0,
+        simAssistantRerankBoost: breakdown?.simAssistantRerankBoost ?? 0,
+        inRerankPool: breakdown?.inRerankPool ?? false,
         spreadContribution: spreadContribution.get(slug) ?? 0,
         source:
           inPrior && inAnn ? "both" : inPrior ? "prior_state" : "ann_top50",
@@ -310,19 +300,6 @@ export async function injectMemoryV2Block(
   );
   conceptRows.sort((a, b) => b.finalActivation - a.finalActivation);
 
-  const skillRows: MemoryV2SkillRowRecord[] = [...skillCandidates].map((id) => {
-    const breakdown = skillBreakdown.get(id);
-    return {
-      id,
-      activation: skillActivation.get(id) ?? 0,
-      simUser: breakdown?.simUser ?? 0,
-      simAssistant: breakdown?.simAssistant ?? 0,
-      simNow: breakdown?.simNow ?? 0,
-      status: topSkillIdSet.has(id) ? "injected" : "not_injected",
-    };
-  });
-  skillRows.sort((a, b) => b.activation - a.activation);
-
   const v2Cfg = config.memory.v2;
   try {
     recordMemoryV2ActivationLog({
@@ -330,7 +307,6 @@ export async function injectMemoryV2Block(
       turn: currentTurn,
       mode,
       concepts: conceptRows,
-      skills: skillRows,
       config: {
         d: v2Cfg.d,
         c_user: v2Cfg.c_user,
@@ -339,7 +315,6 @@ export async function injectMemoryV2Block(
         k: v2Cfg.k,
         hops: v2Cfg.hops,
         top_k: v2Cfg.top_k,
-        top_k_skills: v2Cfg.top_k_skills,
         epsilon: v2Cfg.epsilon,
       },
     });
@@ -353,6 +328,12 @@ export async function injectMemoryV2Block(
   return { block, toInject: newlyInjected };
 }
 
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -380,9 +361,24 @@ interface RenderInjectionBlockResult {
 }
 
 /**
- * Render the inner content of the `<memory>` block for a list of slugs and
- * a list of ranked skill ids. The caller wraps the result in
- * `<memory>...</memory>` exactly once at injection time.
+ * Leading instruction line emitted at the top of every non-empty injection
+ * block. Tells the agent that what follows are page summaries and that it
+ * should read the underlying file when a summary looks relevant. Pages
+ * without a `summary` field render in full instead — the agent treats
+ * those as inline content and doesn't need to follow up.
+ */
+const INJECTION_HEADER =
+  "**CRITICAL:** These are page summaries. Read the page file if it looks relevant.";
+
+/**
+ * Render the inner content of the `<memory>` block for a list of slugs.
+ * The caller wraps the result in `<memory>...</memory>` exactly once at
+ * injection time.
+ *
+ * The slug list is partitioned by prefix: slugs starting with `skills/`
+ * resolve to a `SkillEntry` via `getSkillCapability` and render under the
+ * trailing `### Skills You Can Use` subsection; everything else is read
+ * from disk via `readPage` and rendered as a concept-page section.
  *
  * Concept pages are read in parallel via `readPage`. Pages whose file has
  * gone missing between selection and render (e.g. consolidation deleted
@@ -390,30 +386,31 @@ interface RenderInjectionBlockResult {
  * block but reported back via `missingSlugs` so callers can surface the
  * divergence.
  *
- * Skill ids are looked up via `getSkillCapability`. Ids that the cache no
- * longer knows (e.g. uninstalled mid-run) are silently dropped, mirroring
- * the missing-pages behavior.
+ * Skill slugs whose entry the cache no longer knows (e.g. uninstalled
+ * mid-run) are silently dropped, mirroring the missing-pages behavior but
+ * without entering `missingSlugs` — the skill catalog is the source of
+ * truth for skill availability, not on-disk concept pages, so a missing
+ * skill is an expected catalog-level outcome rather than a stale-index
+ * bug.
+ *
+ * Each concept-page section is rendered as a path header followed by either
+ * the page's `summary` (when present in frontmatter) or the full page (the
+ * fallback for pages predating the summary field). Skills sit at the end
+ * under `### Skills You Can Use`, unchanged. The leading `**CRITICAL:**`
+ * line tells the agent how to read the block.
+ *
+ *   **CRITICAL:** These are page summaries. Read the page file if it looks relevant.
  *
- * The block shape is the §5 layout from the design doc, with an optional
- * trailing skills subsection. Each concept-page section reproduces the page
- * as it lives on disk — frontmatter (`edges`, `ref_files`) plus body — so
- * the agent sees the page's edges and any referenced media paths alongside
- * the prose:
+ *   # memory/concepts/<concept-slug-1>.md
+ *   <summary-1>
  *
- *   ### <slug-1>
+ *   # memory/concepts/<concept-slug-2>.md
  *   ---
  *   edges:
  *     - <neighbor-slug>
  *   ref_files:
  *     - <path/to/asset>
  *   ---
- *   <body-1>
- *
- *   ### <slug-2>
- *   ---
- *   edges: []
- *   ref_files: []
- *   ---
  *   <body-2>
  *
  *   ### Skills You Can Use
@@ -423,10 +420,12 @@ interface RenderInjectionBlockResult {
 async function renderInjectionBlock(
   workspaceDir: string,
   slugs: string[],
-  skillIds: string[],
 ): Promise<RenderInjectionBlockResult> {
+  const conceptSlugs = slugs.filter((s) => !isSkillSlug(s));
+  const skillSlugs = slugs.filter((s) => isSkillSlug(s));
+
   const pages = await Promise.all(
-    slugs.map(async (slug) => {
+    conceptSlugs.map(async (slug) => {
       const page = await readPage(workspaceDir, slug);
       return { slug, page };
     }),
@@ -439,15 +438,23 @@ async function renderInjectionBlock(
       missingSlugs.push(slug);
       continue;
     }
+    const summary = page.frontmatter.summary?.trim();
+    const path = `memory/concepts/${slug}.md`;
+    if (summary && summary.length > 0) {
+      sections.push(`# ${path}\n${summary}`);
+      continue;
+    }
+    // Fallback: page predates the `summary` field (or the field was set to
+    // empty). Render the full page — frontmatter + body — so retrieval
+    // still surfaces the same content the agent saw before this change.
     const content = renderPageContent(page).trim();
     if (content.length === 0) continue;
-    sections.push(`### ${slug}\n${content}`);
+    sections.push(`# ${path}\n${content}`);
   }
 
-  // v2's skills collection is skills-only, so the activation suffix always applies.
   const skillLines: string[] = [];
-  for (const id of skillIds) {
-    const entry = getSkillCapability(id);
+  for (const slug of skillSlugs) {
+    const entry = getSkillCapability(slug);
     if (!entry) continue;
     skillLines.push(`- ${entry.content} → use skill_load to activate`);
   }
@@ -458,7 +465,7 @@ async function renderInjectionBlock(
   if (sections.length === 0) return { block: null, missingSlugs };
 
   return {
-    block: sections.join("\n\n"),
+    block: `${INJECTION_HEADER}\n\n${sections.join("\n\n")}`,
     missingSlugs,
   };
 }

package/src/memory/v2/page-store.ts

@@ -338,6 +338,45 @@ export async function listPages(workspaceDir: string): Promise<string[]> {
   return slugs;
 }
 
+/**
+ * Cheap "do any concept pages exist?" probe — walks the concepts/ tree only
+ * far enough to find one `.md` file and returns immediately. Used by the
+ * daemon-startup rebuild gate so the empty-after-create recovery path skips
+ * a full enumeration of all 1000+ pages just to ask a yes/no question.
+ */
+export async function hasConceptPages(workspaceDir: string): Promise<boolean> {
+  const root = getConceptsDir(workspaceDir);
+  const queue: string[] = [root];
+
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        if (dir === root) return false;
+        continue;
+      }
+      throw err;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      if (entry.isDirectory()) {
+        queue.push(join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
+      if (entry.name.includes(".tmp.")) continue;
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * Delete a concept page. Idempotent — missing files are not an error.
  *

package/src/memory/v2/prompts/consolidation.ts

@@ -16,7 +16,7 @@
  * the convention established for the sweep prompt.
  */
 
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 
@@ -28,6 +28,14 @@ const log = getLogger("memory-v2-consolidate-prompt");
 /** Sentinel substituted with the cutoff timestamp at runtime. */
 export const CUTOFF_PLACEHOLDER = "{{CUTOFF}}";
 
+/**
+ * Upper bound for the override file. Real consolidation prompts are kilobytes;
+ * 1 MiB is generous headroom while preventing a `settings.write` principal from
+ * pointing the field at a multi-gigabyte file (or `/dev/zero`-like stream that
+ * `lstat` can't size cap on its own) and exfiltrating it through the wake hint.
+ */
+const MAX_PROMPT_BYTES = 1 * 1024 * 1024;
+
 /**
  * Consolidation prompt — live-mode only. The agent runs as itself (full
  * SOUL.md + IDENTITY.md + persona + memory autoloads) with the standard
@@ -123,6 +131,7 @@ edges:
   - path/to/sister
   - path/to/parent
 ref_files: []
+summary: 1-4 sentences describing what this article is. Plain prose only — no bullets, no newlines, no markdown lists. Lead with the most identifying detail.
 ---
 # title
 
@@ -132,6 +141,8 @@ ref_files: []
 - **bullet 2.** ...
 \`\`\`
 
+The \`summary\` field is required on every new or updated article. Retrieval injects \`path + summary\` into context — the agent reads the full file only when the summary looks relevant — so make the summary specific and terse. Keep it on a single YAML line (no \`|\` block scalars, no embedded newlines).
+
 **Caps:** ~5-8 bullets per topic/concept article. ~10-12 per arc-node (which can use bold inline labels: \`**the open**: ...\`).
 
 ## One fact, one home
@@ -277,6 +288,7 @@ edges:
   - some-named-phrase
   - objects/some-artifact
 ref_files: []
+summary: A short prose description of the article — 1-4 sentences, single line.
 ---
 \`\`\`
 
@@ -408,6 +420,7 @@ For each article you touched:
 9. **Spawn check.** Did you ask "what's recognizable here?" not "what have I earned?" Did you catch any hedging — and spawn anyway? Any fold-into-parent / defer stealth-skips you almost did?
 10. **Split-not-compress.** If anything went over cap, did you split? If you compressed, can you name the rationale in one sentence?
 11. **Edges.** Outgoing within tiered caps (atomic ≤10, arc ≤15, gravity well ≤25, hard limit 20 on non-hubs)? No noise-edges to gravity wells from non-arc pages?
+11a. **Summary present.** Every new or updated article has a \`summary:\` line — 1-4 sentences, single YAML line, lead with the identifying detail.
 12. **Topic coherence.** Does each article answer ONE question? Gravity wells acting as hubs (pointing at topic articles), not absorbing body?
 13. **\`recent.md\`** under 2000 chars, today=full / older=one-liners?
 14. **\`[SOURCE NEEDED]\`** tags surfaced for human review?
@@ -447,6 +460,33 @@ export function resolveConsolidationPrompt(
   const resolvedPath = resolveOverridePath(overridePath);
   let contents: string;
   try {
+    const stat = lstatSync(resolvedPath);
+    if (!stat.isFile()) {
+      log.warn(
+        {
+          configuredPath: overridePath,
+          resolvedPath,
+          reason: "not_regular_file",
+          fallback: "bundled",
+        },
+        "consolidation prompt override is not a regular file; using bundled prompt",
+      );
+      return renderConsolidationPrompt(cutoff);
+    }
+    if (stat.size > MAX_PROMPT_BYTES) {
+      log.warn(
+        {
+          configuredPath: overridePath,
+          resolvedPath,
+          size: stat.size,
+          limit: MAX_PROMPT_BYTES,
+          reason: "oversized_override",
+          fallback: "bundled",
+        },
+        "consolidation prompt override exceeds size limit; using bundled prompt",
+      );
+      return renderConsolidationPrompt(cutoff);
+    }
     contents = readFileSync(resolvedPath, "utf-8");
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;