remove refreshes the plugin pipeline; spawned plugins advertise their container name (HOSTNAME)

README.md

@@ -3,17 +3,18 @@
 File-watcher and metadata-extraction service for the MetaMesh ecosystem.
 meta-sort consumes file events from meta-core (over SSE), drives metadata
 through a streaming pipeline + container plugins, and writes results back
-to Redis through meta-core's API. It exposes a Fastify REST API and serves
+to Redis through meta-core's HTTP API. It exposes a Fastify REST API and
-the `/files` volume over WebDAV so that other services and plugin
+reads media exclusively over **meta-core's WebDAV** — it mounts neither
-containers can read media without mounting the same volume.
+`/meta-core` nor `/files`.
 
 > **Service role:** meta-sort is **Redis-consuming**, not Redis-managing.
-> It does not run leader election, it does not spawn Redis, and it does
+> It does not run leader election, it does not spawn Redis, and it has
-> not own `kv-leader.lock`. Those responsibilities belong to **meta-core**
+> no direct Redis connection: every read and write goes through
-> (a separate Go service). meta-sort reads
+> **meta-core** (a separate Go service) over HTTP. meta-sort locates
-> `/meta-core/locks/kv-leader.info` via `LeaderClient` to discover the
+> meta-core over UDP multicast (**beacon v2**,
-> Redis URL, API URL, and WebDAV URLs, and registers its own URLs into
+> `239.255.99.1:9099`) — meta-core's announce carries its API and WebDAV
-> `/meta-core/services/<hostname>.json`.
+> URLs — and announces itself on the same group so sibling dashboards can
+> list it. `META_CORE_URL` pins meta-core and disables wire selection.
 
 ---
 
@@ -29,14 +30,18 @@ What this service does:
 3. **Manages container plugins**: spawns plugin containers via the Docker
    socket, exposes a callback endpoint, lets plugins write metadata back
    into Redis via the meta-core-compatible `/meta/*` API on this service.
-4. **Serves files over WebDAV** at `/webdav/*` so container plugins and
+4. **Computes file identity**: `midhash256` in the light phase, full-file
-   sibling services (meta-fuse, meta-stremio) can read media without
+   digests (sha1, sha256, md5, sha3, crc32, btih v2) in the background
-   needing the underlying bind/SMB/rclone mounts.
+   phase. Digests are persisted only as the bare-CID key-set
+   (`cids/<cid>`), never as per-algorithm `cid_*` fields
+   (`src/config/TargetHash.ts`, `src/kv/MetaCoreApiWriter.ts`).
 
 What this service does **not** do (anymore):
 
 - It does not run leader election.
-- It does not spawn or supervise Redis.
+- It does not spawn or supervise Redis, nor talk to it directly.
+- It does not serve WebDAV — files are read from meta-core's WebDAV, and
+  plugin containers get that same URL (`WEBDAV_URL`).
 - It does not watch the filesystem directly (chokidar lives in meta-core).
 - It does not manage remote mounts (mounts are now in meta-core / rclone-smb).
 - It does not have an in-process plugin runtime — all plugins are
@@ -48,43 +53,46 @@ What this service does **not** do (anymore):
 
 ## Architecture
 
-### Two-volume layout
+### Volumes
 
-meta-sort consumes two host-side volumes via standard bind mounts:
+meta-sort needs **no shared volume**. Media lives on meta-core's
+`FILES_VOLUME` and is read over meta-core's WebDAV; file paths stored in
+Redis are **relative to `/files`**, which keeps storage portable across
+hosts. The only mounts are its own cache (`/data/cache`), the Docker
+socket (for plugin containers) and `plugins.yml`.
 
-| Volume | Container path | Owner | Purpose |
+### Locating meta-core (beacon v2)
-|--------|----------------|-------|---------|
-| `META_CORE_VOLUME` | `/meta-core` | meta-core writes, all services read | Leader-info file, Redis data, service registry, SSE cursor |
-| `FILES_VOLUME`     | `/files`     | meta-sort serves over WebDAV       | Watched media, plugin output, dynamic mounts |
-
-File paths stored in Redis are **relative to `/files`**, which makes the
-storage portable across hosts. See the root `CLAUDE.md` for the
-authoritative volume layout description.
-
-### Leader discovery (read-only)
 
 ```
 meta-core (separate container)
-   ├── runs Redis
+   ├── runs Redis, the file watcher, and the WebDAV server for /files
-   ├── runs file watcher (chokidar) and publishes file:events
+   ├── HTTP API: /urls, /api/events/files (SSE), /meta/*, ...
-   ├── runs HTTP API on /api/urls, /api/events/files, /meta/*, /api/services, ...
+   └── advertises metamesh.core on 239.255.99.1:9099 (UDP multicast),
-   └── writes /meta-core/locks/kv-leader.info
+       carrying its /urls payload (apiUrl, webdavUrl, webdavUrlInternal)
                        │
                        ▼
               meta-sort (this service)
-              ├── LeaderClient reads kv-leader.info → Redis URL, API URL,
+              ├── LeaderClient → MetaCoreLocator (src/discovery/meshdisco.ts)
-              │   WebDAV URLs, etc.
+              │   picks up the core announce (or GET {META_CORE_URL}/urls
-              ├── KVManager creates RedisKVClient (writes are routed
+              │   when pinned) and announces meta-sort on the same group
-              │   through meta-core's HTTP API for the api-mediated-access
+              ├── KVManager builds an HTTP-only RedisKVClient against
-              │   model)
+              │   meta-core's API and configures the WebDAV client
-              ├── ServiceRegistration writes
+              ├── GET /api/neighbors serves the UDP neighbour map (nav menu)
-              │   /meta-core/services/meta-sort-<hostname>.json
               └── FileEventConsumer subscribes to
                   ${apiUrl}/api/events/files (SSE)
 ```
 
-Source: `packages/meta-sort-core/src/kv/{KVManager,LeaderClient,RedisClient,ServiceRegistration}.ts`,
+Source: `packages/meta-sort-core/src/discovery/meshdisco.ts`,
+`packages/meta-sort-core/src/kv/{KVManager,LeaderClient,RedisClient,MetaCoreApiWriter}.ts`,
 `packages/meta-sort-core/src/events/{FileEventConsumer,SSEEventClient}.ts`.
+The protocol spec is `docs/project-architecture/beacon-v2.md` in
+the meta-root. The `meshdisco.ts` port is mirrored across services and
+guarded by the meta-root's `scripts/check-mirrors.sh` — change it there in
+lockstep.
+
+The SSE cursor is persisted to `/meta-core/cursors/meta-sort-files.cursor`
+(`FileEventConsumer.ts` default); since `/meta-core` is no longer mounted,
+that path is container-local and does not survive a container recreate.
 
 ### Processing pipeline
 
@@ -119,7 +127,9 @@ them via the Docker socket and a callback endpoint:
 - **Built-in plugins** (each is a separate git submodule under
   `packages/plugins/metamesh-plugin-*` at the repo root): `file-info`,
   `ffmpeg`, `filename-parser`, `jellyfin-nfo`, `tmdb`, `anime-detector`,
-  `language`, `subtitle`, `subtitle-extractor`, `torrent`, `fullhash`.
+  `language`, `subtitle`, `subtitle-extractor`, `still-extractor`,
+  `opensubtitle`, `torrent`, `fullhash`. Which ones actually run is
+  decided by `plugins.yml` — the image ships none.
 - **Dispatch:** `ContainerPluginScheduler.dispatchAllPlugins(hashId,
   filePath, metaFlat)` — fire-and-forget. The scheduler keeps its own
   fast / background queues based on each plugin manifest's
@@ -128,8 +138,10 @@ them via the Docker socket and a callback endpoint:
   `/api/plugins/callback`, and they can read/write Redis metadata
   through the meta-core-compatible `/meta/:hash` routes that meta-sort
   also exposes (so plugins only need one HTTP target).
-- **Plugins access files** by hitting meta-sort's WebDAV
+- **Plugins access files** over meta-core's WebDAV: each plugin
-  (`http://metasort-app/webdav/...` inside the docker network).
+  container is started with `WEBDAV_URL` (meta-core's
+  `webdavUrlInternal`), `META_CORE_URL` (= `CONTAINER_META_CORE_URL`),
+  `CALLBACK_URL` and `PLUGIN_ID` (`ContainerManager.ts`).
 
 For the plugin HTTP contract, see
 [`docs/containerized-plugin-architecture.md`](docs/containerized-plugin-architecture.md)
