@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/tools/registry.ts

@@ -1,18 +1,9 @@
 import { isPluginDisabled } from "../plugins/disabled-state.js";
 import { getLogger } from "../util/logger.js";
-import { coreAppProxyTools } from "./apps/definitions.js";
-import { registerAppTools } from "./apps/registry.js";
-import { hostFileEditTool } from "./host-filesystem/edit.js";
-import { hostFileReadTool } from "./host-filesystem/read.js";
-import { hostFileTransferTool } from "./host-filesystem/transfer.js";
-import { hostFileWriteTool } from "./host-filesystem/write.js";
-import { hostShellTool } from "./host-terminal/host-shell.js";
 import { toProviderSafeToolName } from "./provider-tool-name.js";
-import { registerSystemTools } from "./system/register.js";
 import { finalizeTool } from "./tool-defaults.js";
+import { explicitTools } from "./tool-manifest.js";
 import type { OwnerInfo, Tool, ToolDefinition } from "./types.js";
-import { allUiSurfaceTools } from "./ui-surface/definitions.js";
-import { registerUiSurfaceTools } from "./ui-surface/registry.js";
 
 const log = getLogger("tool-registry");
 
@@ -37,68 +28,6 @@ const DEFAULT_TOOL_OWNER: OwnerInfo = Object.freeze({
   id: "default",
 });
 
-// ── External tool registry ───────────────────────────────────────────
-// Skills register their tools here at initialization time so the tool
-// manifest can include them without importing from `../skills/`.
-//
-// Each registration is stored as a provider closure. Closures are
-// resolved at `getExternalTools()` time (which `initializeTools()`
-// calls), not at registration time — this lets a skill defer its
-// feature-flag check until after the daemon has run
-// `mergeDefaultWorkspaceConfig()`, so skills see the merged config
-// instead of forcing an early `loadConfig()` against unmerged defaults.
-const externalToolProviders: Array<{
-  owner: OwnerInfo;
-  provider: () => Tool[];
-}> = [];
-
-/**
- * Register tools provided by an external skill. Called during skill
- * initialization (e.g. meet-join bootstrap).
- *
- * Accepts either a concrete `Tool[]` (resolved eagerly at the caller)
- * or a `() => Tool[]` closure (resolved lazily inside
- * `getExternalTools()`). Skills that perform feature-flag or config
- * reads to decide which tools to surface must pass a closure so the
- * read happens after daemon-startup config merging.
- *
- * Lives in registry.ts (not tool-manifest.ts) to avoid a circular
- * dependency: skills/load.ts → … → meet-join/register.ts → tool-manifest.ts
- * → skills/load.ts. Keeping it here lets external skill bootstraps import
- * from registry.ts, which is already a leaf in the dependency graph.
- *
- * `owner` records which extension produced these tools — typed
- * {@link OwnerInfo} so ownership flows through `ownersByName` at
- * `initializeTools()` time, the same way `register*` registers it for
- * IPC-loaded tools. Eager (boot-time) skill bootstraps go through this
- * path rather than `registerSkillTools`, so this is where their owner
- * lookup gets established.
- */
-export function registerExternalTools(
-  owner: OwnerInfo,
-  toolsOrProvider: Tool[] | (() => Tool[]),
-): void {
-  const provider =
-    typeof toolsOrProvider === "function"
-      ? toolsOrProvider
-      : () => toolsOrProvider;
-  externalToolProviders.push({ owner, provider });
-}
-
-/** Return all externally registered tools paired with their owners. */
-function getExternalTools(): Array<{ owner: OwnerInfo; tool: Tool }> {
-  return externalToolProviders.flatMap(({ owner, provider }) =>
-    provider().map((tool) => ({ owner, tool })),
-  );
-}
-
-// Snapshot of core tools (with their owners) captured after initializeTools()
-// completes. Lets __resetRegistryForTesting() restore the core baseline — tools
-// and ownership together — synchronously, without re-running the async
-// initializeTools() bootstrap.
-let coreToolsSnapshot: Map<string, { tool: Tool; owner: OwnerInfo }> | null =
-  null;
-
 // Cached promise for the one-time tool-registry initialization. `initializeTools`
 // returns this so repeated calls (across entry points, or an eventual
 // getter-triggered ensure) run the underlying work exactly once. Cleared by the
