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

package/src/memory/onboarding-events-store.ts

@@ -2,6 +2,12 @@ import { and, asc, eq, gt, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getConfig } from "../config/loader.js";
+import {
+  ACTIVATION_AB_VARIANT,
+  ACTIVATION_FUNNEL_VERSION,
+  activationStepIndex,
+  type ActivationStepName,
+} from "../telemetry/activation-funnel.js";
 import { getDb } from "./db-connection.js";
 import { onboardingEvents } from "./schema.js";
 
@@ -16,6 +22,11 @@ export interface OnboardingEvent {
   googleScopesJson: string | null;
   priorAssistantsJson: string | null;
   abVariant: string | null;
+  sessionId: string | null;
+  stepName: string | null;
+  stepIndex: number | null;
+  completedAt: string | null;
+  funnelVersion: string | null;
 }
 
 export interface RecordOnboardingEventParams {
@@ -27,6 +38,17 @@ export interface RecordOnboardingEventParams {
   googleScopes?: string[];
   priorAssistants?: string[];
   abVariant?: string;
+  sessionId?: string | null;
+  stepName?: string | null;
+  stepIndex?: number | null;
+  completedAt?: string | null;
+  funnelVersion?: string | null;
+}
+
+/** Insert a fully-built event row. Shared by all record* entry points. */
+function insertOnboardingEvent(event: OnboardingEvent): OnboardingEvent {
+  getDb().insert(onboardingEvents).values(event).run();
+  return event;
 }
 
 /**
@@ -37,8 +59,7 @@ export function recordOnboardingEvent(
   params: RecordOnboardingEventParams,
 ): OnboardingEvent | null {
   if (!getConfig().collectUsageData) return null;
-  const db = getDb();
-  const event: OnboardingEvent = {
+  return insertOnboardingEvent({
     id: uuid(),
     createdAt: Date.now(),
     screen: params.screen,
@@ -53,22 +74,44 @@ export function recordOnboardingEvent(
       ? JSON.stringify(params.priorAssistants)
       : null,
     abVariant: params.abVariant ?? null,
-  };
-  db.insert(onboardingEvents)
-    .values({
-      id: event.id,
-      createdAt: event.createdAt,
-      screen: event.screen,
-      toolsJson: event.toolsJson,
-      tasksJson: event.tasksJson,
-      tone: event.tone,
-      googleConnected: event.googleConnected,
-      googleScopesJson: event.googleScopesJson,
-      priorAssistantsJson: event.priorAssistantsJson,
-      abVariant: event.abVariant,
-    })
-    .run();
-  return event;
+    sessionId: params.sessionId ?? null,
+    stepName: params.stepName ?? null,
+    stepIndex: params.stepIndex ?? null,
+    completedAt: params.completedAt ?? null,
+    funnelVersion: params.funnelVersion ?? null,
+  });
+}
+
+/**
+ * Record an activation-funnel milestone event. Reuses the onboarding telemetry
+ * substrate (`screen` carries the step name to satisfy the NOT NULL column).
+ * Returns null when usage data collection is disabled.
+ */
+export function recordActivationEvent(params: {
+  stepName: ActivationStepName;
+  sessionId: string;
+  userId?: string | null;
+  abVariant?: string;
+}): OnboardingEvent | null {
+  if (!getConfig().collectUsageData) return null;
+  const createdAt = Date.now();
+  return insertOnboardingEvent({
+    id: uuid(),
+    createdAt,
+    screen: params.stepName,
+    toolsJson: null,
+    tasksJson: null,
+    tone: null,
+    googleConnected: null,
+    googleScopesJson: null,
+    priorAssistantsJson: null,
+    abVariant: params.abVariant ?? ACTIVATION_AB_VARIANT,
+    sessionId: params.sessionId,
+    stepName: params.stepName,
+    stepIndex: activationStepIndex(params.stepName),
+    completedAt: new Date(createdAt).toISOString(),
+    funnelVersion: ACTIVATION_FUNNEL_VERSION,
+  });
 }
 
 /**
@@ -93,6 +136,11 @@ export function queryUnreportedOnboardingEvents(
       googleScopesJson: onboardingEvents.googleScopesJson,
       priorAssistantsJson: onboardingEvents.priorAssistantsJson,
       abVariant: onboardingEvents.abVariant,
+      sessionId: onboardingEvents.sessionId,
+      stepName: onboardingEvents.stepName,
+      stepIndex: onboardingEvents.stepIndex,
+      completedAt: onboardingEvents.completedAt,
+      funnelVersion: onboardingEvents.funnelVersion,
     })
     .from(onboardingEvents)
     .where(

package/src/memory/schema/infrastructure.ts

@@ -277,6 +277,11 @@ export const onboardingEvents = sqliteTable("onboarding_events", {
   googleScopesJson: text("google_scopes_json"),
   priorAssistantsJson: text("prior_assistants_json"),
   abVariant: text("ab_variant"),
+  sessionId: text("session_id"),
+  stepName: text("step_name"),
+  stepIndex: integer("step_index"),
+  completedAt: text("completed_at"),
+  funnelVersion: text("funnel_version"),
 });
 
 // Aggregated legacy-loopback auth-fallback counts forwarded by the gateway.
@@ -294,6 +299,14 @@ export const authFallbackEvents = sqliteTable("auth_fallback_events", {
   windowEnd: integer("window_end").notNull(),
 });
 
+// One row per conversation started on the activation-rail bootstrap template.
+// Lets the activation funnel telemetry scope its events to activation
+// conversations without inspecting the bootstrap template at emit time.
+export const activationSessions = sqliteTable("activation_sessions", {
+  conversationId: text("conversation_id").primaryKey(),
+  createdAt: integer("created_at").notNull(),
+});
+
 export const traceEvents = sqliteTable(
   "trace_events",
   {

package/src/messaging/providers/telegram-bot/api.ts

@@ -8,7 +8,8 @@
  */
 
 import { credentialKey } from "../../../security/credential-key.js";
-import { getSecureKeyAsync } from "../../../security/secure-keys.js";
+import { getSecureKeyResultAsync } from "../../../security/secure-keys.js";
+import { BackendUnavailableError, ConfigError } from "../../../util/errors.js";
 import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("telegram-api");
@@ -197,13 +198,21 @@ async function retryableFetch<T>(
 // ---------------------------------------------------------------------------
 
 async function resolveBotToken(): Promise<string> {
-  const botToken = await getSecureKeyAsync(
+  const result = await getSecureKeyResultAsync(
     credentialKey("telegram", "bot_token"),
   );
-  if (!botToken) {
-    throw new Error("Telegram bot token not configured");
+  if (result.value) {
+    return result.value;
   }
-  return botToken;
+  // Distinguish a transient credential-store outage from a token that was
+  // genuinely never set. Both surface as an absent value, but only the
+  // latter is an operator misconfiguration; the former is retryable
+  // infrastructure unavailability that callers should not treat as
+  // "not configured".
+  if (result.unreachable) {
+    throw new BackendUnavailableError("Telegram credential store unreachable");
+  }
+  throw new ConfigError("Telegram bot token not configured");
 }
 
 // ---------------------------------------------------------------------------

package/src/notifications/adapters/telegram.ts

@@ -10,6 +10,7 @@
 
 import { sendTelegramReply } from "../../messaging/providers/telegram-bot/send.js";
 import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
+import { ConfigError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
 import { isConversationSeedSane } from "../conversation-seed-composer.js";
 import { buildAccessRequestContractText, nonEmpty } from "../copy-composer.js";
@@ -136,7 +137,12 @@ export class TelegramAdapter implements ChannelAdapter {
       return { success: true };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      log.error(
+      // A missing bot token means the operator simply hasn't configured
+      // Telegram; it is not a code fault, so log it at warn to keep it out
+      // of Sentry. Genuine and transient failures (e.g. an unreachable
+      // credential store) stay at error so they remain visible.
+      const logFn = err instanceof ConfigError ? log.warn : log.error;
+      logFn(
         { err, sourceEventName: payload.sourceEventName, chatId },
         "Failed to deliver Telegram notification",
       );

package/src/plugin-api/constants.ts

@@ -26,8 +26,8 @@ export const HOOKS = {
   POST_TOOL_USE: "post-tool-use",
   /** Fires when the model yields a response with no tool calls — the run's stop boundary. Decides whether to stop or continue with a follow-up turn. */
   STOP: "stop",
-  /** Fires for each finalized assistant message, before it is persisted/streamed-final. A hook may transform the message content. */
-  ASSISTANT_MESSAGE: "assistant-message",
+  /** Fires for each finalized assistant message, once per model call, before it is persisted/streamed-final. A hook may transform the message content. */
+  POST_MODEL_CALL: "post-model-call",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -30,7 +30,7 @@
  *   per tool result before it joins the provider-bound history
  * - {@link StopContext} — passed to `stop` hook, fired when the model yields
  *   a response with no tool calls
- * - {@link AssistantMessageContext} — passed to `assistant-message` hook,
+ * - {@link PostModelCallContext} — passed to `post-model-call` hook,
  *   fired for each finalized assistant message to transform its content
  * - {@link PluginHookFn} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
@@ -43,11 +43,11 @@
 export type { HookName } from "./constants.js";
 export { HOOKS } from "./constants.js";
 export type {
-  AssistantMessageContext,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostModelCallContext,
   PostToolUseContext,
   PreModelCallContext,
   StopContext,

package/src/plugin-api/types.ts

@@ -55,7 +55,7 @@ export interface PluginLogger {
  *   - `pre-model-call` — {@link PreModelCallContext}
  *   - `post-tool-use` — {@link PostToolUseContext}
  *   - `stop` — {@link StopContext}
- *   - `assistant-message` — {@link AssistantMessageContext}
+ *   - `post-model-call` — {@link PostModelCallContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -130,6 +130,20 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * Persisted ID of the user message that triggered this turn. Hooks that
+   * attach turn-scoped metadata to the originating message (e.g. recording an
+   * injected memory block so it survives a conversation reload) key off this
+   * row id rather than the in-memory message arrays, whose entries carry no id.
+   */
+  readonly userMessageId: string;
+  /**
+   * Stable ID for the request that drives this turn. Hooks that perform
+   * runtime injection forward it onto the injector turn context so the
+   * assembled blocks are attributed to the originating request; it is fixed
+   * for the turn and cannot be recovered from the message arrays.
+   */
+  readonly requestId: string;
   /**
    * The text of the user prompt that triggered this turn — the resolved
    * user message (after slash-command expansion), independent of any
@@ -321,7 +335,7 @@ export interface PreModelCallContext {
   systemPrompt: string | undefined;
   /**
    * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
-   * live assistant `text_delta` stream; an `assistant-message` hook is then
+   * live assistant `text_delta` stream; a `post-model-call` hook is then
    * expected to produce the text the client sees (emitted once, after the reply
    * is finalized). Lets a plugin replace streamed output wholesale — e.g.
    * redaction that needs the full message — instead of leaking the raw stream.
@@ -331,10 +345,10 @@ export interface PreModelCallContext {
   readonly logger: PluginLogger;
 }
 
-// ─── Assistant-message hook context ──────────────────────────────────────────
+// ─── Post-model-call hook context ────────────────────────────────────────────
 
 /**
- * Context passed to the `assistant-message` hook. Fires for each finalized
+ * Context passed to the `post-model-call` hook. Fires for each finalized
  * assistant message — once per model call, at the message-complete boundary —
  * before the message is persisted and (if deferred) streamed-final. Unlike
  * {@link StopContext}'s read-only `responseContent` (which exists for the stop
@@ -348,7 +362,7 @@ export interface PreModelCallContext {
  * place or return a new context; throwing is contained by the loop (the original
  * content is kept).
  */
-export interface AssistantMessageContext {
+export interface PostModelCallContext {
   /** Conversation ID the message belongs to. */
   readonly conversationId: string;
   /** The call site this message serves — `"mainAgent"` for the user-facing reply. */

package/src/plugins/defaults/compaction/compact.ts

@@ -2,19 +2,19 @@
  * Default compaction implementation.
  *
  * Summarizes conversation history when the context window fills up by
- * delegating to a {@link ContextWindowManager}. The agent loop calls
- * {@link defaultCompact} directly with a {@link CompactionContext}; the request
- * carries the conversational inputs while the manager performs the work.
+ * delegating to the conversation's {@link ContextWindowManager}. The agent loop
+ * calls {@link defaultCompact} directly with a {@link CompactionContext}; the
+ * request carries the conversational inputs while the compaction module resolves
+ * (and, if needed, builds) the manager from its per-conversation store.
  *
  * This module is side-effect free: importing it does not register any plugin.
  */
 
-import type {
-  ContextWindowManager,
-  ContextWindowResult,
-} from "../../../context/window-manager.js";
 import type { Message } from "../../../providers/types.js";
 import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { PluginExecutionError } from "../../types.js";
+import { getContextWindowManager } from "./manager-store.js";
+import type { ContextWindowResult } from "./window-manager.js";
 
 /**
  * Name under which the default compaction plugin registers. Exposed so call
@@ -24,13 +24,14 @@ export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
 
 /**
  * Self-describing compaction request handed to {@link defaultCompact}. Carries
- * the conversational inputs plus the {@link ContextWindowManager} that runs the
- * summary, so the request is the part that can grow toward a model-facing
- * compaction-method shape without coupling callers to the manager's option bag.
+ * the conversational inputs plus the `conversationId` the compaction module
+ * resolves its manager from, so callers never hold or pass a manager handle and
+ * the request can grow toward a model-facing compaction-method shape without
+ * coupling callers to the manager's option bag.
  */
 export interface CompactionContext {
-  /** Context window manager that performs the compaction. */
-  manager: ContextWindowManager;
+  /** Conversation whose manager performs the compaction. */
+  conversationId: string;
   /** Message history to consider for compaction. */
   messages: Message[];
   /** Abort signal forwarded to the compaction summary call. */
@@ -48,12 +49,20 @@ export interface CompactionContext {
 }
 
 /**
- * Run compaction for the turn: delegates to the request's context window
- * manager and returns the (possibly summarized) message history.
+ * Run compaction for the turn: resolves the conversation's context window
+ * manager from the compaction store (building it on first access) and returns
+ * the (possibly summarized) message history.
  */
 export async function defaultCompact(
   context: CompactionContext,
 ): Promise<ContextWindowResult> {
-  const { manager, messages, signal, ...options } = context;
+  const { conversationId, messages, signal, ...options } = context;
+  const manager = getContextWindowManager(conversationId);
+  if (manager == null) {
+    throw new PluginExecutionError(
+      `default-compaction: no ContextWindowManager registered for conversation ${conversationId} — the conversation must register one before compaction runs`,
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
   return manager.maybeCompact(messages, signal, options);
 }

package/src/plugins/defaults/compaction/context-overflow-reducer.ts

@@ -22,10 +22,6 @@ import {
   estimatePromptTokens,
 } from "../../../context/token-estimator.js";
 import { truncateToolResultsAcrossHistory } from "../../../context/tool-result-truncation.js";
-import type {
-  ContextWindowCompactOptions,
-  ContextWindowResult,
-} from "../../../context/window-manager.js";
 import {
   countMediaBlocks,
   estimateUnconditionalStubTokens,
@@ -33,6 +29,10 @@ import {
 } from "../../../daemon/conversation-media-retry.js";
 import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
 import type { Message } from "../../../providers/types.js";
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowResult,
+} from "./window-manager.js";
 
 /**
  * Identifies which reduction tier was applied in a given step.

package/src/plugins/defaults/compaction/manager-store.ts

@@ -15,7 +15,7 @@
 import {
   ContextWindowManager,
   type ContextWindowManagerOptions,
-} from "../../../context/window-manager.js";
+} from "./window-manager.js";
 
 /** Live managers keyed by conversation id. */
 const managersByConversation = new Map<string, ContextWindowManager>();

package/src/{context → plugins/defaults/compaction}/window-manager.ts

@@ -14,23 +14,23 @@
  * marker is wrapped around the assistant-role memory message we emit on
  * successful compaction so those code paths keep working unchanged.
  */
-import { getConfig } from "../config/loader.js";
-import type { CompactionConfig } from "../config/schemas/compaction.js";
-import type { LLMCallSite } from "../config/schemas/llm.js";
-import type { ContextWindowConfig } from "../config/types.js";
+import { getConfig } from "../../../config/loader.js";
+import type { CompactionConfig } from "../../../config/schemas/compaction.js";
+import type { LLMCallSite } from "../../../config/schemas/llm.js";
+import type { ContextWindowConfig } from "../../../config/types.js";
+import {
+  type CompactionRunArgs,
+  runAssistantDrivenCompaction,
+} from "../../../context/compactor.js";
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
 import type {
   ContentBlock,
   Message,
   Provider,
   ToolDefinition,
-} from "../providers/types.js";
-import type { TrustClass } from "../runtime/actor-trust-resolver.js";
-import { getLogger } from "../util/logger.js";
-import {
-  type CompactionRunArgs,
-  runAssistantDrivenCompaction,
-} from "./compactor.js";
-import { estimatePromptTokens } from "./token-estimator.js";
+} from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("context-window");
 

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.ts

@@ -37,8 +37,7 @@ import { getConfig } from "../../../../config/loader.js";
 import { findConversationOrSubagent } from "../../../../daemon/conversation-registry.js";
 import {
   applyRuntimeInjections,
-  type InboundActorContext,
-  type InjectionMode,
+  resolveTurnInboundActorContext,
   type RuntimeInjectionResult,
 } from "../../../../daemon/conversation-runtime-assembly.js";
 import type { ServerMessage } from "../../../../daemon/message-protocol.js";
@@ -78,12 +77,6 @@ export interface MemoryRetrievalHookContext {
    * context. The one turn-identity field the live conversation can't recover.
    */
   readonly requestId: string | undefined;
-  /**
-   * Injection volume for the assembled blocks. `"full"` on the first call;
-   * overflow reduction downgrades subsequent re-injection, but the first-call
-   * assembly this hook performs runs at the loop's committed mode.
-   */
-  readonly mode: InjectionMode;
   /**
    * Whether the in-flight turn has no human present to answer clarification
    * questions. Resolved once at turn start and threaded in so injection uses
@@ -96,12 +89,6 @@ export interface MemoryRetrievalHookContext {
    * at turn start, so it is threaded in rather than re-derived.
    */
   readonly modelProfile: string | null;
-  /**
-   * Inbound actor identity and trust fields for the unified `<turn_context>`
-   * block, or `null` on guardian turns (which suppress the actor section).
-   * Resolved once at turn start from the actor-trust resolver and threaded in.
-   */
-  readonly actorContext: InboundActorContext | null;
 }
 
 /**
@@ -266,6 +253,10 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
   const abortSignal = conversation?.abortController?.signal;
   const isTrustedActor =
     resolveTrustClass(conversation?.trustContext) === "guardian";
+  const actorContext = resolveTurnInboundActorContext(
+    conversation?.trustContext,
+    conversation?.assistantId,
+  );
 
   if (conversation && isTrustedActor && abortSignal) {
     const graphResult = await conversation.graphMemory.prepareMemory(
@@ -309,13 +300,16 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
   // input — the Slack chronological transcript, the unified `<turn_context>`
   // block, channel/voice/transport hints, and the turn's trust/index/call-site
   // — from the live conversation, so we hand in only the request id and
-  // conversation id plus the fields resolved once at turn start (`mode`,
-  // `isNonInteractive`, `modelProfile`, `actorContext`).
+  // conversation id plus the fields resolved once at turn start
+  // (`isNonInteractive`, `modelProfile`). The unified `<turn_context>` actor
+  // input is self-resolved from the live conversation's trust context. This
+  // first-call assembly always runs at `"full"` volume; overflow reduction only
+  // downgrades the mode on later re-injection.
   const injection = await applyRuntimeInjections(ctx.latestMessages, {
     isNonInteractive: ctx.isNonInteractive,
     modelProfile: ctx.modelProfile,
-    actorContext: ctx.actorContext,
-    mode: ctx.mode,
+    actorContext,
+    mode: "full",
     requestId: ctx.requestId,
     conversationId: ctx.conversationId,
   });

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