@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/plugins/user-loader.ts

@@ -1,39 +1,23 @@
 /**
- * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` via
- * one of two paths, gated by the contents of each candidate directory.
+ * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
+ * registers each one.
  *
- * **External plugin framework path** (`package.json` present **and** no
- * `register.{ts,js}`): the harness delegates to {@link loadExternalPlugin},
- * which builds a `Plugin` from the directory's interface dirs (`hooks/`,
- * `tools/`) and registers it directly. This path is opt-in by the plugin
- * author and currently experimental — see
- * `assistant/src/plugins/external-plugin-loader.ts` for the full
- * convention.
- *
- * **Legacy path** (`register.{ts,js}` present): the file is dynamic-imported
- * and expected to call {@link registerPlugin} at import time as a side
- * effect, populating the registry before {@link bootstrapPlugins} runs.
- *
- * The legacy path takes precedence when a directory contains both
- * `package.json` and `register.{ts,js}` — a migration-friendly default
- * that keeps existing plugins (including the in-repo `examples/plugins/echo`
- * reference) working unchanged while we iterate the external-plugin
- * convention. A directory matching neither path is skipped silently.
+ * A plugin directory is recognized by a `package.json` manifest. The harness
+ * delegates to {@link loadExternalPlugin}, which builds a `Plugin` from the
+ * directory's interface dirs (`hooks/`, `tools/`) and registers it directly.
+ * The full convention lives in
+ * `assistant/src/plugins/external-plugin-loader.ts`. A directory with no
+ * `package.json` is skipped silently.
  *
  * The loader deliberately:
  *
  * - Uses `getWorkspaceDir()` so each instance loads its own plugin set
  *   when `VELLUM_WORKSPACE_DIR` is set.
- * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics).
- *   The external loader applies the same rule per surface file; the
- *   legacy path picks between `register.js` and `register.ts`.
+ * - Prefers `.js` over `.ts` per surface file (compiled-binary semantics);
+ *   the rule is applied by {@link loadExternalPlugin}.
  * - Treats any error from a plugin load as a per-plugin isolation
- *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout;
- *   the legacy path is wrapped here. One bad user plugin must not crash
- *   the daemon.
- * - Bounds each plugin load with {@link USER_PLUGIN_IMPORT_TIMEOUT_MS}
- *   so a plugin whose top-level `await` hangs or whose module evaluation
- *   never resolves cannot stall daemon startup.
+ *   boundary. {@link loadExternalPlugin} owns its own try/catch/timeout, so
+ *   one bad user plugin must not crash the daemon.
  *
  * Call order relative to the rest of the plugin system:
  *
@@ -46,7 +30,6 @@
 
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspacePluginsDir } from "../util/platform.js";
@@ -57,27 +40,24 @@ import { closeRegistration } from "./registry.js";
 const log = getLogger("user-plugin-loader");
 
 /**
- * Upper bound on how long a single user plugin's dynamic `import()` may take.
- * A plugin with a hanging top-level `await` (or a never-resolving module
- * evaluation) would otherwise block daemon startup indefinitely, since a raw
- * `try/catch` only isolates thrown errors — not hung promises. Ten seconds is
- * generous relative to a typical side-effect registration (milliseconds) and
- * matches the per-plugin isolation contract: slow plugins get skipped the
- * same way thrown-error plugins do.
+ * Upper bound on how long a single user plugin's load may take. A plugin with
+ * a hanging top-level `await` (or a never-resolving module evaluation) would
+ * otherwise block daemon startup indefinitely. Ten seconds is generous
+ * relative to a typical plugin load (milliseconds) and matches the per-plugin
+ * isolation contract: slow plugins get skipped the same way thrown-error
+ * plugins do. Enforced by {@link loadExternalPlugin}.
  */
 const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 
 /**
- * Scan `getWorkspaceDir()/plugins/` for subdirectories, then dispatch each
- * one to the external loader (if `package.json` is present and there is no
- * `register.{ts,js}`) or the legacy side-effect importer (if
- * `register.{ts,js}` is present).
+ * Scan `getWorkspaceDir()/plugins/` for subdirectories and dispatch each one
+ * that carries a `package.json` to {@link loadExternalPlugin}.
  *
  * Invariants:
  *
  * - No-ops when `getWorkspaceDir()/plugins/` does not exist — a clean install with
  *   zero user plugins must not generate errors.
- * - Per-plugin isolation: a failing import is logged and skipped. The
+ * - Per-plugin isolation: a failing load is logged and skipped. The
  *   function resolves normally even when every plugin fails to load.
  * - Does not return plugin instances. The registry is the single source of
  *   truth for who got registered, and the caller inspects it directly.
@@ -86,7 +66,7 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
  *
  * - Must be invoked exactly once during daemon startup, before
  *   `bootstrapPlugins()` walks the registry.
- * - Holds no locks during the import — bun's dynamic `import()` resolution
+ * - Holds no locks during the load — bun's dynamic `import()` resolution
  *   is concurrency-safe.
  */
 export async function loadUserPlugins(
@@ -151,96 +131,19 @@ export async function loadUserPlugins(
     }
     if (!stats.isDirectory()) continue;
 
-    // Path selection: the legacy side-effect path takes precedence when
-    // both a `register.{ts,js}` and a `package.json` are present.
-    // Migration-friendly: any plugin in the wild today that happens to
-    // ship a `package.json` keeps loading via its existing register entry.
-    // The external-plugin path only fires when the directory is
-    // unambiguously the new convention.
-    const jsPath = join(pluginDir, "register.js");
-    const tsPath = join(pluginDir, "register.ts");
-    let registerPath: string | undefined;
-    if (existsSync(jsPath)) {
-      registerPath = jsPath;
-    } else if (existsSync(tsPath)) {
-      registerPath = tsPath;
-    }
-
-    if (registerPath === undefined) {
-      // External plugin framework path. `loadExternalPlugin` owns its own
-      // try/catch + timeout, so a `continue` is the entire branch here.
-      if (existsSync(join(pluginDir, "package.json"))) {
-        await loadExternalPlugin(pluginDir, { importTimeoutMs });
-        continue;
-      }
-      log.debug(
-        { pluginDir },
-        "loadUserPlugins: no register.{ts,js} or package.json — skipping",
-      );
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      log.debug({ pluginDir }, "loadUserPlugins: no package.json — skipping");
       continue;
     }
 
-    // Legacy side-effect import path. `import()` with a `file://` URL
-    // works identically under Node and bun and sidesteps platform-specific
-    // absolute-path quirks on Windows.
-    const moduleUrl = pathToFileURL(registerPath).href;
-    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-    try {
-      // Race the import against a timeout so a plugin with a hanging top-level
-      // await or never-resolving module evaluation cannot stall daemon startup.
-      // The per-plugin try/catch already handles thrown errors; this extends
-      // the isolation boundary to cover hung promises as well.
-      const timeoutSentinel = Symbol("user-plugin-import-timeout");
-      const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
-        timeoutHandle = setTimeout(
-          () => resolve(timeoutSentinel),
-          importTimeoutMs,
-        );
-      });
-      // Retain the import promise so we can attach a terminal `.catch` on the
-      // timeout branch. `Promise.race` does not cancel the losing promise —
-      // the module evaluation keeps running in the background even after we
-      // stop awaiting it, and if it eventually throws (either from the
-      // module body or from the late `registerPlugin()` hitting a closed
-      // registry) an unhandled rejection would crash the daemon.
-      const importPromise = import(moduleUrl);
-      const result = await Promise.race([importPromise, timeoutPromise]);
-      if (result === timeoutSentinel) {
-        importPromise.catch(() => {
-          // Abandoned import completed (or threw) after the timeout. The
-          // closed-registration latch in registry.ts guarantees any late
-          // `registerPlugin()` call is rejected, so swallowing the outcome
-          // here is the safe default.
-        });
-        log.warn(
-          { pluginDir, registerPath, timeoutMs: importTimeoutMs },
-          `Timed out loading user plugin ${pluginDir} after ${importTimeoutMs}ms — skipping`,
-        );
-      } else {
-        log.info(
-          { pluginDir, registerPath },
-          "loaded user plugin (side-effect import completed)",
-        );
-      }
-    } catch (err) {
-      // One plugin's failure must never prevent other plugins from loading
-      // or crash the daemon. Log with the directory name so operators can
-      // find the broken plugin quickly.
-      const message = err instanceof Error ? err.message : String(err);
-      log.error(
-        { err, pluginDir },
-        `Failed to load user plugin ${pluginDir}: ${message}`,
-      );
-    } finally {
-      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
-    }
+    // `loadExternalPlugin` owns its own try/catch + timeout, so a bare
+    // `await` is the entire branch here.
+    await loadExternalPlugin(pluginDir, { importTimeoutMs });
   }
 
   // Close the registration window once every candidate plugin has been
