@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/plugins/defaults/exploration-drift/hooks/post-tool-use.ts

@@ -0,0 +1,300 @@
+/**
+ * Default `post-tool-use` hook: when a turn's exploration tool calls (bash,
+ * file_read, file_list) show drift — a long unbroken run with no text sent to
+ * the user, or the model re-issuing the exact same call — surface a notice
+ * via `additionalContext` that coaches it to (a) give the user a brief
+ * progress summary and (b) delegate the rest of the investigation to an
+ * `investigator` subagent instead of continuing inline.
+ *
+ * Motivation: a root-cause request investigated inline ran 167 sequential
+ * bash calls in a single turn with no user-facing text, overflowed the
+ * conversation context before any findings were written up, and forced the
+ * user into repeated "Continue?" turns that re-explored the same files (11 of
+ * the 15 files read in the follow-up turn were re-reads). Delegation keeps
+ * the digging in a disposable subagent context. The notices are advisory —
+ * the model decides whether the current run is genuinely an investigation
+ * worth delegating.
+ *
+ * Two triggers, sharing one trailing-run computation:
+ *
+ * 1. **Long dig** (all models): an unbroken run of
+ *    {@link EXPLORATION_NUDGE_THRESHOLD} exploration calls with no user-facing
+ *    text. Repeat nudges are spaced one full threshold apart.
+ * 2. **Loop** (loop-prone models only, currently Kimi K2.6 and MiniMax M3):
+ *    the current call
+ *    is byte-identical (same tool, same input) to at least
+ *    {@link EXPLORATION_LOOP_REPEAT_THRESHOLD}-1 prior calls within the
+ *    trailing run. Re-issuing an identical read-only call inside an unbroken
+ *    read-only run yields no new information — it is the earliest reliable
+ *    sign the model is stuck, so this fires as soon as the repetition
+ *    appears (potentially at call 3 of a run) rather than waiting for the
+ *    long-dig threshold, and re-fires on every further duplicate while the
+ *    model keeps looping. Gated by model so the aggressive trigger covers
+ *    only models prone to this looping; the one legitimate identical-call pattern
+ *    (polling an external process's output) is rare inside an unbroken
+ *    read-only run and the nudge is advisory anyway.
+ *
+ * The trailing run is derived from conversation history on every call
+ * (mirroring the tool-error plugin) so the signal survives mid-run compaction
+ * rewriting the array. The run is bounded by:
+ * - a real user message (turn boundary),
+ * - any non-empty assistant text block (the model spoke to the user),
+ * - any non-exploration tool result (the model did something besides read).
+ *
+ * Nudges dedupe via a per-conversation high-water mark of the streak length
+ * at the last nudge: long-dig nudges require another full threshold of
+ * growth, loop nudges require any growth (each additional duplicate call
+ * re-nudges). The mark also dedupes parallel tool results of one batch (they
+ * all observe identical history and compute the same streak). Entries are
+ * dropped when the streak restarts.
+ *
+ * Subagent conversations are exempt: an investigator is *supposed* to dig at
+ * length, and subagents cannot nest (`SUBAGENT_LIMITS.maxDepth`), so the
+ * delegation advice would be wrong there. The check is a lazy import on the
+ * rare nudge path so the subagent manager's module graph stays out of the
+ * per-tool-result hot path.
+ */
+
+import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+
+import type { Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical long-dig notice. Module-level constant so tests and wrapping
+ * plugins can match it without duplicating the string. Shown to the model as
+ * provider-only context, never to the user.
+ */
+export const EXPLORATION_DRIFT_NUDGE_TEXT =
+  "<system_notice>You have made a long unbroken run of exploration tool calls (shell/file reads) without sending the user any text. Do two things now: (1) send the user a brief summary of what you have found so far — do not keep working silently; (2) if you are tracing a root cause or exploring code/logs at length, stop exploring inline and delegate the remainder to a subagent: call subagent_spawn with role 'investigator' and a precise objective. It will investigate in its own context window and return a compact root-cause report. Continuing inline floods this conversation's context and risks losing your findings before you can report them.</system_notice>";
+
+/**
+ * Canonical loop notice, parameterized on the repeated call. Firmer than the
+ * long-dig text — by the time an identical read-only call repeats, the model
+ * is demonstrably not gaining information.
+ */
+export function explorationLoopNudgeText(
+  toolName: string,
+  repeatCount: number,
+): string {
+  return `<system_notice>You have issued this exact ${toolName} call ${repeatCount} times in the current run of exploration tool calls. Repeating an identical read-only call yields no new information — you are likely stuck. Do two things now: (1) send the user a brief summary of what you have found so far and what you are still missing — do not keep working silently; (2) stop exploring inline and delegate the remaining investigation to a subagent: call subagent_spawn with role 'investigator' and a precise objective that includes what you have already checked and ruled out. It will investigate in its own context window and return a compact root-cause report. Do not re-issue this call again.</system_notice>`;
+}
+
+/**
+ * Exploration streak length that triggers the first long-dig nudge; repeat
+ * long-dig nudges fire each time the streak grows by another full threshold.
+ */
+export const EXPLORATION_NUDGE_THRESHOLD = 25;
+
+/**
+ * Number of byte-identical exploration calls (tool name + input) within one
+ * trailing run that triggers the loop nudge on loop-prone models. The count
+ * includes the current call, so 3 means "the current call is the third
+ * identical issue of this command".
+ */
+export const EXPLORATION_LOOP_REPEAT_THRESHOLD = 3;
+
+/**
+ * Models that get the early loop trigger: Kimi K2.6 and MiniMax M3, matched
+ * across provider naming conventions (Fireworks spells the dot as `p`, e.g.
+ * `accounts/fireworks/models/kimi-k2p6`; OpenRouter reports
+ * `moonshotai/kimi-k2.6` and `minimax/minimax-m3`). Extend the pattern as
+ * other models exhibit the same re-exploration looping.
+ */
+const LOOP_PRONE_MODEL_PATTERN = /kimi-k2[p.]6|minimax-m3/i;
+
+/** Read-only exploration tools whose unbroken runs indicate inline drift. */
+const EXPLORATION_TOOL_NAMES: ReadonlySet<string> = new Set([
+  "bash",
+  "file_read",
+  "file_list",
+]);
+
+/**
+ * Streak length at the last nudge (either kind), per conversation. A
+ * high-water mark rather than a flag so long-dig nudges stay one full
+ * threshold apart, loop nudges fire only when the streak has grown since the
+ * last nudge, and parallel results of one batch (same observed history, same
+ * computed streak) dedupe to a single notice. Entries are dropped when the
+ * streak restarts.
+ */
+const lastNudgedStreakByConversation = new Map<string, number>();
+
+/** Test-only: clear the per-conversation nudge high-water marks. */
+export function resetExplorationDriftStateForTests(): void {
+  lastNudgedStreakByConversation.clear();
+}
+
+/** A `tool_use` block's invocation: tool name plus its raw input. */
+interface ToolInvocation {
+  readonly name: string;
+  readonly input: unknown;
+}
+
+/** Map every `tool_use` block id in history to its invocation. */
+function toolUsesById(
+  messages: ReadonlyArray<Message>,
+): Map<string, ToolInvocation> {
+  const uses = new Map<string, ToolInvocation>();
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    for (const block of message.content) {
+      if (block.type === "tool_use") {
+        uses.set(block.id, { name: block.name, input: block.input });
+      }
+    }
+  }
+  return uses;
+}
+
+/**
+ * Deterministic JSON encoding with object keys sorted recursively, so two
+ * semantically identical tool inputs hash to the same signature regardless of
+ * key order.
+ */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "undefined";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const entries = Object.keys(record)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+  return `{${entries.join(",")}}`;
+}
+
+/**
+ * The trailing unbroken run of exploration tool results in history: its
+ * length and the `tool_use` ids of the calls in it. Walks backwards from the
+ * most recent message and stops at a real user message, a non-empty assistant
+ * text block, or a non-exploration tool result. Text blocks inside
+ * tool-result user rows (e.g. coaching notices appended by other hooks) do
+ * not break the run — they are system notices, not the model speaking to the
+ * user.
+ */
+function trailingExplorationRun(
+  messages: ReadonlyArray<Message>,
+  usesById: ReadonlyMap<string, ToolInvocation>,
+): { streak: number; toolUseIds: string[] } {
+  const toolUseIds: string[] = [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "assistant") {
+      const spokeToUser = message.content.some(
+        (block) => block.type === "text" && block.text.trim().length > 0,
+      );
+      if (spokeToUser) break;
+      continue;
+    }
+    if (message.role !== "user") continue;
+    const hasToolResult = message.content.some(
+      (block) => block.type === "tool_result",
+    );
+    if (!hasToolResult) break;
+    for (let j = message.content.length - 1; j >= 0; j--) {
+      const block = message.content[j];
+      if (block.type !== "tool_result") continue;
+      const use = usesById.get(block.tool_use_id);
+      if (use === undefined || !EXPLORATION_TOOL_NAMES.has(use.name)) {
+        return { streak: toolUseIds.length, toolUseIds };
+      }
+      toolUseIds.push(block.tool_use_id);
+    }
+  }
+  return { streak: toolUseIds.length, toolUseIds };
+}
+
+/**
+ * How many times the current call (tool name + input) has been issued within
+ * the trailing run, including the current call itself. Signatures are only
+ * computed for same-named calls, and only on the loop-prone-model path, to
+ * keep the per-tool-result cost bounded.
+ */
+function currentCallRepeatCount(
+  current: ToolInvocation,
+  runToolUseIds: ReadonlyArray<string>,
+  usesById: ReadonlyMap<string, ToolInvocation>,
+): number {
+  const currentSignature = stableStringify(current.input);
+  let count = 1;
+  for (const id of runToolUseIds) {
+    const use = usesById.get(id);
+    if (
+      use !== undefined &&
+      use.name === current.name &&
+      stableStringify(use.input) === currentSignature
+    ) {
+      count++;
+    }
+  }
+  return count;
+}
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  const usesById = toolUsesById(ctx.messages);
+  const currentUse = usesById.get(ctx.toolResponse.tool_use_id);
+  if (currentUse === undefined || !EXPLORATION_TOOL_NAMES.has(currentUse.name))
+    return;
+
+  // The current result is not in history yet — count it explicitly.
+  const run = trailingExplorationRun(ctx.messages, usesById);
+  const streak = run.streak + 1;
+
+  let lastNudged = lastNudgedStreakByConversation.get(ctx.conversationId) ?? 0;
+  if (streak < lastNudged) {
+    // The streak restarted (new turn, intervening text, or compaction) since
+    // the last nudge — drop the stale high-water mark.
+    lastNudgedStreakByConversation.delete(ctx.conversationId);
+    lastNudged = 0;
+  }
+
+  const longDigNudge = streak - lastNudged >= EXPLORATION_NUDGE_THRESHOLD;
+
+  // Loop detection: only on loop-prone models, and only when the streak has
+  // grown since the last nudge (dedupes parallel batches; re-fires on each
+  // further duplicate). Keyed to the *current* call's signature so the nudge
+  // stops as soon as the model moves on to fresh calls.
+  let loopRepeatCount = 0;
+  if (
+    !longDigNudge &&
+    streak > lastNudged &&
+    LOOP_PRONE_MODEL_PATTERN.test(ctx.model)
+  ) {
+    loopRepeatCount = currentCallRepeatCount(
+      currentUse,
+      run.toolUseIds,
+      usesById,
+    );
+  }
+  const loopNudge = loopRepeatCount >= EXPLORATION_LOOP_REPEAT_THRESHOLD;
+
+  if (!longDigNudge && !loopNudge) return;
+
+  // Subagent conversations are exempt — see module doc.
+  const { getSubagentManager } = await import("../../../../subagent/index.js");
+  if (getSubagentManager().getParentInfo(ctx.conversationId) !== undefined) {
+    return;
+  }
+
+  lastNudgedStreakByConversation.set(ctx.conversationId, streak);
+  const nudgeText = loopNudge
+    ? explorationLoopNudgeText(currentUse.name, loopRepeatCount)
+    : EXPLORATION_DRIFT_NUDGE_TEXT;
+  ctx.logger.info(
+    {
+      plugin: "exploration-drift",
+      streak,
+      toolName: currentUse.name,
+      trigger: loopNudge ? "loop" : "long-dig",
+      ...(loopNudge ? { repeatCount: loopRepeatCount } : {}),
+    },
+    "Exploration drift detected — nudging summary + investigator delegation",
+  );
+  ctx.additionalContext = ctx.additionalContext
+    ? `${ctx.additionalContext}\n${nudgeText}`
+    : nudgeText;
+};
+
+export default postToolUse;

