@petercjl/topazlabscli 0.1.1 → 0.2.1

package/README.md

@@ -15,6 +15,10 @@ 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. 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 npm 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
 
 Use one or more SSH endpoints in priority order. A LAN-only user configures only the LAN entry.
@@ -56,9 +60,11 @@ The worker uses a global Windows mutex and one queue consumer, so jobs from mult
 ## Process a video
 
 ```powershell
-topazlabscli process .\input.mp4 --output .\output-1080p.mp4 --json
+topazlabscli process .\input.mp4 --json
 ```
 
+Without `--output`, the CLI writes `input-topaz-1080p.mp4` beside the source video. An explicit `--output` remains available for automation.
+
 Asynchronous form:
 
 ```powershell
@@ -68,7 +74,7 @@ topazlabscli job wait JOB_ID --json
 topazlabscli job download JOB_ID --output .\output-1080p.mp4 --json
 ```
 
-Version 0.1 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding.
+Version 0.2 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/topazlabscli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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 && 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

@@ -9,41 +9,44 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 ## Input → Strategy → Output
 
-- Input: a local video path or a job identifier, the user's requested action, and an already configured target.
+- Input: a local video path or a job identifier, the user's requested action, and an already configured target. A processing request needs only the input path.
 - Strategy: inspect capabilities and health, select the configured reachable endpoint, submit one deterministic preset to the serialized Windows queue, observe terminal state, and download only when requested.
 - Output: structured CLI evidence, a job identifier and state, and for completed processing an explicitly requested local output file.
 
 ## 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 and the output path is authorized.
-4. Prefer `topazlabscli process INPUT --output OUTPUT --json` for submit, wait, and download as one operation. 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
 
-`seedance-human-1080p` is the only built-in preset in version 0.1. It uses Proteus v4 (`prob-4`), preserves source FPS and aspect ratio, targets a 1080-pixel short edge, and relies on the remote queue's single concurrency slot. Do not silently substitute another model, frame interpolation, stabilization, motion deblur, or 4K output.
+`seedance-human-1080p` is the only built-in preset in version 0.2. It uses Proteus v4 (`prob-4`), preserves source FPS and aspect ratio, targets a 1080-pixel short edge, and relies on the remote queue's single concurrency slot. Do not silently substitute another model, frame interpolation, stabilization, motion deblur, or 4K output.
 
 ## Branches
 
 - Connection failure: report `CONNECTION_FAILED` and the endpoint attempts. The CLI does not start, reconfigure, or grant access to a VPN.
 - Worker/model not ready: run `worker status` or `model status`; stop with the returned dependency error. Installing/licensing Topaz and downloading models remain GUI administration tasks.
 - Long-running work: use `job submit`, return the job ID, then `job wait` when the user asks to remain attached. Do not resubmit merely because a wait timed out.
-- Cancellation: queued work may cancel immediately. A running task records a cancellation request but is not forcibly killed in version 0.1.
+- Cancellation: queued work may cancel immediately. A running task records a cancellation request but is not forcibly killed in version 0.2.
 - Missing capability: return `CAPABILITY_UNAVAILABLE` or the CLI's structured error. Do not invent a platform-specific workaround.
 
 ## Configuration and Safety
 
 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.
 
-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.1.
+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. 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.
+
+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"],
+      "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/skill/topazlabscli/capabilities.json

@@ -6,13 +6,13 @@
   "capabilities": [
     {
       "id": "command.execute",
-      "purpose": "Run the stable topazlabscli executable and parse JSON results.",
+      "purpose": "Run the stable, self-updating topazlabscli executable and parse JSON results.",
       "required": true,
       "required_features": ["local-process", "stdout-json", "exit-code"],
       "input_fields": ["argv"],
       "output_fields": ["ok", "data", "error"],
       "side_effects": {
-        "external_mutation": "May upload videos and enqueue remote processing only when the user requests processing.",
+        "external_mutation": "May update the installed npm package and Agent Skill before a command; may upload videos and enqueue remote processing only when the user requests processing.",
         "may_cost_money": false,
         "authorization": "Requires the user's configured SSH access and an explicit processing request."
       },

package/src/cli.mjs

@@ -8,6 +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";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -17,9 +18,10 @@ const CAPABILITIES = {
   schema_version: 1,
   package: pkg.name,
   version: pkg.version,
-  commands: ["version", "capabilities", "doctor", "target", "connection", "worker", "model", "job", "process", "skill", "update"],
+  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 },
   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"]
 };