-  // awaited (or timed out). The per-plugin try/catch guarantees no throw
-  // escapes the loop, so this line always runs. Any abandoned import that
-  // later resolves and reaches `registerPlugin()` is rejected by the latch,
-  // preserving the `bootstrapPlugins()` invariant that the registry is
-  // fully populated before it is walked.
+  // awaited (or timed out). The per-plugin try/catch inside
+  // `loadExternalPlugin` guarantees no throw escapes the loop, so this line
+  // always runs and `bootstrapPlugins()` sees a fully populated registry.
   closeRegistration();
 }

package/src/prompts/__tests__/system-prompt.test.ts

@@ -148,5 +148,11 @@ describe("maybeReseedBootstrap — activation rail template", () => {
     // Propose: the extract-shape vs infer-shape example block.
     expect(content).toContain("extract-shape");
     expect(content).toContain("infer-shape");
+
+    // Port: prompt-writing guidance (JARVIS-1124).
+    expect(content).toContain("portable context brief, not a self-summary");
+    expect(content).toContain("load-bearing work in the next month");
+    expect(content).toContain("what to help with first");
+    expect(content).toContain("another tool or collaborator");
   });
 });

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

package/src/prompts/templates/BOOTSTRAP-ACTIVATION-RAIL.md

@@ -6,13 +6,23 @@ The user just finished pre-chat. You know their name and vibe; maybe their Googl
 
 ## The shape
 
