agenticros 0.1.11 → 0.1.13

package/dist/util/skills.js

@@ -0,0 +1,361 @@
+/**
+ * Skill discovery, validation, and config-file mutation primitives.
+ *
+ * An AgenticROS skill is a Node package whose `package.json` carries
+ * `"agenticrosSkill": true` and exports a `registerSkill(api, config, context)`
+ * function from its `main` entry. The OpenClaw AgenticROS plugin loads them
+ * at gateway start by walking two arrays in its config:
+ *
+ *   - `skillPaths[]`     — absolute directories to scan (validate `package.json`)
+ *   - `skillPackages[]`  — npm-resolvable names (e.g. `agenticros-skill-find`)
+ *
+ * This module is the single place the CLI talks to those arrays. It also
+ * encapsulates discovery (where on disk users typically clone skill repos)
+ * and the `deriveSkillId` convention shared with `@agenticros/agenticros`'s
+ * skill-loader so menu / list output uses the same short ids the plugin
+ * surfaces (e.g. `followme`, `find`).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { getCliPaths } from "./paths.js";
+import { ensureStringArray, getAgenticrosPluginConfig, openclawConfigExists, openclawConfigPath, readOpenclawConfig, writeOpenclawConfig, } from "./openclaw-config.js";
+/**
+ * Apply the same short-id transform the OpenClaw plugin's skill-loader uses,
+ * so menu output and the plugin's `config.skills.<id>` keys line up exactly.
+ * `agenticros-skill-followme` → `followme`; scoped packages drop the scope.
+ */
+export function deriveSkillId(packageName) {
+    const lower = packageName.toLowerCase();
+    if (lower.startsWith("agenticros-skill-")) {
+        return lower.slice("agenticros-skill-".length);
+    }
+    return lower.replace(/^@[^/]+\//, "").replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Inspect a directory and decide whether it's a valid AgenticROS skill clone.
+ * Returns a partial `SkillRef` (no `registeredAs`) or `undefined` when the
+ * directory is missing, lacks `package.json`, or doesn't opt in via the
+ * `agenticrosSkill: true` flag.
+ */
+export function inspectSkillDir(dir) {
+    const absDir = isAbsolute(dir) ? dir : resolve(dir);
+    if (!existsSync(absDir))
+        return undefined;
+    let stat;
+    try {
+        stat = statSync(absDir);
+    }
+    catch {
+        return undefined;
+    }
+    if (!stat.isDirectory())
+        return undefined;
+    const pkgPath = join(absDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (pkg.agenticrosSkill !== true)
+        return undefined;
+    const packageName = (pkg.name ?? "unknown").toString();
+    const mainRel = pkg.main ?? "index.js";
+    const entry = join(absDir, mainRel);
+    return {
+        id: deriveSkillId(packageName),
+        packageName,
+        dir: absDir,
+        entry,
+        built: existsSync(entry),
+    };
+}
+/**
+ * Return a deduped list of "places we should look for skill clones" — the
+ * directories whose children the CLI scans on `agenticros skills discover`.
+ *
+ * We include both the parent of the active repo / install dir (so siblings
+ * of `agenticros/` work, e.g. `../agenticros-skill-find`) and `$HOME` /
+ * `$HOME/Projects/` / `$HOME/Code/` so a vanilla clone-into-Projects flow
+ * is found without configuration.
+ */
+export function discoveryRoots(extra = []) {
+    const paths = getCliPaths();
+    const home = homedir();
+    const roots = [];
+    const push = (p) => {
+        if (!p)
+            return;
+        const abs = resolve(p);
+        if (!roots.includes(abs))
+            roots.push(abs);
+    };
+    if (paths.repoRoot)
+        push(dirname(paths.repoRoot));
+    push(dirname(paths.installDir));
+    push(home);
+    push(join(home, "Projects"));
+    push(join(home, "Code"));
+    push(join(home, "agenticros-skills"));
+    for (const e of extra)
+        push(e);
+    return roots.filter((r) => {
+        try {
+            return statSync(r).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Walk every directory in `roots`, returning a `SkillRef` for each child
+ * directory that passes `inspectSkillDir`. Used by both `discover` and
+ * `list` (which uses it to render orphaned-but-cloned skills).
+ */
+export function scanForSkills(extra = []) {
+    const out = [];
+    const seenDirs = new Set();
+    for (const root of discoveryRoots(extra)) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const child = join(root, name);
+            if (seenDirs.has(child))
+                continue;
+            seenDirs.add(child);
+            const info = inspectSkillDir(child);
+            if (info) {
+                out.push({ ...info, registeredAs: [] });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Pull skill arrays out of the OpenClaw config in a shape that's easy to
+ * mutate. The returned `paths` / `packages` arrays are filtered to strings
+ * (non-string elements are silently skipped in the view but preserved in
+ * the underlying arrays on disk).
+ */
+function loadOpenclawSkillsView() {
+    const cfg = readOpenclawConfig();
+    if (!cfg)
+        return undefined;
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const rawPaths = ensureStringArray(pluginCfg, "skillPaths");
+    const rawPkgs = ensureStringArray(pluginCfg, "skillPackages");
+    const paths = rawPaths.filter((x) => typeof x === "string");
+    const packages = rawPkgs.filter((x) => typeof x === "string");
+    return { cfg, pluginCfg, paths, packages };
+}
+/**
+ * Build a snapshot of the user's current skill state: what's registered,
+ * what's available-but-not-registered, and what registrations are broken.
+ * The single source of truth for the `agenticros skills` (list) view.
+ */
+export function listSkills() {
+    const view = loadOpenclawSkillsView();
+    const registered = [];
+    const brokenPaths = [];
+    const byId = new Map();
+    if (view) {
+        for (const p of view.paths) {
+            const info = inspectSkillDir(p);
+            if (info) {
+                const existing = byId.get(info.id);
+                if (existing) {
+                    if (!existing.registeredAs.includes("path"))
+                        existing.registeredAs.push("path");
+                    if (existing.entry === undefined) {
+                        existing.entry = info.entry;
+                        existing.built = info.built;
+                    }
+                }
+                else {
+                    const ref = { ...info, registeredAs: ["path"] };
+                    byId.set(info.id, ref);
+                    registered.push(ref);
+                }
+            }
+            else {
+                brokenPaths.push(p);
+            }
+        }
+        for (const name of view.packages) {
+            const id = deriveSkillId(name);
+            const existing = byId.get(id);
+            if (existing) {
+                if (!existing.registeredAs.includes("package"))
+                    existing.registeredAs.push("package");
+            }
+            else {
+                const ref = { id, packageName: name, registeredAs: ["package"] };
+                byId.set(id, ref);
+                registered.push(ref);
+            }
+        }
+    }
+    const available = scanForSkills().filter((s) => !byId.has(s.id));
+    return { registered, available, brokenPaths };
+}
+/**
+ * Add a skill to the OpenClaw plugin config by absolute directory path.
+ * Idempotent: re-adding an existing entry is a no-op and returns `ok: true`
+ * with an explanatory message. The directory must contain a valid
+ * `package.json` with `agenticrosSkill: true`.
+ */
+export function addSkillByPath(dir) {
+    const info = inspectSkillDir(dir);
+    if (!info) {
+        return {
+            ok: false,
+            message: `Not an AgenticROS skill directory: ${dir} (need package.json with "agenticrosSkill": true)`,
+        };
+    }
+    if (!openclawConfigExists()) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found at ${openclawConfigPath()}. ` +
+                "Run `agenticros init` first to install the OpenClaw plugin.",
+        };
+    }
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return {
+            ok: false,
+            message: `Cannot parse OpenClaw config at ${openclawConfigPath()}.`,
+        };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const paths = ensureStringArray(pluginCfg, "skillPaths");
+    if (paths.includes(info.dir)) {
+        return {
+            ok: true,
+            message: `Skill '${info.id}' already registered at ${info.dir}.`,
+            skill: { ...info, registeredAs: ["path"] },
+        };
+    }
+    paths.push(info.dir);
+    writeOpenclawConfig(cfg);
+    return {
+        ok: true,
+        message: `Registered skill '${info.id}' at ${info.dir} (${openclawConfigPath()} → skillPaths).`,
+        skill: { ...info, registeredAs: ["path"] },
+    };
+}
+/**
+ * Add a skill by npm package name (must be resolvable on the gateway's
+ * Node search path). Mainly intended for skills published to a registry —
+ * for local clones, prefer `addSkillByPath` so the absolute directory is
+ * recorded.
+ */
+export function addSkillByPackage(name) {
+    if (!openclawConfigExists()) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found at ${openclawConfigPath()}. ` +
+                "Run `agenticros init` first to install the OpenClaw plugin.",
+        };
+    }
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return { ok: false, message: `Cannot parse OpenClaw config at ${openclawConfigPath()}.` };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const packages = ensureStringArray(pluginCfg, "skillPackages");
+    if (packages.includes(name)) {
+        return {
+            ok: true,
+            message: `Skill package '${name}' already registered.`,
+            skill: { id: deriveSkillId(name), packageName: name, registeredAs: ["package"] },
+        };
+    }
+    packages.push(name);
+    writeOpenclawConfig(cfg);
+    return {
+        ok: true,
+        message: `Registered skill package '${name}' (${openclawConfigPath()} → skillPackages).`,
+        skill: { id: deriveSkillId(name), packageName: name, registeredAs: ["package"] },
+    };
+}
+/**
+ * Remove every registration that matches `idOrName` — either a derived skill
+ * id (e.g. `find`), a full package name (e.g. `agenticros-skill-find`), or an
+ * absolute path that appears in `skillPaths`. Both `skillPaths` (matched by
+ * resolving each path back through `inspectSkillDir`) and `skillPackages`
+ * are cleaned in a single pass.
+ */
+export function removeSkill(idOrName) {
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found or unparseable at ${openclawConfigPath()}.`,
+            removedPaths: [],
+            removedPackages: [],
+        };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const rawPaths = ensureStringArray(pluginCfg, "skillPaths");
+    const rawPkgs = ensureStringArray(pluginCfg, "skillPackages");
+    const wanted = idOrName.trim();
+    const wantedAbs = isAbsolute(wanted) ? resolve(wanted) : undefined;
+    const removedPaths = [];
+    const keptPaths = rawPaths.filter((entry) => {
+        if (typeof entry !== "string")
+            return true;
+        if (wantedAbs && resolve(entry) === wantedAbs) {
+            removedPaths.push(entry);
+            return false;
+        }
+        const info = inspectSkillDir(entry);
+        if (info && (info.id === wanted || info.packageName === wanted)) {
+            removedPaths.push(entry);
+            return false;
+        }
+        return true;
+    });
+    const removedPackages = [];
+    const keptPkgs = rawPkgs.filter((entry) => {
+        if (typeof entry !== "string")
+            return true;
+        if (entry === wanted || deriveSkillId(entry) === wanted) {
+            removedPackages.push(entry);
+            return false;
+        }
+        return true;
+    });
+    if (removedPaths.length === 0 && removedPackages.length === 0) {
+        return {
+            ok: false,
+            message: `No registered skill matches '${idOrName}'.`,
+            removedPaths: [],
+            removedPackages: [],
+        };
+    }
+    pluginCfg["skillPaths"] = keptPaths;
+    pluginCfg["skillPackages"] = keptPkgs;
+    writeOpenclawConfig(cfg);
+    const parts = [];
+    if (removedPaths.length > 0)
+        parts.push(`${removedPaths.length} path(s)`);
+    if (removedPackages.length > 0)
+        parts.push(`${removedPackages.length} package(s)`);
+    return {
+        ok: true,
+        message: `Removed ${parts.join(" + ")} matching '${idOrName}' from ${openclawConfigPath()}.`,
+        removedPaths,
+        removedPackages,
+    };
+}
+//# sourceMappingURL=skills.js.map

package/dist/util/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/util/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticros",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "AgenticROS - agentic AI for ROS-powered robots. Single CLI to launch real-robot or simulated demos, manage configuration, and inspect status.",
   "keywords": [

package/runtime/BUNDLE.json

@@ -1,5 +1,5 @@
 {
-  "packedAt": "2026-06-06T14:01:37.009Z",
+  "packedAt": "2026-06-06T22:08:53.765Z",
   "repo": "https://github.com/PlaiPin/agenticros",
   "note": "This directory is a snapshot of the agenticros monorepo source. `agenticros init` will copy it to ~/agenticros and run pnpm install + colcon build there.",
   "layout": {

package/runtime/README.md

@@ -56,34 +56,95 @@ Gemini CLI → @agenticros/gemini (function calling) → Core → ROS2 robots
 - `**docker/**` — Docker Compose and Dockerfiles for ROS2 + plugin images.
 - `**examples/**` — Example projects.
 
-## Requirements
+## Install
 
-- Node.js >= 20, pnpm >= 9
-- ROS2 (Jazzy or compatible) for building and running the ROS2 packages
-- OpenClaw gateway for the OpenClaw plugin
+You only need one command. The `agenticros` CLI handles everything else —
+installing the ROS 2 workspace, building the MCP server, registering the
+OpenClaw plugin, and wiring up your robot config.
 
-## Quick start
+```bash
+npx agenticros
+```
 
-1. **Install dependencies**
-  ```bash
-   pnpm install
-  ```
-2. **Build ROS2 workspace** (optional, if you need discovery/agent/follow_me nodes)
-  ```bash
-   cd ros2_ws
-   colcon build --packages-select agenticros_msgs agenticros_bringup agenticros_discovery agenticros_agent agenticros_follow_me
-   source install/setup.bash
-  ```
-3. **Type-check packages**
-  ```bash
-   pnpm typecheck
-  ```
-4. **Install and test the OpenClaw plugin**
-  Point the OpenClaw gateway at this repo’s `packages/agenticros` (or at a built package). Configure the plugin under `plugins.entries.agenticros.config` in your OpenClaw config file. Run `./scripts/setup_gateway_plugin.sh` from the repo root to register the plugin and print next steps. **Recommended:** OpenClaw **2026.3.11** or later — plugin routes work at [http://127.0.0.1:18789/plugins/agenticros/](http://127.0.0.1:18789/plugins/agenticros/) (config, teleop). For local dev without token auth, run `**node scripts/setup-openclaw-local.cjs`** then restart the gateway. **If URLs don't load** (e.g. gateway logs "missing or invalid auth" on older versions): run `**./scripts/use-openclaw-2026.2.26.sh`** as fallback. See **docs/openclaw-releases-and-plugin-routes.md**.
+That's it. Run it on any machine with **Node ≥ 20**, no `git clone` required.
+The first run launches the interactive menu:
+
+```text
+╔──────────────────────────────────────────────────╗
+║  AgenticROS - agentic AI for ROS-powered robots  ║
+╚──────────────────────────────────────────────────╝
+
+? What would you like to do?
+  Launch with real robot
+❯ Launch with simulation
+  First-time setup (workspace + OpenClaw plugin + API key)
+  Stop everything
+  Doctor (health check)
+  Configure (API keys, namespace, transport)
+  Tail logs
+```
+
+Pick **First-time setup** once (workspace + OpenClaw plugin + API key, all
+idempotent), then choose how you want to run:
+
+| You want to … | Pick |
+|---|---|
+| Drive your **real robot** (RealSense + motors + MCP) | **Launch with real robot** |
+| Demo a **simulated 2-wheel AMR** in Gazebo + RViz | **Launch with simulation → AMR** |
+| Demo a **simulated 6-DOF arm** (UR5e-shaped, per-joint position control) | **Launch with simulation → 6-DOF arm** |
 
-**With token auth:** Run `node scripts/agenticros-proxy.cjs 18790` and open [http://127.0.0.1:18790/plugins/agenticros/](http://127.0.0.1:18790/plugins/agenticros/). See **docs/teleop.md**.
+Once a stack is up, point any of the supported agents — OpenClaw, Claude Code,
+Claude Desktop / Dispatch, or Gemini CLI — at the same robot and start talking
+to it. The CLI tracks what it spawned (pidfiles + logs under `/tmp/agenticros-*`),
+so **Stop everything** cleanly tears the demo down.
+
+Prefer scripted invocations? Every menu item maps to a direct command:
+
+```bash
+npx agenticros init             # one-time workspace + plugin + API key
+agenticros up real              # real robot stack
+agenticros up sim-amr           # simulated AMR (Gazebo + RViz, headless on Jetson)
+agenticros up sim-arm           # simulated 6-DOF arm
+agenticros mode <real|sim>      # swap the active config profile (namespace, transport)
+agenticros doctor               # coloured health check
+agenticros down                 # stop everything we started
+```
+
+Full CLI reference: **[packages/agenticros-cli/README.md](packages/agenticros-cli/README.md)**.
+
+### Requirements
+
+- **Node.js ≥ 20** (the only hard requirement — `npx agenticros` installs pnpm
+  itself if missing)
+- **ROS 2 Humble or Jazzy** if you plan to use the real-robot stack or any
+  simulation (the CLI sources `/opt/ros/<distro>/setup.bash` and runs
+  `colcon build` for you)
+- **OpenClaw gateway** only if you also want the OpenClaw web UI / chat /
+  teleop adapter
+
+### Contributing / building from source
+
+Hacking on the packages themselves? Clone and use the local checkout — the CLI
+auto-detects the workspace and uses live sources instead of the bundled snapshot:
+
+```bash
+git clone https://github.com/PlaiPin/agenticros && cd agenticros
+pnpm install && pnpm build
+./agenticros                    # repo-local CLI shim, same menu as `npx agenticros`
+```
 
-See `**docs/`** for robot setup, skills, teleop, and Docker.
+For the OpenClaw plugin specifically, point the gateway at this repo's
+`packages/agenticros` and configure under `plugins.entries.agenticros.config`.
+**Recommended:** OpenClaw **2026.3.11+** — routes work at
+[http://127.0.0.1:18789/plugins/agenticros/](http://127.0.0.1:18789/plugins/agenticros/)
+(config, teleop). For local dev without token auth:
+`node scripts/setup-openclaw-local.cjs` then restart the gateway. Older gateways
+needing token auth: run `node scripts/agenticros-proxy.cjs 18790` and open
+[http://127.0.0.1:18790/plugins/agenticros/](http://127.0.0.1:18790/plugins/agenticros/).
+See **[docs/openclaw-releases-and-plugin-routes.md](docs/openclaw-releases-and-plugin-routes.md)**
+and **[docs/teleop.md](docs/teleop.md)**.
+
+See **`docs/`** for robot setup, skills, teleop, simulation internals, and Docker.
 
 ## RViz2 and Gazebo (TurtleBot3 + rosbridge)
 

package/runtime/packages/agenticros/openclaw.plugin.json

@@ -23,7 +23,8 @@
       "memory_status",
       "follow_robot",
       "follow_me_see",
-      "ollama_status"
+      "ollama_status",
+      "find_object"
     ]
   },
   "configSchema": {
@@ -311,7 +312,10 @@
           },
           "backend": {
             "type": "string",
-            "enum": ["local", "mem0"],
+            "enum": [
+              "local",
+              "mem0"
+            ],
             "default": "local",
             "description": "local = JSON-on-disk, no deps; mem0 = semantic search via mem0ai (requires `pnpm add mem0ai`)."
           },

package/runtime/packages/agenticros-claude-code/src/tools.ts

@@ -360,11 +360,40 @@ export async function handleToolCall(
       const topics = await transport.listTopics();
       const MAX = 50;
       const truncated = topics.length > MAX ? topics.slice(0, MAX) : topics;
+
+      // Surface task-specific control hints so the agent (and any LLM
+      // calling list_topics to figure out what's available) doesn't have to
+      // memorise the topic surface for each demo. Cheap to compute and only
+      // included when matching topics are actually present.
+      const hints: Record<string, string> = {};
+      const armJoints = topics
+        .filter((t) => /^\/arm\/[a-z0-9_]+\/cmd_pos$/i.test(t.name))
+        .map((t) => t.name.replace(/^\/arm\/(.+)\/cmd_pos$/, "$1"));
+      if (armJoints.length > 0) {
+        hints["arm"] =
+          `Detected the AgenticROS sim arm (joints: ${armJoints.join(", ")}). ` +
+          "To move a joint, call ros2_publish with topic '/arm/<joint>/cmd_pos', " +
+          "type 'std_msgs/msg/Float64', message {data: <radians>}. " +
+          "Example: rotate shoulder_pan 90 degrees left -> publish {data: 1.5707} " +
+          "to /arm/shoulder_pan/cmd_pos. Listen to /joint_states (sensor_msgs/msg/JointState) " +
+          "to read current positions.";
+      }
+      const baseTwistTopics = topics.filter(
+        (t) => /\/cmd_vel$/.test(t.name) && t.type === "geometry_msgs/msg/Twist",
+      );
+      if (baseTwistTopics.length > 0) {
+        hints["base"] =
+          "To drive the base, publish geometry_msgs/msg/Twist to a cmd_vel topic. " +
+          `Available cmd_vel topics: ${baseTwistTopics.map((t) => t.name).join(", ")}. ` +
+          "When in sim mode the unnamespaced /cmd_vel is the one the simulator listens on.";
+      }
+
       const text = JSON.stringify({
         success: true,
         topics: truncated,
         total: topics.length,
         truncated: topics.length > MAX,
+        ...(Object.keys(hints).length > 0 ? { hints } : {}),
       });
       return { content: [{ type: "text", text }] };
     }

package/runtime/packages/core/src/transport/local/transport.ts

@@ -91,7 +91,11 @@ export class LocalTransport implements RosTransport {
       // Give DDS discovery a brief moment to receive announcements from peers
       // before we report "connected". Without this the very first listTopics()
       // can race the executor and return empty even though peers exist.
-      await new Promise<void>((resolve) => setTimeout(resolve, 750));
+      // 1500ms was chosen empirically on Jetson + Humble where /arm/*/cmd_pos
+      // topics from a sim_arm gz_bridge child take ~1.2s to propagate via
+      // multicast (vs ~400ms on x86); the prior 750ms cap caused first
+      // list_topics() calls to miss them.
+      await new Promise<void>((resolve) => setTimeout(resolve, 1500));
 
       this.setStatus("connected");
     } catch (err) {
@@ -280,24 +284,41 @@ export class LocalTransport implements RosTransport {
   async listTopics(): Promise<TopicInfo[]> {
     this.ensureConnected();
 
-    // DDS discovery is asynchronous. On a freshly-connected node,
-    // getTopicNamesAndTypes() trickles in results as peers respond - the
-    // first call may return 0, the second 2, the third all of them.
-    // Poll until the count is stable across two consecutive 300ms reads (or
-    // time-bounded to ~3s) so we don't return a partial view.
+    // DDS discovery is asynchronous AND stateful. On a freshly-connected
+    // node, getTopicNamesAndTypes() trickles in results as peers respond -
+    // the first call may return 0, the second 2, the third all of them.
+    //
+    // Two issues motivated the current tuning:
+    //
+    //   1. A short single-stable-hit policy (600ms) was returning truncated
+    //      views to Claude: e.g. with the AMR sim alone it'd see /cmd_vel
+    //      etc. on first call, then a second call 2s later would see all
+    //      29 topics including /arm/*/cmd_pos. Claude only calls
+    //      list_topics once and was missing arm joint topics entirely.
+    //
+    //   2. DDS multicast announcements on Jetson take longer than on x86 -
+    //      we routinely see /arm/* topics appear ~1.5s after first call.
+    //
+    // Fix: require 3 consecutive matching polls (2 stable hits at 300ms
+    // intervals = ~900ms of stability), with a 6 s deadline. Worst case
+    // ~900ms latency on a steady graph, ~5s+ if discovery is still
+    // streaming. The min-count guard (>=3) avoids exiting early when only
+    // /clock + /tf + /tf_static have come through.
     const externalFilter = (t: { name: string; types: string[] }) =>
       !INTERNAL_TOPIC_PREFIXES.some((prefix) => t.name.startsWith(prefix));
 
-    const deadline = Date.now() + 3000;
+    const deadline = Date.now() + 6000;
+    const MIN_STABLE_COUNT = 3;
+    const REQUIRED_STABLE_HITS = 2;
     let raw: Array<{ name: string; types: string[] }> = [];
     let prevCount = -1;
     let stableHits = 0;
     while (Date.now() < deadline) {
       raw = this.node.getTopicNamesAndTypes();
       const externalCount = raw.filter(externalFilter).length;
-      if (externalCount === prevCount && externalCount > 0) {
+      if (externalCount === prevCount && externalCount >= MIN_STABLE_COUNT) {
         stableHits++;
-        if (stableHits >= 1) break; // one stable confirmation is enough
+        if (stableHits >= REQUIRED_STABLE_HITS) break;
       } else {
         stableHits = 0;
         prevCount = externalCount;