@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/plugins/defaults/memory-v3-shadow/shadow-plugin.ts

@@ -15,9 +15,10 @@
  *   - both OFF: orchestration is skipped entirely.
  *
  * On each turn (either flag on):
- *   1. Lazy-init the v3 lanes ONCE across the whole process (leaf tree, core
- *      set, BM25 needle, carry-forward working set), memoizing the init
- *      promise so concurrent first turns share a single build.
+ *   1. Lazy-init the v3 lanes ONCE across the whole process (section index,
+ *      section-grain BM25 needle, dense lane config, link-graph edge graph,
+ *      carry-forward working set), memoizing the init promise so concurrent
+ *      first turns share a single build.
  *   2. Build a {@link MemoryRoutingTurn} from the conversation's recent messages.
  *   3. Run {@link orchestrate} and record its selection set to
  *      `memory_v3_selections` with a best-effort lane attribution.
@@ -37,23 +38,25 @@ import { getMessages } from "../../../memory/conversation-crud.js";
 import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
 import { stringifyMessageContent } from "../../../memory/message-content.js";
 import { getPageIndex } from "../../../memory/v2/page-index.js";
+import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
 import { getLogger } from "../../../util/logger.js";
 import {
   getWorkspaceDir,
   getWorkspacePromptPath,
 } from "../../../util/platform.js";
 import { stripCommentLines } from "../../../util/strip-comment-lines.js";
-import { injectCapabilitiesLeaf, isCapabilitySlug } from "./capabilities.js";
-import { loadCore } from "./core.js";
-import type { NeedleIndex } from "./needle.js";
-import { buildNeedleIndex } from "./needle.js";
+import { capabilityOrDiskBody } from "./capabilities.js";
+import type { EdgeGraph } from "./edge.js";
+import { buildEdgeGraph } from "./edge.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
-import { coreSlugs, loadLeafTree, resolveDataDir } from "./tree.js";
+import { ensureSectionCollection } from "./section-dense-store.js";
+import type { SectionNeedle } from "./section-needle.js";
+import { buildSectionNeedle } from "./section-needle.js";
+import { buildSectionIndex } from "./sections.js";
 import {
-  type LeafPath,
-  type LeafTree,
   type MemoryRoutingTurn,
+  type SectionIndex,
   type SelectionSource,
   type Slug,
 } from "./types.js";
