@petercjl/topazlabscli 0.2.0 → 0.2.2

package/README.md

@@ -15,7 +15,9 @@ npm install --global @petercjl/topazlabscli
 topazlabscli skill install --agent all
 ```
 
-The CLI checks npm for a newer stable release before operational commands, at most once every six hours. When an update is available it upgrades itself, refreshes installed Agent Skills, and then resumes the original command. A temporary npm outage does not block video processing. `topazlabscli update` forces an immediate manual update.
+The CLI checks npm for a newer stable release before operational commands, at most once every six hours. It first uses the registry already configured for npm and automatically tries `https://registry.npmmirror.com/` if that registry is unavailable. The successful registry is also used for installation, without changing the user's `.npmrc`. When an update is available the CLI upgrades itself, refreshes installed Agent Skills, and then resumes the original command. It discovers npm through the running Node installation, preserves SealSeek's managed global prefix/cache, and discovers Windows OpenSSH through the standard system location, so it also works in Agent runtimes with a restricted `PATH`. A temporary registry outage does not block video processing. `topazlabscli update` forces an immediate manual update.
+
+On Windows, SealSeek Skills are installed into `%USERPROFILE%\.sealseek\workspace\skills` when that workspace is present. The CLI automatically uses a managed copy because SealSeek rejects junctions that resolve outside the workspace Skill root; subsequent CLI updates refresh the copy from the npm package. The copy includes a local runtime manifest so the Agent can invoke the canonical package even when its PATH is restricted. `SEALSEEK_SKILLS_HOME` remains available as an explicit override.
 
 ## Configure a target
 