package/src/plugins/defaults/exploration-drift/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-exploration-drift",
+  "version": "1.0.0",
+  "description": "First-party default plugin contributing a post-tool-use hook that nudges the model to summarize and delegate to an investigator subagent when a turn accumulates a long run of exploration tool calls, or (on loop-prone models) re-issues an identical exploration call.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/index.ts

@@ -31,6 +31,10 @@ import emptyResponsePostModelCall from "./empty-response/hooks/post-model-call.j
 import emptyResponseStop from "./empty-response/hooks/stop.js";
 import { resetEmptyResponseNudgeStoreForTests } from "./empty-response/nudge-state-store.js";
 import emptyResponsePkg from "./empty-response/package.json" with { type: "json" };
+import explorationDriftPostToolUse, {
+  resetExplorationDriftStateForTests,
+} from "./exploration-drift/hooks/post-tool-use.js";
+import explorationDriftPkg from "./exploration-drift/package.json" with { type: "json" };
 import historyRepairPostModelCall from "./history-repair/hooks/post-model-call.js";
 import historyRepairStop from "./history-repair/hooks/stop.js";
 import historyRepairUserPromptSubmit from "./history-repair/hooks/user-prompt-submit.js";
@@ -194,6 +198,25 @@ export const defaultToolErrorPlugin: Plugin = {
   },
 };
 
