feat: M16 content_migrated + swarm_* analytics events

src/server/infra/process/feature-handlers.ts

@@ -90,6 +90,7 @@ import {
   SourceHandler,
   SpaceHandler,
   StatusHandler,
+  SwarmHandler,
   TeamHandler,
   VcHandler,
   WorktreeHandler,
@@ -567,6 +568,13 @@ export async function setupFeatureHandlers({
   new WorktreeHandler({analyticsClient, resolveProjectPath, transport}).setup()
   new SourceHandler({analyticsClient, resolveProjectPath, transport}).setup()
 
+  // Swarm handler — thin emit surface for federated memory-provider events
+  // (M16.9 / M16.10 / M16.11). The CLI swarm commands and LLM swarm_* tools
+  // run their coordinator client-side and dispatch terminal-state events
+  // through this handler. See `swarm-handler.ts` docblock for the forward
+  // direction (moving the coordinator into the daemon process).
+  new SwarmHandler({analyticsClient, transport}).setup()
+
   log('Feature handlers registered')
 
   // M12.3: expose the cached-analytics check so daemon-side consumers

src/server/infra/transport/handlers/analytics-handler.ts

@@ -9,6 +9,7 @@ import {AuthLogoutSchema} from '../../../../shared/analytics/events/auth-logout.
 import {BrvInitSchema} from '../../../../shared/analytics/events/brv-init.js'
 import {CliInvocationSchema} from '../../../../shared/analytics/events/cli-invocation.js'
 import {ConnectorInstalledSchema} from '../../../../shared/analytics/events/connector-installed.js'
+import {ContentMigratedSchema} from '../../../../shared/analytics/events/content-migrated.js'
 import {ContextTreeFileEditedSchema} from '../../../../shared/analytics/events/context-tree-file-edited.js'
 import {CurateOperationAppliedSchema} from '../../../../shared/analytics/events/curate-operation-applied.js'
 import {CurateRunCompletedSchema} from '../../../../shared/analytics/events/curate-run-completed.js'
@@ -158,6 +159,13 @@ export class AnalyticsHandler {
         break
       }
 
+      case AnalyticsEventNames.CONTENT_MIGRATED: {
+        const props = ContentMigratedSchema.safeParse(rawProperties ?? {})
+        if (!props.success) return
+        this.analyticsClient.track(AnalyticsEventNames.CONTENT_MIGRATED, props.data)
+        break
+      }
+
       case AnalyticsEventNames.CONTEXT_TREE_FILE_EDITED: {
         const props = ContextTreeFileEditedSchema.safeParse(rawProperties ?? {})
         if (!props.success) return

src/server/infra/transport/handlers/index.ts

@@ -46,6 +46,8 @@ export {SpaceHandler} from './space-handler.js'
 export type {SpaceHandlerDeps} from './space-handler.js'
 export {StatusHandler} from './status-handler.js'
 export type {StatusHandlerDeps} from './status-handler.js'
+export {SwarmHandler} from './swarm-handler.js'
+export type {SwarmHandlerDeps} from './swarm-handler.js'
 export {TeamHandler} from './team-handler.js'
 export type {TeamHandlerDeps} from './team-handler.js'
 export {VcHandler} from './vc-handler.js'

src/server/infra/transport/handlers/swarm-handler.ts

@@ -0,0 +1,120 @@
+/**
+ * Handler for `swarm:*` transport events.
+ *
+ * Thin emit surface for the federated-memory-provider operations
+ * (`brv swarm query`, `brv swarm curate`, `brv swarm onboard`). The
+ * coordinator itself still lives in the agent process at
+ * `src/agent/infra/swarm/swarm-coordinator.ts` — the daemon does NOT
+ * proxy the operations today. The CLI commands run swarm-coordinator
+ * client-side and dispatch one of these three transport events to
+ * the daemon when the operation terminates. The handler validates
+ * the payload against the per-event Zod schema and forwards to
+ * `analyticsClient.track()`.
+ *
+ * Mirrors the try/processLog pattern from `SettingsHandler` and
+ * `MigrateHandler` so analytics failures never affect command
+ * outcomes — the CLI gets `tracked: false` plus a reason; nothing
+ * throws.
+ *
+ * Forward direction (out of scope for this commit): if the swarm
+ * coordinator is moved into the daemon process, the SAME three event
+ * names extend to carry the operation request payloads. Only the
+ * handler internals change; CLI / LLM-tool callers stay unchanged.
+ */
+
+import type {
+  SwarmTrackOnboardedRequest,
+  SwarmTrackQueryCompletedRequest,
+  SwarmTrackResponse,
+  SwarmTrackStoreCompletedRequest,
+} from '../../../../shared/transport/events/swarm-events.js'
+import type {IAnalyticsClient} from '../../../core/interfaces/analytics/i-analytics-client.js'
+import type {ITransportServer} from '../../../core/interfaces/transport/i-transport-server.js'
+
+import {AnalyticsEventNames} from '../../../../shared/analytics/event-names.js'
+import {SwarmOnboardedSchema} from '../../../../shared/analytics/events/swarm-onboarded.js'
+import {SwarmQueryCompletedSchema} from '../../../../shared/analytics/events/swarm-query-completed.js'
+import {SwarmStoreCompletedSchema} from '../../../../shared/analytics/events/swarm-store-completed.js'
+import {SwarmEvents} from '../../../../shared/transport/events/swarm-events.js'
+import {processLog} from '../../../utils/process-logger.js'
+
+export interface SwarmHandlerDeps {
+  /**
+   * Optional — when undefined the handler still registers the transport
+   * events but returns `{tracked: false, reason: 'analytics-unavailable'}`
+   * for every call. Lets the wiring exist before analytics is plumbed
+   * in test harnesses.
+   */
+  readonly analyticsClient?: IAnalyticsClient
+  transport: ITransportServer
+}
+
+export class SwarmHandler {
+  private readonly analyticsClient: IAnalyticsClient | undefined
+  private readonly transport: ITransportServer
+
+  constructor(deps: SwarmHandlerDeps) {
+    this.analyticsClient = deps.analyticsClient
+    this.transport = deps.transport
+  }
+
+  setup(): void {
+    this.transport.onRequest<SwarmTrackQueryCompletedRequest, SwarmTrackResponse>(
+      SwarmEvents.TRACK_QUERY_COMPLETED,
+      (data) => this.handleTrackQueryCompleted(data),
+    )
+    this.transport.onRequest<SwarmTrackStoreCompletedRequest, SwarmTrackResponse>(
+      SwarmEvents.TRACK_STORE_COMPLETED,
+      (data) => this.handleTrackStoreCompleted(data),
+    )
+    this.transport.onRequest<SwarmTrackOnboardedRequest, SwarmTrackResponse>(
+      SwarmEvents.TRACK_ONBOARDED,
+      (data) => this.handleTrackOnboarded(data),
+    )
+  }
+
+  private handleTrackOnboarded(data: SwarmTrackOnboardedRequest): SwarmTrackResponse {
+    const parsed = SwarmOnboardedSchema.safeParse(data)
+    if (!parsed.success) return {reason: 'schema-rejection', tracked: false}
+    return this.runEmit(AnalyticsEventNames.SWARM_ONBOARDED, (client) =>
+      client.track(AnalyticsEventNames.SWARM_ONBOARDED, parsed.data),
+    )
+  }
+
+  private handleTrackQueryCompleted(data: SwarmTrackQueryCompletedRequest): SwarmTrackResponse {
+    // Validate at the transport boundary — the CLI is an external trust
+    // boundary even though we ship it ourselves.
+    const parsed = SwarmQueryCompletedSchema.safeParse(data)
+    if (!parsed.success) return {reason: 'schema-rejection', tracked: false}
+    return this.runEmit(AnalyticsEventNames.SWARM_QUERY_COMPLETED, (client) =>
+      client.track(AnalyticsEventNames.SWARM_QUERY_COMPLETED, parsed.data),
+    )
+  }
+
+  private handleTrackStoreCompleted(data: SwarmTrackStoreCompletedRequest): SwarmTrackResponse {
+    const parsed = SwarmStoreCompletedSchema.safeParse(data)
+    if (!parsed.success) return {reason: 'schema-rejection', tracked: false}
+    return this.runEmit(AnalyticsEventNames.SWARM_STORE_COMPLETED, (client) =>
+      client.track(AnalyticsEventNames.SWARM_STORE_COMPLETED, parsed.data),
+    )
+  }
+
+  /**
+   * Shared try/catch wrapper. The thunk does the literal-narrowed
+   * `track(NAME, props)` call so TS infers `PropsArg<E>` per event — no
+   * generic widening, no `as` cast.
+   */
+  private runEmit(eventLabel: string, fn: (client: IAnalyticsClient) => void): SwarmTrackResponse {
+    const client = this.analyticsClient
+    if (!client) return {reason: 'analytics-unavailable', tracked: false}
+    try {
+      fn(client)
+      return {tracked: true}
+    } catch (error) {
+      processLog(
+        `[Swarm] analytics track ${eventLabel} failed: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      return {reason: 'analytics-throw', tracked: false}
+    }
+  }
+}

src/shared/analytics/event-names.ts

@@ -20,6 +20,7 @@ export const AnalyticsEventNames = {
   BRV_INIT: 'brv_init',
   CLI_INVOCATION: 'cli_invocation',
   CONNECTOR_INSTALLED: 'connector_installed',
+  CONTENT_MIGRATED: 'content_migrated',
   CONTEXT_TREE_FILE_EDITED: 'context_tree_file_edited',
   CURATE_OPERATION_APPLIED: 'curate_operation_applied',
   CURATE_RUN_COMPLETED: 'curate_run_completed',
@@ -43,6 +44,9 @@ export const AnalyticsEventNames = {
   SOURCE_ADDED: 'source_added',
   SOURCE_REMOVED: 'source_removed',
   SPACE_SWITCHED: 'space_switched',
+  SWARM_ONBOARDED: 'swarm_onboarded',
+  SWARM_QUERY_COMPLETED: 'swarm_query_completed',
+  SWARM_STORE_COMPLETED: 'swarm_store_completed',
   TASK_COMPLETED: 'task_completed',
   TASK_CREATED: 'task_created',
   TASK_FAILED: 'task_failed',

src/shared/analytics/events/content-migrated.ts

@@ -0,0 +1,48 @@
+/* eslint-disable camelcase */
+import {z} from 'zod'
+
+/**
+ * Per-event schema for `content_migrated`.
+ *
+ * Admin-op content migration between scopes (e.g. moving curated knowledge
+ * between sources, spaces, or projects). Distinct from `migrate_run`
+ * (ENG-3008 / `migrate-run.ts`) which covers the `brv migrate` MD→HTML
+ * one-shot — that operation lives in `MigrateHandler` and its semantics
+ * are file-format-conversion, not scope-aware data movement.
+ *
+ * `source_kind` / `target_kind` are short enum strings naming the
+ * abstract scope on each side (e.g. `'local'`, `'space'`, `'shared'`).
+ * Kept as `z.string().min(1).max(64)` rather than a closed enum so future
+ * scopes can plug in without a schema migration; the producer is
+ * responsible for taxonomizing.
+ *
+ * Per the M15.1 outcome taxonomy: `outcome: 'success' | 'failure'`,
+ * `failure_kind` populated only on failure. Counts are optional so a
+ * failure path that surfaces before counts are known still emits a
+ * well-formed event.
+ *
+ * SCHEMA-ONLY REGISTRATION TODAY: no daemon-handler emit site exists in
+ * this codebase yet. The producer will land alongside the admin op when
+ * its handler is built. See ENG-2770 for the precedent.
+ */
+const failureKindSchema = z.string().min(1).max(64).optional()
+const countSchema = z.number().int().nonnegative().optional()
+
+export const ContentMigratedSchema = z
+  .object({
+    /** True when the run was a no-write dry run. */
+    dry_run: z.boolean().optional(),
+    /** Counts — optional because failure can surface before they're computed. */
+    duration_ms: z.number().int().nonnegative().optional(),
+    failed: countSchema,
+    failure_kind: failureKindSchema,
+    migrated: countSchema,
+    outcome: z.enum(['success', 'failure']),
+    skipped: countSchema,
+    /** Abstract scope identifiers (e.g. 'local', 'space', 'shared'). Producer-taxonomized. */
+    source_kind: z.string().min(1).max(64),
+    target_kind: z.string().min(1).max(64),
+  })
+  .strict()
+
+export type ContentMigratedProps = z.infer<typeof ContentMigratedSchema>

src/shared/analytics/events/index.ts

@@ -7,6 +7,7 @@ import {type AuthLogoutProps, AuthLogoutSchema} from './auth-logout.js'
 import {type BrvInitProps, BrvInitSchema} from './brv-init.js'
 import {type CliInvocationProps, CliInvocationSchema} from './cli-invocation.js'
 import {type ConnectorInstalledProps, ConnectorInstalledSchema} from './connector-installed.js'
+import {type ContentMigratedProps, ContentMigratedSchema} from './content-migrated.js'
 import {type ContextTreeFileEditedProps, ContextTreeFileEditedSchema} from './context-tree-file-edited.js'
 import {type CurateOperationAppliedProps, CurateOperationAppliedSchema} from './curate-operation-applied.js'
 import {type CurateRunCompletedProps, CurateRunCompletedSchema} from './curate-run-completed.js'
@@ -30,6 +31,9 @@ import {type SettingResetProps, SettingResetSchema} from './setting-reset.js'
 import {type SourceAddedProps, SourceAddedSchema} from './source-added.js'
 import {type SourceRemovedProps, SourceRemovedSchema} from './source-removed.js'
 import {type SpaceSwitchedProps, SpaceSwitchedSchema} from './space-switched.js'
+import {type SwarmOnboardedProps, SwarmOnboardedSchema} from './swarm-onboarded.js'
+import {type SwarmQueryCompletedProps, SwarmQueryCompletedSchema} from './swarm-query-completed.js'
+import {type SwarmStoreCompletedProps, SwarmStoreCompletedSchema} from './swarm-store-completed.js'
 import {type TaskCompletedProps, TaskCompletedSchema} from './task-completed.js'
 import {type TaskCreatedProps, TaskCreatedSchema} from './task-created.js'
 import {type TaskFailedProps, TaskFailedSchema} from './task-failed.js'
@@ -72,6 +76,7 @@ export const ALL_EVENT_SCHEMAS = {
   [AnalyticsEventNames.BRV_INIT]: BrvInitSchema,
   [AnalyticsEventNames.CLI_INVOCATION]: CliInvocationSchema,
   [AnalyticsEventNames.CONNECTOR_INSTALLED]: ConnectorInstalledSchema,
+  [AnalyticsEventNames.CONTENT_MIGRATED]: ContentMigratedSchema,
   [AnalyticsEventNames.CONTEXT_TREE_FILE_EDITED]: ContextTreeFileEditedSchema,
   [AnalyticsEventNames.CURATE_OPERATION_APPLIED]: CurateOperationAppliedSchema,
   [AnalyticsEventNames.CURATE_RUN_COMPLETED]: CurateRunCompletedSchema,
@@ -95,6 +100,9 @@ export const ALL_EVENT_SCHEMAS = {
   [AnalyticsEventNames.SOURCE_ADDED]: SourceAddedSchema,
   [AnalyticsEventNames.SOURCE_REMOVED]: SourceRemovedSchema,
   [AnalyticsEventNames.SPACE_SWITCHED]: SpaceSwitchedSchema,
+  [AnalyticsEventNames.SWARM_ONBOARDED]: SwarmOnboardedSchema,
+  [AnalyticsEventNames.SWARM_QUERY_COMPLETED]: SwarmQueryCompletedSchema,
+  [AnalyticsEventNames.SWARM_STORE_COMPLETED]: SwarmStoreCompletedSchema,
   [AnalyticsEventNames.TASK_COMPLETED]: TaskCompletedSchema,
   [AnalyticsEventNames.TASK_CREATED]: TaskCreatedSchema,
   [AnalyticsEventNames.TASK_FAILED]: TaskFailedSchema,
@@ -128,6 +136,7 @@ export type AnyAnalyticsEvent =
   | {name: typeof AnalyticsEventNames.BRV_INIT; properties: BrvInitProps}
   | {name: typeof AnalyticsEventNames.CLI_INVOCATION; properties: CliInvocationProps}
   | {name: typeof AnalyticsEventNames.CONNECTOR_INSTALLED; properties: ConnectorInstalledProps}
+  | {name: typeof AnalyticsEventNames.CONTENT_MIGRATED; properties: ContentMigratedProps}
   | {name: typeof AnalyticsEventNames.CONTEXT_TREE_FILE_EDITED; properties: ContextTreeFileEditedProps}
   | {name: typeof AnalyticsEventNames.CURATE_OPERATION_APPLIED; properties: CurateOperationAppliedProps}
   | {name: typeof AnalyticsEventNames.CURATE_RUN_COMPLETED; properties: CurateRunCompletedProps}
@@ -151,6 +160,9 @@ export type AnyAnalyticsEvent =
   | {name: typeof AnalyticsEventNames.SOURCE_ADDED; properties: SourceAddedProps}
   | {name: typeof AnalyticsEventNames.SOURCE_REMOVED; properties: SourceRemovedProps}
   | {name: typeof AnalyticsEventNames.SPACE_SWITCHED; properties: SpaceSwitchedProps}
+  | {name: typeof AnalyticsEventNames.SWARM_ONBOARDED; properties: SwarmOnboardedProps}
+  | {name: typeof AnalyticsEventNames.SWARM_QUERY_COMPLETED; properties: SwarmQueryCompletedProps}
+  | {name: typeof AnalyticsEventNames.SWARM_STORE_COMPLETED; properties: SwarmStoreCompletedProps}
   | {name: typeof AnalyticsEventNames.TASK_COMPLETED; properties: TaskCompletedProps}
   | {name: typeof AnalyticsEventNames.TASK_CREATED; properties: TaskCreatedProps}
   | {name: typeof AnalyticsEventNames.TASK_FAILED; properties: TaskFailedProps}

src/shared/analytics/events/swarm-onboarded.ts

@@ -0,0 +1,41 @@
+/* eslint-disable camelcase */
+import {z} from 'zod'
+
+/**
+ * Per-event schema for `swarm_onboarded`.
+ *
+ * Activation entry point for `brv swarm onboard` — fires when the wizard
+ * completes (success path) or aborts (failure path). Swarm counterpart
+ * to M15.2's brv-init / onboarding-completed activation events.
+ *
+ * `swarm_kind` is a short producer-taxonomized string (e.g. `'new'` when
+ * the user scaffolded a fresh config, `'joined'` when they pointed at an
+ * existing swarm). Kept as `z.string().min(1).max(64)` so future flows
+ * plug in without a schema migration.
+ *
+ * `member_count` captures the active-provider count from the resulting
+ * swarm config (e.g. `byterover`, `obsidian`, `gbrain`). Optional —
+ * failure paths may surface before the count is computed.
+ *
+ * SCHEMA-ONLY REGISTRATION TODAY: the swarm onboard surface lives in the
+ * agent process (`src/agent/infra/swarm/wizard/swarm-wizard.ts`), not in
+ * a daemon transport handler. The producer requires either a new daemon
+ * handler that the CLI command calls, or a synthetic-emit pattern (cf.
+ * M17). That wiring is deferred to a follow-up. See ENG-2770 for the
+ * schema-only precedent.
+ */
+const failureKindSchema = z.string().min(1).max(64).optional()
+
+export const SwarmOnboardedSchema = z
+  .object({
+    duration_ms: z.number().int().nonnegative().optional(),
+    failure_kind: failureKindSchema,
+    /** Number of active providers in the resulting swarm config. */
+    member_count: z.number().int().nonnegative().optional(),
+    outcome: z.enum(['success', 'failure']),
+    /** Onboarding flow taxonomy (e.g. 'new', 'joined'). Producer-taxonomized. */
+    swarm_kind: z.string().min(1).max(64).optional(),
+  })
+  .strict()
+
+export type SwarmOnboardedProps = z.infer<typeof SwarmOnboardedSchema>

src/shared/analytics/events/swarm-query-completed.ts

@@ -0,0 +1,50 @@
+/* eslint-disable camelcase */
+import {z} from 'zod'
+
+/**
+ * Per-event schema for `swarm_query_completed`.
+ *
+ * Swarm counterpart to `query_completed` (ENG-2770 / M12) — fires once
+ * per `brv swarm query` invocation OR per `swarm_query` LLM tool call,
+ * covering the read loop across federated memory providers (byterover,
+ * obsidian, gbrain, …) coordinated by `swarm-coordinator.ts`.
+ *
+ * `swarm_scope` is a short producer-taxonomized string describing which
+ * provider set the query spanned: `'local'` (current project only),
+ * `'remote'` (external providers only), or `'mixed'` (both). Kept as
+ * `z.string().min(1).max(64)` so future scope kinds plug in without a
+ * schema migration; the producer is responsible for the taxonomy.
+ *
+ * `tags` / `keywords` / `related` mirror the M12.3 frontmatter-harvest
+ * precedent — when the query fuses results from a Memory-Wiki adapter
+ * that carries those fields, surface them so the funnel stays comparable
+ * to the in-project `query_completed` events.
+ *
+ * Per the M15.1 outcome taxonomy: `outcome: 'success' | 'failure'`,
+ * `failure_kind` populated only on failure. `duration_ms` is required
+ * because the coordinator always knows it by terminal time.
+ *
+ * SCHEMA-ONLY REGISTRATION TODAY: the swarm query surface lives in the
+ * agent process (`src/agent/infra/swarm/swarm-coordinator.ts`), not in
+ * a daemon transport handler. Emit wiring deferred per plan flag #2.
+ */
+const failureKindSchema = z.string().min(1).max(64).optional()
+const stringArraySchema = z.array(z.string().max(256)).max(50).optional()
+
+export const SwarmQueryCompletedSchema = z
+  .object({
+    duration_ms: z.number().int().nonnegative(),
+    failure_kind: failureKindSchema,
+    /** Optional frontmatter harvest (M12.3 parity) for the top-N fused results. */
+    keywords: stringArraySchema,
+    outcome: z.enum(['success', 'failure']),
+    related: stringArraySchema,
+    /** Number of fused results returned to the caller. */
+    result_count: z.number().int().nonnegative().optional(),
+    /** Provider-set kind ('local' | 'remote' | 'mixed' | …). Producer-taxonomized. */
+    swarm_scope: z.string().min(1).max(64).optional(),
+    tags: stringArraySchema,
+  })
+  .strict()
+
+export type SwarmQueryCompletedProps = z.infer<typeof SwarmQueryCompletedSchema>