@@ -82,4 +84,6 @@ Configuration is stored outside the package:
 - macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/topazlabscli/config.json`
 - Override for testing or automation: `TOPAZLABSCLI_CONFIG`
 
+Update registry selection is CLI-local. `settings set update-registry <url>` sets a preferred registry, and `settings set update-registry auto` restores automatic selection. `TOPAZLABSCLI_UPDATE_REGISTRY` can provide one or more comma-separated preferred registries for managed environments.
+
 Do not publish configuration files, keys, internal addresses, media, Topaz model files, or authentication data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/topazlabscli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Cross-Agent CLI and portable Skill for queued remote Topaz Video AI processing",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/update.mjs && npm test"
+    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/runtime.mjs && node --check src/update.mjs && npm test"
   },
   "publishConfig": {
     "access": "public",

package/skill/topazlabscli/SKILL.md

@@ -15,12 +15,13 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 ## Main Line
 
-1. Run `topazlabscli capabilities --json` when the live contract is not already known.
-2. Run `topazlabscli doctor --json` before the first job in a conversation or after a connection/model failure.
-3. For a processing request, confirm the input exists. When the user does not name an output, let the CLI create `INPUT-BASENAME-topaz-1080p.EXT` beside the source.
-4. Prefer `topazlabscli process INPUT --json` for submit, wait, and download as one operation. Add `--output OUTPUT` only when the user explicitly requests another destination. Use separate `job` commands when the user wants asynchronous control.
-5. Inspect the final JSON. Completion requires `state=completed`, a successful download result, and a real local output file.
-6. Report the selected target/endpoint, job ID, output path, preset/model, dimensions, and any warning or failure.
+1. Resolve the CLI invocation once. Prefer `topazlabscli`. In a Windows SealSeek managed-copy installation, if the npm command shim cannot find `node`, read `.topazlabscli-runtime.json` beside this file and execute its `bin` with its `node`; the CLI creates and refreshes that local manifest. SealSeek-managed npm installs must retain its managed global prefix rather than writing into a Node version directory. Reuse the invocation for the rest of the task; do not disable automatic updates.
+2. Run `topazlabscli capabilities --json` when the live contract is not already known.
+3. Run `topazlabscli doctor --json` before the first job in a conversation or after a connection/model failure, and wait for its terminal result before continuing.
+4. For a processing request, confirm the input exists. When the user does not name an output, let the CLI create `INPUT-BASENAME-topaz-1080p.EXT` beside the source.
+5. Prefer `topazlabscli process INPUT --json` for submit, wait, and download as one operation. Add `--output OUTPUT` only when the user explicitly requests another destination. Use separate `job` commands when the user wants asynchronous control.
+6. Inspect the final JSON. Completion requires `state=completed`, a successful download result, and a real local output file.
+7. Report the selected target/endpoint, job ID, output path, preset/model, dimensions, and any warning or failure.
 
 ## Preset Boundary
 
@@ -38,14 +39,14 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 Configuration, hostnames, addresses, usernames, SSH identities, VPN details, media, Topaz binaries, models, and credentials are external to this Skill and npm package. Installation does not grant access to a workstation. Treat the configured server and Topaz license as user-managed resources.
 
-Before operational commands, the CLI performs a cached npm update check. A newer stable package is installed automatically, installed Agent Skills are refreshed, and the original command resumes under the new version. Registry failures produce a warning and continue with the installed version.
+Before operational commands, the CLI performs a cached npm update check. It tries the user's current npm registry and then its built-in reachable-registry fallback without changing the user's global npm configuration. A newer stable package is installed from the same registry that answered the version check, installed Agent Skills are refreshed, and the original command resumes under the new version. The CLI resolves npm through the running Agent's Node installation when PATH is restricted. Registry, npm, and Skill-refresh failures produce a warning and continue with the installed version. Treat `doctor`'s `updates.registry` check as advisory; a failed update source does not make video processing unavailable.
 
 Do not overwrite a local output unless the user has authorized that exact existing target. The remote worker retains job inputs, outputs, status, and logs for operator review; cleanup is an administrative action outside version 0.2.
 
 ## Skill Management
 
-The npm package is the canonical source. Discover it with `topazlabscli skill source --json`; use `skill status`, `skill install`, and `skill update` for Codex and SealSeek targets. Do not edit installed links or copies as independent sources.
+The npm package is the canonical source. Discover it with `topazlabscli skill source --json`; use `skill status`, `skill install`, and `skill update` for Codex and SealSeek targets. Windows SealSeek automatically receives a managed copy because its Skill loader rejects junctions that escape the workspace root; updates refresh that copy from the package. Do not edit installed links or copies as independent sources.
 
 ## QA and Evolution
 
-Use `doctor --json` plus the final job status as runtime evidence. Treat Codex and SealSeek adapters as `implemented` until each has a recorded real runtime test. New models, presets, cleanup rules, or worker behavior require an authorized package update with CLI, worker, Skill, capability, and test changes together.
+Use `doctor --json` plus the final job status as runtime evidence. Do not leave health checks or job commands running without collecting their terminal result. New models, presets, cleanup rules, or worker behavior require an authorized package update with CLI, worker, Skill, capability, and test changes together.

package/skill/topazlabscli/adapters/sealseek.json

@@ -5,12 +5,20 @@
   "mappings": [
     {
       "capability_id": "command.execute",
-      "implementation": { "kind": "cli", "command": "topazlabscli" },
+      "implementation": {
+        "kind": "cli",
+        "command": "topazlabscli",
+        "fallback": "Read .topazlabscli-runtime.json from the managed Skill copy and run its bin with its node"
+      },
       "features": ["local-process", "stdout-json", "exit-code"],
-      "status": "implemented",
-      "configuration": ["topazlabscli must resolve from PATH", "The bundled topazlabscli Skill must be installed through the CLI"],
+      "status": "tested",
+      "tested_date": "2026-09-21",
+      "evidence": [
+        "A clean Windows SealSeek conversation loaded the managed Skill copy, resolved the global package through its runtime manifest, ran version 0.2.1, capabilities, Skill status, and doctor to terminal results, and reported the bounded remote connection failure without disabling automatic updates."
+      ],
+      "configuration": ["Install the npm package globally", "Install the bundled Skill through the CLI into the SealSeek workspace"],
       "permissions": ["local process execution", "network access to configured SSH target"],
-      "normalization": "Invoke with --json and consume {ok,data,error}."
+      "normalization": "Invoke with --json and consume {ok,data,error}. On Windows with a sanitized PATH, use the CLI-managed runtime manifest in the installed Skill copy."
     },
     {
       "capability_id": "filesystem.local",

package/src/cli.mjs

@@ -8,7 +8,7 @@ import { CliError, requireValue } from "./errors.mjs";
 import { run } from "./process.mjs";
 import { psLiteral, runPowerShell, selectEndpoint, sftpGet, sftpPut, startPowerShellDetached } from "./ssh.mjs";
 import { skillInstall, skillSource, skillStatus } from "./skill.mjs";
-import { maybeAutoUpdate } from "./update.mjs";
+import { installLatestPackage, maybeAutoUpdate, queryLatestVersion, updateRegistryWarning } from "./update.mjs";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -19,9 +19,9 @@ const CAPABILITIES = {
   package: pkg.name,
   version: pkg.version,
   commands: ["version", "capabilities", "doctor", "settings", "target", "connection", "worker", "model", "job", "process", "skill", "update"],
-  automatic_updates: { enabled_by_default: true, registry_check_hours: 6, refreshes_installed_skills: true },
+  automatic_updates: { enabled_by_default: true, registry_check_hours: 6, registry_fallback: true, refreshes_installed_skills: true },
   presets: [{ id: PRESET, model: "prob-4", output: "aspect-preserving 1080p", fps: "source", concurrency: 1 }],
-  agents: { codex: "tested", sealseek: "implemented" },
+  agents: { codex: "tested", sealseek_windows: "tested" },
   worker_os: ["windows"],
   transport: ["ssh", "sftp"]
 };
@@ -60,7 +60,7 @@ function help() {
   return `topazlabscli ${pkg.version}\n\n` +
     `Commands:\n` +
     `  version | capabilities | doctor\n` +
-    `  settings show | set auto-update <on|off> | set update-check-hours <hours>\n` +
+    `  settings show | set auto-update <on|off> | set update-check-hours <hours> | set update-registry <auto|url>\n` +
     `  target add <name> --endpoint <label=host>... --user <user> [--identity <path>] [--workspace <windows-path>] [--default]\n` +
     `  target list\n` +
     `  connection check [--target <name>]\n` +
@@ -152,16 +152,33 @@ export function defaultOutputPath(inputPath) {
   return path.join(path.dirname(resolved), `${path.basename(resolved, path.extname(resolved))}-topaz-1080p${extension}`);
 }
 
-async function doctor(requestedTarget) {
+async function doctor(requestedTarget, updateInfo = null) {
   const checks = [];
   for (const command of ["ssh", "sftp", "node", "npm"]) {
     const args = command === "node" || command === "npm" ? ["--version"] : command === "sftp" ? ["-h"] : ["-V"];
     const result = await run(command, args);
     const detail = (result.stdout || result.stderr).trim().split("\n")[0];
     const ok = result.code === 0 || (command === "sftp" && /usage:\s*sftp/i.test(result.stderr));
-    checks.push({ id: `local.${command}`, ok, detail });
+    checks.push({
+      id: `local.${command}`,
+      ok,
+      detail,
+      resolved_command: result.resolvedCommand,
+      resolution: result.resolution,
+      timed_out: Boolean(result.timedOut)
+    });
   }
   checks.push({ id: "config", ok: fs.existsSync(configPath()), detail: configPath() });
+  if (updateInfo) {
+    checks.push({
+      id: "updates.registry",
+      ok: Boolean(updateInfo.registry),
+      required: false,
+      detail: updateInfo.registry
+        ? { registry: updateInfo.registry, latest: updateInfo.latest || null, checked: updateInfo.checked }
+        : { warning: updateInfo.warning || "Update registry was not checked.", attempts: updateInfo.attempts || [] }
+    });
+  }
   if (requestedTarget || fs.existsSync(configPath())) {
     try {
       const { target, endpoint } = await getConnectedTarget(requestedTarget);
@@ -176,7 +193,7 @@ async function doctor(requestedTarget) {
       checks.push({ id: "connection", ok: false, detail: error.details || error.message });
     }
   }
-  return { ok: checks.every((item) => item.ok), checks };
+  return { ok: checks.filter((item) => item.required !== false).every((item) => item.ok), checks };
 }
 
 export async function main(rawArgs) {
@@ -187,11 +204,12 @@ export async function main(rawArgs) {
   if (command === "version" || command === "--version" || command === "-V") return output(pkg.version, json);
   if (command === "capabilities") return output(CAPABILITIES, json);
 
+  let updateInfo = null;
   if (!["update", "settings"].includes(command)) {
-    const update = await maybeAutoUpdate(rawArgs, pkg);
-    if (update.warning) process.stderr.write(`[AUTO_UPDATE_WARNING] ${update.warning}\n`);
-    if (update.reexecuted) {
-      process.exitCode = update.exitCode;
+    updateInfo = await maybeAutoUpdate(rawArgs, pkg);
+    if (updateInfo.warning) process.stderr.write(`[AUTO_UPDATE_WARNING] ${updateInfo.warning}\n`);
+    if (updateInfo.reexecuted) {
+      process.exitCode = updateInfo.exitCode;
       return;
     }
   }
@@ -210,6 +228,9 @@ export async function main(rawArgs) {
         const hours = Number(value);
         if (!Number.isFinite(hours) || hours < 0) throw new CliError("SETTING_INVALID", "update-check-hours must be zero or a positive number.");
         config.settings.update_check_hours = hours;
+      } else if (name === "update-registry") {
+        if (value !== "auto" && !/^https?:\/\//i.test(value)) throw new CliError("SETTING_INVALID", "update-registry must be auto or an http(s) URL.");
+        config.settings.update_registry = value;
       } else throw new CliError("SETTING_UNKNOWN", `Unknown setting: ${name}`);
       const saved = saveConfig(config);
       return output({ path: saved, settings: config.settings }, json);
@@ -217,7 +238,7 @@ export async function main(rawArgs) {
     throw new CliError("COMMAND_UNKNOWN", `Unknown settings action: ${action}`);
   }
 
-  if (command === "doctor") return output(await doctor(option(args, "--target")), json);
+  if (command === "doctor") return output(await doctor(option(args, "--target"), updateInfo), json);
 
   if (command === "target") {
     const action = args.shift();
@@ -312,14 +333,17 @@ export async function main(rawArgs) {
   }
 
   if (command === "update") {
+    const config = loadConfig();
+    const query = await queryLatestVersion(pkg, config);
+    if (!query.ok) throw new CliError("UPDATE_FAILED", updateRegistryWarning(query.attempts), { attempts: query.attempts });
     const previousSkills = skillStatus("all");
-    const result = await run("npm", ["install", "-g", `${pkg.name}@latest`]);
+    const result = await installLatestPackage(pkg, query.registry);
     if (result.code !== 0) throw new CliError("UPDATE_FAILED", result.stderr.trim() || "npm update failed.");
     const skills = [];
     for (const existing of previousSkills.filter((item) => item.installed)) {
       skills.push(...skillInstall(existing.agent, existing.mode || "link", true));
     }
-    return output({ package: pkg.name, updated: true, skills, detail: result.stdout.trim() }, json);
+    return output({ package: pkg.name, updated: true, registry: query.registry, latest: query.latest, skills, detail: result.stdout.trim() }, json);
   }
   throw new CliError("COMMAND_UNKNOWN", `Unknown command: ${command}`);
 }

package/src/config.mjs

@@ -8,7 +8,7 @@ export function emptyConfig() {
     schema_version: 1,
     default_target: null,
     targets: {},
-    settings: { auto_update: true, update_check_hours: 6 }
+    settings: { auto_update: true, update_check_hours: 6, update_registry: "auto" }
   };
 }
 
@@ -29,7 +29,10 @@ export function loadConfig({ required = false } = {}) {
         auto_update: parsed.settings?.auto_update !== false,
         update_check_hours: Number.isFinite(parsed.settings?.update_check_hours)
           ? parsed.settings.update_check_hours
-          : 6
+          : 6,
+        update_registry: typeof parsed.settings?.update_registry === "string"
+          ? parsed.settings.update_registry
+          : "auto"
       }
     };
   } catch (error) {

package/src/paths.mjs

@@ -1,4 +1,5 @@
 import os from "node:os";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -21,13 +22,22 @@ export function updateStatePath() {
   return path.join(path.dirname(configPath()), "update-state.json");
 }
 
-export function skillTarget(agent) {
-  const home = os.homedir();
+export function skillTarget(agent, options = {}) {
+  const home = options.home || os.homedir();
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const exists = options.exists || fs.existsSync;
+  const pathApi = platform === "win32" ? path.win32 : path;
   if (agent === "codex") {
-    return path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "skills", "topazlabscli");
+    return pathApi.join(env.CODEX_HOME || pathApi.join(home, ".codex"), "skills", "topazlabscli");
   }
   if (agent === "sealseek") {
-    return path.join(process.env.SEALSEEK_SKILLS_HOME || path.join(home, ".agents", "skills"), "topazlabscli");
+    if (env.SEALSEEK_SKILLS_HOME) return pathApi.join(env.SEALSEEK_SKILLS_HOME, "topazlabscli");
+    const workspace = pathApi.join(home, ".sealseek", "workspace");
+    const root = platform === "win32" && (exists(workspace) || exists(pathApi.dirname(workspace)))
+      ? pathApi.join(workspace, "skills")
+      : pathApi.join(home, ".agents", "skills");
+    return pathApi.join(root, "topazlabscli");
   }
   throw new Error(`Unknown Agent: ${agent}`);
 }

package/src/process.mjs

@@ -1,19 +1,34 @@
 import { spawn } from "node:child_process";
+import { resolveExecutable } from "./runtime.mjs";
 
 export function run(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+  return new Promise((resolve) => {
+    const executable = resolveExecutable(command, { env: options.env || process.env });
+    const child = spawn(executable.command, [...executable.argsPrefix, ...args], {
       cwd: options.cwd,
-      env: options.env || process.env,
+      env: { ...(options.env || process.env), ...(executable.envPatch || {}) },
       stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
       windowsHide: true
     });
     let stdout = "";
     let stderr = "";
+    let timedOut = false;
+    let timer = null;
+    const finish = (value) => {
+      if (timer) clearTimeout(timer);
+      resolve({ ...value, resolvedCommand: executable.command, resolution: executable.resolution, timedOut });
+    };
     child.stdout.on("data", (chunk) => { stdout += chunk; });
     child.stderr.on("data", (chunk) => { stderr += chunk; });
-    child.on("error", reject);
-    child.on("close", (code, signal) => resolve({ code, signal, stdout, stderr }));
+    child.on("error", (error) => finish({ code: 127, signal: null, stdout, stderr: stderr || error.message, error: error.message }));
+    child.on("close", (code, signal) => finish({ code, signal, stdout, stderr }));
+    if (Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+      }, options.timeoutMs);
+      timer.unref?.();
+    }
     if (options.input !== undefined) {
       child.stdin.end(options.input);
     }
@@ -21,14 +36,15 @@ export function run(command, args, options = {}) {
 }
 
 export function runInherited(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+  return new Promise((resolve) => {
+    const executable = resolveExecutable(command, { env: options.env || process.env });
+    const child = spawn(executable.command, [...executable.argsPrefix, ...args], {
       cwd: options.cwd,
-      env: options.env || process.env,
+      env: { ...(options.env || process.env), ...(executable.envPatch || {}) },
       stdio: "inherit",
       windowsHide: true
     });
-    child.on("error", reject);
+    child.on("error", (error) => resolve({ code: 127, signal: null, error: error.message }));
     child.on("close", (code, signal) => resolve({ code, signal }));
   });
 }

package/src/runtime.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function firstExisting(candidates, exists) {
+  return candidates.find((candidate) => candidate && exists(candidate)) || null;
+}
+
+export function resolveExecutable(name, options = {}) {
+  const platform = options.platform || process.platform;
+  const env = options.env || process.env;
+  const execPath = options.execPath || process.execPath;
+  const exists = options.exists || fs.existsSync;
+  const pathApi = platform === "win32" ? path.win32 : path;
+
+  if (name === "node") {
+    return { command: execPath, argsPrefix: [], resolution: "process.execPath" };
+  }
+
+  if (name === "npm") {
+    if (env.TOPAZLABSCLI_NPM) {
+      return { command: env.TOPAZLABSCLI_NPM, argsPrefix: [], resolution: "TOPAZLABSCLI_NPM" };
+    }
+    const npmExecPath = env.npm_execpath && pathApi.resolve(env.npm_execpath);
+    const managedNpm = firstExisting([
+      npmExecPath,
+      pathApi.join(pathApi.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js")
+    ], exists);
+    if (managedNpm) {
+      const versionDirectory = pathApi.dirname(execPath);
+      const versionsDirectory = pathApi.dirname(versionDirectory);
+      const managedRoot = pathApi.basename(versionsDirectory).toLowerCase() === "versions"
+        ? pathApi.dirname(versionsDirectory)
+        : null;
+      const managedPrefix = managedRoot && pathApi.join(managedRoot, "global");
+      const managedCache = managedRoot && pathApi.join(managedRoot, "cache");
+      const envPatch = managedPrefix && exists(managedPrefix)
+        ? {
+            npm_config_prefix: env.npm_config_prefix || managedPrefix,
+            ...(managedCache && exists(managedCache) ? { npm_config_cache: env.npm_config_cache || managedCache } : {})
+          }
+        : {};
+      return { command: execPath, argsPrefix: [managedNpm], envPatch, resolution: "managed-node-npm-cli" };
+    }
+  }
+
+  if (platform === "win32" && ["ssh", "sftp"].includes(name)) {
+    const override = env[`TOPAZLABSCLI_${name.toUpperCase()}`];
+    if (override) return { command: override, argsPrefix: [], resolution: `TOPAZLABSCLI_${name.toUpperCase()}` };
+    const windowsRoot = env.SystemRoot || env.WINDIR || "C:\\Windows";
+    const openSsh = pathApi.join(windowsRoot, "System32", "OpenSSH", `${name}.exe`);
+    if (exists(openSsh)) return { command: openSsh, argsPrefix: [], resolution: "windows-openssh" };
+  }
+
+  return { command: name, argsPrefix: [], resolution: "PATH" };
+}

package/src/skill.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { bundledSkill, skillTarget } from "./paths.mjs";
+import { binScript, bundledSkill, packageRoot, skillTarget } from "./paths.mjs";
 import { CliError } from "./errors.mjs";
 
 const agents = ["codex", "sealseek"];
@@ -23,7 +23,24 @@ export function skillStatus(selected = "all") {
   });
 }
 
+export function effectiveSkillMode(agent, requestedMode, platform = process.platform) {
+  if (platform === "win32" && agent === "sealseek" && requestedMode === "link") return "copy";
+  return requestedMode;
+}
+
+function writeRuntimeManifest(target) {
+  const manifest = {
+    schema: "topazlabscli-skill-runtime",
+    schema_version: 1,
+    node: process.execPath,
+    bin: binScript,
+    package_root: packageRoot
+  };
+  fs.writeFileSync(path.join(target, ".topazlabscli-runtime.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+}
+
 function installOne(agent, mode, update) {
+  const effectiveMode = effectiveSkillMode(agent, mode);
   const target = skillTarget(agent);
   fs.mkdirSync(path.dirname(target), { recursive: true });
   if (fs.existsSync(target)) {
@@ -32,9 +49,11 @@ function installOne(agent, mode, update) {
     if (stat.isSymbolicLink()) fs.unlinkSync(target);
     else fs.rmSync(target, { recursive: true, force: true });
   }
-  if (mode === "copy") fs.cpSync(bundledSkill, target, { recursive: true });
-  else fs.symlinkSync(bundledSkill, target, process.platform === "win32" ? "junction" : "dir");
-  return { agent, target, mode };
+  if (effectiveMode === "copy") {
+    fs.cpSync(bundledSkill, target, { recursive: true });
+    writeRuntimeManifest(target);
+  } else fs.symlinkSync(bundledSkill, target, process.platform === "win32" ? "junction" : "dir");
+  return { agent, target, mode: effectiveMode, source: bundledSkill };
 }
 
 export function skillInstall(selected = "all", mode = "link", update = false) {

package/src/ssh.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { run } from "./process.mjs";
+import { resolveExecutable } from "./runtime.mjs";
 import { CliError } from "./errors.mjs";
 
 function destination(target, endpoint) {
@@ -22,13 +23,15 @@ export function encodePowerShell(script) {
 export async function runPowerShell(target, endpoint, script, { timeout = 7 } = {}) {
   const args = [...commonArgs(target, endpoint, { timeout }), destination(target, endpoint),
     "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
-  return run("ssh", args);
+  return run("ssh", args, { timeoutMs: (timeout + 3) * 1000 });
 }
 
 export function startPowerShellDetached(target, endpoint, script) {
   const args = [...commonArgs(target, endpoint, { timeout: 10 }), destination(target, endpoint),
     "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
-  const child = spawn("ssh", args, { detached: true, stdio: "ignore", windowsHide: true });
+  const executable = resolveExecutable("ssh");
+  const child = spawn(executable.command, [...executable.argsPrefix, ...args], { detached: true, stdio: "ignore", windowsHide: true });
+  child.on("error", () => {});
   child.unref();
   return child.pid;
 }
@@ -38,7 +41,13 @@ export async function selectEndpoint(target) {
   for (const endpoint of target.endpoints) {
     const result = await runPowerShell(target, endpoint, "[Console]::Out.Write('TOPAZLABSCLI_OK')");
     const ok = result.code === 0 && result.stdout.includes("TOPAZLABSCLI_OK");
-    attempts.push({ name: endpoint.name, host: endpoint.host, ok, error: ok ? null : result.stderr.trim() });
+    attempts.push({
+      name: endpoint.name,
+      host: endpoint.host,
+      ok,
+      timed_out: Boolean(result.timedOut),
+      error: ok ? null : result.stderr.trim()
+    });
     if (ok) return { endpoint, attempts };
   }
   throw new CliError("CONNECTION_FAILED", `No endpoint is reachable for target ${target.name}.`, { attempts });
@@ -61,7 +70,7 @@ export async function sftpPut(target, endpoint, localPath, remotePath) {
   if (endpoint.port) args.push("-P", String(endpoint.port));
   args.push(destination(target, endpoint));
   const input = `put ${quoteSftp(path.resolve(localPath))} ${quoteSftp(windowsToSftp(remotePath))}\n`;
-  const result = await run("sftp", args, { input });
+  const result = await run("sftp", args, { input, timeoutMs: 15000 });
   if (result.code !== 0) throw new CliError("UPLOAD_FAILED", result.stderr.trim() || "SFTP upload failed.");
   return result;
 }
@@ -73,7 +82,7 @@ export async function sftpGet(target, endpoint, remotePath, localPath) {
   if (endpoint.port) args.push("-P", String(endpoint.port));
   args.push(destination(target, endpoint));
   const input = `get ${quoteSftp(windowsToSftp(remotePath))} ${quoteSftp(path.resolve(localPath))}\n`;
-  const result = await run("sftp", args, { input });
+  const result = await run("sftp", args, { input, timeoutMs: 15000 });
   if (result.code !== 0) throw new CliError("DOWNLOAD_FAILED", result.stderr.trim() || "SFTP download failed.");
   return result;
 }

package/src/update.mjs

@@ -6,6 +6,8 @@ import { run, runInherited } from "./process.mjs";
 import { skillInstall, skillStatus } from "./skill.mjs";
 
 const DEFAULT_INTERVAL_HOURS = 6;
+const DEFAULT_MIRROR_REGISTRY = "https://registry.npmmirror.com/";
+const UPDATE_TIMEOUT_MS = 8000;
 const UPDATE_GUARD = "TOPAZLABSCLI_AUTO_UPDATE_GUARD";
 
 function numericParts(version) {
@@ -41,6 +43,87 @@ function automaticUpdateEnabled(config, env) {
   return config.settings?.auto_update !== false;
 }
 
+function normalizeRegistry(value) {
+  const text = String(value || "").trim();
+  if (!/^https?:\/\//i.test(text)) return null;
+  return text.endsWith("/") ? text : `${text}/`;
+}
+
+function uniqueRegistries(values) {
+  return [...new Set(values.map(normalizeRegistry).filter(Boolean))];
+}
+
+export async function resolveUpdateRegistries(config, dependencies = {}) {
+  const env = dependencies.env || process.env;
+  const execute = dependencies.run || run;
+  const configured = config.settings?.update_registry;
+  const overrides = String(env.TOPAZLABSCLI_UPDATE_REGISTRY || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const preferred = configured && configured !== "auto" ? [configured] : [];
+  let npmRegistry = null;
+  try {
+    const result = await execute("npm", ["config", "get", "registry"], {
+      env,
+      timeoutMs: dependencies.timeoutMs || UPDATE_TIMEOUT_MS
+    });
+    if (result.code === 0) npmRegistry = result.stdout.trim();
+  } catch {}
+  return uniqueRegistries([...overrides, ...preferred, npmRegistry, DEFAULT_MIRROR_REGISTRY]);
+}
+
+export async function queryLatestVersion(pkg, config, dependencies = {}) {
+  const env = dependencies.env || process.env;
+  const execute = dependencies.run || run;
+  const registries = dependencies.registries || await resolveUpdateRegistries(config, dependencies);
+  const attempts = [];
+  for (const registry of registries) {
+    let result;
+    try {
+      result = await execute("npm", ["view", pkg.name, "version", "--json", "--registry", registry], {
+        env: {
+          ...env,
+          npm_config_fetch_timeout: env.npm_config_fetch_timeout || "5000",
+          npm_config_fetch_retries: "0"
+        },
+        timeoutMs: dependencies.timeoutMs || UPDATE_TIMEOUT_MS
+      });
+    } catch (error) {
+      attempts.push({ registry, ok: false, detail: error.message });
+      continue;
+    }
+    if (result.code !== 0) {
+      attempts.push({
+        registry,
+        ok: false,
+        detail: result.timedOut ? "timed out" : (result.stderr.trim() || "registry query failed")
+      });
+      continue;
+    }
+    let latest;
+    try { latest = JSON.parse(result.stdout.trim()); }
+    catch { latest = result.stdout.trim().replace(/^"|"$/g, ""); }
+    attempts.push({ registry, ok: true, latest });
+    return { ok: true, latest, registry, attempts };
+  }
+  return { ok: false, attempts };
+}
+
+function registryFailureMessage(attempts) {
+  if (!attempts.length) return "No valid npm update registry is configured.";
+  return `Unable to check npm for updates: ${attempts.map((item) => `${item.registry} (${item.detail})`).join("; ")}`;
+}
+
+export async function installLatestPackage(pkg, registry, dependencies = {}) {
+  const env = dependencies.env || process.env;
+  const execute = dependencies.run || run;
+  return execute("npm", ["install", "--global", `${pkg.name}@latest`, "--registry", registry], {
+    env,
+    timeoutMs: dependencies.installTimeoutMs
+  });
+}
+
 export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
   const env = dependencies.env || process.env;
   if (env[UPDATE_GUARD] === "1") return { checked: false, reason: "guard" };
@@ -54,35 +137,46 @@ export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
   const intervalMs = Math.max(0, intervalHours) * 60 * 60 * 1000;
   const state = readState(stateFile);
   if (intervalMs > 0 && Number.isFinite(state.last_checked_at) && now - state.last_checked_at < intervalMs) {
-    return { checked: false, reason: "fresh", latest: state.latest || null };
+    return { checked: false, reason: "fresh", latest: state.latest || null, registry: state.registry || null };
   }
 
-  const execute = dependencies.run || run;
-  const query = await execute("npm", ["view", pkg.name, "version", "--json"], {
-    env: { ...env, npm_config_fetch_timeout: env.npm_config_fetch_timeout || "5000", npm_config_fetch_retries: "0" }
-  });
-  if (query.code !== 0) {
-    return { checked: true, warning: query.stderr.trim() || "Unable to check npm for updates." };
-  }
+  const query = await queryLatestVersion(pkg, config, dependencies);
+  if (!query.ok) return { checked: true, warning: registryFailureMessage(query.attempts), attempts: query.attempts };
 
-  let latest;
-  try { latest = JSON.parse(query.stdout.trim()); }
-  catch { latest = query.stdout.trim().replace(/^"|"$/g, ""); }
-  writeState(stateFile, { last_checked_at: now, latest, current: pkg.version });
-  if (!isNewerVersion(latest, pkg.version)) return { checked: true, updated: false, latest };
+  const { latest, registry } = query;
+  writeState(stateFile, { last_checked_at: now, latest, current: pkg.version, registry });
+  if (!isNewerVersion(latest, pkg.version)) return { checked: true, updated: false, latest, registry, attempts: query.attempts };
 
   const getSkillStatus = dependencies.skillStatus || skillStatus;
   const installSkill = dependencies.skillInstall || skillInstall;
   const installedSkills = getSkillStatus("all").filter((item) => item.installed);
-  const install = await execute("npm", ["install", "--global", `${pkg.name}@latest`], { env });
+  let install;
+  try {
+    install = await installLatestPackage(pkg, registry, dependencies);
+  } catch (error) {
+    return { checked: true, warning: `Automatic npm update failed: ${error.message}`, latest, registry };
+  }
   if (install.code !== 0) {
-    return { checked: true, warning: install.stderr.trim() || "Automatic npm update failed.", latest };
+    return { checked: true, warning: install.stderr.trim() || "Automatic npm update failed.", latest, registry };
+  }
+  const warnings = [];
+  for (const item of installedSkills) {
+    try { installSkill(item.agent, item.mode || "link", true); }
+    catch (error) { warnings.push(`Skill refresh failed for ${item.agent}: ${error.message}`); }
   }
-  for (const item of installedSkills) installSkill(item.agent, item.mode || "link", true);
 
   const reexecute = dependencies.runInherited || runInherited;
-  const child = await reexecute(process.execPath, [binScript, ...rawArgs], {
-    env: { ...env, [UPDATE_GUARD]: "1" }
-  });
-  return { checked: true, updated: true, latest, reexecuted: true, exitCode: child.code ?? 1 };
+  try {
+    const child = await reexecute(process.execPath, [binScript, ...rawArgs], {
+      env: { ...env, [UPDATE_GUARD]: "1" }
+    });
+    return { checked: true, updated: true, latest, registry, reexecuted: true, exitCode: child.code ?? 1, warnings };
+  } catch (error) {
+    warnings.push(`Updated package could not restart the command: ${error.message}`);
+    return { checked: true, updated: true, latest, registry, warning: warnings.join(" ") };
+  }
+}
+
+export function updateRegistryWarning(attempts) {
+  return registryFailureMessage(attempts);
 }