@@ -115,6 +44,17 @@ const skillRefCount = new Map<string, number>();
 // separate and covers the case of two extensions choosing the same tool name.
 const pluginRefCount = new Map<string, number>();
 
+// Fingerprints of the user-plugin tool sets `loadPluginTools` last pulled
+// from the plugin mtime-cache, keyed by plugin name. The pull reconcile diffs
+// the cache's current fingerprints against this map, so it only ever touches
+// registrations it created itself — plugin-owned tools registered by other
+// callers (the in-process default-plugin bootstrap) are never disturbed.
+const pulledPluginFingerprints = new Map<string, string>();
+
+// In-flight plugin pull — concurrent `loadPluginTools` callers coalesce onto
+// a single reconcile (mirrors `loadWorkspaceTools`).
+let pluginToolsReconcileInFlight: Promise<void> | null = null;
+
 /**
  * Format an owner for log messages and error strings. Returns a stable
  * human-readable description (e.g. `skill "deploy"`, `plugin "weather"`,
@@ -215,9 +155,7 @@ export function registerTool(definition: ToolDefinition): void {
   }
   tools.set(name, tool);
   // A tool registered through this bare path has no explicit extension owner,
-  // so it is a built-in: record the shared `default` owner by name. Callers
-  // that own the tool (external skill bootstraps) overwrite this entry with
-  // their own owner immediately after calling `registerTool`.
+  // so it is a built-in: record the shared `default` owner by name.
   ownersByName.set(name, DEFAULT_TOOL_OWNER);
   log.info({ name, category: tool.category }, "Tool registered");
 }
@@ -249,17 +187,6 @@ export function getTool(name: string): Tool | undefined {
   return tools.get(name);
 }
 
-/**
- * True once {@link initializeTools} has populated the core registry (the core
- * snapshot is captured at the end of init). Callers that must not run before the
- * read-only baseline (`file_read`/`web_fetch`/etc.) exists — e.g. the scheduler
- * deferring boot-time workflow triggers — gate on this. It only ever flips
- * false→true, so a true reading is stable for the process lifetime.
- */
-export function areCoreToolsInitialized(): boolean {
-  return coreToolsSnapshot !== null;
-}
-
 export function getAllTools(): Tool[] {
   return Array.from(tools.values());
 }
@@ -497,6 +424,93 @@ export function unregisterPluginTools(pluginName: string): void {
   }
 }
 