@@ -74,26 +77,29 @@ const RECENT_CONTEXT_MESSAGES = 6;
  * carry-forward lane.
  */
 export interface ShadowLanes {
-  tree: LeafTree;
-  core: Set<LeafPath>;
-  needle: NeedleIndex;
+  sectionIndex: SectionIndex;
+  needle: SectionNeedle;
+  /** Config the dense lane needs to embed the query + search the section
+   *  collection. */
+  denseConfig: AssistantConfig;
+  edgeGraph: EdgeGraph;
   workingSet: WorkingSet;
 }
 
 /**
  * Memoized init promise. Caching the PROMISE (not the resolved value) means
  * concurrent first turns all await the same build instead of racing several
- * `loadLeafTree`/`buildNeedleIndex` passes.
+ * section-index / needle / edge-graph passes.
  */
 let lanesPromise: Promise<ShadowLanes> | null = null;
 
 /**
  * Drop the memoized lanes so the NEXT `getLanes` rebuilds them from scratch
- * (fresh topic-tree load + fresh needle index). The rebuild is lazy — this only
- * clears the cache, so the cost is paid by the next caller, and concurrent
- * first-callers after the invalidation still share a single build via the
- * re-memoized promise. Call this whenever the underlying tree or needle sources
- * change on disk.
+ * (fresh section index + fresh needle + fresh edge graph). The rebuild is lazy
+ * — this only clears the cache, so the cost is paid by the next caller, and
+ * concurrent first-callers after the invalidation still share a single build via
+ * the re-memoized promise. Call this whenever the underlying pages change on
+ * disk.
  */
 export function invalidateLanes(): void {
   lanesPromise = null;
@@ -104,48 +110,78 @@ export function resetShadowLanesForTests(): void {
   invalidateLanes();
 }
 
-/**
- * Pull a page's summary from the existing v2 page index. Missing summaries
- * (and any read failure) degrade to "" — the needle and L2 selector treat an
- * empty summary as "no signal" rather than throwing.
- */
-async function pageSummary(slug: Slug): Promise<string> {
-  try {
-    const index = await getPageIndex(getWorkspaceDir());
-    return index.bySlug.get(slug)?.summary ?? "";
-  } catch {
-    return "";
-  }
-}
-
 async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
-  const dataDir = resolveDataDir();
   const pageIndex = await getPageIndex(getWorkspaceDir());
-  const pageLeaves = new Map<Slug, LeafPath[]>();
-  for (const entry of pageIndex.entries) {
-    pageLeaves.set(entry.slug, entry.leaves);
+  const slugs = pageIndex.entries.map((entry) => entry.slug);
+
+  // Read each page ONCE and feed BOTH forms downstream: the frontmatter-stripped
+  // body to the section index (lexical/dense matching), and the raw page
+  // (frontmatter + body) to the edge graph (so the `links:` frontmatter is
+  // available). A per-slug cache holds the parsed page so the second consumer
+  // reuses the first read.
+  const pageCache = new Map<Slug, { body: string; raw: string } | null>();
+  async function loadPage(
+    slug: Slug,
+  ): Promise<{ body: string; raw: string } | null> {
+    if (pageCache.has(slug)) return pageCache.get(slug)!;
+    let loaded: { body: string; raw: string } | null = null;
+    try {
+      const page = await readPage(getWorkspaceDir(), slug);
+      if (page) loaded = { body: page.body, raw: renderPageContent(page) };
+    } catch {
+      loaded = null;
+    }
+    pageCache.set(slug, loaded);
+    return loaded;
   }
-  const tree = await loadLeafTree(dataDir, pageLeaves);
-  const core = await loadCore(dataDir);
+  // Synthetic capability slugs (skills / CLI commands) have no on-disk page, so
+  // they contribute their rendered capability content to the section index —
+  // exactly the content `page-content.ts` injects for them. This puts them in
+  // the section index, so the needle lane (and, once a backfill embeds them, the
+  // dense lane) ranks them by relevance like any other page, instead of being
+  // blindly added to the select pool every turn. Real pages read their body
+  // through the cached `loadPage`.
+  const pageBody = async (slug: Slug): Promise<string> =>
+    capabilityOrDiskBody(slug, async (s) => (await loadPage(s))?.body ?? "");
+  const pageRaw = async (slug: Slug): Promise<string> => {
+    const loaded = await loadPage(slug);
+    if (!loaded) throw new Error(`page not found: ${slug}`);
+    return loaded.raw;
+  };
 
-  // Always-on synthetic capabilities leaf: skill + CLI-command rows the page
-  // index already carries (with summaries). Injecting them as leaf members puts
-  // them in the needle corpus (`tree.byPage`) and, via `core`, makes L1 always
-  // open the leaf so L2 selects the relevant subset each turn — matching v2's
-  // "always in the pool, router-selected" capability surfacing. Done before
-  // `buildNeedleIndex` so the synthetic members are indexed.
-  const capabilitySlugs = pageIndex.entries
-    .map((entry) => entry.slug)
-    .filter(isCapabilitySlug);
-  injectCapabilitiesLeaf(tree, core, capabilitySlugs);
+  const sectionIndex = await buildSectionIndex(slugs, pageBody);
+  const needle = buildSectionNeedle(sectionIndex);
+  const edgeGraph = await buildEdgeGraph(pageIndex.entries, pageRaw, {
+    hubDegree: config.memory.v3.edge.hubDegree,
+  });
+  // Ensuring the dense collection is best-effort: the needle + edge lanes and
+  // carry-forward are in-memory and independent of Qdrant, so a Qdrant outage
+  // must NOT reject lane init (which would return `null` from observeTurn and
+  // disable ALL of v3, plus poison the memoized lanes until invalidation). On
+  // failure we log and continue with the dense lane degraded — denseLane already
+  // returns no hits on a Qdrant error, and maintain/backfill re-ensure the
+  // collection once Qdrant recovers.
+  try {
+    await ensureSectionCollection(config);
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "memory-v3: section collection ensure failed; continuing with the dense lane degraded",
+    );
+  }
 
-  const needle = await buildNeedleIndex(tree, pageSummary);
   const workingSet = new WorkingSet(
     config.memory.v3.workingSet.maxPages,
     config.memory.v3.workingSet.evictWindow,
   );
 
-  return { tree, core, needle, workingSet };
+  return {
+    sectionIndex,
+    needle,
+    denseConfig: config,
+    edgeGraph,
+    workingSet,
+  };
 }
 
 /** Lazy, memoized accessor for the shadow lanes. */
