agenticros 0.1.18 → 0.1.19

package/runtime/scripts/refresh-skill-deps.mjs

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+/**
+ * refresh-skill-deps.mjs
+ *
+ * Prevents the pnpm-hardlink-cascade we've hit three times running:
+ *
+ *   1. Add a new file to packages/core/src/ (e.g. capabilities.ts, mission.ts).
+ *   2. Build core. The workspace's dist/ has the new file.
+ *   3. External skill repos consume @agenticros/core via `file:` deps, so
+ *      pnpm hardlinks them through a virtual store snapshot
+ *      (.pnpm/@agenticros+core@file+..+agenticros+packages+core/...).
+ *   4. That snapshot is taken once at install time and is NEVER refreshed
+ *      automatically when the source's dist/ gains new files.
+ *   5. The skill repo's @agenticros/core now silently lags behind. Imports
+ *      that reference the new file fail with ERR_MODULE_NOT_FOUND.
+ *   6. `sync-skill-tools.mjs` runs, fails to import the skill, and (prior
+ *      to the hardening done alongside this script) silently strips the
+ *      skill's tools from contracts.tools + tools.alsoAllow.
+ *   7. The chat agent loses access to follow_robot, find_object, etc. The
+ *      failure mode is silent until somebody asks "why can't the robot
+ *      follow me anymore?"
+ *
+ * This script detects + repairs that cascade. It compares the workspace's
+ * packages/core/dist/ file list against each skill repo's resolved
+ * @agenticros/core/dist/. If anything is missing, it refreshes the skill
+ * repo's node_modules (pnpm install, escalating to a clean reinstall if
+ * pnpm decides to no-op).
+ *
+ * Usage
+ * -----
+ *   node scripts/refresh-skill-deps.mjs                # refresh stale skills
+ *   node scripts/refresh-skill-deps.mjs --dry-run      # check + report only
+ *   node scripts/refresh-skill-deps.mjs --verbose      # extra logging
+ *   node scripts/refresh-skill-deps.mjs --force        # always reinstall
+ *   node scripts/refresh-skill-deps.mjs --skill <path> # extra path (repeatable)
+ *   node scripts/refresh-skill-deps.mjs --quiet        # suppress non-error log
+ *
+ * Discovery order for skill paths (deduped):
+ *   1. --skill <path> CLI flags
+ *   2. AGENTICROS_SKILL_PATHS env var (colon-separated)
+ *   3. OpenClaw config (OPENCLAW_CONFIG or ~/.openclaw/openclaw.json)
+ *      under plugins.entries.agenticros.config.skillPaths
+ *   4. AgenticROS standalone config (AGENTICROS_CONFIG_PATH or
+ *      ~/.agenticros/config.json) under skillPaths
+ *
+ * Exit codes:
+ *   0 — nothing was stale, OR every stale repo was refreshed successfully
+ *   1 — at least one stale repo could not be refreshed
+ *   2 — invalid arguments / unexpected error
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync, rmSync } from "node:fs";
+import { join, resolve, dirname, relative, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, "..");
+const CORE_DIST = join(REPO_ROOT, "packages", "core", "dist");
+
+// ---------- CLI parsing ----------
+
+function parseArgs(argv) {
+  const opts = {
+    dryRun: false,
+    verbose: false,
+    quiet: false,
+    force: false,
+    extraSkillPaths: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run" || a === "-n") opts.dryRun = true;
+    else if (a === "--verbose" || a === "-v") opts.verbose = true;
+    else if (a === "--quiet" || a === "-q") opts.quiet = true;
+    else if (a === "--force") opts.force = true;
+    else if (a === "--skill") opts.extraSkillPaths.push(argv[++i]);
+    else if (a.startsWith("--skill=")) opts.extraSkillPaths.push(a.slice("--skill=".length));
+    else if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (a.startsWith("-")) {
+      console.error(`[refresh-skill-deps] Unknown arg: ${a}`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`refresh-skill-deps — repair stale pnpm hardlinks in external skill repos.
+
+Usage:
+  node scripts/refresh-skill-deps.mjs [options]
+
+Options:
+  --dry-run, -n        Report what's stale, don't refresh.
+  --verbose, -v        Print per-file comparison details.
+  --quiet, -q          Suppress all output except errors and summary.
+  --force              Always reinstall, even if not stale.
+  --skill <path>       Additional skill path to check (repeatable).
+  --help, -h           Show this help.
+
+Exit codes:
+  0 — nothing was stale, OR every stale repo was refreshed.
+  1 — at least one skill could not be refreshed.
+  2 — invalid arguments.
+`);
+}
+
+// ---------- Skill discovery ----------
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function discoverSkillPaths({ extraSkillPaths = [] } = {}) {
+  const out = new Set();
+  for (const p of extraSkillPaths) if (p) out.add(resolve(p));
+
+  if (process.env.AGENTICROS_SKILL_PATHS) {
+    for (const p of process.env.AGENTICROS_SKILL_PATHS.split(":")) {
+      if (p) out.add(resolve(p));
+    }
+  }
+
+  const openclawConfigPath =
+    process.env.OPENCLAW_CONFIG ||
+    join(homedir(), ".openclaw", "openclaw.json");
+  const openclawConfig = readJsonSafe(openclawConfigPath);
+  const pluginCfg =
+    openclawConfig?.plugins?.entries?.agenticros?.config ??
+    openclawConfig?.plugins?.agenticros?.config ??
+    null;
+  if (pluginCfg?.skillPaths && Array.isArray(pluginCfg.skillPaths)) {
+    for (const p of pluginCfg.skillPaths) if (p) out.add(resolve(p));
+  }
+
+  const agenticrosConfigPath =
+    process.env.AGENTICROS_CONFIG_PATH ||
+    join(homedir(), ".agenticros", "config.json");
+  const agenticrosConfig = readJsonSafe(agenticrosConfigPath);
+  if (agenticrosConfig?.skillPaths && Array.isArray(agenticrosConfig.skillPaths)) {
+    for (const p of agenticrosConfig.skillPaths) if (p) out.add(resolve(p));
+  }
+
+  return [...out];
+}
+
+// ---------- Staleness detection ----------
+
+/**
+ * Recursively list relative file paths under a directory. Returns a sorted
+ * array. Returns an empty array if the directory doesn't exist.
+ */
+export function listFilesRecursive(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = join(cur, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) out.push(relative(dir, full));
+    }
+  }
+  out.sort();
+  return out;
+}
+
+/**
+ * Compare a source file list (the truth) against a target file list (the
+ * skill's hardlinked copy) and return any files present in source but
+ * missing in target.
+ *
+ * Exported so unit tests can pin the comparison logic without touching fs.
+ */
+export function findMissingFiles(sourceFiles, targetFiles) {
+  const targetSet = new Set(targetFiles);
+  return sourceFiles.filter((f) => !targetSet.has(f));
+}
+
+/**
+ * Check one skill repo for staleness against the workspace core's dist/.
+ *
+ * Returns: { skillPath, hasCoreLink, missingFiles, sourceCount, targetCount }
+ *   - hasCoreLink: false → skill doesn't depend on @agenticros/core (skip).
+ *   - missingFiles: non-empty → STALE; needs refresh.
+ */
+export function checkSkillStaleness(skillPath, opts = {}) {
+  const sourceCoreDist = opts.sourceCoreDist ?? CORE_DIST;
+  const coreLink = join(skillPath, "node_modules", "@agenticros", "core");
+  if (!existsSync(coreLink)) {
+    return {
+      skillPath,
+      hasCoreLink: false,
+      missingFiles: [],
+      sourceCount: 0,
+      targetCount: 0,
+    };
+  }
+  const skillDist = join(coreLink, "dist");
+  const sourceFiles = listFilesRecursive(sourceCoreDist);
+  const targetFiles = listFilesRecursive(skillDist);
+  const missingFiles = findMissingFiles(sourceFiles, targetFiles);
+  return {
+    skillPath,
+    hasCoreLink: true,
+    missingFiles,
+    sourceCount: sourceFiles.length,
+    targetCount: targetFiles.length,
+  };
+}
+
+// ---------- Refresh logic ----------
+
+function log(opts, level, ...m) {
+  if (level === "error") {
+    console.error("[refresh-skill-deps]", ...m);
+    return;
+  }
+  if (opts.quiet) return;
+  if (level === "verbose" && !opts.verbose) return;
+  console.log("[refresh-skill-deps]", ...m);
+}
+
+function runPnpm(args, cwd, opts) {
+  // --ignore-workspace prevents pnpm from picking up the agenticros
+  // workspace's pnpm-workspace.yaml when the skill repo sits next to it on
+  // disk. Without it pnpm errors with "packages field missing or empty"
+  // because it thinks the skill is part of a workspace that doesn't
+  // declare it. The skill repos are standalone projects with their own
+  // package.json + lockfile, so workspace mode is incorrect for them.
+  const finalArgs = ["--ignore-workspace", ...args];
+  log(opts, "verbose", `→ pnpm ${finalArgs.join(" ")}  (cwd=${cwd})`);
+  const res = spawnSync("pnpm", finalArgs, {
+    cwd,
+    stdio: opts.verbose ? "inherit" : ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+function refreshSkill(skillPath, opts) {
+  // First try: plain pnpm install. Cheap, no-op when up to date.
+  const r1 = runPnpm(["install"], skillPath, opts);
+  // ERR_PNPM_IGNORED_BUILDS is just a warning about postinstall scripts;
+  // treat any non-zero with that marker as success.
+  const isBenignWarn = (out) =>
+    typeof out === "string" && out.includes("ERR_PNPM_IGNORED_BUILDS");
+  if (r1.code !== 0 && !isBenignWarn(r1.stderr) && !isBenignWarn(r1.stdout)) {
+    log(opts, "error", `pnpm install failed in ${skillPath}`);
+    if (r1.stderr) log(opts, "error", r1.stderr.trim());
+    return { ok: false, escalated: false };
+  }
+
+  const after = checkSkillStaleness(skillPath);
+  if (after.missingFiles.length === 0) {
+    log(opts, "info", `  ✓ refreshed via pnpm install`);
+    return { ok: true, escalated: false };
+  }
+
+  // pnpm decided it was already up to date but the hardlinks are still
+  // stale. This happens when the .pnpm virtual store hash matches even
+  // though dist/ contents changed. Escalate to a clean reinstall.
+  log(opts, "info", `  pnpm install no-op'd; escalating to clean reinstall`);
+  const nm = join(skillPath, "node_modules");
+  if (existsSync(nm)) {
+    try {
+      rmSync(nm, { recursive: true, force: true });
+    } catch (e) {
+      log(opts, "error", `failed to rm -rf ${nm}: ${e.message}`);
+      return { ok: false, escalated: true };
+    }
+  }
+  const r2 = runPnpm(["install"], skillPath, opts);
+  if (r2.code !== 0 && !isBenignWarn(r2.stderr) && !isBenignWarn(r2.stdout)) {
+    log(opts, "error", `clean pnpm install failed in ${skillPath}`);
+    if (r2.stderr) log(opts, "error", r2.stderr.trim());
+    return { ok: false, escalated: true };
+  }
+  const final = checkSkillStaleness(skillPath);
+  if (final.missingFiles.length > 0) {
+    log(opts, "error", `${skillPath} STILL stale after clean reinstall; missing ${final.missingFiles.length} file(s)`);
+    return { ok: false, escalated: true };
+  }
+  log(opts, "info", `  ✓ refreshed via clean reinstall`);
+  return { ok: true, escalated: true };
+}
+
+// ---------- Main ----------
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+  const skillPaths = discoverSkillPaths({ extraSkillPaths: opts.extraSkillPaths });
+  if (skillPaths.length === 0) {
+    log(opts, "info", "No skill paths discovered (checked --skill, AGENTICROS_SKILL_PATHS, ~/.openclaw/openclaw.json, ~/.agenticros/config.json).");
+    return 0;
+  }
+
+  log(opts, "info", `Checking ${skillPaths.length} skill path(s) against ${CORE_DIST}`);
+  if (!existsSync(CORE_DIST)) {
+    log(opts, "error", `packages/core/dist/ does not exist. Run \`pnpm --filter @agenticros/core build\` first.`);
+    return 2;
+  }
+
+  const sourceCount = listFilesRecursive(CORE_DIST).length;
+  let stale = 0;
+  let refreshed = 0;
+  let failed = 0;
+  let skipped = 0;
+
+  for (const skillPath of skillPaths) {
+    if (!existsSync(skillPath)) {
+      log(opts, "info", `· ${skillPath}: directory does not exist; skipping`);
+      skipped++;
+      continue;
+    }
+    const status = checkSkillStaleness(skillPath);
+    if (!status.hasCoreLink && !opts.force) {
+      log(opts, "verbose", `· ${skillPath}: no @agenticros/core dep; skipping`);
+      skipped++;
+      continue;
+    }
+    const isStale = status.missingFiles.length > 0;
+    if (!isStale && !opts.force) {
+      log(opts, "verbose", `· ${skillPath}: up to date (${status.targetCount}/${status.sourceCount} files)`);
+      continue;
+    }
+    stale++;
+    if (isStale) {
+      log(
+        opts,
+        "info",
+        `· ${skillPath}: STALE — missing ${status.missingFiles.length} file(s) in @agenticros/core/dist` +
+          (opts.verbose ? `: ${status.missingFiles.join(", ")}` : ""),
+      );
+    } else {
+      log(opts, "info", `· ${skillPath}: --force refresh`);
+    }
+    if (opts.dryRun) continue;
+    const result = refreshSkill(skillPath, opts);
+    if (result.ok) refreshed++;
+    else failed++;
+  }
+
+  const sum = `Summary: ${skillPaths.length} skill(s) checked — ${stale} stale, ${refreshed} refreshed, ${failed} failed, ${skipped} skipped. Core source has ${sourceCount} file(s).`;
+  if (opts.dryRun && stale > 0) {
+    log(opts, "info", sum);
+    log(opts, "info", "Re-run without --dry-run to refresh.");
+    return 0;
+  }
+  log(opts, "info", sum);
+  return failed > 0 ? 1 : 0;
+}
+
+// Run only when invoked directly (preserves importability for tests).
+if (
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith("refresh-skill-deps.mjs")
+) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("[refresh-skill-deps] Unexpected error:", err);
+      process.exit(2);
+    });
+}