@@ -143,15 +155,16 @@ and [`docs/plugin-task-queue-architecture.md`](docs/plugin-task-queue-architectu
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `META_CORE_PATH` | `/meta-core` | Mount of META_CORE_VOLUME. Required — startup fails fast if absent. |
+| `META_CORE_URL` | — | Pins meta-core's API URL; UDP discovery then never overrides it. |
-| `FILES_PATH` | `/files` | Mount of FILES_VOLUME. |
+| `ENABLE_UDP_DISCOVERY` | on | `false`/`0` disables the beacon v2 announce/listen. |
+| `ALLOW_LEGACY_REDIS_URL` | — | `1` downgrades the "meta-core still publishes `redisUrl`" startup error to a warning. |
+| `FILES_PATH` | `/files` | Virtual root that relative paths resolve under (on meta-core's WebDAV). |
 | `CACHE_FOLDER_PATH` | `/data/cache` | Local cache root. |
-| `SERVICE_NAME` | `meta-sort` | Identifier used for service registration. |
+| `SERVICE_NAME` | `meta-sort` | Name announced on the discovery group. |
-| `SERVICE_VERSION` | `1.0.0` | Recorded in the service registry. |
 | `FUSE_API_PORT` | `3000` | HTTP API port (legacy name; this is the Fastify API). |
 | `FUSE_API_HOST` | `0.0.0.0` | API bind host. |
-| `BASE_URL` | — | External base URL recorded in service registration. |
+| `PUBLIC_URL` | — | Browser-facing URL announced for neighbours' nav menus. Wins over `BASE_URL` (use it for a debug-direct port when no Caddy is in front). |
-| `ADVERTISE_HOST` | — | Hostname to advertise to other services. Falls back to auto-detected IP. |
+| `BASE_URL` | — | Perimeter URL announced when `PUBLIC_URL` is unset; falls back to `http://<hostname>:<FUSE_API_PORT>`. |
 | `MAX_WORKER_THREADS` | `os.cpus().length` | If set, overrides all pipeline concurrencies to `(M*2, M, M)`. |
 | `FAST_QUEUE_CONCURRENCY` | `32` | Container-plugin fast queue concurrency (see plugin-task-queue-architecture.md). |
 | `FILE_LIGHT_SLOTS` | `16` | Max files concurrently in the light phase. |
@@ -160,16 +173,22 @@ and [`docs/plugin-task-queue-architecture.md`](docs/plugin-task-queue-architectu
 | `CONTAINER_PLUGINS_CONFIG` | `/app/plugins.yml` | Path to plugin manifest YAML. If missing, container plugins are skipped. |
 | `DOCKER_SOCKET_PATH` | `/var/run/docker.sock` | Docker socket for container management. |
 | `CONTAINER_CALLBACK_URL` | `http://meta-sort:8180` | URL plugins POST callbacks to. |
-| `CONTAINER_META_CORE_URL` | `http://meta-sort` | URL plugins use for meta-core-compatible `/meta/*` routes (served by meta-sort itself for now). |
+| `CONTAINER_META_CORE_URL` | `http://meta-sort` | URL plugins use for meta-core-compatible `/meta/*` routes (served by meta-sort itself). The default host doesn't resolve on current stacks — dev sets `http://metasort-app` (port 80 dev nginx proxies `/meta/`), the store app `http://metasort-app:3000` (the stock nginx has no `/meta/` location). |
 | `CONTAINER_NETWORK` | `meta-network` | Docker network to attach plugin containers to. |
 | `PLUGIN_STACK_NAME` | — | Docker Compose project label so plugin containers group together in Docker Desktop. |
 | `PLUGIN_CACHE_HOST_PATH` | — | Host path bind-mounted into each plugin for persistent caches. |
 
-Source of truth: `packages/meta-sort-core/src/config/EnvConfig.ts`.
+Source of truth: `packages/meta-sort-core/src/config/EnvConfig.ts` (plus
+`PUBLIC_URL` in `kv/KVManager.ts` and `ENABLE_UDP_DISCOVERY` /
+`ALLOW_LEGACY_REDIS_URL` in `kv/LeaderClient.ts`). `META_CORE_PATH`,
+`REDIS_URL`, `ADVERTISE_HOST` and `SERVICE_VERSION` are still parsed by
+`EnvConfig.ts` but nothing acts on them any more. The discovery group
+defaults to the protocol endpoint (`239.255.99.1:9099`, 10 s interval);
+`BEACON_GROUP` / `BEACON_PORT` / `BEACON_INTERVAL_MS` override it.
 
-The Redis URL and WebDAV URLs are **not** configured via environment
+The WebDAV URLs are **not** configured via environment variables —
-variables — meta-sort discovers them from `kv-leader.info` (or its
+meta-sort takes them from meta-core's announce (or `GET /urls` when
-in-memory equivalent fetched through meta-core's `/api/urls`).
+pinned).
 
 ### Concurrency defaults
 
@@ -239,7 +258,9 @@ Defined in `packages/meta-sort-core/src/api/UnifiedAPIServer.ts`.
 | `POST /api/plugins/callback` | Container plugin task-complete callback (used by plugins, not humans). |
 | `GET /api/plugins/containers` | Container-plugin status (health, instances, queue depths). |
 | `GET /api/plugins/containers/:pluginId/manifest` | Plugin manifest. |
+| `GET /api/plugins/containers/:pluginId/logs` | Container logs (`?instance=`, `?tail=`). |
 | `POST /api/plugins/containers/:pluginId/restart` | Restart instances. |
+| `POST /api/plugins/containers/:pluginId/stop` / `start` | Stop / start instances. |
 | `POST /api/plugins/containers/restart-all` | Restart all. |
 | `POST /api/plugins/containers` | Add a new plugin (image, instances, resources, config, defaultQueue). |
 | `PUT /api/plugins/containers/:pluginId` | Update plugin spec. |
@@ -249,9 +270,8 @@ Defined in `packages/meta-sort-core/src/api/UnifiedAPIServer.ts`.
 
 | Endpoint | Description |
 |----------|-------------|
-| `GET /api/file/download?path=...` | Download a file via the configured WebDAV backend. |
+| `GET /api/file/download?path=...` | Download a file via meta-core's WebDAV. |
 | `POST /file/cid` | Compute the CID (midhash256) for a path (`{ path }`). |
-| `GET /webdav/*` (and `PUT`, `DELETE`, `MKCOL`, `PROPFIND`) | WebDAV view of `/files`. Unauthenticated. |
 
 ### meta-core-compatible KV (for container plugins)
 
@@ -272,8 +292,8 @@ single host. They are only registered when the KV client is up.
 | Endpoint | Description |
 |----------|-------------|
 | `GET /api/metrics` | Performance metrics. |
-| `GET /api/stats` | Redis stats summary (only when KV is up). |
+| `GET /api/stats` | File count + total size from meta-core's `/api/files/tuples` summary, cached stale-while-revalidate. |
-| `GET /api/services` | Proxy to meta-core's `/api/services` via the LeaderClient. |
+| `GET /api/neighbors` | beacon v2 neighbour map (nav menu). Served locally — works while meta-core is down. Replaces the removed `/api/services`. |
 
 ---
 
@@ -286,6 +306,18 @@ single host. They are only registered when the KV client is up.
 - Debug-direct backend (no auth, no TLS): `http://localhost:18180`
 - Container name (backend): `metasort-app`
 - Container name (hash-lock proxy): `metasort`
+- CasaOS store app: `MetaSort` in the meta-root's `packages/MetaAppStore`
+  (`ghcr.io/worph/meta-sort`, fronted by an `appshield` perimeter).
+
+### Docker image
+
+The repo `Dockerfile` (published to `ghcr.io/worph/meta-sort` by
+`.github/workflows/docker-publish.yml`) is an all-in-one image: nginx on
+`:80` → Fastify on `:3000`, rclone, and a bundled `meta-core` binary
+copied from `ghcr.io/worph/meta-core` and started by
+`docker/supervisord.conf`. Deployments run meta-core as its own app, so
+both the dev stack and the store app mount their own supervisord/nginx
+configs that drop the bundled meta-core.
 
 ### Logs
 
@@ -310,7 +342,8 @@ cd dev
 ### Running tests
 
 ```bash
-docker exec meta-test-runner /app/test/test.sh sort
+docker exec meta-test-runner /app/test/test.sh sort   # E2E (meta-root dev stack)
+pnpm test                                             # unit tests (@meta-sort/core, mocha)
 ```
 
 See the root `CLAUDE.md` "Running Tests" section for the full matrix.
@@ -336,9 +369,10 @@ packages/meta-sort/
 │   │   │   ├── api/              # UnifiedAPIServer.ts (Fastify)
 │   │   │   ├── config/           # EnvConfig.ts, SupportedFileTypes.ts
 │   │   │   ├── container-plugins/# ContainerManager, ContainerPluginScheduler, ...
+│   │   │   ├── discovery/        # meshdisco.ts (beacon v2, mirrored port)
 │   │   │   ├── events/           # FileEventConsumer, SSEEventClient
 │   │   │   ├── jellyfin/         # Jellyfin / NFO output helpers
-│   │   │   ├── kv/               # KVManager, LeaderClient, RedisClient
+│   │   │   ├── kv/               # KVManager, LeaderClient, RedisClient, MetaCoreApiWriter
 │   │   │   ├── logic/            # StreamingPipeline, state managers, fileProcessor
 │   │   │   ├── metrics/          # PerformanceMetrics
 │   │   │   ├── plugin-engine/    # Vestigial in-process types + TaskScheduler glue
@@ -350,27 +384,28 @@ packages/meta-sort/
 │   ├── meta-sort-ui/             # @meta-sort/ui - React dashboard (Vite)
 │   ├── meta-sort-editor/         # Metadata editor UI (Vite)
 │   ├── async-utils/              # @worph/async-utils - MultiQueue, etc.
-│   └── shared/                   # Symlinks to filename-tool, meta-hash, meta-interface
+│   └── shared/                   # Vendored copies of filename-tool, meta-hash, meta-interface
 ├── pnpm-workspace.yaml
 └── pnpm-lock.yaml
 ```
 
 > Built-in container plugins **do not live here.** They live at the
 > repo root as separate submodules:
-> `packages/plugins/metamesh-plugin-{file-info,ffmpeg,filename-parser,jellyfin-nfo,tmdb,anime-detector,language,subtitle,subtitle-extractor,torrent,fullhash}`.
+> `packages/plugins/metamesh-plugin-{file-info,ffmpeg,filename-parser,jellyfin-nfo,tmdb,anime-detector,language,subtitle,subtitle-extractor,still-extractor,opensubtitle,torrent,fullhash}`.
 
 ### Key components
 
 | Component | File | Purpose |
 |-----------|------|---------|
 | Entry point | `src/index.ts` | Wires KVManager → API server → plugin manager → ContainerManager → StreamingPipeline → FileEventConsumer. |
+| Discovery | `src/discovery/meshdisco.ts` | beacon v2 node + `MetaCoreLocator`. |
 | Streaming pipeline | `src/logic/pipeline/StreamingPipeline.ts` | 3-queue (validation / fast / background) orchestrator. |
 | State manager | `src/logic/UnifiedProcessingStateManager.ts` | Tracks `discovered → lightProcessing → hashProcessing → done`. |
 | File processor | `src/logic/WatchedFileProcessor.ts` | Light + hash phase implementation. |
 | SSE consumer | `src/events/FileEventConsumer.ts` | Translates meta-core events into pipeline calls. |
 | SSE transport | `src/events/SSEEventClient.ts` | Long-lived HTTP SSE with cursor persistence. |
-| KV manager | `src/kv/KVManager.ts` | Bootstraps RedisKVClient + ServiceRegistration from LeaderClient. |
+| KV manager | `src/kv/KVManager.ts` | Bootstraps the HTTP-only RedisKVClient + WebDAV client from LeaderClient. |
-| Leader client | `src/kv/LeaderClient.ts` | Reads `/meta-core/locks/kv-leader.info`, fetches `/api/urls`. |
+| Leader client | `src/kv/LeaderClient.ts` | Legacy name: thin adapter over `MetaCoreLocator` (UDP), or `GET /urls` when `META_CORE_URL` is pinned. |
 | Container manager | `src/container-plugins/ContainerManager.ts` | Docker socket orchestration. |
 | Container scheduler | `src/container-plugins/ContainerPluginScheduler.ts` | Plugin fast/background queues + callbacks. |
 | API server | `src/api/UnifiedAPIServer.ts` | Fastify REST + WebDAV-facing meta routes. |
@@ -393,8 +428,9 @@ Repo-level docs of interest:
 - Root `CLAUDE.md` — authoritative ground truth on the dev stack, ports,
   containers, and operational commands.
 - `/METADATA_KEYS.md` — schema for the `/file/{cid}` Redis hash.
-- `packages/meta-core/docs/` — leader election and Redis storage owner.
+- `packages/meta-core/docs/` — Redis storage owner, api-mediated access.
+- `docs/project-architecture/beacon-v2.md` — beacon v2 spec.
 
 ## License
 
-MIT — see LICENSE.
+MIT (see `package.json`).

packages/meta-sort-core/.mocharc.json

@@ -1,5 +1,10 @@
 {
-  "spec": ["dist/api/api.test.js", "dist/kv/*.test.js"],
+  "spec": [
+    "dist/api/api.test.js",
+    "dist/kv/*.test.js",
+    "dist/container-plugins/*.test.js",
+    "dist/discovery/*.test.js"
+  ],
   "timeout": 30000,
   "exit": true
 }

packages/meta-sort-core/src/api/UnifiedAPIServer.ts

@@ -237,7 +237,7 @@ export class UnifiedAPIServer {
       this.setupStatsRoutes();
     }
 
-    // Service discovery — meta-discovery v1 neighbour list, served from the
+    // Service discovery — beacon v2 neighbour list, served from the
     // LeaderClient to resolve meta-core's current URL dynamically.
     this.setupServiceDiscoveryRoutes();
 
@@ -592,20 +592,23 @@ export class UnifiedAPIServer {
   }
 
   /**
-   * Service discovery — meta-discovery v1. Served from this service's own UDP
+   * Service discovery — beacon v2 (docs/project-architecture/beacon-v2.md).
-   * neighbour map; no meta-core round trip, so the nav survives a core outage.
+   * Served from this service's own beacon view; no meta-core round trip, so
+   * the nav survives a core outage.
    */
   private setupServiceDiscoveryRoutes(): void {
-    // meta-discovery v1: neighbours heard over UDP, served from this service's
+    // beacon v2: neighbours heard over UDP, served from this service's own
-    // own map. Unlike /api/services below it needs no meta-core, so the nav
+    // view. Unlike /api/services below it needs no meta-core, so the nav still
-    // still renders when the core is down. `services` is kept as an alias
+    // renders when the core is down. `?all=1` returns every instance,
+    // `?cap=<pattern>` filters by capability. `services` is kept as an alias
     // while any older dashboard build is still in circulation.
-    this.app.get('/api/neighbors', async (_request, reply) => {
+    this.app.get('/api/neighbors', async (request, reply) => {
       const leaderClient = this.kvManager?.getLeaderClient();
       if (!leaderClient) {
         return reply.send({ current: 'meta-sort', enabled: false, count: 0, neighbors: [] });
       }
-      const neighbors = leaderClient.getNeighbors();
+      const q = (request.query ?? {}) as { all?: string; cap?: string };
+      const neighbors = leaderClient.getNeighbors({ all: !!q.all, cap: q.cap || undefined });
       return reply.send({
         current: 'meta-sort',
         enabled: true,
@@ -1024,7 +1027,9 @@ export class UnifiedAPIServer {
             instanceCount: p.instances,
             healthyCount: p.healthyInstances,
             enabled: p.enabled,
-            image: p.image
+            image: p.image,
+            kind: p.kind,
+            url: p.url
           })),
           queue: queueStatus || null
         };
@@ -1037,6 +1042,67 @@ export class UnifiedAPIServer {
       }
     });
 
+    // Beacon v2 Scan card: enrichment plugins advertising on the network
+    // (metamesh.enrich/<id>), classified against what this meta-sort runs.
+    this.app.post('/api/plugins/discover', async (_request, reply) => {
+      const leaderClient = this.kvManager?.getLeaderClient();
+      const empty = {
+        cap: 'metamesh.enrich/*', disabled: true,
+        summary: { nodes: 0, capable: 0, configured: 0, boundElsewhere: 0, addable: 0 },
+        candidates: [],
+      };
+      if (!leaderClient) return reply.send(empty);
+      const status = this.containerManager?.getStatus();
+      const configured: Array<[string, string]> = (status?.plugins ?? [])
+        .filter((p) => p.url)
+        .map((p) => [p.pluginId, p.url as string]);
+      const report = await leaderClient.scan('metamesh.enrich/*', configured, 1500);
+      // Same plugin id already loaded under another URL (e.g. our own spawned
+      // container of it): adding it would clash, so it counts as configured.
+      const loaded = new Set((status?.plugins ?? []).map((p) => p.pluginId));
+      for (const c of report.candidates) {
+        if (c.state !== 'addable') continue;
+        const id = c.caps.map((cap) => cap.match(/^metamesh\.enrich\/([^@]+)/)?.[1]).find((x) => x && loaded.has(x));
+        if (id) {
+          c.state = 'configured';
+          c.configuredAs = id;
+          report.summary.addable--;
+          report.summary.configured++;
+        }
+      }
+      return reply.send(report);
+    });
+
+    // External plugin (one meta-sort did not spawn) — the Scan card's Add.
+    this.app.post<{ Body: { url?: string; name?: string } }>('/api/plugins/external', async (request, reply) => {
+      if (!this.containerManager) {
+        return reply.status(503).send({ error: 'Container manager not initialized' });
+      }
+      const url = request.body?.url;
+      if (!url) return reply.status(400).send({ error: 'url is required' });
+      try {
+        const entry = await this.containerManager.addExternalPlugin(url, request.body?.name);
+        // Bring it into the processing pipeline (same as /api/plugins/rescan).
+        await this.getPluginManager?.()?.loadContainerPlugins();
+        return { success: true, plugin: entry };
+      } catch (error: any) {
+        return reply.status(400).send({ error: error.message });
+      }
+    });
+
+    this.app.delete<{ Params: { pluginId: string } }>('/api/plugins/external/:pluginId', async (request, reply) => {
+      if (!this.containerManager) {
+        return reply.status(503).send({ error: 'Container manager not initialized' });
+      }
+      try {
+        await this.containerManager.removeExternalPlugin(request.params.pluginId);
+        await this.getPluginManager?.()?.loadContainerPlugins();
+        return { success: true };
+      } catch (error: any) {
+        return reply.status(400).send({ error: error.message });
+      }
+    });
+
     // Get container plugin manifest
     this.app.get<{
       Params: { pluginId: string }
@@ -1181,6 +1247,9 @@ export class UnifiedAPIServer {
 
       try {
         await this.containerManager.removePlugin(pluginId);
+        // Drop it from the processing pipeline too (else it lingers in
+        // /api/plugins until the next rescan or restart).
+        await this.getPluginManager?.()?.loadContainerPlugins();
         return {
           success: true,
           message: `Plugin '${pluginId}' removed successfully`

packages/meta-sort-core/src/config/EnvConfig.ts

@@ -89,6 +89,13 @@ interface EnvConfig {
     /** Path to container plugins config file (default: '/app/plugins.yml') */
     CONTAINER_PLUGINS_CONFIG: string;
 
+    /**
+     * External plugins added by URL from the Plugins page's beacon Scan card
+     * (default: '<CACHE_FOLDER_PATH>/state/external-plugins.json'). Kept apart
+     * from plugins.yml, which the store app mounts read-only.
+     */
+    EXTERNAL_PLUGINS_PATH: string;
+
     /** Docker socket path (default: '/var/run/docker.sock') */
     DOCKER_SOCKET_PATH: string;
 
@@ -156,6 +163,8 @@ export const config: EnvConfig = {
 
     // Container Plugins Configuration
     CONTAINER_PLUGINS_CONFIG: process.env.CONTAINER_PLUGINS_CONFIG || '/app/plugins.yml',
+    EXTERNAL_PLUGINS_PATH: process.env.EXTERNAL_PLUGINS_PATH
+        || `${process.env.CACHE_FOLDER_PATH || '/data/cache'}/state/external-plugins.json`,
     DOCKER_SOCKET_PATH: process.env.DOCKER_SOCKET_PATH || '/var/run/docker.sock',
     CONTAINER_CALLBACK_URL: process.env.CONTAINER_CALLBACK_URL || 'http://meta-sort:8180',
     CONTAINER_META_CORE_URL: process.env.CONTAINER_META_CORE_URL || 'http://meta-sort',

packages/meta-sort-core/src/container-plugins/ContainerManager.ts

@@ -25,6 +25,9 @@ import type {
     PluginConfigureResponse,
 } from './types.js';
 import { config } from '../config/EnvConfig.js';
+import { existsSync } from 'fs';
+import { hostname } from 'os';
+import { ExternalPluginStore, type ExternalPluginEntry } from './ExternalPluginStore.js';
 
 /**
  * Service info structure from meta-core service discovery
@@ -96,6 +99,11 @@ export class ContainerManager extends EventEmitter {
     private stackName?: string;
     private callbackUrl: string;
     private metaCoreUrl: string;
+    /** External plugins (added by URL); see ExternalPluginStore. */
+    private externalStore: ExternalPluginStore;
+    private externalEntries: ExternalPluginEntry[] = [];
+    /** False when Docker is unreachable: only external plugins run then. */
+    private dockerAvailable = false;
 
     constructor(
         private configPath: string = config.CONTAINER_PLUGINS_CONFIG,
@@ -116,6 +124,12 @@ export class ContainerManager extends EventEmitter {
 
         // Configure stack name for Docker Desktop grouping
         this.stackName = config.PLUGIN_STACK_NAME;
+        this.externalStore = new ExternalPluginStore(config.EXTERNAL_PLUGINS_PATH);
+    }
+
+    /** Swap the external-plugin store (tests). */
+    setExternalStore(store: ExternalPluginStore): void {
+        this.externalStore = store;
     }
 
     /**
@@ -183,22 +197,41 @@ export class ContainerManager extends EventEmitter {
             console.warn('  Plugins will not have access to files.');
         }
 
-        // Initialize Docker client
+        // Docker is needed only for the plugins we spawn. Without it (no
+        // socket, permission denied) external plugins still run.
+        try {
             await this.dockerClient.initialize();
-
-        // Ensure network exists
             await this.dockerClient.ensureNetwork(this.network);
+            this.dockerAvailable = true;
+        } catch (error) {
+            console.warn('[ContainerManager] Docker unavailable — only external plugins will run:', error);
+        }
 
-        // Load configuration
+        // Load configuration. A missing or broken plugins.yml means "no
+        // spawned plugins", not "no plugin manager": external plugins can
+        // still be added from the UI.
+        if (existsSync(this.configPath)) {
+            try {
                 this.pluginsConfig = await loadConfig(this.configPath);
+            } catch (error) {
+                console.error(`[ContainerManager] Ignoring ${this.configPath}:`, error);
+            }
+        } else {
+            console.log(`[ContainerManager] No ${this.configPath}; no spawned plugins`);
+        }
+        if (!this.pluginsConfig) {
+            this.pluginsConfig = { version: '1.0', plugins: {} };
+        }
 
         // Get enabled plugins
-        const enabledPlugins = getEnabledPlugins(this.pluginsConfig);
+        const enabledPlugins = this.dockerAvailable ? getEnabledPlugins(this.pluginsConfig) : [];
 
         console.log(`[ContainerManager] Found ${enabledPlugins.length} enabled plugins`);
 
+        if (this.dockerAvailable) {
             // Clean up any stale containers from previous runs
             await this.cleanupStaleContainers();
+        }
 
         // Spawn containers for each enabled plugin
         for (const { id, config: pluginConfig } of enabledPlugins) {
@@ -213,6 +246,21 @@ export class ContainerManager extends EventEmitter {
             }
         }
 
+        // External plugins (added by URL). One unreachable at boot is
+        // registered anyway and picked up by the health loop when it appears.
+        this.externalEntries = await this.externalStore.load();
+        for (const entry of this.externalEntries.filter((e) => e.enabled)) {
+            if (this.instances.has(entry.pluginId)) {
+                console.warn(
+                    `[ContainerManager] External plugin '${entry.pluginId}' (${entry.url}) skipped: ` +
+                    'a spawned plugin already has that id'
+                );
+                continue;
+            }
+            this.attachExternal(entry);
+        }
+        console.log(`[ContainerManager] ${this.externalEntries.length} external plugin(s) configured`);
+
         this.initialized = true;
         this.emit('manager:initialized', { pluginCount: enabledPlugins.length });
 
@@ -415,6 +463,14 @@ export class ContainerManager extends EventEmitter {
                 CALLBACK_URL: this.callbackUrl,
                 WEBDAV_URL: this.webdavUrl || '',
                 FILES_PATH: '/files', // Virtual path - files accessed via WebDAV
+                // Beacon v2: advertise the URL we reach it on (so a Scan shows it
+                // as configured), and only to this meta-sort (another one's
+                // Scan shows it as bound elsewhere, never addable).
+                BEACON_ADVERTISE_URL: `http://${containerName}:8080`,
+                BEACON_BINDS: hostname(),
+                // Docker's own HOSTNAME is the container id; advertise a name
+                // an operator can read in the Scan card.
+                HOSTNAME: containerName,
             },
             // Docker Desktop grouping
             stackName: this.stackName,
@@ -427,6 +483,7 @@ export class ContainerManager extends EventEmitter {
         // Create instance record
         const instance: ContainerPluginInstance = {
             pluginId,
+            kind: 'container',
             containerId,
             containerName,
             baseUrl: `http://${containerName}:8080`,
@@ -445,6 +502,12 @@ export class ContainerManager extends EventEmitter {
      * Stop a container instance
      */
     private async stopInstance(instance: ContainerPluginInstance): Promise<void> {
+        if (instance.kind === 'external') {
+            // Not ours to stop: just stop using it.
+            instance.status = 'stopped';
+            this.emit('plugin:stopped', { pluginId: instance.pluginId, instanceIndex: instance.instanceIndex });
+            return;
+        }
         console.log(`[ContainerManager] Stopping ${instance.containerName}...`);
 
         try {
@@ -490,6 +553,11 @@ export class ContainerManager extends EventEmitter {
                     if (healthy) {
                         instance.status = 'healthy';
                         instance.lastHealthCheck = Date.now();
+                        // An external plugin unreachable at boot has no manifest
+                        // yet; the scheduler needs one.
+                        if (!instance.manifest) {
+                            instance.manifest = await this.fetchManifest(instance).catch(() => undefined);
+                        }
 
                         if (previousStatus !== 'healthy') {
                             this.emit('plugin:healthy', { pluginId, instance });
@@ -609,9 +677,12 @@ export class ContainerManager extends EventEmitter {
             throw new Error(`Failed to configure plugin: ${response.status}`);
         }
 
+        // Two contracts in the wild: `{ success: true }` and the TS plugins'
+        // `{ status: 'ok' }`. Before both were accepted every configure of a
+        // TS plugin "failed" (silently, behind a try/warn).
         const data = (await response.json()) as PluginConfigureResponse;
-        if (!data.success) {
+        if (!data.success && data.status !== 'ok') {
-            throw new Error(`Plugin configuration failed: ${data.error}`);
+            throw new Error(`Plugin configuration failed: ${data.error ?? JSON.stringify(data)}`);
         }
     }
 
@@ -678,11 +749,14 @@ export class ContainerManager extends EventEmitter {
         for (const [pluginId, instances] of this.instances) {
             const pluginConfig = this.pluginsConfig?.plugins[pluginId];
             const healthyCount = instances.filter((i) => i.status === 'healthy').length;
+            const external = instances[0]?.kind === 'external';
 
             plugins.push({
                 pluginId,
                 enabled: pluginConfig?.enabled !== false,
-                image: pluginConfig?.image || 'unknown',
+                image: external ? instances[0].baseUrl : pluginConfig?.image || 'unknown',
+                kind: external ? 'external' : 'container',
+                url: instances[0]?.baseUrl,
                 instances: instances.length,
                 healthyInstances: healthyCount,
                 manifest: instances[0]?.manifest,
@@ -717,6 +791,16 @@ export class ContainerManager extends EventEmitter {
         const instances = this.instances.get(pluginId);
         const pluginConfig = this.pluginsConfig?.plugins[pluginId];
 
+        if (instances?.[0]?.kind === 'external') {
+            // Nothing to respawn: re-probe it and refresh its manifest.
+            for (const instance of instances) {
+                const healthy = await this.checkHealth(instance);
+                instance.status = healthy ? 'healthy' : 'unhealthy';
+                if (healthy) instance.manifest = await this.fetchManifest(instance).catch(() => instance.manifest);
+            }
+            return;
+        }
+
         if (!instances || !pluginConfig) {
             throw new Error(`Plugin '${pluginId}' not found`);
         }
@@ -779,6 +863,93 @@ export class ContainerManager extends EventEmitter {
         }
     }
 
+    /** The external plugins, as persisted. */
+    getExternalPlugins(): ExternalPluginEntry[] {
+        return [...this.externalEntries];
+    }
+
+    /**
+     * Register an external plugin (one meta-sort did not spawn) by URL — what
+     * the beacon Scan card's Add does. Its manifest id becomes its plugin id,
+     * so it must be reachable now and its id must not clash with a loaded one.
+     */
+    async addExternalPlugin(rawUrl: string, name?: string): Promise<ExternalPluginEntry> {
+        const url = rawUrl.trim().replace(/\/+$/, '');
+        if (!/^https?:\/\//.test(url)) {
+            throw new Error('url must start with http:// or https://');
+        }
+        for (const list of this.instances.values()) {
+            const holder = list.find((i) => i.baseUrl.replace(/\/+$/, '') === url);
+            if (holder) throw new Error(`${url} is already registered as '${holder.pluginId}'`);
+        }
+        const probe: ContainerPluginInstance = {
+            pluginId: '?', kind: 'external', containerId: '', containerName: url, baseUrl: url,
+            instanceIndex: 0, status: 'starting', tasksProcessed: 0, tasksFailed: 0,
+        };
+        let manifest: ContainerPluginManifest;
+        try {
+            manifest = await this.fetchManifest(probe);
+        } catch (error) {
+            throw new Error(`could not read ${url}/manifest: ${error instanceof Error ? error.message : error}`);
+        }
+        const pluginId = manifest?.id;
+        if (!pluginId || !/^[a-z][a-z0-9-]*$/.test(pluginId)) {
+            throw new Error(`${url}/manifest has no usable plugin id`);
+        }
+        if (this.instances.has(pluginId)) {
+            throw new Error(`a plugin with id '${pluginId}' is already loaded`);
+        }
+        const entry: ExternalPluginEntry = {
+            pluginId, url, enabled: true, name: name?.trim() || undefined, addedAt: new Date().toISOString(),
+        };
+        this.externalEntries = [...this.externalEntries.filter((e) => e.pluginId !== pluginId), entry];
+        await this.externalStore.save(this.externalEntries);
+        this.attachExternal(entry, manifest);
+        console.log(`[ContainerManager] External plugin '${pluginId}' added (${url})`);
+        return entry;
+    }
+
+    /** Forget an external plugin. Throws if `pluginId` is not one. */
+    async removeExternalPlugin(pluginId: string): Promise<void> {
+        const known = this.externalEntries.some((e) => e.pluginId === pluginId);
+        const instances = this.instances.get(pluginId);
+        if (!known && !(instances?.[0]?.kind === 'external')) {
+            throw new Error(`'${pluginId}' is not an external plugin`);
+        }
+        if (instances?.[0]?.kind === 'external') {
+            const interval = this.healthCheckIntervals.get(pluginId);
+            if (interval) {
+                clearInterval(interval);
+                this.healthCheckIntervals.delete(pluginId);
+            }
+            for (const instance of instances) await this.stopInstance(instance);
+            this.instances.delete(pluginId);
+            this.roundRobinCounters.delete(pluginId);
+        }
+        this.externalEntries = this.externalEntries.filter((e) => e.pluginId !== pluginId);
+        await this.externalStore.save(this.externalEntries);
+        console.log(`[ContainerManager] External plugin '${pluginId}' removed`);
+    }
+
+    /** One instance pointing at `entry.url`, kept alive by the health loop. */
+    private attachExternal(entry: ExternalPluginEntry, manifest?: ContainerPluginManifest): void {
+        const instance: ContainerPluginInstance = {
+            pluginId: entry.pluginId,
+            kind: 'external',
+            containerId: '',
+            // The scheduler reports completions by this name; the URL is unique.
+            containerName: entry.url,
+            baseUrl: entry.url,
+            instanceIndex: 0,
+            status: 'starting',
+            manifest,
+            tasksProcessed: 0,
+            tasksFailed: 0,
+        };
+        this.instances.set(entry.pluginId, [instance]);
+        this.startHealthCheck(entry.pluginId);
+    }
+
     /**
      * Add a new plugin dynamically
      */
@@ -838,6 +1009,11 @@ export class ContainerManager extends EventEmitter {
         console.log(`[ContainerManager] Removing plugin '${pluginId}'...`);
 
         const instances = this.instances.get(pluginId);
+        // An external plugin is forgotten (and un-persisted), never stopped.
+        if (instances?.[0]?.kind === 'external' || this.externalEntries.some((e) => e.pluginId === pluginId)) {
+            await this.removeExternalPlugin(pluginId);
+            return;
+        }
 
         if (instances) {
             // Stop health check

packages/meta-sort-core/src/container-plugins/ExternalPluginStore.ts

@@ -0,0 +1,52 @@
+/**
+ * External plugins — enrichment plugins meta-sort did NOT spawn, reached by
+ * URL (typically a MetaPlugin* store app found with the Plugins page's beacon
+ * Scan card). Persisted as JSON next to the cache, because the store app
+ * mounts plugins.yml read-only.
+ */
+
+import { promises as fs } from 'fs';
+import { dirname } from 'path';
+
+export interface ExternalPluginEntry {
+    /** The plugin's manifest id — its identity in the pipeline. */
+    pluginId: string;
+    /** Base URL of the plugin's HTTP contract (/manifest, /health, /process). */
+    url: string;
+    enabled: boolean;
+    /** Name it was added under (the advertising instance), display only. */
+    name?: string;
+    addedAt?: string;
+}
+
+export class ExternalPluginStore {
+    constructor(private readonly path: string) {}
+
+    /** The persisted list; empty when the file is missing or unreadable. */
+    async load(): Promise<ExternalPluginEntry[]> {
+        let raw: string;
+        try {
+            raw = await fs.readFile(this.path, 'utf-8');
+        } catch {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            const list = Array.isArray(parsed?.plugins) ? parsed.plugins : [];
+            return list.filter(
+                (e: Partial<ExternalPluginEntry>) => typeof e?.pluginId === 'string' && typeof e?.url === 'string'
+            ).map((e: ExternalPluginEntry) => ({ ...e, enabled: e.enabled !== false }));
+        } catch (error) {
+            console.error(`[ExternalPluginStore] ${this.path} is not valid JSON; ignoring it:`, error);
+            return [];
+        }
+    }
+
+    /** Atomic write: a crash mid-save leaves the previous file intact. */
+    async save(entries: ExternalPluginEntry[]): Promise<void> {
+        await fs.mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify({ plugins: entries }, null, 2), 'utf-8');
+        await fs.rename(tmp, this.path);
+    }
+}

packages/meta-sort-core/src/container-plugins/ExternalPlugins.test.ts

@@ -0,0 +1,74 @@
+import { strict as assert } from 'assert';
+import { createServer, type Server } from 'http';
+import { mkdtempSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { ContainerManager } from './ContainerManager.js';
+import { ExternalPluginStore } from './ExternalPluginStore.js';
+
+/**
+ * External plugins are the meta-sort side of the beacon Scan card's Add: a
+ * plugin meta-sort did not spawn, reached by URL, identified by its manifest
+ * id, persisted outside the read-only plugins.yml.
+ */
+describe('external plugins', () => {
+    let server: Server;
+    let url: string;
+
+    before(async () => {
+        server = createServer((req, res) => {
+            res.setHeader('Content-Type', 'application/json');
+            if (req.url === '/manifest') {
+                res.end(JSON.stringify({ id: 'language', name: 'Language', version: '1.0.2', defaultQueue: 'fast' }));
+            } else if (req.url === '/health') {
+                res.end(JSON.stringify({ status: 'healthy', ready: true, version: '1.0.2' }));
+            } else {
+                res.statusCode = 404;
+                res.end('{}');
+            }
+        });
+        await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()));
+        const addr = server.address();
+        url = `http://127.0.0.1:${typeof addr === 'object' && addr ? addr.port : 0}`;
+    });
+
+    after(() => server.close());
+
+    function manager(path: string): ContainerManager {
+        const m = new ContainerManager('/nonexistent/plugins.yml', 'none', '/files', 'http://cb', 'http://core');
+        m.setExternalStore(new ExternalPluginStore(path));
+        return m;
+    }
+
+    it('adds by URL under the manifest id, persists, and refuses duplicates', async () => {
+        const path = join(mkdtempSync(join(tmpdir(), 'ext-')), 'state', 'external-plugins.json');
+        const m = manager(path);
+        const entry = await m.addExternalPlugin(`${url}/`, 'metapluginlanguage-plugin');
+        assert.equal(entry.pluginId, 'language');
+        assert.equal(entry.url, url, 'trailing slash normalised');
+
+        const saved = JSON.parse(readFileSync(path, 'utf-8'));
+        assert.equal(saved.plugins[0].pluginId, 'language');
+
+        await assert.rejects(m.addExternalPlugin(url), /already registered/);
+        const status = m.getStatus().plugins.find((p) => p.pluginId === 'language');
+        assert.equal(status?.kind, 'external');
+        assert.equal(status?.url, url);
+
+        await m.removeExternalPlugin('language');
+        assert.equal(m.getStatus().plugins.length, 0);
+        assert.deepEqual(JSON.parse(readFileSync(path, 'utf-8')).plugins, []);
+        await assert.rejects(m.removeExternalPlugin('language'), /not an external plugin/);
+    });
+
+    it('rejects a URL whose manifest cannot be read', async () => {
+        const m = manager(join(mkdtempSync(join(tmpdir(), 'ext-')), 'x.json'));
+        await assert.rejects(m.addExternalPlugin('http://127.0.0.1:9/'), /could not read/);
+        await assert.rejects(m.addExternalPlugin('ftp://x'), /http/);
+    });
+
+    it('a missing or corrupt store reads as empty', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'ext-'));
+        assert.deepEqual(await new ExternalPluginStore(join(dir, 'missing.json')).load(), []);
+    });
+});

packages/meta-sort-core/src/container-plugins/types.ts

@@ -164,7 +164,12 @@ export type ContainerInstanceStatus = 'starting' | 'healthy' | 'unhealthy' | 'st
 export interface ContainerPluginInstance {
     /** Plugin ID */
     pluginId: string;
-    /** Docker container ID */
+    /**
+     * `container` = spawned by meta-sort from plugins.yml; `external` = added by
+     * URL (beacon Scan card), not ours to start or stop. Absent = container.
+     */
+    kind?: 'container' | 'external';
+    /** Docker container ID ('' for an external plugin) */
     containerId: string;
     /** Container name (e.g., 'meta-plugin-ffmpeg-0') */
     containerName: string;
@@ -211,7 +216,9 @@ export interface PluginConfigureRequest {
  * Configure response from POST /configure
  */
 export interface PluginConfigureResponse {
-    success: boolean;
+    /** Older contract. The TS plugins answer `{ status: 'ok' }` instead. */
+    success?: boolean;
+    status?: string;
     error?: string;
 }
 
@@ -315,7 +322,11 @@ export interface ContainerManagerStatus {
     plugins: Array<{
         pluginId: string;
         enabled: boolean;
+        /** Docker image, or the plugin URL for an external plugin. */
         image: string;
+        kind: 'container' | 'external';
+        /** Base URL of the first instance. */
+        url?: string;
         instances: number;
         healthyInstances: number;
         manifest?: ContainerPluginManifest;

packages/meta-sort-core/src/discovery/meshdisco.test.ts

@@ -0,0 +1,30 @@
+import { strict as assert } from 'assert';
+import { capMatches, classifyScan, suggestedName, type MeshNeighbor } from './meshdisco.js';
+
+/** Mirrors meta-feeder-sdk `beacon::scan` tests: same rules, same JSON. */
+describe('beacon v2 scan classification', () => {
+    const node = (instance: string, cap: string, http?: string, binds?: string): MeshNeighbor => ({
+        name: 'plugin', instance, caps: [cap], addr: '10.0.0.1', lastSeen: 0,
+        resources: [{ id: 'x', caps: [cap], ...(http ? { endpoints: { http } } : {}), ...(binds ? { binds } : {}) }],
+    });
+
+    it('classifies configured, addable and bound-elsewhere', () => {
+        const r = classifyScan('metamesh.enrich/*', 'metasort-app', [
+            node('meta-plugin-language-0', 'metamesh.enrich/language', 'http://meta-plugin-language-0:8080/', 'metasort-app'),
+            node('metapluginffmpeg-plugin', 'metamesh.enrich/ffmpeg', 'http://metapluginffmpeg-plugin:8080'),
+            node('other-sort-plugin', 'metamesh.enrich/tmdb', 'http://x:8080', 'other-metasort'),
+            node('no-endpoint', 'metamesh.enrich/tmdb'),
+            node('a-service', 'metamesh.service/meta-core', 'http://core'),
+        ], [['language', 'http://meta-plugin-language-0:8080']]);
+        assert.deepEqual(r.summary, { nodes: 5, capable: 3, configured: 1, boundElsewhere: 1, addable: 1 });
+        assert.equal(r.candidates[0].instance, 'metapluginffmpeg-plugin');
+        assert.equal(r.candidates[1].configuredAs, 'language');
+        assert.equal(r.candidates[2].state, 'bound-elsewhere');
+    });
+
+    it('caps and names', () => {
+        assert.ok(capMatches('metamesh.enrich/*', 'metamesh.enrich/language@1'));
+        assert.ok(!capMatches('metamesh.enrich/*', 'metamesh.enrichx/a'));
+        assert.equal(suggestedName('MetaPlugin Language'), 'metaplugin-language');
+    });
+});

packages/meta-sort-core/src/discovery/meshdisco.ts

@@ -1,14 +1,14 @@
 /**
- * meta-discovery v1 — UDP multicast service discovery.
+ * Beacon v2 — local resource advertise / discover over UDP multicast
+ * (239.255.99.1:9099).
  *
- * Replaces the two file-based mechanisms that required a shared /meta-core
+ * Every node advertises resources tagged with capability strings
- * volume: `locks/kv-leader.info` (locating meta-core at boot) and
+ * (`metamesh.core`, `metamesh.service/meta-sort`, `metamesh.transport/nzb@1`)
- * `services/<name>-<host>.json` (the dashboard nav registry). Both answered the
+ * and keeps a live view of everyone else's. This service uses it to locate
- * same question — where is meta-core, and who else is on this network — so one
+ * meta-core (the `metamesh.core` resource carries its /urls block) and to feed
- * announce packet answers both, and discovery scope becomes the docker network
+ * the nav menu (`metamesh.service/*`), with no shared volume.
- * rather than the mounted volume.
  *
- * The normative spec is docs/project-architecture/service-discovery.md.
+ * The normative spec is docs/project-architecture/beacon-v2.md.
  *
  * ⚠ MIRRORED FILE. Byte-identical copies live in meta-sort-core, meta-fuse-core
  * and meta-dup-core. They cannot share a package: meta-fuse-core and
@@ -21,17 +21,23 @@
 import dgram from 'dgram';
 import { hostname, networkInterfaces } from 'os';
 
-export const PROTOCOL_VERSION = 1;
+export const PROTO = 'beacon';
-export const DEFAULT_GROUP = '239.255.77.1';
+export const VERSION = 2;
-export const DEFAULT_PORT = 9399;
+export const DEFAULT_GROUP = '239.255.99.1';
+export const DEFAULT_PORT = 9099;
 export const DEFAULT_INTERVAL_MS = 10_000;
-/** A neighbour unseen for interval × this is dropped. Replaces the reaper. */
+/** A node unheard for interval × this is dropped (evaluated at read time). */
 export const LIVENESS_FACTOR = 3;
+/** Senders stay under this so nothing fragments. */
+export const MAX_DATAGRAM = 1400;
 
-export const TYPE_DISCOVERY = 'discovery';
+export const TYPE_PROBE = 'probe';
-export const TYPE_ANNOUNCE = 'announce';
+export const TYPE_ADVERTISE = 'advertise';
-export const ROLE_CORE = 'core';
+export const TYPE_BYE = 'bye';
-export const ROLE_SERVICE = 'service';
+
+export const CAP_CORE = 'metamesh.core';
+export const CAP_SERVICE_PREFIX = 'metamesh.service/';
+export const CAP_ANY_SERVICE = 'metamesh.service/*';
 
 /** Mirrors meta-core's GET /urls response minus redisUrl (retired). */
 export interface MeshUrls {
@@ -42,38 +48,193 @@ export interface MeshUrls {
     webdavUrlInternal: string;
 }
 
-export interface MeshMessage {
+export interface BeaconNodeInfo {
-    v: number;
+    name: string;
-    type: string;
+    instance: string;
-    name?: string;
-    instance?: string;
-    role?: string;
     version?: string;
+    /** 'starting' | 'running'; absent reads as running. */
     status?: string;
-    baseUrl?: string;
-    /** Present only when role === 'core'. */
-    urls?: MeshUrls;
-    /** Reserved for a future HMAC; v1 ignores it. */
-    token?: string;
 }
 
-export interface MeshNeighbor extends MeshMessage {
+export interface BeaconResource {
+    id: string;
+    caps: string[];
+    /** Well-known: http, ui, manifest, mcp. A '/…' value is relative to http. */
+    endpoints?: Record<string, string>;
+    rev?: string;
+    /** The one consumer instance this resource belongs to. */
+    binds?: string;
+    data?: Record<string, unknown>;
+}
+
+export interface BeaconMessage {
+    proto: string;
+    v: number;
+    type: string;
+    node?: BeaconNodeInfo;
+    resources?: BeaconResource[];
+    from?: string;
+    want?: string[];
+}
+
+/** A node as served by /api/neighbors. */
+export interface MeshNeighbor extends BeaconNodeInfo {
+    resources: BeaconResource[];
+    /** Every resource's caps, flattened. */
+    caps: string[];
+    /** The metamesh.service/* resource's endpoints.ui (v1-compatible field). */
+    baseUrl?: string;
     /** Source address taken from the packet, never from the payload. */
     addr: string;
+    /** Unix seconds. */
     lastSeen: number;
 }
 
 export interface MeshNodeConfig {
     name: string;
     instance?: string;
-    role?: string;
     version?: string;
     group?: string;
     port?: number;
     intervalMs?: number;
     enabled?: boolean;
-    /** Rebuilt on every announce so the payload never goes stale. */
+    /** Rebuilt on every advertise so the payload never goes stale. */
-    payload?: () => { baseUrl?: string; status?: string; urls?: MeshUrls };
+    payload?: () => { status?: string; resources: BeaconResource[] };
+}
+
+/** How a discovered resource relates to this consumer (Scan card). */
+export type ScanState = 'configured' | 'addable' | 'bound-elsewhere';
+
+export interface ScanCandidate {
+    instance: string;
+    name: string;
+    version?: string;
+    resourceId: string;
+    caps: string[];
+    /** endpoints.http — what the consumer would register. */
+    url: string;
+    binds?: string;
+    state: ScanState;
+    /** The list entry that already holds this URL (state `configured`). */
+    configuredAs?: string;
+    /** A list-safe name to register it under. */
+    suggestedName: string;
+}
+
+/** Same JSON as meta-feeder-sdk `beacon::ScanReport`. */
+export interface ScanReport {
+    cap: string;
+    self: string;
+    durationMs: number;
+    summary: { nodes: number; capable: number; configured: number; boundElsewhere: number; addable: number };
+    candidates: ScanCandidate[];
+}
+
+/** Lower-case, `[a-z0-9._-]` only — accepted by every consumer's name rules. */
+export function suggestedName(instance: string): string {
+    const s = instance.trim().toLowerCase().replace(/[^a-z0-9._-]/g, '-');
+    return s || 'plugin';
+}
+
+const normUrl = (u: string) => u.trim().replace(/\/+$/, '');
+
+/**
+ * Classify every resource matching `pattern` against the consumer's
+ * `(name, url)` list. Mirrors meta-feeder-sdk `beacon::classify`.
+ */
+export function classifyScan(
+    pattern: string,
+    self: string,
+    neighbors: MeshNeighbor[],
+    configured: Array<[string, string]>,
+): ScanReport {
+    const summary = { nodes: neighbors.length, capable: 0, configured: 0, boundElsewhere: 0, addable: 0 };
+    const candidates: ScanCandidate[] = [];
+    for (const n of neighbors) {
+        for (const r of n.resources) {
+            if (!resourceMatches(r, pattern)) continue;
+            const http = resourceEndpoint(r, 'http');
+            if (!http) continue; // nothing a consumer could register
+            const url = normUrl(http);
+            summary.capable++;
+            const hit = configured.find(([, u]) => normUrl(u) === url);
+            let state: ScanState;
+            if (hit) { state = 'configured'; summary.configured++; }
+            else if (r.binds && r.binds !== self) { state = 'bound-elsewhere'; summary.boundElsewhere++; }
+            else { state = 'addable'; summary.addable++; }
+            candidates.push({
+                instance: n.instance,
+                name: n.name,
+                ...(n.version ? { version: n.version } : {}),
+                resourceId: r.id,
+                caps: r.caps ?? [],
+                url,
+                ...(r.binds ? { binds: r.binds } : {}),
+                state,
+                ...(hit ? { configuredAs: hit[0] } : {}),
+                suggestedName: suggestedName(n.instance),
+            });
+        }
+    }
+    const rank: Record<ScanState, number> = { addable: 0, configured: 1, 'bound-elsewhere': 2 };
+    candidates.sort((a, b) => rank[a.state] - rank[b.state] || a.instance.localeCompare(b.instance));
+    return { cap: pattern, self, durationMs: 0, summary, candidates };
+}
+
+/**
+ * Does capability `cap` satisfy `pattern`? `*` matches everything; an `@N` on
+ * the pattern must equal the cap's contract (none ignores it); `x/*` matches
+ * any variant of `x`; otherwise the bases must be equal.
+ */
+export function capMatches(pattern: string, cap: string): boolean {
+    if (pattern === '*') return true;
+    const split = (s: string): [string, string | null] => {
+        const i = s.lastIndexOf('@');
+        return i >= 0 ? [s.slice(0, i), s.slice(i + 1)] : [s, null];
+    };
+    const [pbase, pc] = split(pattern);
+    const [cbase, cc] = split(cap);
+    if (pc !== null && cc !== pc) return false;
+    if (pbase.endsWith('/*')) {
+        const prefix = pbase.slice(0, -2);
+        if (!cbase.startsWith(prefix)) return false;
+        const rest = cbase.slice(prefix.length);
+        return rest.startsWith('/') && rest.length > 1;
+    }
+    return pbase === cbase;
+}
+
+export function resourceMatches(r: BeaconResource, pattern: string): boolean {
+    return (r.caps ?? []).some((c) => capMatches(pattern, c));
+}
+
+/** The named endpoint as an absolute URL ('/…' joins onto endpoints.http). */
+export function resourceEndpoint(r: BeaconResource, name: string): string | undefined {
+    const v = r.endpoints?.[name];
+    if (!v) return undefined;
+    if (!v.startsWith('/')) return v;
+    const base = r.endpoints?.http;
+    return base ? base.replace(/\/+$/, '') + v : undefined;
+}
+
+/**
+ * Decode a datagram; null for anything that is not a well-formed beacon v2
+ * message (beacon v1, meta-discovery v1, other versions, junk).
+ */
+export function parseMessage(buf: Buffer): BeaconMessage | null {
+    let m: BeaconMessage;
+    try {
+        m = JSON.parse(buf.toString('utf8')) as BeaconMessage;
+    } catch {
+        return null;
+    }
+    if (!m || m.proto !== PROTO || m.v !== VERSION) return null;
+    if (m.type === TYPE_PROBE) return m;
+    if (m.type === TYPE_ADVERTISE || m.type === TYPE_BYE) {
+        if (!m.node?.name || !m.node?.instance) return null;
+        return m;
+    }
+    return null;
 }
 
 /** IPv4 addresses of every up, non-internal interface. */
@@ -96,15 +257,44 @@ export function localIPv4(): string {
     return localInterfaceAddresses()[0] ?? hostname();
 }
 
+function envNum(key: string): number | undefined {
+    const n = Number(process.env[key]);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+interface Seen {
+    node: BeaconNodeInfo;
+    resources: BeaconResource[];
+    addr: string;
+    lastSeen: number; // ms
+}
+
+function toNeighbor(s: Seen): MeshNeighbor {
+    const caps: string[] = [];
+    let baseUrl: string | undefined;
+    for (const r of s.resources) {
+        for (const c of r.caps ?? []) if (!caps.includes(c)) caps.push(c);
+        if (!baseUrl && resourceMatches(r, CAP_ANY_SERVICE)) baseUrl = resourceEndpoint(r, 'ui');
+    }
+    return {
+        ...s.node,
+        resources: s.resources,
+        caps,
+        ...(baseUrl ? { baseUrl } : {}),
+        addr: s.addr,
+        lastSeen: s.lastSeen / 1000,
+    };
+}
+
 /**
- * One participant in the mesh: announces itself, answers probes, and keeps a
+ * One beacon v2 participant: advertises its resources, answers probes, and
- * TTL map of everyone else.
+ * keeps a TTL map of every other node.
  */
 export class MeshNode {
     private cfg: Required<Omit<MeshNodeConfig, 'payload'>> & Pick<MeshNodeConfig, 'payload'>;
     private socket: dgram.Socket | null = null;
     private timer: NodeJS.Timeout | null = null;
-    private neighbors = new Map<string, MeshNeighbor>();
+    private nodes = new Map<string, Seen>();
     private ifaceAddrs: string[] = [];
     private listeners: ((n: MeshNeighbor) => void)[] = [];
     private started = false;
@@ -113,11 +303,10 @@ export class MeshNode {
         this.cfg = {
             name: config.name,
             instance: config.instance ?? hostname(),
-            role: config.role ?? ROLE_SERVICE,
             version: config.version ?? '',
-            group: config.group ?? DEFAULT_GROUP,
+            group: config.group ?? process.env.BEACON_GROUP ?? DEFAULT_GROUP,
-            port: config.port ?? DEFAULT_PORT,
+            port: config.port ?? envNum('BEACON_PORT') ?? DEFAULT_PORT,
-            intervalMs: config.intervalMs ?? DEFAULT_INTERVAL_MS,
+            intervalMs: config.intervalMs ?? envNum('BEACON_INTERVAL_MS') ?? DEFAULT_INTERVAL_MS,
             enabled: config.enabled ?? true,
             payload: config.payload,
         };
@@ -125,12 +314,14 @@ export class MeshNode {
 
     async start(): Promise<void> {
         if (this.started || !this.cfg.enabled) {
-            if (!this.cfg.enabled) console.log('[meshdisco] Disabled by configuration');
+            if (!this.cfg.enabled) console.log('[beacon] Disabled by configuration');
             return;
         }
         this.started = true;
 
         await new Promise<void>((resolve) => {
+            // reuseAddr sets SO_REUSEADDR (+ SO_REUSEPORT on Linux for udp4),
+            // so several listeners can share 9099 on one host.
             const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
             this.socket = socket;
 
@@ -138,14 +329,14 @@ export class MeshNode {
             socket.on('error', (err) => {
                 // Never fatal: a host that blocks multicast must degrade, not
                 // take the service down.
-                console.error('[meshdisco] Socket error:', err.message);
+                console.error('[beacon] Socket error:', err.message);
             });
 
             socket.bind(this.cfg.port, '0.0.0.0', () => {
                 try {
                     socket.setMulticastTTL(1); // link-local only
                 } catch (e) {
-                    console.warn('[meshdisco] Could not set multicast TTL:', e);
+                    console.warn('[beacon] Could not set multicast TTL:', e);
                 }
 
                 // Join on EVERY interface. A container on two docker networks
@@ -157,20 +348,20 @@ export class MeshNode {
                         socket.addMembership(this.cfg.group, addr);
                         joined++;
                     } catch (e) {
-                        console.warn(`[meshdisco] Join ${this.cfg.group} on ${addr} failed:`, e);
+                        console.warn(`[beacon] Join ${this.cfg.group} on ${addr} failed:`, e);
                     }
                 }
                 console.log(
-                    `[meshdisco] Listening on ${this.cfg.group}:${this.cfg.port} as ` +
+                    `[beacon] Listening on ${this.cfg.group}:${this.cfg.port} as ` +
                     `${this.cfg.name}/${this.cfg.instance} (joined ${joined} of ${this.ifaceAddrs.length} interfaces)`
                 );
                 resolve();
             });
         });
 
-        this.announce();
+        this.advertise();
         this.probe();
-        this.timer = setInterval(() => this.announce(), this.cfg.intervalMs);
+        this.timer = setInterval(() => this.advertise(), this.cfg.intervalMs);
         // Don't hold the event loop open on shutdown.
         this.timer.unref?.();
     }
@@ -179,9 +370,9 @@ export class MeshNode {
         if (!this.started) return;
         this.started = false;
         if (this.timer) { clearInterval(this.timer); this.timer = null; }
-        // Final "stopping" announce so neighbours drop us immediately rather
+        // Bye, so neighbours drop us immediately rather than waiting out the
-        // than waiting out the staleness window.
+        // staleness window.
-        this.announce('stopping');
+        this.multicast({ proto: PROTO, v: VERSION, type: TYPE_BYE, node: this.nodeInfo() });
         await new Promise<void>((resolve) => {
             if (!this.socket) return resolve();
             try { this.socket.close(() => resolve()); } catch { resolve(); }
@@ -190,135 +381,150 @@ export class MeshNode {
         this.listeners = [];
     }
 
-    /** Multicast a probe; every listener replies immediately. */
+    /**
-    probe(): void {
+     * Multicast a probe. Every node owning a resource matching one of `want`
-        this.send({ v: PROTOCOL_VERSION, type: TYPE_DISCOVERY });
+     * (every node, when empty) replies immediately.
+     */
+    probe(want: string[] = []): void {
+        const msg: BeaconMessage = { proto: PROTO, v: VERSION, type: TYPE_PROBE, from: this.cfg.instance };
+        if (want.length) msg.want = want;
+        this.multicast(msg);
     }
 
-    /** Everyone heard from inside the staleness window, sorted by name. */
+    /** Every live node, sorted by (name, instance). */
     getNeighbors(): MeshNeighbor[] {
         const cutoff = Date.now() - this.cfg.intervalMs * LIVENESS_FACTOR;
         const out: MeshNeighbor[] = [];
-        for (const [key, nb] of this.neighbors) {
+        for (const [key, s] of this.nodes) {
-            if (nb.lastSeen < cutoff) { this.neighbors.delete(key); continue; }
+            if (s.lastSeen < cutoff) { this.nodes.delete(key); continue; }
-            out.push(nb);
+            out.push(toNeighbor(s));
         }
-        return out.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
+        return out.sort((a, b) => a.name.localeCompare(b.name) || a.instance.localeCompare(b.instance));
     }
 
-    /** One row per service name, most recently seen instance wins. */
+    /** One row per node name, most recently seen instance wins. */
     getNeighborsByName(): MeshNeighbor[] {
         const best = new Map<string, MeshNeighbor>();
         for (const nb of this.getNeighbors()) {
-            const cur = best.get(nb.name ?? '');
+            const cur = best.get(nb.name);
-            if (!cur || nb.lastSeen > cur.lastSeen) best.set(nb.name ?? '', nb);
+            if (!cur || nb.lastSeen > cur.lastSeen) best.set(nb.name, nb);
         }
-        return [...best.values()].sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
+        return [...best.values()].sort((a, b) => a.name.localeCompare(b.name));
     }
 
-    /** Cores only — what a locator filters on. */
+    /**
-    getCores(): MeshNeighbor[] {
+     * The Scan card: probe everyone, wait `waitMs` for the replies, then
-        return this.getNeighbors().filter((n) => n.role === ROLE_CORE && n.urls);
+     * classify what matches `pattern` against `configured` ([name, url]).
+     */
+    async scan(pattern: string, configured: Array<[string, string]>, waitMs = 1500): Promise<ScanReport> {
+        const started = Date.now();
+        this.probe();
+        await new Promise((r) => setTimeout(r, waitMs));
+        const report = classifyScan(pattern, this.cfg.instance, this.getNeighbors(), configured);
+        report.durationMs = Date.now() - started;
+        return report;
     }
 
-    /** This node's own announce, so a UI can render itself without waiting. */
+    /** This node as a row, so a UI can render itself without waiting. */
     self(): MeshNeighbor {
-        return { ...this.buildAnnounce('running'), addr: '', lastSeen: Date.now() };
+        const { status, resources } = this.payload();
+        return toNeighbor({ node: this.nodeInfo(status), resources, addr: '', lastSeen: Date.now() });
     }
 
-    /** Fires for every announce received (after the self-echo filter). */
+    /** Fires for every advertise received (after the self-echo filter). */
-    onAnnounce(cb: (n: MeshNeighbor) => void): void {
+    onAdvertise(cb: (n: MeshNeighbor) => void): void {
         this.listeners.push(cb);
     }
 
-    private onMessage(buf: Buffer, rinfo: dgram.RemoteInfo): void {
+    private payload(): { status?: string; resources: BeaconResource[] } {
-        let msg: MeshMessage;
+        return this.cfg.payload ? this.cfg.payload() : { resources: [] };
-        try {
-            msg = JSON.parse(buf.toString('utf8')) as MeshMessage;
-        } catch {
-            return; // foreign traffic on the group
     }
-        if (msg.v !== PROTOCOL_VERSION) return;
-        // Drop our own multicast echo.
-        if (msg.instance && msg.instance === this.cfg.instance && msg.name === this.cfg.name) return;
 
-        if (msg.type === TYPE_DISCOVERY) {
+    private nodeInfo(status?: string): BeaconNodeInfo {
-            this.replyTo(rinfo);
+        const n: BeaconNodeInfo = { name: this.cfg.name, instance: this.cfg.instance };
+        if (this.cfg.version) n.version = this.cfg.version;
+        if (status) n.status = status;
+        return n;
+    }
+
+    private advertiseMsg(): BeaconMessage {
+        const { status, resources } = this.payload();
+        return { proto: PROTO, v: VERSION, type: TYPE_ADVERTISE, node: this.nodeInfo(status), resources };
+    }
+
+    private onMessage(buf: Buffer, rinfo: dgram.RemoteInfo): void {
+        const msg = parseMessage(buf);
+        if (!msg) return; // v1 or foreign traffic on the shared group
+
+        if (msg.type === TYPE_PROBE) {
+            if (msg.from === this.cfg.instance) return;
+            const ad = this.advertiseMsg();
+            const want = msg.want ?? [];
+            const wanted = want.length === 0 ||
+                (ad.resources ?? []).some((r) => want.some((p) => resourceMatches(r, p)));
+            if (wanted) this.replyTo(ad, rinfo);
             return;
         }
-        if (msg.type !== TYPE_ANNOUNCE || !msg.name) return;
 
-        const key = msg.instance ? `${msg.name}|${msg.instance}` : msg.name;
+        const node = msg.node!;
-        if (msg.status === 'stopping') { this.neighbors.delete(key); return; }
+        if (node.instance === this.cfg.instance) return; // our own echo
+        if (msg.type === TYPE_BYE) { this.nodes.delete(node.instance); return; }
 
-        const nb: MeshNeighbor = { ...msg, addr: rinfo.address, lastSeen: Date.now() };
+        const seen: Seen = { node, resources: msg.resources ?? [], addr: rinfo.address, lastSeen: Date.now() };
-        this.neighbors.set(key, nb);
+        this.nodes.set(node.instance, seen);
+        const nb = toNeighbor(seen);
         for (const cb of this.listeners) {
-            try { cb(nb); } catch (e) { console.error('[meshdisco] Listener threw:', e); }
+            try { cb(nb); } catch (e) { console.error('[beacon] Listener threw:', e); }
         }
     }
 
-    private buildAnnounce(status: string): MeshMessage {
+    private encode(msg: BeaconMessage): Buffer {
-        const msg: MeshMessage = {
+        const body = Buffer.from(JSON.stringify(msg));
-            v: PROTOCOL_VERSION,
+        if (body.length > MAX_DATAGRAM) {
-            type: TYPE_ANNOUNCE,
+            console.warn(`[beacon] ${body.length}-byte datagram exceeds the fragmentation-safe ${MAX_DATAGRAM}`);
-            name: this.cfg.name,
-            instance: this.cfg.instance,
-            role: this.cfg.role,
-            version: this.cfg.version,
-            status,
-        };
-        if (this.cfg.payload) {
-            const p = this.cfg.payload();
-            if (p.baseUrl) msg.baseUrl = p.baseUrl;
-            if (p.status && status === 'running') msg.status = p.status;
-            // Only a core may carry a URLs block — a service announcing one
-            // would let any container impersonate meta-core.
-            if (this.cfg.role === ROLE_CORE && p.urls) msg.urls = p.urls;
         }
-        return msg;
+        return body;
     }
 
-    private announce(status = 'running'): void {
+    private advertise(): void {
-        this.send(this.buildAnnounce(status));
+        this.multicast(this.advertiseMsg());
     }
 
-    private replyTo(rinfo: dgram.RemoteInfo): void {
+    private replyTo(msg: BeaconMessage, rinfo: dgram.RemoteInfo): void {
-        const body = Buffer.from(JSON.stringify(this.buildAnnounce('running')));
         try {
-            this.socket?.send(body, rinfo.port, rinfo.address);
+            this.socket?.send(this.encode(msg), rinfo.port, rinfo.address);
         } catch (e) {
-            console.warn('[meshdisco] Reply failed:', e);
+            console.warn('[beacon] Reply failed:', e);
         }
     }
 
     /** Writes once per interface — the default route alone reaches one network. */
-    private send(msg: MeshMessage): void {
+    private multicast(msg: BeaconMessage): void {
         const socket = this.socket;
         if (!socket) return;
-        const body = Buffer.from(JSON.stringify(msg));
+        const body = this.encode(msg);
         for (const addr of this.ifaceAddrs) {
             try {
                 socket.setMulticastInterface(addr);
                 socket.send(body, this.cfg.port, this.cfg.group);
             } catch (e) {
-                console.warn(`[meshdisco] Send on ${addr} failed:`, e);
+                console.warn(`[beacon] Send on ${addr} failed:`, e);
             }
         }
     }
 }
 
 export interface MetaCoreLocatorConfig {
-    /** This service's name, for its own announce. */
+    /** This service's name, for its own advertise. */
     serviceName: string;
     /** Browser-facing URL for the nav menu. */
     baseUrl?: string;
     version?: string;
     /**
      * Explicit meta-core API URL. When set this ALWAYS wins and the wire is
-     * never consulted for core selection — see the spec's "the pin always
+     * never consulted for core selection — see the spec's "the
-     * wins". This is what stops a client box from latching onto a gateway
+     * metamesh.core pin". This is what stops a client box from latching onto a
-     * box's core when both are reachable on a shared network.
+     * gateway box's core when both are reachable on a shared network.
      */
     metaCoreUrl?: string;
     group?: string;
@@ -328,8 +534,9 @@ export interface MetaCoreLocatorConfig {
 }
 
 /**
- * Locates meta-core over UDP, replacing the read of
+ * Locates meta-core over beacon v2 (the first `metamesh.core` resource that
- * /meta-core/locks/kv-leader.info.
+ * carries `data.urls`), and advertises this service as
+ * `metamesh.service/<serviceName>`.
  */
 export class MetaCoreLocator {
     private node: MeshNode;
@@ -341,35 +548,42 @@ export class MetaCoreLocator {
         this.cfg = config;
         this.node = new MeshNode({
             name: config.serviceName,
-            role: ROLE_SERVICE,
             version: config.version,
             group: config.group,
             port: config.port,
             intervalMs: config.intervalMs,
             enabled: config.enabled,
-            payload: () => ({ baseUrl: config.baseUrl ?? `http://${localIPv4()}` }),
+            payload: () => ({
+                resources: [{
+                    id: 'service',
+                    caps: [CAP_SERVICE_PREFIX + config.serviceName],
+                    endpoints: { ui: config.baseUrl ?? `http://${localIPv4()}` },
+                }],
+            }),
         });
 
-        this.node.onAnnounce((nb) => {
+        this.node.onAdvertise((nb) => {
-            if (nb.role !== ROLE_CORE || !nb.urls) return;
             if (this.cfg.metaCoreUrl) return; // pinned: the wire cannot move us
+            const core = nb.resources.find((r) => resourceMatches(r, CAP_CORE));
+            const urls = core?.data?.urls as MeshUrls | undefined;
+            if (!urls?.apiUrl) return;
 
             const prev = this.current;
             if (!prev) {
-                this.current = nb.urls;
+                this.current = urls;
-                console.log(`[meshdisco] meta-core discovered at ${nb.urls.apiUrl} (${nb.addr})`);
+                console.log(`[beacon] meta-core discovered at ${urls.apiUrl} (${nb.addr})`);
                 this.notifyChange();
                 return;
             }
-            if (prev.apiUrl === nb.urls.apiUrl) {
+            if (prev.apiUrl === urls.apiUrl) {
-                this.current = nb.urls; // refresh the rest of the fields
+                this.current = urls; // refresh the rest of the fields
                 return;
             }
-            // A second, different core is announcing. Do not flap between
+            // A second, different core is advertising. Do not flap between
             // them — keep the first and say so loudly, because on a PCS box
             // this means a client container can see the gateway's core.
             console.warn(
-                `[meshdisco] Ignoring a second meta-core at ${nb.urls.apiUrl} (${nb.addr}); ` +
+                `[beacon] Ignoring a second meta-core at ${urls.apiUrl} (${nb.addr}); ` +
                 `staying with ${prev.apiUrl}. Set META_CORE_URL to pin this explicitly.`
             );
         });
@@ -377,7 +591,7 @@ export class MetaCoreLocator {
 
     async start(): Promise<void> {
         if (this.cfg.metaCoreUrl) {
-            console.log(`[meshdisco] meta-core pinned to ${this.cfg.metaCoreUrl}; discovery is advisory`);
+            console.log(`[beacon] meta-core pinned to ${this.cfg.metaCoreUrl}; discovery is advisory`);
         }
         await this.node.start();
     }
@@ -409,11 +623,11 @@ export class MetaCoreLocator {
         while (Date.now() < deadline) {
             const url = this.getApiUrl();
             if (url) return url;
-            if (!logged) { console.log('[meshdisco] Waiting for meta-core...'); logged = true; }
+            if (!logged) { console.log('[beacon] Waiting for meta-core...'); logged = true; }
-            this.node.probe();
+            this.node.probe([CAP_CORE]);
             await new Promise((r) => setTimeout(r, 500));
         }
-        throw new Error(`[meshdisco] No meta-core found within ${timeoutMs}ms`);
+        throw new Error(`[beacon] No meta-core found within ${timeoutMs}ms`);
     }
 
     /** Fires when the elected core's apiUrl changes. Replaces the fs.watch. */
@@ -421,21 +635,32 @@ export class MetaCoreLocator {
         this.changeCallbacks.push(cb);
     }
 
-    getNeighbors(): MeshNeighbor[] {
+    /**
-        return this.node.getNeighborsByName();
+     * Neighbours for /api/neighbors: one row per name (or every instance with
+     * `all`), optionally only nodes with a resource matching `cap`.
+     */
+    getNeighbors(opts: { all?: boolean; cap?: string } = {}): MeshNeighbor[] {
+        const list = opts.all ? this.node.getNeighbors() : this.node.getNeighborsByName();
+        const cap = opts.cap;
+        return cap ? list.filter((n) => n.resources.some((r) => resourceMatches(r, cap))) : list;
     }
 
     self(): MeshNeighbor {
         return this.node.self();
     }
 
-    probe(): void {
+    /** The Scan card — see {@link MeshNode.scan}. */
-        this.node.probe();
+    scan(pattern: string, configured: Array<[string, string]>, waitMs = 1500): Promise<ScanReport> {
+        return this.node.scan(pattern, configured, waitMs);
+    }
+
+    probe(want: string[] = []): void {
+        this.node.probe(want);
     }
 
     private notifyChange(): void {
         for (const cb of this.changeCallbacks) {
-            try { cb(); } catch (e) { console.error('[meshdisco] Change callback threw:', e); }
+            try { cb(); } catch (e) { console.error('[beacon] Change callback threw:', e); }
         }
     }
 }

packages/meta-sort-core/src/index.ts

@@ -1,7 +1,6 @@
 import {config} from "./config/EnvConfig.js";
 
 import os from 'os';
-import {existsSync} from 'fs';
 import {WatchedFileProcessor} from "./logic/WatchedFileProcessor.js";
 import {UnifiedAPIServer} from "./api/UnifiedAPIServer.js";
 import {StreamingPipeline} from "./logic/pipeline/StreamingPipeline.js";
@@ -125,7 +124,7 @@ process.on('SIGINT', async () => {
 // Start initial discovery and processing (streaming pipeline)
 (async () => {
     try {
-        // meta-core is located over UDP (meta-discovery v1) — no /meta-core
+        // meta-core is located over UDP (beacon v2) — no /meta-core
         // volume required. META_CORE_URL, when set, pins it and discovery
         // never overrides; see docs/project-architecture/service-discovery.md.
         {
@@ -168,8 +167,11 @@ process.on('SIGINT', async () => {
         const pluginManager = await initializePluginManager();
         console.log('[Startup] Plugin manager initialized');
 
-        // Initialize container plugins if config file exists
+        // Container plugins: the ones spawned from plugins.yml AND the external
-        if (existsSync(config.CONTAINER_PLUGINS_CONFIG)) {
+        // ones added by URL (beacon Scan card). Always initialised — with no
+        // plugins.yml and no Docker it still serves the external ones, and the
+        // Plugins page can add the first one.
+        {
             console.log('[Startup] Initializing container plugins...');
             try {
                 // Get webdavUrlInternal from meta-core via LeaderClient (for container-to-container access)
@@ -215,8 +217,6 @@ process.on('SIGINT', async () => {
                 console.error('[Startup] Failed to initialize container plugins:', error);
                 console.log('[Startup] Continuing without container plugins...');
             }
-        } else {
-            console.log(`[Startup] Container plugins config not found at ${config.CONTAINER_PLUGINS_CONFIG}, skipping`);
         }
 
         // Initialize hash index cache (loads existing hashes from disk)

packages/meta-sort-core/src/kv/KVManager.ts

@@ -2,7 +2,7 @@
  * KV Manager - Unified manager for KV storage and service discovery
  *
  * This is the main entry point for the KV subsystem. It:
- * 1. Uses LeaderClient to locate meta-core over UDP (meta-discovery v1)
+ * 1. Uses LeaderClient to locate meta-core over UDP (beacon v2)
  * 2. Creates and manages the KV client (Redis)
  * 4. Manages reconnection on leader changes
  *

packages/meta-sort-core/src/kv/LeaderClient.ts

@@ -1,7 +1,8 @@
 /**
  * LeaderClient - locates meta-core and exposes its URLs.
  *
- * Since meta-discovery v1 this is a thin adapter over MetaCoreLocator
+ * Since UDP discovery (meta-discovery v1, now beacon v2) this is a thin adapter
+ * over MetaCoreLocator
  * (../discovery/meshdisco.js): meta-core is found by UDP announce instead of by
  * reading /meta-core/locks/kv-leader.info, which means this service no longer
  * needs the /meta-core volume mounted at all.
@@ -22,7 +23,7 @@
  * api-mediated-access lockdown; everything routes over HTTP.
  */
 
-import { MetaCoreLocator, type MeshNeighbor } from '../discovery/meshdisco.js';
+import { MetaCoreLocator, type MeshNeighbor, type ScanReport } from '../discovery/meshdisco.js';
 import type { LeaderLockInfo } from './IKVClient.js';
 
 export interface LeaderClientConfig {
@@ -259,16 +260,24 @@ export class LeaderClient {
         return this.leaderInfo;
     }
 
-    /** Neighbours for the nav menu (one row per service name). */
+    /**
-    getNeighbors(): MeshNeighbor[] {
+     * Neighbours for /api/neighbors: one row per name (every instance with
-        return this.locator.getNeighbors();
+     * `all`), optionally only nodes with a capability matching `cap`.
+     */
+    getNeighbors(opts: { all?: boolean; cap?: string } = {}): MeshNeighbor[] {
+        return this.locator.getNeighbors(opts);
     }
 
-    /** This service's own announce, so the menu can show itself. */
+    /** This service's own row, so the menu can show itself. */
     self(): MeshNeighbor {
         return this.locator.self();
     }
 
+    /** Beacon v2 Scan card: probe, wait, classify `pattern` against `configured`. */
+    scan(pattern: string, configured: Array<[string, string]>, waitMs = 1500): Promise<ScanReport> {
+        return this.locator.scan(pattern, configured, waitMs);
+    }
+
     close(): void {
         this.onChangeCallbacks = [];
         void this.locator.stop();

packages/meta-sort-core/src/kv/index.ts

@@ -5,7 +5,7 @@
  * - IKVClient interface for KV storage abstraction
  * - RedisKVClient for Redis-based storage
  * - LeaderClient for reading leader info from meta-core
- * Services announce and discover over UDP (meta-discovery v1); there is no
+ * Services announce and discover over UDP (beacon v2); there is no
  * separate registration step, so no ServiceRegistration export.
  * - KVManager for unified management of all components
  * - MetadataUtils for flattening/reconstructing nested metadata

packages/meta-sort-core/src/plugin-engine/PluginManager.ts

@@ -220,6 +220,17 @@ export class PluginManager extends EventEmitter {
             return;
         }
 
+        // Forget container-backed plugins that are gone (an external plugin
+        // removed from the Plugins page); they have no local dir.
+        const present = new Set(status.plugins.map((p) => p.pluginId));
+        for (const [id, loaded] of this.loadedPlugins) {
+            if (loaded.pluginDir === '' && !present.has(id)) {
+                this.loadedPlugins.delete(id);
+                this.manifests.delete(id);
+                this.activePluginIds.delete(id);
+            }
+        }
+
         // Load state for plugin active status
         const state = await this.loadState();
 

packages/meta-sort-ui/src/components/BeaconScanCard.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useRef } from 'react';
+import '../meta-beacon-scan.js';
+
+/**
+ * The Plugins page's beacon v2 Scan card: enrichment plugins advertising on
+ * the network (`metamesh.enrich/<id>`, typically MetaPlugin* store apps), with
+ * an Add per new one. A thin wrapper around the framework-free
+ * <meta-beacon-scan> element shared with meta-share and meta-gateway; the
+ * --mm-scan-* tokens map this dashboard's palette onto it.
+ *
+ * Add registers the plugin as an EXTERNAL plugin (POST /api/plugins/external):
+ * meta-sort calls it by URL and never starts or stops it.
+ */
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace JSX {
+        interface IntrinsicElements {
+            'meta-beacon-scan': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                'scan-endpoint'?: string;
+                'add-endpoint'?: string;
+                'add-extra'?: string;
+                label?: string;
+            };
+        }
+    }
+}
+
+const TOKENS = {
+    display: 'block',
+    '--mm-scan-fg': 'var(--text-primary)',
+    '--mm-scan-bg': 'var(--bg-secondary)',
+    '--mm-scan-border': 'var(--border-color)',
+    '--mm-scan-accent': 'var(--accent-primary)',
+    '--mm-scan-err': 'var(--accent-secondary)',
+} as React.CSSProperties;
+
+function BeaconScanCard({ onAdded }: { onAdded: () => void }) {
+    const ref = useRef<HTMLElement>(null);
+
+    useEffect(() => {
+        const el = ref.current;
+        if (!el) return;
+        const handler = () => onAdded();
+        el.addEventListener('beacon-added', handler);
+        return () => el.removeEventListener('beacon-added', handler);
+    }, [onAdded]);
+
+    return (
+        <meta-beacon-scan
+            ref={ref}
+            style={TOKENS}
+            scan-endpoint="/api/plugins/discover"
+            add-endpoint="/api/plugins/external"
+            label="enrichment plugins"
+        />
+    );
+}
+
+export default BeaconScanCard;

packages/meta-sort-ui/src/meta-beacon-scan.js

@@ -0,0 +1,277 @@
+/**
+ * <meta-beacon-scan> — "what plugins are on the network?", as a card.
+ *
+ * The Scan button POSTs to the host's own discover endpoint, which probes the
+ * beacon v2 group (239.255.99.1:9099), waits for the replies, and classifies
+ * every resource matching the host's capability (transport plugins for
+ * meta-share, feeders for meta-gateway, enrichment plugins for meta-sort):
+ *
+ *   10 nodes on the network · 3 transport plugins · 3 already configured
+ *
+ * Each `addable` row gets an Add button that POSTs {name, url} to the host's
+ * existing add endpoint. Response shape: meta-feeder-sdk `beacon::ScanReport`
+ * (docs/project-architecture/beacon-v2.md).
+ *
+ * ⚠ MIRRORED FILE. Byte-identical copies live in meta-share, meta-gateway and
+ * meta-sort-ui; see `scripts/check-mirrors.sh`. Edit one → edit all.
+ *
+ * Shadow DOM for the same reason as <meta-service-menu>: the three hosts use
+ * incompatible token vocabularies. Style it from the host with
+ *     --mm-scan-fg, --mm-scan-bg, --mm-scan-border, --mm-scan-accent,
+ *     --mm-scan-ok, --mm-scan-err
+ *
+ * Attributes:
+ *   scan-endpoint  POST → ScanReport (required)
+ *   add-endpoint   POST {name, url, ...add-extra} (required)
+ *   add-extra      JSON object merged into the add body (optional)
+ *   label          what the host calls a capable resource, plural
+ *                  (default "plugins")
+ *
+ * Events (bubbling, composed):
+ *   beacon-added   detail = { candidate, response }, after a successful Add
+ */
+
+const STATE_TEXT = {
+  addable: "new",
+  configured: "configured",
+  "bound-elsewhere": "bound elsewhere",
+};
+
+const TEMPLATE = `
+<style>
+  :host {
+    --_fg: var(--mm-scan-fg, #e8eaed);
+    --_bg: var(--mm-scan-bg, transparent);
+    --_border: var(--mm-scan-border, rgba(255, 255, 255, 0.14));
+    --_accent: var(--mm-scan-accent, #4ecdc4);
+    --_ok: var(--mm-scan-ok, #3fb950);
+    --_err: var(--mm-scan-err, #f85149);
+    display: block;
+    color: var(--_fg);
+    font-family: inherit;
+    font-size: 14px;
+    line-height: 1.4;
+  }
+  .card {
+    background: var(--_bg);
+    border: 1px solid var(--_border);
+    border-radius: 10px;
+    padding: 0.9rem 1rem;
+  }
+  .head { display: flex; align-items: center; gap: 0.75rem; flex-wrap: wrap; }
+  .title { font-weight: 600; }
+  .hint { opacity: 0.7; font-size: 0.85em; }
+  .spacer { flex: 1; }
+  button {
+    font: inherit;
+    font-size: 0.85em;
+    cursor: pointer;
+    color: var(--_fg);
+    background: transparent;
+    border: 1px solid var(--_border);
+    border-radius: 6px;
+    padding: 0.3rem 0.8rem;
+  }
+  button:hover:not(:disabled) { border-color: var(--_accent); color: var(--_accent); }
+  button:disabled { opacity: 0.5; cursor: progress; }
+  button.add { border-color: var(--_accent); color: var(--_accent); }
+  .summary { margin-top: 0.6rem; font-size: 0.9em; }
+  .summary b { color: var(--_accent); }
+  .error { margin-top: 0.6rem; color: var(--_err); font-size: 0.85em; }
+  ul { list-style: none; margin: 0.6rem 0 0; padding: 0; }
+  li {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 0.2rem 0.75rem;
+    align-items: center;
+    padding: 0.5rem 0;
+    border-top: 1px solid var(--_border);
+  }
+  .who { display: flex; gap: 0.5rem; align-items: baseline; flex-wrap: wrap; min-width: 0; }
+  .name { font-weight: 600; }
+  .muted { opacity: 0.65; font-size: 0.85em; }
+  code { font-size: 0.8em; opacity: 0.8; overflow-wrap: anywhere; }
+  .chips { display: inline-flex; gap: 0.3rem; flex-wrap: wrap; }
+  .chip {
+    font-size: 0.72em;
+    padding: 0 0.4rem;
+    border-radius: 3px;
+    border: 1px solid var(--_border);
+    opacity: 0.85;
+  }
+  .state { font-size: 0.75em; padding: 0.05rem 0.45rem; border-radius: 999px; border: 1px solid currentColor; }
+  .state.addable { color: var(--_accent); }
+  .state.configured { color: var(--_ok); }
+  .state.bound-elsewhere { opacity: 0.6; }
+  .row-actions { display: flex; gap: 0.5rem; align-items: center; grid-row: span 2; }
+  .row-err { color: var(--_err); font-size: 0.8em; }
+</style>
+<div class="card">
+  <div class="head">
+    <span class="title">Beacon discovery</span>
+    <span class="hint">plugins advertising themselves on this network</span>
+    <span class="spacer"></span>
+    <button class="scan" type="button">Scan</button>
+  </div>
+  <div class="summary" hidden></div>
+  <div class="error" hidden></div>
+  <ul></ul>
+</div>
+`;
+
+function h(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text != null) n.textContent = text;
+  return n;
+}
+
+async function readError(res) {
+  const body = await res.text().catch(() => "");
+  try {
+    const j = JSON.parse(body);
+    return j.error || j.message || body || `HTTP ${res.status}`;
+  } catch {
+    return body || `HTTP ${res.status}`;
+  }
+}
+
+class MetaBeaconScan extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+    this.shadowRoot.innerHTML = TEMPLATE;
+    this._scanBtn = this.shadowRoot.querySelector("button.scan");
+    this._summary = this.shadowRoot.querySelector(".summary");
+    this._error = this.shadowRoot.querySelector(".error");
+    this._list = this.shadowRoot.querySelector("ul");
+    this._busy = false;
+  }
+
+  connectedCallback() {
+    if (this._wired) return;
+    this._wired = true;
+    this._scanBtn.addEventListener("click", () => this.scan());
+  }
+
+  get label() {
+    return this.getAttribute("label") || "plugins";
+  }
+
+  async scan() {
+    const endpoint = this.getAttribute("scan-endpoint");
+    if (!endpoint || this._busy) return;
+    this._busy = true;
+    this._scanBtn.disabled = true;
+    this._scanBtn.textContent = "Scanning…";
+    this._error.hidden = true;
+    try {
+      const res = await fetch(endpoint, { method: "POST", headers: { Accept: "application/json" } });
+      if (!res.ok) throw new Error(await readError(res));
+      this._render(await res.json());
+    } catch (e) {
+      // Keep the last result visible; just say what went wrong.
+      this._error.textContent = `Scan failed: ${e.message}`;
+      this._error.hidden = false;
+    } finally {
+      this._busy = false;
+      this._scanBtn.disabled = false;
+      this._scanBtn.textContent = "Scan again";
+    }
+  }
+
+  _render(report) {
+    const s = report.summary || {};
+    this._summary.replaceChildren();
+    const part = (n, text) => {
+      const span = h("span");
+      span.append(h("b", null, String(n ?? 0)), ` ${text}`);
+      return span;
+    };
+    const parts = [
+      part(s.nodes, s.nodes === 1 ? "node on the network" : "nodes on the network"),
+      part(s.capable, this.label),
+      part(s.configured, "already configured"),
+      part(s.addable, "new"),
+    ];
+    if (s.boundElsewhere) parts.push(part(s.boundElsewhere, "bound to another consumer"));
+    parts.forEach((p, i) => {
+      if (i) this._summary.append(" · ");
+      this._summary.append(p);
+    });
+    this._summary.hidden = false;
+
+    this._list.replaceChildren(...(report.candidates || []).map((c) => this._row(c)));
+  }
+
+  _row(c) {
+    const li = h("li");
+    const who = h("div", "who");
+    who.append(h("span", "name", c.instance));
+    if (c.name && c.name !== c.instance) who.append(h("span", "muted", c.name));
+    if (c.version) who.append(h("span", "muted", `v${c.version}`));
+    const chips = h("span", "chips");
+    for (const cap of c.caps || []) chips.append(h("span", "chip", cap));
+    who.append(chips);
+
+    const actions = h("div", "row-actions");
+    const state = h("span", `state ${c.state}`, STATE_TEXT[c.state] || c.state);
+    if (c.state === "configured" && c.configuredAs) state.title = `listed as "${c.configuredAs}"`;
+    if (c.state === "bound-elsewhere" && c.binds) state.title = `belongs to ${c.binds}`;
+    actions.append(state);
+    if (c.state === "addable") {
+      const add = h("button", "add", "Add");
+      add.type = "button";
+      add.addEventListener("click", () => this._add(c, add, li));
+      actions.append(add);
+    }
+
+    const where = h("div");
+    where.append(h("code", null, c.url));
+    li.append(who, actions, where);
+    return li;
+  }
+
+  async _add(candidate, btn, li) {
+    const endpoint = this.getAttribute("add-endpoint");
+    if (!endpoint) return;
+    let extra = {};
+    try {
+      extra = JSON.parse(this.getAttribute("add-extra") || "{}");
+    } catch {
+      /* a malformed attribute must not block the add */
+    }
+    btn.disabled = true;
+    btn.textContent = "Adding…";
+    li.querySelector(".row-err")?.remove();
+    try {
+      const res = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ ...extra, name: candidate.suggestedName, url: candidate.url }),
+      });
+      if (!res.ok) throw new Error(await readError(res));
+      const text = await res.text();
+      let response = null;
+      try {
+        response = text ? JSON.parse(text) : null;
+      } catch {
+        response = text;
+      }
+      this.dispatchEvent(
+        new CustomEvent("beacon-added", { bubbles: true, composed: true, detail: { candidate, response } }),
+      );
+      btn.textContent = "Added";
+    } catch (e) {
+      btn.disabled = false;
+      btn.textContent = "Add";
+      li.append(h("div", "row-err", e.message));
+    }
+  }
+}
+
+if (!customElements.get("meta-beacon-scan")) {
+  customElements.define("meta-beacon-scan", MetaBeaconScan);
+}
+
+export default MetaBeaconScan;

packages/meta-sort-ui/src/meta-service-menu.js

@@ -238,6 +238,10 @@ class MetaServiceMenu extends HTMLElement {
     for (const n of this._neighbors) {
       const name = n.name || "";
       if (!name || seen.has(name)) continue;
+      // Beacon v2 neighbours include plugins; the nav lists services only.
+      // (A row without `caps` comes from a pre-v2 backend — keep it.)
+      const isService = (c) => String(c).startsWith("metamesh.service/");
+      if (Array.isArray(n.caps) && !n.caps.some(isService)) continue;
       seen.add(name);
       rows.push(n);
     }
@@ -275,7 +279,7 @@ class MetaServiceMenu extends HTMLElement {
         el.href = url;
         el.setAttribute("role", "menuitem");
       }
-      if (!isActive && !url) el.title = "No reachable URL announced";
+      if (!isActive && !url) el.title = "No reachable URL advertised";
 
       const icon = document.createElement("span");
       icon.className = "icon";
@@ -285,7 +289,8 @@ class MetaServiceMenu extends HTMLElement {
       label.textContent = titleCase(n.name);
 
       el.append(icon, label);
-      if (n.status === "running" || isActive) {
+      // Beacon v2 omits `status` when running.
+      if ((n.status || "running") === "running" || isActive) {
         const dot = document.createElement("span");
         dot.className = "dot";
         dot.title = n.status || "running";

packages/meta-sort-ui/src/pages/Plugins.tsx

@@ -5,6 +5,7 @@ import {
     PluginTimingsResponse
 } from '../types';
 import { formatMs, formatNumber } from '../utils/format';
+import BeaconScanCard from '../components/BeaconScanCard';
 
 interface AddPluginForm {
     pluginId: string;
@@ -33,6 +34,8 @@ function Plugins() {
         cpus: '0.5',
     });
     const [restartAllStatus, setRestartAllStatus] = useState<string | null>(null);
+    // Plugins meta-sort reaches by URL but did not spawn (added from the Scan card).
+    const [externalUrls, setExternalUrls] = useState<Record<string, string>>({});
 
     const fetchPlugins = useCallback(async () => {
         try {
@@ -41,6 +44,14 @@ function Plugins() {
                 const data = await res.json();
                 setPluginsData(data);
                 setError(null);
+                fetch('/api/plugins/containers')
+                    .then((r) => (r.ok ? r.json() : null))
+                    .then((c: { plugins?: Array<{ id: string; kind?: string; url?: string }> } | null) => {
+                        const map: Record<string, string> = {};
+                        for (const p of c?.plugins ?? []) if (p.kind === 'external' && p.url) map[p.id] = p.url;
+                        setExternalUrls(map);
+                    })
+                    .catch(() => {});
             } else if (res.status === 503) {
                 setError('Plugin manager not yet initialized. Process a file to initialize plugins.');
             }
@@ -370,6 +381,9 @@ function Plugins() {
                                             <div className="plugin-info">
                                                 <span className="plugin-name">{plugin.name}</span>
                                                 <span className="plugin-version">v{plugin.version}</span>
+                                                {externalUrls[plugin.id] && (
+                                                    <span className="plugin-external" title={`external: ${externalUrls[plugin.id]}`}>external</span>
+                                                )}
                                             </div>
                                             <label className="toggle" onClick={(e) => e.stopPropagation()}>
                                                 <input
@@ -677,6 +691,17 @@ function Plugins() {
                 </div>
             )}
 
+            {/* Beacon v2: plugins advertising on the network, with Scan + Add */}
+            <div className="card beacon-scan-card">
+                <h2>Discover plugins</h2>
+                <p className="card-description">
+                    Enrichment plugins installed as their own apps announce themselves on the network.
+                    Scan to list them; Add registers one as an external plugin (meta-sort calls it by URL
+                    and never starts or stops it). Remove it from the list like any other plugin.
+                </p>
+                <BeaconScanCard onAdded={fetchPlugins} />
+            </div>
+
             {/* Queue Assignment Section */}
             {pluginsData && pluginsData.activeCount > 0 && (
                 <div className="card queue-assignment-card">
@@ -920,6 +945,14 @@ function Plugins() {
                     overflow-y: auto;
                 }
 
+                .plugin-external {
+                    margin-left: 0.5rem;
+                    font-size: 0.7rem;
+                    padding: 0 0.4rem;
+                    border-radius: 3px;
+                    border: 1px dashed var(--accent-primary);
+                    color: var(--accent-primary);
+                }
                 .plugin-item {
                     background: var(--bg-tertiary);
                     border-radius: 8px;

packages/shared/meta-interface/src/lib/metadata-type/LanguagesMeta.ts

@@ -1,10 +1,25 @@
 import {TypedRecordSet} from "./basic/RecordSet.js";
-import {ISO639_1_CODE} from "./basic/LanguageData.js";
+import {LANG3_CODE} from "./basic/LanguageData.js";
 
+/**
+ * The language triad (METADATA_KEYS.md §9).
+ *
+ * `languages` is the **union** — every language the record offers by any route
+ * — and the only one a query filters on. The two splits refine it and are
+ * optional. Rule #7: a writer that adds a member to a split MUST add the same
+ * member to the union in the same write; nothing reconciles them afterwards.
+ */
 export interface LanguagesMeta{
-    languages?: TypedRecordSet<ISO639_1_CODE>;
+    /** The union: audio ∪ subtitles ∪ bare language statements. Filterable. */
+    languages?: TypedRecordSet<LANG3_CODE>;
+    /** Spoken/audio-track languages only. Refinement, never filtered on. */
+    audioLanguages?: TypedRecordSet<LANG3_CODE>;
+    /** Subtitle languages only (§8). Refinement, never filtered on. */
+    subtitleLanguages?: TypedRecordSet<LANG3_CODE>;
 }
 
 export const LanguagesMetaFields = [
     "languages",
+    "audioLanguages",
+    "subtitleLanguages",
 ];

packages/shared/meta-interface/src/lib/metadata-type/basic/LanguageData.ts

@@ -1,9 +1,21 @@
 /**
- * key is language ISO 639-3 code
+ * key is a `lang3` code: ISO 639-2/**B** — `eng`, `jpn`, `fre`/`ger`/`chi`,
- * https://en.wikipedia.org/wiki/List_of_ISO_639-3_codes
+ * NOT the 639-2/T (= 639-3) spellings `fra`/`deu`/`zho`.
+ *
+ * This is the vocabulary the stack compares against: `languages:` query filters
+ * match it literally, and `meta_feeder_sdk::lang::normalize_lang_code` folds
+ * incoming codes onto it. See METADATA_KEYS.md §"Value formats" and §14.3 —
+ * the card tier (`titles/*`, `posters/*`) is still on /T and has not converged.
+ * https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
  */
 export type LanguageData<T> = Record<string, T>;
-export type ISO639_1_CODE = string;
+export type LANG3_CODE = string;
+
+/**
+ * @deprecated Misnamed: no writer has ever emitted 2-letter ISO 639-1 codes
+ * here. Use {@link LANG3_CODE}. Kept as an alias so existing imports compile.
+ */
+export type ISO639_1_CODE = LANG3_CODE;
 
 /**
  * jpn, jpr and jpa already exist. Creating jpl is for japan-latin. Used for japanese romaji NON ISO 639-3 standard.