+/**
+ * Pull the active user-plugin tool set from the plugin mtime-cache into the
+ * registry. This is the pull half of the plugin-tool relationship — the
+ * mtime-cache never writes to the registry; instead this reconcile reads
+ * {@link import("../plugins/mtime-cache.js").getActiveUserPluginTools} (which
+ * syncs against the source-versions sentinel first) and diffs the result into
+ * the registry: plugins that vanished are unregistered, new plugins register,
+ * and a plugin whose per-tool source mtimes moved is re-registered. Mirrors
+ * how hooks resolve through `getUserHookEntriesFor`.
+ *
+ * Idempotent, cheap when nothing changed (one sentinel stat + fingerprint
+ * compares), and concurrency-safe (concurrent callers coalesce onto one
+ * in-flight reconcile). Runs as the final step of `initializeTools()` (at
+ * daemon boot the plugin cache is already populated by then), and
+ * fire-and-forget from the per-turn conversation tool resolver — the same
+ * cadence `loadWorkspaceTools` runs on.
+ */
+export function loadPluginTools(): Promise<void> {
+  if (pluginToolsReconcileInFlight) {
+    return pluginToolsReconcileInFlight;
+  }
+  // `reconcilePluginToolsFromCache` never rejects (failures are caught and
+  // logged); `.finally` clears the slot either way so the next caller pulls
+  // fresh.
+  pluginToolsReconcileInFlight = reconcilePluginToolsFromCache().finally(() => {
+    pluginToolsReconcileInFlight = null;
+  });
+  return pluginToolsReconcileInFlight;
+}
+
+async function reconcilePluginToolsFromCache(): Promise<void> {
+  // Dynamic import: the mtime-cache pulls the plugin-loader subtree in with
+  // it, which must stay out of this module's eager import graph — the
+  // registry is a widely-imported leaf.
+  let active: Map<string, { fingerprint: string; tools: Tool[] }>;
+  try {
+    const { getActiveUserPluginTools } =
+      await import("../plugins/mtime-cache.js");
+    active = await getActiveUserPluginTools();
+  } catch (err) {
+    log.warn(
+      { err },
+      "loadPluginTools: plugin cache pull failed — keeping current registrations",
+    );
+    return;
+  }
+
+  // Tear down plugins this reconcile registered that are no longer active
+  // (uninstalled, disabled, or their last tool file was deleted).
+  for (const pluginName of pulledPluginFingerprints.keys()) {
+    if (!active.has(pluginName)) {
+      unregisterPluginTools(pluginName);
+      pulledPluginFingerprints.delete(pluginName);
+    }
+  }
+
+  // Register new plugins; re-register ones whose tool set changed. Per-plugin
+  // isolation: one plugin's conflict/failure never blocks the others.
+  for (const [pluginName, { fingerprint, tools: pluginTools }] of active) {
+    const prev = pulledPluginFingerprints.get(pluginName);
+    if (prev === fingerprint) {
+      continue;
+    }
+    try {
+      if (prev !== undefined) {
+        // Changed tool set: drop the previous registration first so tools
+        // removed in the new set don't linger (re-registering alone would
+        // only overwrite the survivors).
+        unregisterPluginTools(pluginName);
+      }
+      registerPluginTools(pluginName, pluginTools);
+      pulledPluginFingerprints.set(pluginName, fingerprint);
+      log.info(
+        { plugin: pluginName, count: pluginTools.length },
+        "user plugin tools registered",
+      );
+    } catch (err) {
+      // Leave no fingerprint so the next reconcile retries this plugin.
+      pulledPluginFingerprints.delete(pluginName);
+      log.error(
+        { err, plugin: pluginName },
+        `Failed to register tools for user plugin ${pluginName}`,
+      );
+    }
+  }
+}
+
 /**
  * Return the current reference count for a plugin's tools. Exposed for testing.
  */