package/runtime/scripts/setup_gateway_plugin.sh

@@ -29,6 +29,12 @@
 #   --robot-namespace N ROS2 namespace for cmd_vel (e.g. robot3946b404c33e4aa39a8d16deb1c5c593)
 #   --camera-topic T    Camera topic for ros2_camera_snapshot / teleop
 #   --skip-build        Skip `pnpm build` (assume it's already done)
+#   --skip-refresh-skills
+#                       Skip the skill-hardlink refresh step. By default this
+#                       script runs scripts/refresh-skill-deps.mjs to keep
+#                       external skill repos in lockstep with packages/core
+#                       (prevents the pnpm cascade where new core exports
+#                       silently disappear from the chat agent's tool list).
 #   --no-systemd        Skip systemd service tweaks
 #   --no-restart        Don't restart the gateway at the end
 #   -h, --help          Show this help
@@ -43,6 +49,7 @@ ZENOH_ENDPOINT=""
 ROBOT_NAMESPACE=""
 CAMERA_TOPIC=""
 SKIP_BUILD=false
+SKIP_REFRESH_SKILLS=false
 NO_SYSTEMD=false
 NO_RESTART=false
 
@@ -58,9 +65,10 @@ while [[ $# -gt 0 ]]; do
     --robot-namespace)  ROBOT_NAMESPACE="$2"; shift 2 ;;
     --camera-topic)     CAMERA_TOPIC="$2"; shift 2 ;;
     --skip-build)       SKIP_BUILD=true; shift ;;