@@ -58,6 +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` +
     `  target add <name> --endpoint <label=host>... --user <user> [--identity <path>] [--workspace <windows-path>] [--default]\n` +
     `  target list\n` +
     `  connection check [--target <name>]\n` +
@@ -66,7 +69,7 @@ function help() {
     `  job submit <video> [--target <name>] [--preset ${PRESET}]\n` +
     `  job list [--target <name>]\n` +
     `  job status|wait|download|cancel <job-id> [--target <name>] [--output <path>]\n` +
-    `  process <video> --output <path> [--target <name>]\n` +
+    `  process <video> [--output <path>] [--target <name>]\n` +
     `  skill source|status|install|update [--agent codex|sealseek|all] [--copy]\n` +
     `  update\n\nUse --json for machine-readable output.`;
 }
@@ -143,6 +146,12 @@ async function downloadJob(id, requestedTarget, outputPath) {
   return { id, target: target.name, endpoint: endpoint.name, output: destination };
 }
 
+export function defaultOutputPath(inputPath) {
+  const resolved = path.resolve(inputPath);
+  const extension = path.extname(resolved) || ".mp4";
+  return path.join(path.dirname(resolved), `${path.basename(resolved, path.extname(resolved))}-topaz-1080p${extension}`);
+}
+
 async function doctor(requestedTarget) {
   const checks = [];
   for (const command of ["ssh", "sftp", "node", "npm"]) {
@@ -150,7 +159,14 @@ async function doctor(requestedTarget) {
     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 (requestedTarget || fs.existsSync(configPath())) {
@@ -177,6 +193,37 @@ export async function main(rawArgs) {
   const command = args.shift();
   if (command === "version" || command === "--version" || command === "-V") return output(pkg.version, json);
   if (command === "capabilities") return output(CAPABILITIES, json);
+
+  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;
+      return;
+    }
+  }
+
+  if (command === "settings") {
+    const action = args.shift() || "show";
+    const config = loadConfig();
+    if (action === "show") return output(config.settings, json);
+    if (action === "set") {
+      const name = requireValue(args.shift(), "SETTING_REQUIRED", "settings set requires a setting name.");
+      const value = requireValue(args.shift(), "VALUE_REQUIRED", `settings set ${name} requires a value.`);
+      if (name === "auto-update") {
+        if (!["on", "off"].includes(value)) throw new CliError("SETTING_INVALID", "auto-update must be on or off.");
+        config.settings.auto_update = value === "on";
+      } else if (name === "update-check-hours") {
+        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 throw new CliError("SETTING_UNKNOWN", `Unknown setting: ${name}`);
+      const saved = saveConfig(config);
+      return output({ path: saved, settings: config.settings }, json);
+    }
+    throw new CliError("COMMAND_UNKNOWN", `Unknown settings action: ${action}`);
+  }
+
   if (command === "doctor") return output(await doctor(option(args, "--target")), json);
 
   if (command === "target") {
@@ -253,7 +300,7 @@ export async function main(rawArgs) {
 
   if (command === "process") {
     const input = requireValue(args.shift(), "INPUT_REQUIRED", "process requires a video.");
-    const destination = requireValue(option(args, "--output"), "OUTPUT_REQUIRED", "process requires --output.");
+    const destination = option(args, "--output") || defaultOutputPath(input);
     const requested = option(args, "--target");
     const submitted = await submitJob(input, requested, option(args, "--preset") || PRESET);
     const finished = await waitJob(submitted.id, requested, Number(option(args, "--interval") || 10), Number(option(args, "--timeout") || 86400));

package/src/config.mjs

@@ -4,7 +4,12 @@ import { configPath } from "./paths.mjs";
 import { CliError } from "./errors.mjs";
 
 export function emptyConfig() {
-  return { schema_version: 1, default_target: null, targets: {} };
+  return {
+    schema_version: 1,
+    default_target: null,
+    targets: {},
+    settings: { auto_update: true, update_check_hours: 6 }
+  };
 }
 
 export function loadConfig({ required = false } = {}) {
@@ -18,7 +23,15 @@ export function loadConfig({ required = false } = {}) {
     if (parsed.schema_version !== 1 || typeof parsed.targets !== "object") {
       throw new Error("unsupported configuration schema");
     }
-    return parsed;
+    return {
+      ...parsed,
+      settings: {
+        auto_update: parsed.settings?.auto_update !== false,
+        update_check_hours: Number.isFinite(parsed.settings?.update_check_hours)
+          ? parsed.settings.update_check_hours
+          : 6
+      }
+    };
   } catch (error) {
     throw new CliError("CONFIG_INVALID", `Cannot read configuration: ${error.message}`, { path: filename });
   }

package/src/paths.mjs

@@ -1,9 +1,11 @@
 import os from "node:os";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const packageRoot = path.resolve(here, "..");
+export const binScript = path.join(packageRoot, "bin", "topazlabscli.mjs");
 export const bundledSkill = path.join(packageRoot, "skill", "topazlabscli");
 export const workerScript = path.join(packageRoot, "worker", "windows", "topazlabs-worker.ps1");
 
@@ -15,13 +17,27 @@ export function configPath() {
   return path.join(base, "topazlabscli", "config.json");
 }
 
-export function skillTarget(agent) {
-  const home = os.homedir();
+export function updateStatePath() {
+  if (process.env.TOPAZLABSCLI_UPDATE_STATE) return path.resolve(process.env.TOPAZLABSCLI_UPDATE_STATE);
+  return path.join(path.dirname(configPath()), "update-state.json");
+}
+
+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,21 +1,50 @@
 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);
     }
   });
 }
+
+export function runInherited(command, args, options = {}) {
+  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), ...(executable.envPatch || {}) },
+      stdio: "inherit",
+      windowsHide: true
+    });
+    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

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.mjs";
+import { binScript, updateStatePath } from "./paths.mjs";
+import { run, runInherited } from "./process.mjs";
+import { skillInstall, skillStatus } from "./skill.mjs";
+
+const DEFAULT_INTERVAL_HOURS = 6;
+const UPDATE_GUARD = "TOPAZLABSCLI_AUTO_UPDATE_GUARD";
+
+function numericParts(version) {
+  return String(version).replace(/^v/, "").split(/[.+-]/).slice(0, 3).map((part) => Number(part) || 0);
+}
+
+export function isNewerVersion(candidate, current) {
+  const left = numericParts(candidate);
+  const right = numericParts(current);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function readState(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, "utf8")); }
+  catch { return {}; }
+}
+
+function writeState(filename, value) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temporary = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, filename);
+  try { fs.chmodSync(filename, 0o600); } catch {}
+}
+
+function automaticUpdateEnabled(config, env) {
+  const override = env.TOPAZLABSCLI_AUTO_UPDATE?.toLowerCase();
+  if (["0", "false", "off", "no"].includes(override)) return false;
+  if (["1", "true", "on", "yes"].includes(override)) return true;
+  return config.settings?.auto_update !== false;
+}
+
+export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
+  const env = dependencies.env || process.env;
+  if (env[UPDATE_GUARD] === "1") return { checked: false, reason: "guard" };
+
+  const config = (dependencies.loadConfig || loadConfig)();
+  if (!automaticUpdateEnabled(config, env)) return { checked: false, reason: "disabled" };
+
+  const stateFile = dependencies.stateFile || updateStatePath();
+  const now = dependencies.now?.() || Date.now();
+  const intervalHours = Number(config.settings?.update_check_hours ?? DEFAULT_INTERVAL_HOURS);
+  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 };
+  }
+
+  const execute = dependencies.run || run;
+  let query;
+  try {
+    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" }
+    });
+  } catch (error) {
+    return { checked: true, warning: `Unable to check npm for updates: ${error.message}` };
+  }
+  if (query.code !== 0) {
+    return { checked: true, warning: query.stderr.trim() || "Unable to check npm for updates." };
+  }
+
+  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 getSkillStatus = dependencies.skillStatus || skillStatus;
+  const installSkill = dependencies.skillInstall || skillInstall;
+  const installedSkills = getSkillStatus("all").filter((item) => item.installed);
+  let install;
+  try {
+    install = await execute("npm", ["install", "--global", `${pkg.name}@latest`], { env });
+  } catch (error) {
+    return { checked: true, warning: `Automatic npm update failed: ${error.message}`, latest };
+  }
+  if (install.code !== 0) {
+    return { checked: true, warning: install.stderr.trim() || "Automatic npm update failed.", latest };
+  }
+  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}`); }
+  }
+
+  const reexecute = dependencies.runInherited || runInherited;
+  try {
+    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, warnings };
+  } catch (error) {
+    warnings.push(`Updated package could not restart the command: ${error.message}`);
+    return { checked: true, updated: true, latest, warning: warnings.join(" ") };
+  }
+}