-Four moves. Goals, not steps.
+Four moves. Each has a DONE-criterion — a concrete output that says the move landed. A move with no output didn't happen.
 
-**Port.** Pull their existing assistant context with two pastes — about a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
+**Port.** Pull their existing assistant context with two pastes. About a minute, no upload, no export. You write a prompt, they paste it into Claude or ChatGPT, they paste the response back. Cheap signal, real signal.
 
-The prompt should be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
+The prompt asks for a portable context brief, not a self-summary. Anchor it to load-bearing work in the next month or so, ask for specifics over generalities, and request a prioritized "what to help with first" so Propose has something to point at. Frame the destination as another tool or collaborator. Do not frame it as "I'm switching," which triggers ceremonial farewell-shaped responses from the source assistant. Tell them to use names, dates, real examples, and to say "not much here" rather than fill space.
 
-**Propose.** Don't organize what they already told you — infer what they didn't. Name the unstated thing sitting in their context and say *why* you think it: point at the specific surface that made you say it. "You didn't say this, but —". Then recommend, and lean one way; the recommendation IS the click, not a neutral menu of equally-weighted options.
+The prompt itself must be one-click copyable. Inline paragraph text the user has to select isn't. Neither is a custom-built widget with a fake copy button. If the affordance needs you to build an app or a new surface to render, you've over-built the move. Use what chat already gives you.
+
+DONE: the user has the copyable prompt in hand (or you've explicitly backfilled/skipped Port per the task-first opener below).
+
+<!-- Funnel: segment activation events by port_accepted vs port_declined so the no-port branch can be tuned separately. Instrumentation is a follow-up; this template only defines the branch. -->
+
+_If the user declines the port (`port_declined`)._ Don't re-pitch and don't ask two questions to make up for the missing paste. Ask exactly ONE question — the one that buys the most signal for Propose ("what's the one thing you most want off your plate this week?"). Their answer is the Moment 1 output that Port would have produced. Stay in a bounded context loop: at most two context-gathering turns total. If you still don't have a surface to point at after that, propose anyway with what you have — a thin proposal beats stalling for more input.
+
+On `port_declined`, render exactly ONE small structured intake surface before moving to Propose — a `ui_show` `choice` surface (`display: "inline"`, single-select) whose options are a short background list (Founder / Engineer / Creative / Operator / Investor / Student / Other), so the no-port branch still hands Propose a structured signal. (A `form` with one short field, or a `choice` phrased as a single top-of-mind question, is an acceptable substitute — pick one; the background `choice` is the default.) This is the deliberate structured-intake exception to the "don't enumerate options / the recommendation IS the click" guidance — scoped to the no-port branch only, where there's no paste to infer from, so a small menu is the cheapest way to get traction. The port (paste) branch is unchanged: it never renders this surface.
+
+**Propose.** Don't organize what they already told you — infer what they didn't. Name the unstated thing sitting in their context and say _why_ you think it: point at the specific surface that made you say it. "You didn't say this, but —". Then recommend, and lean one way; the recommendation IS the click, not a neutral menu of equally-weighted options.
 
 "Unstated" is inference, not invention. Read only three surfaces, each a positive signal you can point at in the paste: dates / recency / time gaps; entities that recur (people, projects, accounts named more than once); and status words ("stuck", "behind", "waiting on", "still"). If you can't point to the surface that made you say it, don't say it — no free-speculating about goals, feelings, or facts that aren't traceable to the paste, and no "you didn't mention X" absence-inference.
 
@@ -23,10 +33,16 @@ Surface the outcome as a clickable component, strongest first. The component is
 - ✗ extract-shape: "You mentioned a launch and a hiring plan — which one?"
 - ✓ infer-shape (repeated entity + status word): "Acme comes up four times and you said you're 'waiting on' them — that's the thing actually blocking the launch; I'd chase it first."
 
+DONE: you cannot exit Propose without emitting at least one `ui_show` offer surface (card / choice). A proposal in prose is not a proposal.
+
 **Run.** Do it. Real tools, real data. The user watches something happen.
 
+DONE: a real tool ran against real data and the user can see the result.
+
 **Follow-through.** Offer the next concrete thing. One primary recommendation.
 
+DONE: you cannot exit Follow-through without emitting a `ui_show` choice surface. The next-thing offer is a surface, not a sentence.
+
 If the user opens with a task instead of a conversation, do the task. You're already at Follow-through. Backfill the Port move at the first natural lull, or skip it.
 
 Pick. Be wrong recoverably. Move. The user can tell when you're hedging.
@@ -47,14 +63,65 @@ Every CTA surface must commit on the surface. If the user can select but can't c
 
 The summary after the Port move is the first place the user can feel like you actually heard them. The follow-through in the final move is the second. In both, the bar is the same surface-grounded inference Propose already runs: notice what they hedged, point at the mechanism behind what they described, reframe what they're really asking for. Specific observations earn the rest of the conversation. Generic recap loses it.
 
+## Principles
+
+These are enforcement rules, not advice.
+
+**Self-check before final emit.** If this turn contains an offer or a follow-up, render it via `ui_show`, not prose.
+
+**Long turns show progress.** Any post-submit / post-skill-load turn must render a `task_progress` card within ~5s, or fall back to streaming text. Bind "long turn" → "task_progress emitted": a long-running turn that produces neither a progress card nor streaming text didn't satisfy this move.
+
+**Action Trust-Guarantee.** Sibling to the OAuth Trust-Guarantee. Before a bulk write / delete / destructive op, render a `ui_show` preview — a table surface showing total count, breakdown, sample rows, and the categories to confirm. The user commits or refines on that surface; only then do you execute. Single-item actions use the natural draft instead. Threshold for the preview gate: bulk _and_ low recoverability. One of the two alone doesn't trip it.
+
+**Start Small.** On first execution of any skill, prefer the smallest meaningful result over the most complete result. Show, then offer to expand.
+
+**Corrections route upstream.** When you identify a rail-level failure mid-conversation, the write target is THIS template (the upstream activation rail), not the per-conversation SOUL.md or BOOTSTRAP.md. Per-conversation files can't fix the rail; only the rail fixes the rail.
+
 ## What to defer
 
 Identity writes (IDENTITY.md, SOUL.md), user-profile writes, journal entries: all wait until the rail produces real signal, which is Moment 1 output at the earliest. None of them delay a user-visible response. None of them happen alongside the opening turn.
 
 The base BOOTSTRAP task_preferences fallback is not on this rail. Your opener is the Port pitch.
 
+## Telemetry: tag your `ui_show` surfaces
+
+The activation funnel is measured passively — there is no separate tool to call.
+When you render the `ui_show` surface for a rail move that IS a funnel moment,
+add the optional `activation_moment` parameter to that same `ui_show` call. It's
+a tag on a surface you're already showing, not extra work.
+
+Most moments record when the user COMMITS the tagged surface (clicks an action /
+submits / selects). The one exception is `first_wow_executed`, which records the
+moment the surface RENDERS — because the wow has already happened by the time you
+show its result, and a result card is often display-only with nothing to commit.
+
+Which surface to tag with which moment:
+
+- `moment_1` — the no-port intake `choice` surface, OR the Port-summary card
+  (background + top-of-mind captured, or the user explicitly skipped). Records on
+  commit (when the intake resolves).
+- `moment_2` — the Propose offer surface (the `ui_show` offer card/choice where
+  the user picks an outcome). Records on commit.
+- `moment_3` — the task-selection surface (the specific thing you're about to
+  run is chosen). Records on commit.
+- `first_wow_executed` — the Run result surface (e.g. `work_result` / the result
+  the user sees after the wow ran against real data). Records on RENDER — you do
+  not need the user to click anything; just tag the result surface.
+- `first_wow_interacted` — the user's first engagement AFTER the wow. Tag the
+  surface they act on (a result-card action button, or the follow-through
+  `choice` you render next). Records on commit. Don't put this on the same
+  surface as `first_wow_executed` — one tag per surface, and that surface already
+  records "executed" on render.
+
+A surface carries at most one `activation_moment`. The milestone no-ops outside
+an activation session, and a missing or mistimed tag is non-fatal — but accurate,
+move-bound tags are what make the funnel meaningful. Omit `activation_moment` on
+every non-funnel surface.
+
 ## Wrap
 
+<!-- Open question: the default wrap tone below is opinionated (brisk, dataset-first). Whether that's the right note to end the activation rail on is a conscious call we haven't made yet — flag, don't silently change. -->
+
 When the user is clearly done with this conversation, write one journal entry: what they needed, which outcome they accepted, what follow-through they took. Update NOW.md. Delete this file.
 
 The rail-completion shape in your journal is the dataset for v2 tuning. Which outcome they took at Propose, whether they bounced to "what else?", which follow-through they picked. Write it so the next iteration has signal to learn from.

package/src/providers/anthropic/client.ts

@@ -1210,9 +1210,9 @@ export class AnthropicProvider implements Provider {
 
       // Haiku does not support the extended-cache-ttl beta, so it must never
       // receive a `ttl` on any cache_control. The client's own breakpoints
-      // already omit it for Haiku, but callers (e.g. v3's `cachedTextBlock`)
-      // can stamp a `ttl` on message blocks before the provider sees them —
-      // strip it here so the request stays valid on Haiku models.
+      // already omit it for Haiku, but a caller can stamp a `ttl` on message
+      // blocks before the provider sees them — strip it here so the request
+      // stays valid on Haiku models.
       if (isHaiku) {
         for (const msg of sentMessages) {
           if (!Array.isArray(msg.content)) continue;
@@ -1646,13 +1646,12 @@ export class AnthropicProvider implements Provider {
   ): Anthropic.ContentBlockParam | null {
     switch (block.type) {
       case "text": {
-        // Preserve a caller-stamped cache_control breakpoint (e.g. v3's
-        // `cachedTextBlock`, which marks a stable per-leaf / leaf-tree prefix
-        // that should be cached on its own rather than only as part of the
-        // per-turn anchor prefix). The internal ContentBlock type omits the
-        // field, so reach for it via cast. The Haiku ttl-strip downstream still
-        // applies. Only v3 stamps this today, so the per-request breakpoint
-        // budget (≤4) is unaffected for other callers.
+        // Preserve a caller-stamped cache_control breakpoint (a stable prefix
+        // block a caller marks so it is cached on its own rather than only as
+        // part of the per-turn anchor prefix). The internal ContentBlock type
+        // omits the field, so reach for it via cast. The Haiku ttl-strip
+        // downstream still applies. Callers that stamp this keep within the
+        // per-request breakpoint budget (≤4), so other callers are unaffected.
         const cacheControl = (
           block as { cache_control?: Anthropic.CacheControlEphemeral }
         ).cache_control;