+/**
+ * `exploration-drift` — a `post-tool-use` hook that detects exploration
+ * drift — a long unbroken run of exploration tool calls (bash, file_read,
+ * file_list) with no user-facing text, or (on loop-prone models such as Kimi
+ * K2.6 and MiniMax M3) the model re-issuing a byte-identical exploration call — and nudges
+ * the model via `additionalContext` to summarize progress for the user and
+ * delegate the remaining investigation to an `investigator` subagent rather
+ * than continuing inline.
+ */
+export const defaultExplorationDriftPlugin: Plugin = {
+  manifest: {
+    name: explorationDriftPkg.name,
+    version: explorationDriftPkg.version,
+  },
+  hooks: {
+    "post-tool-use": explorationDriftPostToolUse,
+  },
+};
+
 /**
  * `tool-result-truncate` — a `post-tool-use` hook that tail-drops an oversized
  * tool result down to a character budget derived from the model's context
@@ -221,6 +244,7 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
+    defaultExplorationDriftPlugin,
     defaultHistoryRepairPlugin,
     defaultImageRecoveryPlugin,
     defaultCompactionPlugin,
@@ -268,5 +292,6 @@ export function resetPluginRegistryAndRegisterDefaults(): void {
   resetEmptyResponseNudgeStoreForTests();
   resetRepairStateStoreForTests();
   resetImageRecoveryStoreForTests();
+  resetExplorationDriftStateForTests();
   registerDefaultPlugins();
 }

package/src/plugins/defaults/memory-retrieval/injectors.ts

@@ -15,6 +15,7 @@
  * | `disk-pressure-warning`  | 5     | prepend-user-tail       |
  * | `workspace-context`      | 10    | prepend-user-tail       |
  * | `unified-turn-context`   | 20    | prepend-user-tail       |
+ * | `config-quarantine-notice` | 25  | prepend-user-tail       |
  * | `pkb-context`            | 30    | after-memory-prefix     |
  * | `pkb-reminder`           | 35    | after-memory-prefix     |
  * | `memory-v2-static`       | 38    | after-memory-prefix     |
@@ -43,6 +44,7 @@
  * through the registry.
  */
 
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { getConfig } from "../../../config/loader.js";
@@ -65,7 +67,10 @@ import { getPkbRoot, PKB_WORKSPACE_SCOPE } from "../../../memory/pkb/types.js";
 import { readMemoryV2StaticContent } from "../../../memory/v2/static-context.js";
 import type { Message } from "../../../providers/types.js";
 import { getLogger } from "../../../util/logger.js";