+    --skip-refresh-skills) SKIP_REFRESH_SKILLS=true; shift ;;
     --no-systemd)       NO_SYSTEMD=true; shift ;;
     --no-restart)       NO_RESTART=true; shift ;;
-    -h|--help)          sed -n '2,38p' "$0"; exit 0 ;;
+    -h|--help)          sed -n '2,45p' "$0"; exit 0 ;;
     *) echo "Unknown option: $1"; exit 1 ;;
   esac
 done
@@ -105,17 +113,36 @@ else
 fi
 echo ""
 
+# 2b. Refresh external skill repos so they pick up new @agenticros/core
+# exports. Skips itself when no skill paths are configured. See
+# scripts/refresh-skill-deps.mjs for the cascade this prevents.
+if [[ "$SKIP_REFRESH_SKILLS" != true ]]; then
+  echo "[2b/5] Refreshing external skill repos (use --skip-refresh-skills to opt out)..."
+  if ! node "$REPO_ROOT/scripts/refresh-skill-deps.mjs"; then
+    echo "WARN: skill refresh reported failures; continuing with deploy. Re-run \`pnpm refresh:skills\` manually to investigate." >&2
+  fi
+  echo ""
+fi
+
 # 3. Flatten the plugin into a deploy directory.
 # OpenClaw 2026.6+ rejects `node_modules/<dep>` symlinks that resolve outside
 # the plugin install root. `pnpm deploy --prod` materialises every dep inside
 # the deploy directory, so all symlinks are safely contained.