@@ -180,11 +216,11 @@ function readNowContext(): string | null {
 }
 
 /**
- * Compose the situational signal threaded into L1 routing and L2 selection: the
- * current date plus the live NOW.md scratchpad. The date alone is a weak signal,
- * but together with the scratchpad it lets retrieval surface a leaf the message
- * never names (e.g. an anniversary that falls today). Always returns at least
- * the date line — this mirrors the `c_now`/NOW.md signal the v2 retriever uses.
+ * Compose the situational signal threaded into pool selection: the current date
+ * plus the live NOW.md scratchpad. The date alone is a weak signal, but together
+ * with the scratchpad it lets retrieval surface a page the message never names
+ * (e.g. an anniversary that falls today). Always returns at least the date line
+ * — this mirrors the `c_now`/NOW.md signal the v2 retriever uses.
  */
 function buildSituationalContext(): string {
   const now = readNowContext();
@@ -237,32 +273,24 @@ interface SelectionRow {
 }
 
 /**
- * Map an orchestrate result onto telemetry rows with best-effort lane
+ * Map an orchestrate result onto telemetry rows with precise per-lane source
  * attribution.
  *
- * - A current selection whose page belongs to a core leaf → `"core+l2"`,
- *   otherwise `"l1+l2"`.
+ * - A current selection is tagged with the candgen lane that FIRST surfaced its
+ *   page this turn — `result.laneBySlug` (`"needle"` / `"dense"` / `"edge"`),
+ *   recorded at pool-build time. (`"needle"` is the fallback if a selected slug
+ *   is somehow absent from the lane map, which should not happen since every
+ *   pooled candidate is recorded there.)
  * - A slug in `finalInjection` but NOT re-selected this turn → `"carry-forward"`.
- *
- * Precise needle attribution is a documented follow-up: the needle lane only
- * widens the open set, so a needle-surfaced page that survives L2 selection is
- * indistinguishable here from an L1-routed one. This coarse mapping is
- * acceptable for v0 shadow telemetry.
  */
-function attributeSelections(
-  tree: LeafTree,
-  core: Set<LeafPath>,
-  result: OrchestrateResult,
-): SelectionRow[] {
-  const coreOwnedSlugs = coreSlugs(tree, core);
-
+export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
   const rows: SelectionRow[] = [];
   const seen = new Set<Slug>();
   for (const sel of result.currentSelections) {
     seen.add(sel.slug);
     rows.push({
       slug: sel.slug,
-      source: coreOwnedSlugs.has(sel.slug) ? "core+l2" : "l1+l2",
+      source: result.laneBySlug.get(sel.slug) ?? "needle",
       pinned: sel.pinned ? 1 : 0,
     });
   }
@@ -275,7 +303,7 @@ function attributeSelections(
 }
 
 /** Write the attributed selection rows to `memory_v3_selections`. */
-function writeSelections(
+export function writeSelections(
   conversationId: string,
   turn: number,
   rows: SelectionRow[],
@@ -311,16 +339,21 @@ export async function observeTurn(
 
     const cfg = getConfig();
     const lanes = await getLanes(cfg);
+    const v3 = cfg.memory.v3;
     const result = await orchestrate(turn, {
-      tree: lanes.tree,
-      core: lanes.core,
+      sectionIndex: lanes.sectionIndex,
       needle: lanes.needle,
+      denseConfig: lanes.denseConfig,
+      edgeGraph: lanes.edgeGraph,
       workingSet: lanes.workingSet,
-      pageSummary,
-      l2Concurrency: cfg.memory.v3.l2Concurrency,
+      needleK: v3.needleK,
+      denseK: v3.denseK,
+      edgeSeeds: v3.edge.seedCount,
+      edgePerSeed: v3.edge.perSeed,
+      edgeCap: v3.edge.cap,
     });
 
-    const rows = attributeSelections(lanes.tree, lanes.core, result);
+    const rows = attributeSelections(result);
     writeSelections(conversationId, turnIndex, rows);
     return result;
   } catch (err) {

package/src/plugins/defaults/memory-v3-shadow/types.ts

@@ -1,4 +1,3 @@
-export type LeafPath = string; // dot- or slash-pathed taxonomy node
 export type Slug = string;
 
 /**
@@ -11,27 +10,34 @@ export type Slug = string;
  */
 export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
 
-export interface LeafFrontmatter {
-  path: LeafPath;
-  in_core: boolean;
-  /**
-   * Optional stable identifier for the leaf, independent of its taxonomy path.
-   * Older leaves predate this field and omit it, so it is optional.
-   */
-  id?: string;
+/**
+ * A single section of a page: the lead (text before the first `## heading`,
+ * ordinal 0) or a heading-delimited block. Over-long sections are split into
+ * multiple ordered `Section`s, each with its own consecutive `ordinal`, so each
+ * fits a typical embedding window. `text` is prefixed with a
+ * `${lastSlugSegment} — ${title}` head line for lexical/dense matching.
+ */
+export interface Section {
+  article: Slug;
+  title: string;
+  text: string;
+  ordinal: number;
 }
 
-export interface LeafNode {
-  path: LeafPath;
-  frontmatter: LeafFrontmatter;
-  description: string;
-  members: Slug[];
-  domain: string;
+/**
+ * A flat, deterministic index of every page's sections plus an article→section
+ * lookup. `byArticle` maps each article slug to the indices (into `sections`)
+ * of that article's sections, in order.
+ */
+export interface SectionIndex {
+  sections: Section[];
+  byArticle: Map<Slug, number[]>;
 }
 
-export interface LeafTree {
-  leaves: Map<LeafPath, LeafNode>;
-  byPage: Map<Slug, LeafPath[]>;
+/** A page selected from the candidate pool, with whether the turn centers on it. */
+export interface SelectedPage {
+  slug: Slug;
+  pinned: boolean;
 }
 
 export interface WorkingSetEntry {
@@ -56,4 +62,31 @@ export interface MemoryRoutingTurn {
   situationalContext?: string;
 }
 
-export type SelectionSource = "l1+l2" | "core+l2" | "needle" | "carry-forward";
+/**
+ * Canonical ordered list of the lane sources recorded per selection. The
+ * {@link SelectionSource} type is derived from this so a new lane is added in
+ * exactly one place and the runtime list (used for telemetry roll-ups and
+ * source validation) can never drift from the type.
+ *
+ * The `memory_v3_selections.source` column is free-text, so tightening this set
+ * needs no migration: any historical rows with older labels still read back
+ * fine via the permissive `z.string()` row schema.
+ */
+export const SELECTION_SOURCES = [
+  "needle",
+  "dense",
+  "edge",
+  "carry-forward",
+] as const;
+
+export type SelectionSource = (typeof SELECTION_SOURCES)[number];
+
+/**
+ * The candidate-generation lanes — the strict subset of {@link SelectionSource}
+ * a pooled candidate can be tagged with at pool-build time. (`carry-forward` is
+ * the one source assigned later, by the orchestrator's working-set union, not by
+ * a candgen lane.) Defined as `Exclude<SelectionSource, "carry-forward">` so it
+ * can never drift from {@link SELECTION_SOURCES}: adding a lane there widens this
+ * automatically.
+ */
+export type CandidateLane = Exclude<SelectionSource, "carry-forward">;

package/src/plugins/defaults/memory-v3-shadow/working-set.ts

@@ -42,13 +42,16 @@ export class WorkingSet {
   /**
    * Prune the working set, in order:
    *   1. Core slugs never belong here — drop any entry whose slug is core.
+   *      The section-lane pipeline has no core set, so `coreSlugs` defaults to
+   *      empty (no-op); the tree pipeline passed its core slugs here. Stale and
+   *      cap eviction semantics are identical either way.
    *   2. Pinned entries never evict.
    *   3. Window eviction: drop a non-pinned entry unseen for more than
    *      `evictWindow` turns.
    *   4. Cap eviction: while over `maxPages`, evict the lowest-scoring
    *      non-pinned entry first (ties broken deterministically).
    */
-  evict(currentTurn: number, coreSlugs: Set<Slug>): void {
+  evict(currentTurn: number, coreSlugs: Set<Slug> = new Set()): void {
     // 1. Core slugs are owned by core, not the working set.
     for (const slug of this.entries.keys()) {
       if (coreSlugs.has(slug)) {

package/src/plugins/external-api.ts

@@ -0,0 +1,114 @@
+/**
+ * External plugin runtime — `globalThis.__vellumPluginRuntime` bridge.
+ *
+ * ⚠️ DO NOT DELETE THIS AS "UNUSED". There is intentionally NO in-repo consumer:
+ * the consumers are out-of-repo, user-authored workspace plugins under
+ * `<workspaceDir>/plugins/*`, which a repo-wide reference search cannot see. On
+ * a `bun --compile` daemon (the shipped macOS app) this bridge is the ONLY way
+ * such a plugin can reach the daemon's real `assistantEventHub` /
+ * `getSecureKeyAsync` singletons — an absolute-path `import` re-loads a disjoint
+ * copy (see the module-identity note below). Removing it silently breaks every
+ * event-subscribing workspace plugin on the next app rebuild. This was already
+ * removed once on the false "unused" assumption (PR #33825) and restored here.
+ *
+ * Workspace-local plugins (`<workspaceDir>/plugins/*`) get dynamic-imported by
+ * {@link loadUserPlugins}. They need to call `registerPlugin()` from their
+ * module body and they typically also want to read secrets, subscribe to
+ * runtime events, etc.
+ *
+ * Importing those symbols by absolute path
+ * (`/abs/path/to/assistant/src/plugins/registry.js`) works when the daemon is
+ * running from source — both the daemon and the dynamic-imported plugin
+ * resolve the same on-disk file and share module identity. It DOES NOT work
+ * when the daemon is a `bun --compile` binary: the daemon's modules are baked
+ * into the executable, and any absolute-path import re-loads a fresh disk
+ * copy. `registerPlugin()` then writes into a disjoint registry instance and
+ * the daemon never sees the plugin.
+ *
+ * The fix is to expose a single, stable handle on `globalThis` that plugins
+ * read at module-load time. The daemon's bundled modules attach themselves
+ * here once at startup; plugins consume the same instance regardless of how
+ * the daemon was built.
+ *
+ * Plugins use the bridge like this:
+ *
+ *   const runtime = (globalThis as { __vellumPluginRuntime?: ... })
+ *     .__vellumPluginRuntime;
+ *   if (!runtime || runtime.version !== 1) throw new Error("...");
+ *   const { registerPlugin, assistantEventHub, getSecureKeyAsync } = runtime;
+ *
+ * Type-only imports (`import type { Plugin } from "..."`) remain free to use
+ * absolute paths or workspace-local copies — the TypeScript compiler erases
+ * them and they have no module-identity effect at runtime.
+ *
+ * See `experimental/plugins/README.md` for the full authoring contract and
+ * `assistant/examples/plugins/echo/` for a worked example.
+ */
+
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { registerPlugin } from "./registry.js";
+
+/**
+ * The handle plugins read from `globalThis.__vellumPluginRuntime`.
+ *
+ * `version` is the contract version. Plugins should assert against the
+ * version they were authored against and refuse to register if they see a
+ * different one — bumping it is a breaking change to the plugin surface.
+ *
+ * The field set is intentionally small: the most-commonly-needed symbols
+ * across both static (module-load-time) and dynamic (init-time) plugin
+ * lifecycle. Plugins that need richer runtime state can still receive it
+ * through {@link PluginInitContext} during `init()`.
+ */
+export interface VellumPluginRuntime {
+  readonly version: 1;
+  readonly registerPlugin: typeof registerPlugin;
+  readonly assistantEventHub: typeof assistantEventHub;
+  readonly getSecureKeyAsync: typeof getSecureKeyAsync;
+}
+
+/** Stable globalThis key. Don't rename — plugins reference it by string. */
+const RUNTIME_GLOBAL_KEY = "__vellumPluginRuntime" as const;
+
+interface GlobalWithRuntime {
+  [RUNTIME_GLOBAL_KEY]?: VellumPluginRuntime;
+}
+
+/**
+ * Install the plugin runtime bridge on `globalThis`. Idempotent — repeat
+ * calls are no-ops, so it's safe to invoke from tests that also touch the
+ * lifecycle path.
+ *
+ * Must be called BEFORE {@link loadUserPlugins} runs, otherwise plugins that
+ * touch `globalThis.__vellumPluginRuntime` in their module body will throw.
+ */
+export function installPluginRuntime(): void {
+  const g = globalThis as GlobalWithRuntime;
+  if (g[RUNTIME_GLOBAL_KEY]) return;
+  g[RUNTIME_GLOBAL_KEY] = {
+    version: 1,
+    registerPlugin,
+    assistantEventHub,
+    getSecureKeyAsync,
+  };
+}
+
+/**
+ * Read the installed runtime. Returns `undefined` if {@link installPluginRuntime}
+ * hasn't been called yet — plugins should treat this as a fatal error.
+ *
+ * Exposed mainly for tests and for the rare in-process consumer that wants
+ * to read the bridge from the same module graph that installed it.
+ */
+export function getPluginRuntime(): VellumPluginRuntime | undefined {
+  return (globalThis as GlobalWithRuntime)[RUNTIME_GLOBAL_KEY];
+}
+
+/**
+ * Tear down the runtime handle. Test-only — production code never uninstalls
+ * because the runtime lifetime is the daemon lifetime.
+ */
+export function uninstallPluginRuntimeForTests(): void {
+  delete (globalThis as GlobalWithRuntime)[RUNTIME_GLOBAL_KEY];
+}

package/src/prompts/system-prompt.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { getIsContainerized } from "../config/env-registry.js";
 import type { ChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
 import type { TrustContext } from "../daemon/trust-context.js";
+import { markActivationSession } from "../memory/activation-session-store.js";
+import { ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE } from "../telemetry/activation-funnel.js";
 import type { OnboardingContext } from "../types/onboarding-context.js";
 import { resolveBundledDir } from "../util/bundled-asset.js";
 import { getLogger } from "../util/logger.js";
@@ -206,7 +208,7 @@ export function ensurePromptFiles(): void {
  * overwrite the workspace file with the specified variant.  No-op when
  * BOOTSTRAP.md has been deleted, modified, or the template file is missing.
  */
-export function maybeReseedBootstrap(templateFileName: string): void {
+export function maybeReseedBootstrap(templateFileName: string): boolean {
   // Path traversal guard: reject filenames containing directory separators or
   // parent-directory references, and require a `.md` extension.
   if (
@@ -218,11 +220,11 @@ export function maybeReseedBootstrap(templateFileName: string): void {
       { templateFileName },
       "Rejected bootstrap template filename: invalid characters or extension",
     );
-    return;
+    return false;
   }
 
   const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
-  if (!existsSync(bootstrapPath)) return;
+  if (!existsSync(bootstrapPath)) return false;
 
   const currentContent = readPromptFile(bootstrapPath);
   // Compare against the GENERIC "BOOTSTRAP.md" template, not the specified
@@ -230,7 +232,7 @@ export function maybeReseedBootstrap(templateFileName: string): void {
   // template, so this guard returns false on subsequent calls — making the
   // swap idempotent.  Do NOT change the comparison target to the provided
   // template filename; that would re-swap on every prompt build.
-  if (!isTemplateContent(currentContent, "BOOTSTRAP.md")) return;
+  if (!isTemplateContent(currentContent, "BOOTSTRAP.md")) return false;
 
   const templatesDir = resolveBundledDir(
     import.meta.dirname ?? __dirname,
@@ -243,7 +245,7 @@ export function maybeReseedBootstrap(templateFileName: string): void {
       { templateFileName },
       "Bootstrap template not found, keeping generic BOOTSTRAP.md",
     );
-    return;
+    return false;
   }
 
   try {
@@ -253,11 +255,51 @@ export function maybeReseedBootstrap(templateFileName: string): void {
       { templateFileName },
       "Replaced generic BOOTSTRAP.md with specified template",
     );
+    return true;
   } catch (err) {
     log.warn(
       { err, templateFileName },
       "Failed to reseed BOOTSTRAP.md with template",
     );
+    return false;
+  }
+}
+
+/**
+ * Reseed BOOTSTRAP.md from the requested onboarding template (one-shot,
+ * idempotent) and, when that template is the activation rail AND the rail is
+ * now the active bootstrap, mark the conversation as an activation session.
+ *
+ * Marking happens here — at the single point where the bootstrap selection is
+ * known — so it lands BEFORE the agent loop resolves tools and BEFORE the model
+ * can call the emit tool on the first activation-rail turn. (`resolveTools`
+ * runs before `resolveSystemPrompt` in the loop, so the system-prompt build is
+ * too late to be the *only* marking site.) The marker write is best-effort and
+ * idempotent (`markActivationSession` swallows errors and dedups on the PK), so
+ * calling this from both `setOnboardingContext` and `buildSystemPrompt` is safe.
+ *
+ * The activation mark is gated on the rail actually being the active bootstrap —
+ * either this call just installed it, OR BOOTSTRAP.md already holds the
+ * activation-rail template. When the reseed no-ops because BOOTSTRAP.md is
+ * missing or customized to something else, the rail is NOT active, so we must
+ * NOT mark (otherwise non-rail conversations would pollute activation
+ * telemetry).
+ */
+export function applyBootstrapTemplate(
+  bootstrapTemplate: string,
+  conversationId?: string,
+): void {
+  const installedActivationRail = maybeReseedBootstrap(bootstrapTemplate);
+  if (
+    bootstrapTemplate === ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE &&
+    conversationId &&
+    (installedActivationRail ||
+      isTemplateContent(
+        readPromptFile(getWorkspacePromptPath("BOOTSTRAP.md")),
+        ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE,
+      ))
+  ) {
+    markActivationSession(conversationId);
   }
 }
 
@@ -268,6 +310,13 @@ export interface BuildSystemPromptOptions {
   trustContext?: TrustContext;
   channelCapabilities?: ChannelCapabilities;
   onboardingContext?: OnboardingContext;
+  /**
+   * Conversation this prompt is being built for. Optional because several
+   * callers build a prompt outside a conversation (e.g. home greeting,
+   * suggested prompts). When present and the activation-rail bootstrap template
+   * is selected, the conversation is marked as an activation session.
+   */
+  conversationId?: string;
 }
 
 /**
@@ -278,11 +327,13 @@ export interface BuildSystemPromptOptions {
  * file-backed bodies, and runtime-computed transforms.
  */
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
-  // One-shot bootstrap swap: if the onboarding context specifies a bootstrap
-  // template and BOOTSTRAP.md is still the generic template, replace it with
-  // the specified variant before the prompt reads the file.
-  if (options?.onboardingContext?.bootstrapTemplate) {
-    maybeReseedBootstrap(options.onboardingContext.bootstrapTemplate);
+  // One-shot bootstrap reseed + activation-rail marking. The marking also runs
+  // earlier, at `setOnboardingContext`, so the activation session is recorded
+  // before the agent loop resolves tools on the first turn; this call is a
+  // harmless idempotent backstop for prompt builds outside that path.
+  const bootstrapTemplate = options?.onboardingContext?.bootstrapTemplate;
+  if (bootstrapTemplate) {
+    applyBootstrapTemplate(bootstrapTemplate, options?.conversationId);
   }
 
   // Slugs used by the persona sections (`10-user-persona`,