@@ -627,23 +641,37 @@ export function getMcpToolDefinitions(): Tool[] {
 }
 
 /**
- * Return tool definitions for all currently registered plugin-origin tools.
- * Used by the session resolver to dynamically pick up plugin tools that were
- * registered after session creation — e.g. a plugin installed at runtime and
- * activated on a subsequent turn (see `plugins/mtime-cache.ts`). Mirrors
+ * Return tool definitions for every registered plugin-origin tool, INCLUDING
+ * tools from workspace-disabled plugins. This does NOT apply the `.disabled`
+ * sentinel gate — the caller owns the scoping decision. Use this when a
+ * conversation's explicit `enabledPlugins` scope is the authority (a plugin the
+ * conversation explicitly enabled must surface its tools even when it is
+ * disabled at the workspace level; see `getEffectiveEnabledPluginSet`). Callers
+ * that report the workspace-level *available* surface want
+ * {@link getPluginToolDefinitions} instead.
+ */
+export function getAllPluginToolDefinitions(): Tool[] {
+  return Array.from(tools.values()).filter(
+    (t) => ownersByName.get(t.name)?.kind === "plugin",
+  );
+}
+
+/**
+ * Return tool definitions for currently registered plugin-origin tools, minus
+ * those contributed by a workspace-disabled plugin. Used by the session
+ * resolver to dynamically pick up plugin tools that were registered after
+ * session creation — e.g. a plugin installed at runtime and activated on a
+ * subsequent turn (see `plugins/mtime-cache.ts`). Mirrors
  * {@link getMcpToolDefinitions} so a plugin install behaves like `mcp reload`.
+ *
+ * The `.disabled` sentinel is filtered at read time so `assistant plugins
+ * disable <name>` takes effect on the next turn without a daemon restart,
+ * mirroring `getHooksFor` (plugins/registry.ts).
  */
 export function getPluginToolDefinitions(): Tool[] {
-  return Array.from(tools.values()).filter((t) => {
+  return getAllPluginToolDefinitions().filter((t) => {
     const owner = ownersByName.get(t.name);
-    if (owner?.kind !== "plugin") {
-      return false;
-    }
-    // Filter out tools contributed by disabled plugins at read time so
-    // `assistant plugins disable <name>` takes effect on the next turn
-    // without a daemon restart. Mirrors the `.disabled` sentinel filtering
-    // in `getHooksFor` (plugins/registry.ts).
-    return !isPluginDisabled(owner.id);
+    return owner !== undefined && !isPluginDisabled(owner.id);
   });
 }
 
@@ -1039,82 +1067,10 @@ export function initializeTools(): Promise<void> {
 }
 
 async function runToolInitialization(): Promise<void> {
-  const { explicitTools } = await import("./tool-manifest.js");
-
-  // Capture tool names already in the registry before any manifest
-  // registrations.  In production this is empty; in tests a non-skill tool
-  // may have been registered before the first initializeTools() call.
-  const preExisting = new Set(tools.keys());
-
   for (const tool of explicitTools) {
     registerTool(tool);
   }
 
-  // External skill tools — registered by skill bootstrap modules via
-  // `registerExternalTools()`. Called at init time (not spread into
-  // `explicitTools`) so registrations that happen between module-load
-  // and `initializeTools()` are picked up. Each provider pairs its tools
-  // with an OwnerInfo so the registry can record ownership in
-  // {@link ownersByName} alongside the bare `registerTool()` install.
-  const extEntries = getExternalTools();
-  for (const { owner, tool } of extEntries) {
-    registerTool(tool);
-    ownersByName.set(tool.name, owner);
-  }
-
-  // Host tools are registered here so host access stays opt-in until this
-  // point in startup.
-  const hostTools = [
-    hostFileReadTool,
-    hostFileWriteTool,
-    hostFileEditTool,
-    hostFileTransferTool,
-    hostShellTool,
-  ];
-  for (const tool of hostTools) {
-    registerTool(tool);
-  }
-
-  registerUiSurfaceTools();
-  registerAppTools();
-  registerSystemTools();
-
-  // Snapshot core tools for __resetRegistryForTesting().  We include every
-  // non-skill tool that was registered by the manifest, while excluding
-  // arbitrary test tools that were registered before init.
-  //
-  // A pre-existing tool is included only if it is a known manifest tool
-  // (declared in explicitTools, hostTools, or any registered external
-  // skill tool) — e.g. a test registered a manifest tool directly before
-  // its first initializeTools() call.
-  if (!coreToolsSnapshot) {
-    // Core tool literals always set `name` (verified by `registerTool` —
-    // it throws on missing name). The `!` assertions reflect that
-    // invariant at the iteration sites.
-    const manifestToolNames = new Set<string>([
-      ...explicitTools.map((t) => t.name!),
-      ...extEntries.map(({ tool }) => tool.name),
-      ...hostTools.map((t) => t.name!),
-      ...allUiSurfaceTools.map((t) => t.name!),
-      ...coreAppProxyTools.map((t) => t.name!),
-    ]);
-
-    coreToolsSnapshot = new Map<string, { tool: Tool; owner: OwnerInfo }>();
-    for (const [name, tool] of tools) {
-      const owner = ownersByName.get(name);
-      if (owner?.kind === "skill" || owner?.kind === "plugin") {
-        continue;
-      }
-      // Exclude pre-existing tools not declared in the manifest
-      if (preExisting.has(name) && !manifestToolNames.has(name)) {
-        continue;
-      }
-      // Every registered tool carries an owner (built-ins get DEFAULT_TOOL_OWNER
-      // stamped by registerTool), so `owner` is defined here.
-      coreToolsSnapshot.set(name, { tool, owner: owner! });
-    }
-  }
-
   log.info({ count: tools.size }, "Tools initialized");
 
   // Load workspace tool overrides from `<workspaceDir>/tools/<name>.{ts,js,json}`
@@ -1122,8 +1078,6 @@ async function runToolInitialization(): Promise<void> {
   // registrations get a chance to claim names. This ordering makes
   // workspace tools the canonical owner per name:
   //   core registrations → workspace tools → MCP → plugins.
-  // Workspace tools land after the core snapshot above so they're never
-  // baked into the test-reset baseline.
   //
   // `loadWorkspaceTools` is idempotent: this is the first reconcile, and
   // conversation reads re-run it later to pick up on-disk edits without a
@@ -1131,9 +1085,18 @@ async function runToolInitialization(): Promise<void> {
   //
   // Imported dynamically because the loader imports back from this module
   // (registerWorkspaceTools / removeCoreToolViaWorkspace); a static import
-  // here would create a registry ↔ loader cycle.
+  // here would create a registry ↔ loader cycle that `lint:circular` flags.
   const { loadWorkspaceTools } = await import("./workspace-tools/loader.js");
   await loadWorkspaceTools();
+
+  // Pull the active user-plugin tool set last, so core and workspace
+  // registrations already own their names when plugin conflicts resolve.
+  // At daemon boot the plugin mtime-cache is populated before this runs
+  // (`initializePlugins()` precedes `initializeTools()` in the lifecycle);
+  // in worker/standalone processes the cache is empty and this is a no-op.
+  // Runtime changes keep flowing through the same reconcile, re-fired by
+  // the per-turn conversation tool resolver.
+  await loadPluginTools();
 }
 
 /**
@@ -1141,29 +1104,28 @@ async function runToolInitialization(): Promise<void> {
  * exclusively for test isolation - prevents cross-file contamination
  * when multiple test suites share a single Bun process.
  *
- * Restores core tools from a snapshot taken after the first
- * initializeTools() call, so the reset is synchronous and does not
- * depend on re-running the async init bootstrap.
+ * Re-registers the core manifest tools synchronously (the async workspace /
+ * plugin reconciles are NOT re-run, so their file-backed tools drop out of
+ * the baseline). `registerTool` reuses the finalized instances memoized on
+ * first init, so restored tools keep their identity.
  */
 export function __resetRegistryForTesting(): void {
   tools.clear();
   ownersByName.clear();
   skillRefCount.clear();
   pluginRefCount.clear();
-  // Drop the override stash too — the snapshot already represents the
-  // pre-override baseline, so leaving stashed entries here would let a
-  // later registerWorkspaceTools() falsely report "overridesCore: true"
+  pulledPluginFingerprints.clear();
+  // Drop the override stash too — re-registering the core baseline below
+  // restores the pre-override state, so leaving stashed entries here would let
+  // a later registerWorkspaceTools() falsely report "overridesCore: true"
   // against a fresh registry.
   coreToolOverrides.clear();
   // Clear the cached init promise so a later initializeTools() re-runs against
   // the freshly reset registry rather than returning the previous settled run.
   toolsInitPromise = null;
 
-  if (coreToolsSnapshot) {
-    for (const [name, { tool, owner }] of coreToolsSnapshot) {
-      tools.set(name, tool);
-      ownersByName.set(name, owner);
-    }
+  for (const tool of explicitTools) {
+    registerTool(tool);
   }
 }
 
@@ -1177,17 +1139,7 @@ export function __clearRegistryForTesting(): void {
   ownersByName.clear();
   skillRefCount.clear();
   pluginRefCount.clear();
+  pulledPluginFingerprints.clear();
   coreToolOverrides.clear();
   toolsInitPromise = null;
 }
-
-/**
- * Drop every registered external-tool provider. Exposed exclusively for
- * tests that want to verify a single `registerExternalTools()` call in
- * isolation — the provider array otherwise accumulates across cases
- * because ESM import caching prevents re-running the tool-manifest
- * bootstrap.
- */
-export function __clearExternalToolProvidersForTesting(): void {
-  externalToolProviders.length = 0;
-}

package/src/tools/skills/find-similar-skills.test.ts

@@ -20,13 +20,6 @@ import { describe, expect, mock, test } from "bun:test";
 import type { SkillSource } from "../../config/skills.js";
 import type { OwnerInfo } from "../types.js";
 
-mock.module("../../util/logger.js", () => ({
-  getLogger: () =>
-    new Proxy({} as Record<string, unknown>, {
-      get: () => () => {},
-    }),
-}));
-
 // Map managed skill id → recorded author, consulted by the mocked
 // `readInstallMeta` below. Tests set entries to drive the author join.
 const installMetaAuthors: Record<string, "assistant" | "user" | undefined> = {};

package/src/tools/skills/sandbox-runner.ts

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
 import { safeStringSlice } from "../../util/unicode.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
@@ -148,6 +149,8 @@ function spawnRunner(
       conversationId: context.conversationId,
     });
     env.__CONVERSATION_ID = context.conversationId;
+    // Secret binding for reveal-derived chat authority — see reveal-nonce.ts.
+    env.__REVEAL_NONCE = conversationRevealNonce(context.conversationId);
 
     const child = spawn(wrapped.command, wrapped.args, {
       cwd: runDir,
@@ -255,7 +258,7 @@ function parseSkillResult(
   let searchFrom = stdout.length;
   while (searchFrom > 0) {
     const markerIdx = stdout.lastIndexOf("__skill_result", searchFrom - 1);
-    if (markerIdx === -1) break;
+    if (markerIdx === -1) {break;}
 
     const lineStart = stdout.lastIndexOf("\n", markerIdx) + 1;
     const lineEnd = stdout.indexOf("\n", markerIdx);
@@ -279,7 +282,7 @@ function parseSkillResult(
   searchFrom = stdout.length;
   while (searchFrom > 0) {
     const markerIdx = stdout.lastIndexOf("__skill_error", searchFrom - 1);
-    if (markerIdx === -1) break;
+    if (markerIdx === -1) {break;}
 
     const lineStart = stdout.lastIndexOf("\n", markerIdx) + 1;
     const lineEnd = stdout.indexOf("\n", markerIdx);

package/src/tools/skills/scaffold-managed.ts

@@ -5,14 +5,22 @@ import type { SkillSource } from "../../config/skills.js";
 import { loadSkillCatalog } from "../../config/skills.js";
 import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
+import { upsertSkillCardInsertJob } from "../../persistence/jobs-store.js";
 import { MEMORY_RETROSPECTIVE_ORIGIN } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
 import { readInstallMeta } from "../../skills/install-meta.js";
 import {
   createManagedSkill,
   getManagedSkillDir,
 } from "../../skills/managed-store.js";
+import { recordWatchdogEvent } from "../../telemetry/watchdog-events-store.js";
+import { getLogger } from "../../util/logger.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+const log = getLogger("scaffold-managed-skill");
+
+/** Watchdog check_name for the per-creation skill-authoring counter. */
+const SKILL_AUTHORED_CHECK_NAME = "skill_authored";
+
 /** Strip embedded newlines/carriage returns to prevent YAML frontmatter injection. */
 function sanitizeFrontmatterValue(value: string): string {
   return value.replace(/[\r\n]+/g, " ").trim();
@@ -33,7 +41,9 @@ function normalizeOptionalStringArray(
   raw: unknown,
   field: string,
 ): { value?: string[]; error?: string } {
-  if (raw === undefined) return {};
+  if (raw === undefined) {
+    return {};
+  }
   if (!Array.isArray(raw)) {
     return { error: `${field} must be an array of strings` };
   }
@@ -47,7 +57,9 @@ function normalizeOptionalStringArray(
     if (!cleaned) {
       return { error: `each element in ${field} must be a non-empty string` };
     }
-    if (seen.has(cleaned)) continue;
+    if (seen.has(cleaned)) {
+      continue;
+    }
     seen.add(cleaned);
     normalized.push(cleaned);
   }
@@ -195,6 +207,15 @@ export async function executeScaffoldManagedSkill(
     context.requestOrigin === MEMORY_RETROSPECTIVE_ORIGIN;
   const author = fromRetrospective ? "assistant" : "user";
 
+  // Whether a managed SKILL.md already existed before this call. Drives the
+  // ownership backstop below, the created-vs-refined discriminant for the
+  // skill-card enqueue, and the `skill_authored` telemetry counter: only a
+  // genuine CREATE (no pre-existing skill, regardless of the `overwrite`
+  // flag) gets a card or a counter event.
+  const managedSkillExistedBefore = existsSync(
+    join(getManagedSkillDir(id), "SKILL.md"),
+  );
+
   // Ownership backstop (retrospective origin only): the retrospective may author
   // a skill ONLY if it owns it. Fail closed on either of two collisions.
   if (fromRetrospective) {
@@ -223,11 +244,9 @@ export async function executeScaffoldManagedSkill(
     // exactly "assistant". This fails closed on user-authored, untagged, and
     // unverifiable (missing/corrupt meta) managed skills alike, matching the
     // prune side where such skills are never pruned.
-    const managedDir = getManagedSkillDir(id);
-    const managedSkillExists = existsSync(join(managedDir, "SKILL.md"));
     if (
-      managedSkillExists &&
-      readInstallMeta(managedDir)?.author !== "assistant"
+      managedSkillExistedBefore &&
+      readInstallMeta(getManagedSkillDir(id))?.author !== "assistant"
     ) {
       return {
         content: `Error: skill "${id}" is not verifiably assistant-authored; the retrospective may not overwrite it or write companion files into it. Author a new skill instead.`,
@@ -255,15 +274,21 @@ export async function executeScaffoldManagedSkill(
     }
   }
 
+  // Normalized frontmatter values, shared by the persisted SKILL.md and the
+  // skill-card payload below so the card always shows the values as persisted.
+  const normalizedName = sanitizeFrontmatterValue(name);
+  const normalizedDescription = sanitizeFrontmatterValue(description);
+  const normalizedEmoji =
+    typeof input.emoji === "string"
+      ? sanitizeFrontmatterValue(input.emoji)
+      : undefined;
+
   const result = createManagedSkill({
     id,
-    name: sanitizeFrontmatterValue(name),
-    description: sanitizeFrontmatterValue(description),
+    name: normalizedName,
+    description: normalizedDescription,
     bodyMarkdown: bodyMarkdown,
-    emoji:
-      typeof input.emoji === "string"
-        ? sanitizeFrontmatterValue(input.emoji)
-        : undefined,
+    emoji: normalizedEmoji,
     overwrite: input.overwrite === true,
     includes,
     activationHints,
@@ -281,6 +306,74 @@ export async function executeScaffoldManagedSkill(
 
   refreshSkillCapabilityMemories();
 
+  // Central adoption counter for skill authoring (admin analytics groups on
+  // the watchdog check_name). Genuine creates only — refinements of a
+  // pre-existing skill are not new capabilities and would double-count.
+  // `authored_by` distinguishes proactive retrospective authoring from
+  // user-directed scaffolds; the skill id itself stays out of the detail
+  // bag — ids derive from user/model content (a name can encode a
+  // customer or procedure), and watchdog events are metadata-only with no
+  // deletion-redaction tie to the source conversation. Never throws: a
+  // telemetry failure must not fail a scaffold that already succeeded.
+  if (!managedSkillExistedBefore) {
+    try {
+      recordWatchdogEvent({
+        checkName: SKILL_AUTHORED_CHECK_NAME,
+        value: 1,
+        detail: {
+          authored_by: fromRetrospective ? "retrospective" : "user",
+        },
+      });
+    } catch {
+      // recordWatchdogEvent already no-ops on opt-out and a missing
+      // telemetry DB; anything past that is not worth surfacing here.
+    }
+  }
+
+  // Surface a genuine retrospective CREATE to the user as a skill card on the
+  // source conversation, via the durable `skill_card_insert` delivery job
+  // (memory-retrospective-skill-card.ts). The creation site is the one place
+  // that knows created-vs-refined (`managedSkillExistedBefore` — an
+  // `overwrite: true` call on a skill that did not previously exist is still a
+  // create), the request origin, and the fork-parent lineage as facts.
+  // Refinements of a pre-existing skill never get a card, and delivery needs a
+  // resolved source conversation to land in. Best-effort: an enqueue failure
+  // must never fail the scaffold — the skill is already created.
+  if (
+    fromRetrospective &&
+    !managedSkillExistedBefore &&
+    sourceConversationId &&
+    retrospectiveConversationId
+  ) {
+    try {
+      upsertSkillCardInsertJob({
+        sourceConversationId,
+        runConversationId: retrospectiveConversationId,
+        skills: [
+          {
+            skillId: id,
+            name: normalizedName,
+            description: normalizedDescription,
+            ...(normalizedEmoji ? { emoji: normalizedEmoji } : {}),
+          },
+        ],
+      });
+      log.info(
+        {
+          skillId: id,
+          sourceConversationId,
+          runConversationId: retrospectiveConversationId,
+        },
+        "skill card: enqueued skill_card_insert for retrospective-authored skill",
+      );
+    } catch (err) {
+      log.warn(
+        { err, skillId: id, sourceConversationId },
+        "skill card: failed to enqueue skill_card_insert; skill creation unaffected",
+      );
+    }
+  }
+
   return {
     content: JSON.stringify({
       created: true,