+#
+# --config.strict-peer-dependencies=false: mem0ai has unmet peer ranges for
+# pg / redis / @qdrant/js-client-rest that don't affect us (we only use the
+# in-memory + JSON local backends and ship our own pinned mem0ai). Without
+# this flag pnpm fails the deploy on what is effectively a non-issue.
 echo "[3/5] Building flat plugin deployment at $DEPLOY_DIR ..."
 mkdir -p "$(dirname "$DEPLOY_DIR")"
 rm -rf "$DEPLOY_DIR"
-(cd "$REPO_ROOT" && pnpm --filter ./packages/agenticros deploy --prod "$DEPLOY_DIR")
-# pnpm leaves one self-reference symlink (.pnpm/node_modules/agenticros → the
-# source path) that the safety scan will reject. It's not needed at runtime.
-rm -f "$DEPLOY_DIR/node_modules/.pnpm/node_modules/agenticros"
+(cd "$REPO_ROOT" && pnpm --config.strict-peer-dependencies=false --filter ./packages/agenticros deploy --prod "$DEPLOY_DIR")
+# pnpm leaves a self-reference symlink (.pnpm/node_modules/<pkg> → the source
+# path) that OpenClaw's safety scan will reject. The plugin's npm name is
+# `@agenticros/openclaw` (scoped), so the symlink lives under @agenticros/.
+# Older builds used the bare name `agenticros`; clear both to be tolerant.
+rm -rf "$DEPLOY_DIR/node_modules/.pnpm/node_modules/@agenticros/openclaw"
+rm -f  "$DEPLOY_DIR/node_modules/.pnpm/node_modules/agenticros"
 
 # `pnpm deploy --prod` skips lifecycle scripts, so rclnodejs's postinstall
 # (which runs `node scripts/generate_messages.js` to materialise ROS message

