@vellumai/assistant 0.8.11-dev.202606120321.552e02e → 0.8.11-dev.202606120751.ef8e25a

package/ARCHITECTURE.md

@@ -770,30 +770,28 @@ The macOS `SpeechRecognizerAdapter` protocol in `clients/macos/vellum-assistant/
 - Terminology: "STT" and "transcription" refer to the same operation (converting audio to text). "Speech recognition" is used in client-native contexts where Apple's Speech framework terminology is canonical. All three terms map to the same conceptual operation.
 - **Onboarding**: For a step-by-step guide to adding a new STT provider, see `docs/stt-provider-onboarding.md`.
 
-### Update Bulletin System
+### On-Demand Home Content Generation
 
-Release-driven update notification system that dispatches a background conversation to process release notes when a release lands.
+LLM-generated content shown by clients (personalized home greeting, suggested prompts, conversation starters, identity intro) is produced on demand, never at daemon startup or on unconditional timers.
 
-**Data flow:**
+**Data flow (home greeting + suggested prompts):**
 
-1. **Storage** — Release notes live at `<workspace>/UPDATES.md`. The file is written by workspace migrations; each release that needs to surface notes ships a dedicated migration in `src/workspace/migrations/` that appends a release-notes block to the file. The workspace-migration runner is the authoritative idempotency mechanism: `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and never re-runs an ID that is already in the `applied` set.
-2. **Dispatch** — At daemon startup (after `runWorkspaceMigrations()`), `runUpdateBulletinJobIfNeeded()` is invoked fire-and-forget. It hashes the current `UPDATES.md` content and compares against the `updates:last_processed_hash` checkpoint. When the hashes differ, it bootstraps a `conversationType: "background"` conversation and calls `wakeAgentForOpportunity()` so the agent processes the bulletin without any interactive session.
-3. **Completion** — The agent acts on the contents and deletes `UPDATES.md` when done. The job persists the new hash to `updates:last_processed_hash` post-wake, so subsequent startups short-circuit until the file is repopulated by a future migration.
+1. **Read** — `GET /v1/home/feed` reads both caches synchronously: the greeting from `memory_checkpoints` (`home:greeting:*`, 4-hour TTL, busted when identity files change) and suggested prompts from `memory_checkpoints` (`home:suggested_prompts:*`, 4-hour TTL, invalidated on OAuth connect/disconnect). When a cache is empty the handler falls back to a time-of-day greeting and an empty prompt list.
+2. **Revalidate** — The same GET fires `revalidateHomeContentInBackground()` (`src/home/home-content-refresh.ts`) fire-and-forget. It is single-flight (concurrent GETs share one run) and each refresher no-ops while its cache is fresh, so generation happens at most once per TTL window — and only when a user actually views Home.
+3. **Notify** — When fresh content lands, the coordinator publishes a `home_feed_updated` event; connected clients refetch the feed and the personalized content swaps in.
 
-**Checkpoint keys** (in `memory_checkpoints` table):
-
-- `updates:last_processed_hash` — content hash of the `UPDATES.md` payload most recently dispatched to the background job.
+Conversation starters follow the same pattern via `GET /v1/conversation-starters`, which enqueues a `generate_conversation_starters` memory job when the starter set is stale (cooldown-gated, deduped against in-flight jobs).
 
 **Key source files:**
 
-| File                                   | Purpose                                                                                   |
-| -------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `src/workspace/migrations/`            | Per-release migrations that append release notes to `UPDATES.md`                          |
-| `src/workspace/migrations/registry.ts` | Append-only `WORKSPACE_MIGRATIONS` registry                                               |
-| `src/prompts/update-bulletin-job.ts`   | `runUpdateBulletinJobIfNeeded()` — hash check, background dispatch, and checkpoint update |
-| `src/daemon/lifecycle.ts`              | Fire-and-forget dispatch of `runUpdateBulletinJobIfNeeded()` after DB init at startup     |
-| `src/config/schemas/updates.ts`        | `updates.enabled` config toggle (defaults to `true`; disables the background dispatch)    |
-| `src/permissions/defaults.ts`          | Auto-allow rules for file_read/write/edit + bare-filename `rm UPDATES.md`                 |
+| File                                                | Purpose                                                                  |
+| --------------------------------------------------- | ------------------------------------------------------------------------ |
+| `src/home/home-content-refresh.ts`                  | Single-flight on-demand revalidation coordinator + SSE notify            |
+| `src/home/home-greeting.ts`                         | Greeting generation (BTW side-chain, `homeGreeting` call site)           |
+| `src/home/home-greeting-cache.ts`                   | Checkpoint-backed greeting cache with identity-hash invalidation         |
+| `src/home/suggested-prompts.ts`                     | Prompt generation + checkpoint-backed cache + OAuth invalidation         |
+| `src/runtime/routes/home-feed-routes.ts`            | `GET /v1/home/feed` — cached read + fire-and-forget revalidation trigger |
+| `src/runtime/routes/conversation-starter-routes.ts` | On-demand starter refresh via memory job enqueue                         |
 
 ---
 