-import { getSandboxWorkingDir } from "../../../util/platform.js";
+import {
+  getConfigQuarantineNoticePath,
+  getSandboxWorkingDir,
+} from "../../../util/platform.js";
 import {
   type InjectionBlock,
   type Injector,
@@ -99,6 +104,7 @@ export const DEFAULT_INJECTOR_ORDER = {
   workspaceContext: 10,
   backgroundTurn: 15,
   unifiedTurnContext: 20,
+  configQuarantineNotice: 25,
   pkbContext: 30,
   pkbReminder: 35,
   memoryV2Static: 38,
@@ -277,6 +283,114 @@ const unifiedTurnContextInjector: Injector = {
   },
 };
 
+/**
+ * Maximum age of a config-quarantine notice before it is considered stale.
+ * After this window the sentinel is deleted and nothing is injected — the
+ * event is no longer actionable context for the agent.
+ */
+const CONFIG_QUARANTINE_NOTICE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Shape of the config-quarantine notice sentinel written by the config loader. */
+interface ConfigQuarantineNotice {
+  quarantinedAt: string;
+  quarantinePath: string;
+  originalPath: string;
+}
+
+/**
+ * Read and validate the config-quarantine notice sentinel. Returns the parsed
+ * notice when the file exists and carries the expected string fields, otherwise
+ * `null`. Best-effort: any read/parse error is swallowed and treated as absent.
+ */
+function readConfigQuarantineNotice(): ConfigQuarantineNotice | null {
+  const noticePath = getConfigQuarantineNoticePath();
+  if (!existsSync(noticePath)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(noticePath, "utf-8"));
+    if (parsed == null || typeof parsed !== "object") return null;
+    const { quarantinedAt, quarantinePath, originalPath } = parsed as Record<
+      string,
+      unknown
+    >;
+    if (
+      typeof quarantinedAt !== "string" ||
+      typeof quarantinePath !== "string" ||
+      typeof originalPath !== "string"
+    ) {
+      return null;
+    }
+    return { quarantinedAt, quarantinePath, originalPath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `config-quarantine-notice` injector — order 25, prepend-user-tail.
+ *
+ * Surfaces a recent config-quarantine event to the agent. The config loader
+ * writes a JSON sentinel ({@link getConfigQuarantineNoticePath}) when it
+ * quarantines a corrupt `config.json` and falls back to defaults. This injector
+ * reads that sentinel and, when it is younger than
+ * {@link CONFIG_QUARANTINE_NOTICE_MAX_AGE_MS}, injects a short block telling the
+ * agent the user's settings were reset and where the original is preserved, so
+ * it can explain the change if the user asks about missing settings/API keys —
+ * or mention it proactively when relevant. A stale sentinel is deleted and
+ * nothing is injected.
+ *
+ * Active in both `full` and `minimal` mode — a settings reset is grounding the
+ * agent should not lose to injection downgrade. The block is non-persisted
+ * (re-evaluated every turn) so the notice naturally stops appearing once the
+ * sentinel ages out or is removed.
+ *
+ * Guardian-only: turns driven by non-guardian actors (trusted contacts,
+ * unknown channel senders) must not see workspace file paths or be told the
+ * guardian's settings were reset — the notice is only actionable in guardian
+ * conversations.
+ */
+const configQuarantineNoticeInjector: Injector = {
+  name: "config-quarantine-notice",
+  order: DEFAULT_INJECTOR_ORDER.configQuarantineNotice,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    if (ctx.trust.trustClass !== "guardian") return null;
+
+    const notice = readConfigQuarantineNotice();
+    if (!notice) return null;
+
+    const quarantinedAtMs = Date.parse(notice.quarantinedAt);
+    const ageMs = Number.isNaN(quarantinedAtMs)
+      ? Number.POSITIVE_INFINITY
+      : Date.now() - quarantinedAtMs;
+    if (ageMs > CONFIG_QUARANTINE_NOTICE_MAX_AGE_MS) {
+      try {
+        rmSync(getConfigQuarantineNoticePath(), { force: true });
+      } catch {
+        // Best-effort cleanup — a failed delete just means we re-check (and
+        // re-attempt deletion) next turn.
+      }
+      return null;
+    }
+
+    const text =
+      `<config_reset_notice>\n` +
+      `The user's config.json was unreadable and was reset to defaults at ` +
+      `${notice.quarantinedAt}. The original file was preserved at ` +
+      `${notice.quarantinePath}. Any custom settings the user had (API keys, ` +
+      `model choices, voice preferences) are still in that file but are not ` +
+      `currently active.\n\n` +
+      `If the user asks why a setting, API key, or preference is missing or ` +
+      `changed, explain this reset and point them at the preserved file to ` +
+      `recover their settings. Otherwise mention it proactively only when it ` +
+      `is clearly relevant — do not interrupt unrelated work.\n` +
+      `</config_reset_notice>`;
+    return {
+      id: "config-quarantine-notice",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
 /**
  * `pkb-context` injector — order 30, after-memory-prefix.
  *
@@ -389,9 +503,17 @@ function readGatedNowScratchpad(trust: TrustContext): string | null {
  * otherwise `null`. {@link readMemoryV2StaticContent} self-gates on the v2
  * flag + config, so the `memory-v2-static` injector owns its input rather than
  * having it threaded in from the agent loop.
+ *
+ * `excludeBuffer` is forwarded for consolidation turns, whose contract is the
+ * buffer FILE itself — see {@link readMemoryV2StaticContent}.
  */
-function readGatedMemoryV2Static(trust: TrustContext): string | null {
-  return isPersonalMemoryAllowed(trust) ? readMemoryV2StaticContent() : null;
+function readGatedMemoryV2Static(
+  trust: TrustContext,
+  options: { excludeBuffer?: boolean } = {},
+): string | null {
+  return isPersonalMemoryAllowed(trust)
+    ? readMemoryV2StaticContent(options)
+    : null;
 }
 
 /**
@@ -629,7 +751,12 @@ const memoryV2StaticInjector: Injector = {
   ): Promise<InjectionBlock | null> {
     const mode = ctx.mode ?? "full";
     if (mode !== "full") return null;
-    const content = readGatedMemoryV2Static(ctx.trust);
+    // The consolidation agent reads and rewrites memory/buffer.md through
+    // file tools; injecting the buffer section here would duplicate the
+    // entire backlog into its context (and go stale as it edits the file).
+    const content = readGatedMemoryV2Static(ctx.trust, {
+      excludeBuffer: ctx.callSite === "memoryV2Consolidation",
+    });
     if (!content) return null;
     if (hasInjectedUserTextBlock(runMessages, MEMORY_V2_STATIC_BLOCK_MATCHERS))
       return null;
@@ -921,6 +1048,7 @@ export const defaultInjectors: Injector[] = [
   workspaceContextInjector,
   backgroundTurnInjector,
   unifiedTurnContextInjector,
+  configQuarantineNoticeInjector,
   pkbContextInjector,
   pkbReminderInjector,
   memoryV2StaticInjector,

package/src/plugins/defaults/memory-v3-shadow/__tests__/card.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for `card.ts` — the compact card renderer. Focused on the annotation
+ * line: it must sit directly under the header (the always-rendered card
+ * surface) and leave the card untouched when absent.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { renderCard } from "../card.js";
+
+const PAGE = `---
+title: Page A
+---
+
+Lead paragraph for page a.
+
+## Alpha
+
+Body text.
+`;
+
+describe("renderCard — annotation line", () => {
+  test("renders the annotation directly under the header, before the head", () => {
+    const card = renderCard(
+      "page-a",
+      PAGE,
+      "[lane: fresh · updated 2026-06-10 14:23 UTC]",
+    );
+    expect(
+      card.startsWith(
+        "# memory/concepts/page-a.md\n[lane: fresh · updated 2026-06-10 14:23 UTC]\nLead paragraph for page a.",
+      ),
+    ).toBe(true);
+    expect(card).toContain("[sections: §Alpha]");
+  });
+
+  test("an absent or empty annotation leaves the card unchanged", () => {
+    const bare = renderCard("page-a", PAGE);
+    expect(renderCard("page-a", PAGE, "")).toBe(bare);
+    expect(bare).not.toContain("[lane:");
+    expect(
+      bare.startsWith(
+        "# memory/concepts/page-a.md\nLead paragraph for page a.",
+      ),
+    ).toBe(true);
+  });
+
+  test("renders a `current:` frontmatter line first, before the lane annotation", () => {
+    const page = `---
+title: Page A
+current: "bridge check owed before thursday's dry-run (as of jun 10)"
+---
+
+Lead paragraph for page a.
+`;
+    const card = renderCard("page-a", page, "[lane: fresh]");
+    expect(
+      card.startsWith(
+        "# memory/concepts/page-a.md\n[current: bridge check owed before thursday's dry-run (as of jun 10)]\n[lane: fresh]\nLead paragraph for page a.",
+      ),
+    ).toBe(true);
+  });
+
+  test("collapses whitespace and caps a runaway `current:` value", () => {
+    const long = `a  line  with   breaks ${"x".repeat(400)}`;
+    const card = renderCard(
+      "page-a",
+      `---\ncurrent: "${long}"\n---\n\nLead.\n`,
+    );
+    const line = card.split("\n")[1]!;
+    expect(line.startsWith("[current: a line with breaks x")).toBe(true);
+    expect(line.endsWith("…]")).toBe(true);
+    expect(line.length).toBeLessThan(300);
+  });
+
+  test("the `status:` draft marker does NOT render as a card line", () => {
+    const card = renderCard("page-a", `---\nstatus: cc-draft\n---\n\nLead.\n`);
+    expect(card).not.toContain("cc-draft");
+    expect(card).not.toContain("[current:");
+  });
+
+  test("annotates a page with no head section without a dangling blank line", () => {
+    const card = renderCard(
+      "page-b",
+      "## Only Section\n\nBody.",
+      "[lane: core]",
+    );
+    expect(card.startsWith("# memory/concepts/page-b.md\n[lane: core]")).toBe(
+      true,
+    );
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/__tests__/carry-integration.test.ts

@@ -255,6 +255,7 @@ async function scriptedObserveTurn(conversationId: string, turnIndex: number) {
       edgeGraph: lanes.edgeGraph,
       coreSlugs: lanes.coreSlugs,
       hotSlugs: lanes.hotSlugs,
+      freshSlugs: [],
       prefixCards: lanes.prefixCards,
     },
   );
@@ -487,7 +488,7 @@ function candidateSlugs(messages: Message[]): Slug[] {
       );
       if (finder) {
         for (const line of finder[1].split("\n")) {
-          const m = /^\[(\d+)\] (\S+)(?: — |$)/.exec(line);
+          const m = /^\[(\d+)\] (?:\([^)]*\) )?(\S+)(?: — |$)/.exec(line);
           if (m) entries.push({ id: Number(m[1]), slug: m[2]! });
         }
       }