package/runtime/scripts/sync-skill-tools.mjs

@@ -56,6 +56,14 @@ const CORE_TOOLS = [
   "ros2_param_get",
   "ros2_param_set",
   "ros2_list_topics",
+  "ros2_list_capabilities",
+  "ros2_list_robots",
+  "ros2_discover_robots",
+  // Phase 1.e fleet-capability filter — `ros2_find_robots_for(capability, kind, online)`.
+  "ros2_find_robots_for",
+  "run_mission",
+  // Phase 1.f mission control — cancel a running mission by id.
+  "mission_cancel",
   "ros2_camera_snapshot",
   "ros2_depth_distance",
   // Memory tools (registered conditionally at runtime when memory.enabled=true).
@@ -206,14 +214,21 @@ async function discoverSkillTools(entryPath, packageName) {
   try {
     mod = await import(url);
   } catch (e) {
-    warn(`Failed to import ${packageName} (${entryPath}): ${e?.message ?? e}`);
-    return [];
+    const errMsg = e?.message ?? String(e);
+    warn(`Failed to import ${packageName} (${entryPath}): ${errMsg}`);
+    // Detect the classic pnpm-hardlink-cascade signature: an
+    // ERR_MODULE_NOT_FOUND for something inside @agenticros/core/dist/.
+    // When we see it, surface it as a structured failure so the caller can
+    // preserve the skill's previously-known tools instead of silently
+    // stripping them.
+    const isCoreCascade = /@agenticros\+?core.*dist\/.+\.js/i.test(errMsg);
+    return { tools: [], importFailed: true, cascadeSuspected: isCoreCascade };
   }
   const registerSkill =
     mod.registerSkill ?? mod.default?.registerSkill ?? mod.default;
   if (typeof registerSkill !== "function") {
     warn(`${packageName}: no registerSkill export — skipping discovery`);
-    return [];
+    return { tools: [], importFailed: false };
   }
   const { tools, api } = createSpyApi();
   const ctx = createStubContext();
@@ -235,7 +250,7 @@ async function discoverSkillTools(entryPath, packageName) {
       `${packageName} registerSkill threw during discovery — captured ${tools.length} tools before error: ${e?.message ?? e}`,
     );
   }
-  return tools;
+  return { tools, importFailed: false };
 }
 
 function uniqueOrdered(...lists) {
@@ -277,13 +292,18 @@ async function main() {
   log(`skillPackages: ${skillPackages.length === 0 ? "(none)" : skillPackages.join(", ")}`);
 
   const discovered = new Map(); // skillId/packageName -> tools[]
+  const importFailures = []; // [{ name, cascadeSuspected }]
 
   for (const pkg of skillPackages) {
     const entry = resolvePackageEntry(pkg);
     if (!entry) continue;
     vlog(`Resolving package "${pkg}" → ${entry}`);
-    const tools = await discoverSkillTools(entry, pkg);
-    if (tools.length > 0) discovered.set(pkg, tools);
+    const result = await discoverSkillTools(entry, pkg);
+    if (result.importFailed) {
+      importFailures.push({ name: pkg, cascadeSuspected: result.cascadeSuspected });
+      continue;
+    }
+    if (result.tools.length > 0) discovered.set(pkg, result.tools);
     else vlog(`  no tools discovered for ${pkg}`);
   }
 
@@ -292,8 +312,12 @@ async function main() {
     const resolved = findSkillEntryFromPath(absDir);
     if (!resolved) continue;
     vlog(`Resolving path "${absDir}" → ${resolved.entry} (${resolved.packageName})`);
-    const tools = await discoverSkillTools(resolved.entry, resolved.packageName);
-    if (tools.length > 0) discovered.set(resolved.packageName, tools);
+    const result = await discoverSkillTools(resolved.entry, resolved.packageName);
+    if (result.importFailed) {
+      importFailures.push({ name: resolved.packageName, cascadeSuspected: result.cascadeSuspected });
+      continue;
+    }
+    if (result.tools.length > 0) discovered.set(resolved.packageName, result.tools);
     else vlog(`  no tools discovered for ${resolved.packageName}`);
   }
 
@@ -305,12 +329,45 @@ async function main() {
     }
   }
 
-  const skillTools = [...discovered.values()].flat();
-  const merged = uniqueOrdered(CORE_TOOLS, skillTools);
   const previous = Array.isArray(manifest?.contracts?.tools)
     ? manifest.contracts.tools.slice()
     : [];
 
+  // If any skill failed to import, preserve its presumed entries from the
+  // previous manifest instead of silently stripping them. We can't tell
+  // exactly which tools belonged to that specific skill, but we know any
+  // tool in `previous` that's not in CORE_TOOLS and not in the freshly
+  // discovered set must have come from one of these skills — and dropping
+  // them silently was exactly the regression we hit on 2026-06-10.
+  const coreSet = new Set(CORE_TOOLS);
+  const freshSkillTools = [...discovered.values()].flat();
+  const freshSet = new Set(freshSkillTools);
+  let preservedTools = [];
+  if (importFailures.length > 0) {
+    preservedTools = previous.filter(
+      (t) => typeof t === "string" && !coreSet.has(t) && !freshSet.has(t),
+    );
+    const failedNames = importFailures.map((f) => f.name).join(", ");
+    warn(`Some skill(s) failed to import: ${failedNames}`);
+    if (preservedTools.length > 0) {
+      warn(
+        `Preserving ${preservedTools.length} previously-known tool(s) from contracts.tools so the chat agent does not silently lose them: ${preservedTools.join(", ")}`,
+      );
+    }
+    const cascade = importFailures.some((f) => f.cascadeSuspected);
+    if (cascade) {
+      warn(
+        "Cascade signature detected (ERR_MODULE_NOT_FOUND inside @agenticros/core/dist). " +
+          "Run `pnpm refresh:skills` to repair the stale pnpm hardlinks, then re-run this sync.",
+      );
+    } else {
+      warn("Re-run this sync after fixing the import error to refresh the manifest.");
+    }
+  }
+
+  const skillTools = [...freshSkillTools, ...preservedTools];
+  const merged = uniqueOrdered(CORE_TOOLS, skillTools);
+
   if (arraysEqual(previous, merged)) {
     log("Manifest is already up to date.");
     return;