package/README.md

@@ -45,12 +45,6 @@ cp .env.example .env
 | `RUNTIME_HTTP_PORT` | No       | —                           | Enable the HTTP server (required for gateway/web) |
 | `RUNTIME_HTTP_HOST` | No       | `127.0.0.1`                 | HTTP server bind address                          |
 
-## Update Bulletin
-
-Release notes are surfaced via a background conversation dispatched at daemon startup. Workspace migrations write release notes to `<workspace>/UPDATES.md`; `runUpdateBulletinJobIfNeeded()` then spawns a `conversationType: "background"` conversation via `runBackgroundJob()` (see `runtime/background-job-runner.ts`) whenever the file's content hash changes. The agent uses judgment to surface updates to the user when relevant, and deletes the file when done.
-
-**For release maintainers:** Add a new migration under `assistant/src/workspace/migrations/0XX-release-notes-<slug>.ts` with the release notes inline as a string literal, and append the export to `WORKSPACE_MIGRATIONS` in `assistant/src/workspace/migrations/registry.ts`. Migrations are append-only. Idempotency requires both the workspace-migration runner AND an in-file marker: `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and skips IDs already in the `applied` set, but a crash between `UPDATES.md` append and checkpoint finalize can cause a duplicate append on next boot. Embed an HTML marker like `<!-- release-note-id:<migration-id> -->` in the appended block, and short-circuit when the marker is already present. See the root `AGENTS.md` "Release Update Hygiene" section for the full rationale. Skip the migration entirely for releases with no user/assistant-facing changes.
-
 ## Usage
 
 ### Lifecycle management (recommended)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.11-dev.202606120321.552e02e",
+  "version": "0.8.11-dev.202606120751.ef8e25a",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/anthropic-provider.test.ts

@@ -389,6 +389,49 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     ).not.toContain("extended-cache-ttl-2025-04-11");
   });
 
+  test("disableCache sends no cache_control anywhere and strips caller-stamped block markers", async () => {
+    // A one-shot call site that opted out of prompt caching: no breakpoint
+    // on system, tools, turn-start, or tail — and a caller-stamped block
+    // marker is removed rather than forwarded.
+    const messages: Message[] = [
+      {
+        role: "user",
+        content: [
+          cachedPrefixBlock("stable pages block"),
+          { type: "text", text: "Do something" },
+        ],
+      },
+      toolUseMsg("tu_1", "bash"),
+      toolResultMsg("tu_1", "output"),
+    ];
+    await provider.sendMessage(messages, {
+      tools: sampleTools,
+      systemPrompt: "You are a helpful assistant.",
+      config: { disableCache: true },
+    });
+
+    const system = lastStreamParams!.system as Array<{
+      cache_control?: unknown;
+    }>;
+    expect(system[0].cache_control).toBeUndefined();
+
+    const tools = lastStreamParams!.tools as Array<{
+      cache_control?: unknown;
+    }>;
+    for (const tool of tools) {
+      expect(tool.cache_control).toBeUndefined();
+    }
+
+    const sent = lastStreamParams!.messages as Array<{
+      content: Array<{ cache_control?: unknown }>;
+    }>;
+    for (const message of sent) {
+      for (const block of message.content) {
+        expect(block.cache_control).toBeUndefined();
+      }
+    }
+  });
+
   test("v3-shape call (system + tools + cached prefix block) stays within the 4-breakpoint cap", async () => {
     // Mirrors a v3 L2 selector call: a system prompt, a forced tool, and a user
     // message whose stable <pages> block carries a cache_control breakpoint

package/src/__tests__/background-workers-disk-pressure.test.ts

@@ -52,7 +52,7 @@ mock.module("../config/loader.js", () => ({
   getNestedValue: () => undefined,
   setNestedValue: () => {},
   API_KEY_PROVIDERS: [],
-  _appendQuarantineBulletin: () => {},
+  _writeQuarantineNotice: () => {},
   invalidateConfigCache: () => {},
 }));
 
@@ -158,6 +158,9 @@ mock.module("../memory/conversation-crud.js", () => ({
 
 mock.module("../memory/conversation-title-service.js", () => ({
   GENERATING_TITLE: "Generating title...",
+  AUTO_TITLE_DETERMINISTIC: 2,
+  deriveDeterministicTitle: (context: { systemHint?: string }) =>
+    context.systemHint ?? "Untitled Conversation",
   isReplaceableTitle: () => true,
   queueGenerateConversationTitle: () => {},
   queueRegenerateConversationTitle: () => {},

package/src/__tests__/checker.test.ts

@@ -428,21 +428,15 @@ describe("Permission Checker", () => {
       expect(result.decision).toBe("allow");
     });
 
-    test("file_read of workspace UPDATES.md is auto-allowed", async () => {
-      const updatesPath = join(checkerTestDir, "UPDATES.md");
-      const result = await check("file_read", { path: updatesPath }, "/tmp");
-      expect(result.decision).toBe("allow");
-    });
-
-    test("file_write of workspace UPDATES.md is auto-allowed", async () => {
-      const updatesPath = join(checkerTestDir, "UPDATES.md");
-      const result = await check("file_write", { path: updatesPath }, "/tmp");
+    test("file_read of workspace BOOTSTRAP.md is auto-allowed", async () => {
+      const bootstrapPath = join(checkerTestDir, "BOOTSTRAP.md");
+      const result = await check("file_read", { path: bootstrapPath }, "/tmp");
       expect(result.decision).toBe("allow");
     });
 
-    test("file_edit of workspace UPDATES.md is auto-allowed", async () => {
-      const updatesPath = join(checkerTestDir, "UPDATES.md");
-      const result = await check("file_edit", { path: updatesPath }, "/tmp");
+    test("file_edit of workspace BOOTSTRAP.md is auto-allowed", async () => {
+      const bootstrapPath = join(checkerTestDir, "BOOTSTRAP.md");
+      const result = await check("file_edit", { path: bootstrapPath }, "/tmp");
       expect(result.decision).toBe("allow");
     });
 

package/src/__tests__/config-loader-backfill.test.ts

@@ -82,6 +82,7 @@ import { migrateProviderConnectionStatusLabel } from "../memory/migrations/244-p
 import { migrateProviderConnectionBaseUrlAndModels } from "../memory/migrations/250-provider-connection-base-url-and-models.js";
 import * as schema from "../memory/schema.js";
 import { getConnection } from "../providers/inference/connections.js";
+import { getConfigQuarantineNoticePath } from "../util/platform.js";
 import { setStorePathForTesting } from "./encrypted-store-test-helpers.js";
 
 // ---------------------------------------------------------------------------
@@ -325,8 +326,9 @@ describe("loadConfig startup behavior", () => {
         }
       }
     }
-    const updatesPath = join(WORKSPACE_DIR, "UPDATES.md");
-    if (existsSync(updatesPath)) rmSync(updatesPath, { force: true });
+    // Clear any leftover config-quarantine notice sentinel from prior runs.
+    const noticePath = getConfigQuarantineNoticePath();
+    if (existsSync(noticePath)) rmSync(noticePath, { force: true });
     ensureTestDir();
     setStorePathForTesting(join(WORKSPACE_DIR, "keys.enc"));
     delete process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH;

package/src/__tests__/config-loader-quarantine-notice.test.ts

@@ -0,0 +1,167 @@
+/**
+ * When loadConfig()/loadRawConfig() quarantines a corrupt config.json, it
+ * writes a small JSON sentinel to <workspace>/data/config-quarantine-notice.json
+ * recording the event. The per-turn `config-quarantine-notice` injector reads
+ * that sentinel and surfaces the reset to the agent — it's agent-visible
+ * context, not a push notification.
+ *
+ * The sentinel is overwritten on each quarantine (idempotent per event) and
+ * resolves from a workspace-derived path so it is safe to write during the
+ * very early config load, before the SQLite DB or getConfig().dataDir exist.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  _writeQuarantineNotice,
+  invalidateConfigCache,
+  loadConfig,
+} from "../config/loader.js";
+import { getConfigQuarantineNoticePath } from "../util/platform.js";
+import { setStorePathForTesting } from "./encrypted-store-test-helpers.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+const NOTICE_PATH = getConfigQuarantineNoticePath();
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "memory", "knowledge"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function resetWorkspace(): void {
+  for (const name of readdirSync(WORKSPACE_DIR)) {
+    rmSync(join(WORKSPACE_DIR, name), { recursive: true, force: true });
+  }
+  ensureTestDir();
+}
+
+function listQuarantinedFiles(): string[] {
+  return readdirSync(WORKSPACE_DIR).filter((name) =>
+    /^config\.json\.corrupt-.+\.json$/.test(name),
+  );
+}
+
+function readNotice(): {
+  quarantinedAt: string;
+  quarantinePath: string;
+  originalPath: string;
+} {
+  return JSON.parse(readFileSync(NOTICE_PATH, "utf-8"));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("config-quarantine notice sentinel", () => {
+  beforeEach(() => {
+    resetWorkspace();
+    setStorePathForTesting(join(WORKSPACE_DIR, "keys.enc"));
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    setStorePathForTesting(null);
+    invalidateConfigCache();
+  });
+
+  test("writes a sentinel recording the quarantine when config.json is corrupt", () => {
+    writeFileSync(CONFIG_PATH, '{"provider": "anthropic", "mo');
+
+    loadConfig();
+
+    const [quarantinedName] = listQuarantinedFiles();
+    expect(quarantinedName).toBeDefined();
+    const quarantinedPath = join(WORKSPACE_DIR, quarantinedName);
+
+    expect(existsSync(NOTICE_PATH)).toBe(true);
+    const notice = readNotice();
+    expect(notice.quarantinePath).toBe(quarantinedPath);
+    expect(notice.originalPath).toBe(CONFIG_PATH);
+    // quarantinedAt is a parseable ISO timestamp.
+    expect(Number.isNaN(Date.parse(notice.quarantinedAt))).toBe(false);
+  });
+
+  test("a second quarantine overwrites the sentinel with the latest event", () => {
+    // First corruption round.
+    writeFileSync(CONFIG_PATH, '{"partial": ');
+    loadConfig();
+    invalidateConfigCache();
+
+    const firstNotice = readNotice();
+    expect(listQuarantinedFiles()).toHaveLength(1);
+
+    // Loader wrote a fresh default config.json after quarantine; corrupt it
+    // again. Spin briefly so the second quarantine gets a distinct
+    // millisecond-precision filename (and a later timestamp).
+    const untilDifferentMs = Date.now() + 5;
+    while (Date.now() < untilDifferentMs) {
+      /* spin */
+    }
+    writeFileSync(CONFIG_PATH, "still not json");
+    loadConfig();
+
+    const quarantined = listQuarantinedFiles().sort();
+    expect(quarantined).toHaveLength(2);
+
+    // Single sentinel, pointing at the most recent quarantine.
+    const secondNotice = readNotice();
+    expect(secondNotice.quarantinePath).not.toBe(firstNotice.quarantinePath);
+    expect(secondNotice.quarantinePath).toBe(
+      join(WORKSPACE_DIR, quarantined[quarantined.length - 1]),
+    );
+  });
+
+  test("valid config.json does not create a sentinel (regression guard)", () => {
+    writeFileSync(
+      CONFIG_PATH,
+      JSON.stringify({ provider: "anthropic", model: "claude-opus-4-7" }),
+    );
+
+    loadConfig();
+
+    expect(listQuarantinedFiles()).toHaveLength(0);
+    expect(existsSync(NOTICE_PATH)).toBe(false);
+  });
+
+  test("sentinel write failure is swallowed (startup never blocks)", () => {
+    // Make the notice directory unwritable by replacing it with a file so the
+    // write/mkdir path throws. The helper must not propagate the error.
+    const noticeDir = join(WORKSPACE_DIR, "data");
+    rmSync(noticeDir, { recursive: true, force: true });
+    // A regular file where the `data` directory is expected makes mkdir/write
+    // fail with ENOTDIR/EEXIST.
+    writeFileSync(noticeDir, "not a directory", "utf-8");
+
+    const quarantinePath = join(
+      WORKSPACE_DIR,
+      "config.json.corrupt-2026-04-20T12-00-00.000Z.json",
+    );
+
+    expect(() =>
+      _writeQuarantineNotice(CONFIG_PATH, quarantinePath),
+    ).not.toThrow();
+  });
+});

package/src/__tests__/config-watcher.test.ts

@@ -266,12 +266,12 @@ describe("ConfigWatcher workspace file handlers", () => {
     expect(identityCallCount).toBe(1);
   });
 
-  test("UPDATES.md is not subscribed (only the registered handler set is)", () => {
+  test("unregistered workspace files are not subscribed (only the registered handler set is)", () => {
     watcher.start(onConversationEvict);
     // Per-file watching only registers config.json, SOUL.md, IDENTITY.md.
     // The whole workspace dir must not be watched either — that was the
     // ENXIO-on-Unix-sockets bug.
-    expect(findFileWatch(join(WORKSPACE_DIR, "UPDATES.md"))).toBeUndefined();
+    expect(findFileWatch(join(WORKSPACE_DIR, "OTHER.md"))).toBeUndefined();
     expect(findWatcher(WORKSPACE_DIR)).toBeUndefined();
   });
 

package/src/__tests__/conversation-agent-loop-inference-profile.test.ts

@@ -3,7 +3,7 @@
  * `inferenceProfile` column at turn start and threads it through to
  * `AgentLoop.run()` as the per-turn `overrideProfile`. Background
  * conversations intentionally skip the column so background fan-out
- * (subagents, scheduled tasks, update bulletins) runs on the workspace
+ * (subagents, scheduled tasks) runs on the workspace
  * defaults rather than inheriting an interactive override.
  *
  * This is the "conversation-agent-loop integration" half of the

package/src/__tests__/conversation-title-service.test.ts

@@ -59,6 +59,7 @@ mock.module("../runtime/sync/resource-sync-events.js", () => ({
 }));
 
 import {
+  AUTO_TITLE_DETERMINISTIC,
   generateAndPersistConversationTitle,
   queueGenerateConversationTitle,
   regenerateConversationTitle,
@@ -260,7 +261,7 @@ describe("conversation-title-service", () => {
     expect(mockUpdateConversationTitle).toHaveBeenCalledWith(
       "conv-1",
       "Untitled Conversation",
-      1,
+      AUTO_TITLE_DETERMINISTIC,
     );
   });
 

package/src/__tests__/disk-pressure-tools.test.ts

@@ -41,7 +41,7 @@ mock.module("../config/loader.js", () => ({
   setNestedValue: () => undefined,
   mergeDefaultWorkspaceConfig: (config: unknown) => config,
   API_KEY_PROVIDERS: [] as const,
-  _appendQuarantineBulletin: () => undefined,
+  _writeQuarantineNotice: () => undefined,
 }));
 
 mock.module("../daemon/conversation-skill-tools.js", () => ({

package/src/__tests__/filing-service.test.ts

@@ -96,9 +96,14 @@ mock.module("../util/logger.js", () => ({
   }),
 }));
 
-// Mock conversation title service
+// Mock conversation title service. `deriveDeterministicTitle` mirrors the
+// real implementation's systemHint passthrough so bootstrap-created
+// conversations carry their job hint as the title.
 mock.module("../memory/conversation-title-service.js", () => ({
   GENERATING_TITLE: "Generating title...",
+  AUTO_TITLE_DETERMINISTIC: 2,
+  deriveDeterministicTitle: (context: { systemHint?: string }) =>
+    context.systemHint ?? "Untitled Conversation",
   queueGenerateConversationTitle: () => {},
 }));
 
@@ -230,12 +235,12 @@ describe("FilingService", () => {
     );
   });
 
-  test("creates background conversation with generating title placeholder", async () => {
+  test("creates background conversation with the deterministic filing title", async () => {
     const service = createService();
     await service.runOnce();
 
     expect(createdConversations).toHaveLength(1);
-    expect(createdConversations[0].title).toBe("Generating title...");
+    expect(createdConversations[0].title).toBe("Knowledge base filing");
     expect(createdConversations[0].conversationType).toBe("background");
     // Confirms FilingService routes through runBackgroundJob:
     //   source="filing" + runner-default groupId="system:background".

package/src/__tests__/handlers-skills-memory-v2-reseed.test.ts

@@ -65,7 +65,7 @@ mock.module("../config/loader.js", () => ({
   saveRawConfig: () => {},
   getNestedValue: () => undefined,
   setNestedValue: () => {},
-  _appendQuarantineBulletin: () => {},
+  _writeQuarantineNotice: () => {},
 }));
 
 mock.module("../config/skill-state.js", () => ({

package/src/__tests__/heartbeat-disk-pressure.test.ts

@@ -37,7 +37,7 @@ mock.module("../config/loader.js", () => ({
   getNestedValue: () => undefined,
   setNestedValue: () => {},
   API_KEY_PROVIDERS: [],
-  _appendQuarantineBulletin: () => {},
+  _writeQuarantineNotice: () => {},
   invalidateConfigCache: () => {},
 }));
 
@@ -102,6 +102,9 @@ mock.module("../prompts/persona-resolver.js", () => ({
 
 mock.module("../memory/conversation-title-service.js", () => ({
   GENERATING_TITLE: "Generating title...",
+  AUTO_TITLE_DETERMINISTIC: 2,
+  deriveDeterministicTitle: (context: { systemHint?: string }) =>
+    context.systemHint ?? "Untitled Conversation",
   queueGenerateConversationTitle: () => {},
 }));
 

package/src/__tests__/heartbeat-service.test.ts

@@ -250,6 +250,9 @@ mock.module("../notifications/emit-signal.js", () => ({
 // Mock conversation title service
 mock.module("../memory/conversation-title-service.js", () => ({
   GENERATING_TITLE: "Generating title...",
+  AUTO_TITLE_DETERMINISTIC: 2,
+  deriveDeterministicTitle: (context: { systemHint?: string }) =>
+    context.systemHint ?? "Untitled Conversation",
   queueGenerateConversationTitle: () => {},
 }));
 
@@ -497,12 +500,12 @@ describe("HeartbeatService", () => {
     expect(processMessageCalls[0].content).toContain("Check in with yourself");
   });
 
-  test("creates background conversation with generating title placeholder", async () => {
+  test("creates background conversation with the deterministic heartbeat title", async () => {
     const service = createService();
     await service.runOnce();
 
     expect(createdConversations).toHaveLength(1);
-    expect(createdConversations[0].title).toBe("Generating title...");
+    expect(createdConversations[0].title).toBe("Heartbeat");
     expect(createdConversations[0].conversationType).toBe("background");
   });
 

package/src/__tests__/injector-chain.test.ts

@@ -5,9 +5,10 @@
  *
  * 1. The default injectors ({@link defaultInjectors}) are listed in the
  *    documented order (disk-pressure-warning → workspace-context →
- *    background-turn → unified-turn-context → pkb-context → pkb-reminder →
- *    memory-v2-static → now-md → active-documents → document-comments →
- *    subagent-status → slack-messages → thread-focus).
+ *    background-turn → unified-turn-context → config-quarantine-notice →
+ *    pkb-context → pkb-reminder → memory-v2-static → now-md →
+ *    active-documents → document-comments → subagent-status →
+ *    slack-messages → thread-focus).
  * 2. The assembled {@link injectorChain} sorts the defaults together with the
  *    memory-v3 injector by ascending `order`, so memory-v3 (order 1000) lands
  *    last.
@@ -298,6 +299,7 @@ describe("injector chain", () => {
       "workspace-context",
       "background-turn",
       "unified-turn-context",
+      "config-quarantine-notice",
       "pkb-context",
       "pkb-reminder",
       "memory-v2-static",
@@ -324,6 +326,9 @@ describe("injector chain", () => {
     expect(byName.get("unified-turn-context")).toBe(
       DEFAULT_INJECTOR_ORDER.unifiedTurnContext,
     );
+    expect(byName.get("config-quarantine-notice")).toBe(
+      DEFAULT_INJECTOR_ORDER.configQuarantineNotice,
+    );
     expect(byName.get("pkb-context")).toBe(DEFAULT_INJECTOR_ORDER.pkbContext);
     expect(byName.get("pkb-reminder")).toBe(DEFAULT_INJECTOR_ORDER.pkbReminder);
     expect(byName.get("memory-v2-static")).toBe(

package/src/__tests__/injector-config-quarantine-notice.test.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  DEFAULT_INJECTOR_ORDER,
+  defaultInjectors,
+} from "../plugins/defaults/memory-retrieval/injectors.js";
+import type { Injector, TurnContext } from "../plugins/types.js";
+import { getConfigQuarantineNoticePath } from "../util/platform.js";
+
+function findInjector(name: string): Injector {
+  const injector = defaultInjectors.find(
+    (candidate) => candidate.name === name,
+  );
+  if (!injector) {
+    throw new Error(`injector '${name}' not registered`);
+  }
+  return injector;
+}
+
+function makeContext(overrides: Partial<TurnContext> = {}): TurnContext {
+  return {
+    requestId: "req-test",
+    conversationId: "conv-test",
+    turnIndex: 0,
+    trust: { sourceChannel: "vellum", trustClass: "guardian" },
+    ...overrides,
+  };
+}
+
+const NOTICE_PATH = getConfigQuarantineNoticePath();
+
+function writeNotice(quarantinedAt: string): void {
+  const dir = dirname(NOTICE_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    NOTICE_PATH,
+    JSON.stringify(
+      {
+        quarantinedAt,
+        quarantinePath: "/ws/config.json.corrupt-x.json",
+        originalPath: "/ws/config.json",
+      },
+      null,
+      2,
+    ),
+    "utf-8",
+  );
+}
+
+function clearNotice(): void {
+  rmSync(NOTICE_PATH, { force: true });
+}
+
+const injector = findInjector("config-quarantine-notice");
+
+describe("config-quarantine-notice injector", () => {
+  beforeEach(() => {
+    clearNotice();
+  });
+
+  afterEach(() => {
+    clearNotice();
+  });
+
+  test("registered at the expected order with prepend-user-tail placement", async () => {
+    expect(injector.order).toBe(DEFAULT_INJECTOR_ORDER.configQuarantineNotice);
+    writeNotice(new Date().toISOString());
+    const block = await injector.produce(makeContext());
+    expect(block?.placement).toBe("prepend-user-tail");
+  });
+
+  test("returns null when no sentinel is present", async () => {
+    const block = await injector.produce(makeContext());
+    expect(block).toBeNull();
+  });
+
+  test("injects a config-reset block when the sentinel is present and fresh", async () => {
+    writeNotice(new Date().toISOString());
+
+    const block = await injector.produce(makeContext());
+    expect(block).not.toBeNull();
+    expect(block?.id).toBe("config-quarantine-notice");
+    expect(block?.text).toContain("<config_reset_notice>");
+    expect(block?.text).toContain("</config_reset_notice>");
+    expect(block?.text).toContain("/ws/config.json.corrupt-x.json");
+    // The sentinel is left in place for subsequent turns until it ages out.
+    expect(existsSync(NOTICE_PATH)).toBe(true);
+  });
+
+  test("injects nothing on non-guardian turns even when the sentinel is fresh", async () => {
+    writeNotice(new Date().toISOString());
+
+    for (const trustClass of ["trusted_contact", "unknown"] as const) {
+      const block = await injector.produce(
+        makeContext({ trust: { sourceChannel: "slack", trustClass } }),
+      );
+      expect(block).toBeNull();
+    }
+    // The sentinel is untouched — it remains for guardian turns.
+    expect(existsSync(NOTICE_PATH)).toBe(true);
+  });
+
+  test("deletes the sentinel and injects nothing when it is stale (>7 days)", async () => {
+    const eightDaysAgo = new Date(
+      Date.now() - 8 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    writeNotice(eightDaysAgo);
+
+    const block = await injector.produce(makeContext());
+    expect(block).toBeNull();
+    expect(existsSync(NOTICE_PATH)).toBe(false);
+  });
+});