agentworkforce 4.1.27 → 4.1.30

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.29] - 2026-07-17
+
+### Fixed
+
+- Select a newer coherent project-local `agentworkforce` installation ahead of
+  an older global one, while refusing partial or version-skewed wrapper/CLI
+  pairs. Version output now validates the exact implementation it represents
+  (#163).
+
 ## [4.1.18] - 2026-07-15
 
 ### Added

package/README.md

@@ -22,6 +22,17 @@ This package is a thin wrapper around [`@agentworkforce/cli`](https://www.npmjs.
 It exists so the global install command and the binary name match the
 project name.
 
+The wrapper validates that its associated `@agentworkforce/cli` has the same
+version before running it. When the current project has a newer local
+`agentworkforce` install, the wrapper uses that install only when its wrapper
+and associated CLI versions also match. Partial installs fail with a copyable
+reinstall command instead of silently executing a stale nested CLI.
+An already-running pre-fix wrapper cannot use this selection logic, so users on
+4.1.25 must reinstall or update `agentworkforce` before the fix can take effect.
+The fixed wrapper does not query a registry for the latest release, so without a
+newer coherent local install it cannot detect that its own coherent version is
+stale relative to a future release; updating or reinstalling remains required.
+
 See the [main README](https://github.com/AgentWorkforce/workforce#readme)
 for the full feature tour, and [`packages/cli/README.md`](https://github.com/AgentWorkforce/workforce/blob/main/packages/cli/README.md)
 for command reference.

package/bin/agentworkforce.js

@@ -1,30 +1,242 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+class InstallationError extends Error {}
 
 // Top-level wrapper. Delegates to the @agentworkforce/cli entry point under the
 // shorter `agentworkforce` bin name so users can `npm i -g agentworkforce` and
 // run `agentworkforce agent <persona>`. The CLI derives its help-text bin name
 // from process.argv[1], so this file's basename (sans extension) is what
 // shows up in usage strings.
-function readPackageVersion() {
-  const pkg = JSON.parse(
-    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
-  );
+function readPackage(packageJson, label) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(packageJson, 'utf8'));
+  } catch {
+    throw new InstallationError(`${label} package metadata is invalid.`);
+  }
   if (typeof pkg.version !== 'string' || !pkg.version) {
-    throw new Error('Could not read agentworkforce package version.');
+    throw new InstallationError(`Could not read ${label} package version.`);
   }
-  return pkg.version;
+  return pkg;
+}
+
+function resolveCli() {
+  const wrapperPackageJsonUrl = new URL('../package.json', import.meta.url);
+  const wrapper = readPackage(
+    wrapperPackageJsonUrl,
+    'agentworkforce'
+  );
+  parseVersion(wrapper.version, 'agentworkforce wrapper');
+  const project = resolveProjectInstall(
+    fileURLToPath(wrapperPackageJsonUrl),
+    wrapper.version
+  );
+
+  if (project) {
+    if (project.wrapperVersion !== project.cli.version) {
+      throw new InstallationError(
+        [
+          'project-local agentworkforce installation is inconsistent; refusing to run it.',
+          `project wrapper version: ${project.wrapperVersion}`,
+          `project @agentworkforce/cli version: ${project.cli.version}`,
+          `Repair it with: npm install agentworkforce@${project.wrapperVersion}`
+        ].join('\n')
+      );
+    }
+    return { version: project.cli.version, entryUrl: project.cli.entryUrl };
+  }
+
+  // Only require the invoked wrapper's dependency after checking whether a
+  // newer coherent project install wins. A partial global install must not
+  // mask a complete, newer local candidate.
+  const bundledRepair = `npm install -g agentworkforce@${wrapper.version}`;
+  const bundled = readCliCandidate(
+    resolveAssociatedCliPackageJson(
+      require,
+      'agentworkforce installation',
+      bundledRepair
+    ),
+    'wrapper dependency',
+    bundledRepair
+  );
+
+  if (wrapper.version !== bundled.version) {
+    throw new InstallationError(
+      [
+        'agentworkforce installation is inconsistent; refusing to run a stale nested CLI.',
+        `wrapper version: ${wrapper.version}`,
+        `resolved @agentworkforce/cli version: ${bundled.version}`,
+        `Repair it with: npm install -g agentworkforce@${wrapper.version}`
+      ].join('\n')
+    );
+  }
+
+  return {
+    version: bundled.version,
+    entryUrl: bundled.entryUrl
+  };
+}
+
+function resolveProjectInstall(invokedWrapperPackageJsonPath, invokedWrapperVersion) {
+  const projectRequire = createRequire(
+    pathToFileURL(path.join(process.cwd(), '__agentworkforce_resolve__.cjs'))
+  );
+  let wrapperPackageJsonPath;
+  try {
+    wrapperPackageJsonPath = projectRequire.resolve('agentworkforce/package.json');
+  } catch (error) {
+    if (error?.code === 'MODULE_NOT_FOUND') return undefined;
+    throw new InstallationError(
+      [
+        'project-local agentworkforce package metadata cannot be inspected; refusing to run an unverified local installation.',
+        'Repair it with: npm install agentworkforce'
+      ].join('\n')
+    );
+  }
+
+  if (path.resolve(wrapperPackageJsonPath) === path.resolve(invokedWrapperPackageJsonPath)) {
+    return undefined;
+  }
+
+  const projectWrapper = readPackage(wrapperPackageJsonPath, 'project-local agentworkforce');
+  // Validate candidate version syntax even when it would not win selection;
+  // a broken local launcher must not be silently mistaken for an older one.
+  parseVersion(projectWrapper.version, 'project-local agentworkforce');
+  if (compareVersions(projectWrapper.version, invokedWrapperVersion) <= 0) {
+    return undefined;
+  }
+  const localRequire = createRequire(pathToFileURL(wrapperPackageJsonPath));
+  const repairCommand = `npm install agentworkforce@${projectWrapper.version}`;
+  const cliPackageJsonPath = resolveAssociatedCliPackageJson(
+    localRequire,
+    'project-local agentworkforce installation',
+    repairCommand
+  );
+  return {
+    wrapperVersion: projectWrapper.version,
+    cli: readCliCandidate(
+      cliPackageJsonPath,
+      'project-local wrapper dependency',
+      repairCommand
+    )
+  };
+}
+
+function resolveAssociatedCliPackageJson(localRequire, installationLabel, repairCommand) {
+  try {
+    return localRequire.resolve('@agentworkforce/cli/package.json');
+  } catch {
+    throw new InstallationError(
+      [
+        `${installationLabel} has no resolvable @agentworkforce/cli metadata; refusing to run a partial or unverified installation.`,
+        `Repair it with: ${repairCommand}`
+      ].join('\n')
+    );
+  }
+}
+
+function readCliCandidate(packageJsonPath, source, repairCommand) {
+  const pkg = readPackage(packageJsonPath, `@agentworkforce/cli ${source}`);
+  parseVersion(pkg.version, `@agentworkforce/cli ${source}`);
+  const entryUrl = new URL('./dist/cli.js', pathToFileURL(packageJsonPath));
+  if (!existsSync(fileURLToPath(entryUrl))) {
+    throw new InstallationError(
+      [
+        `@agentworkforce/cli ${source} has no executable entry; refusing to run a partial installation.`,
+        `Repair it with: ${repairCommand}`
+      ].join('\n')
+    );
+  }
+  return {
+    version: pkg.version,
+    entryUrl: entryUrl.href
+  };
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  for (let i = 0; i < 3; i += 1) {
+    if (a.numbers[i] < b.numbers[i]) return -1;
+    if (a.numbers[i] > b.numbers[i]) return 1;
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+function comparePrerelease(left, right) {
+  const a = left.split('.');
+  const b = right.split('.');
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    if (a[i] === undefined) return -1;
+    if (b[i] === undefined) return 1;
+    if (a[i] === b[i]) continue;
+    const aNumeric = /^\d+$/.test(a[i]);
+    const bNumeric = /^\d+$/.test(b[i]);
+    if (aNumeric && bNumeric) {
+      const aNumber = BigInt(a[i]);
+      const bNumber = BigInt(b[i]);
+      if (aNumber < bNumber) return -1;
+      if (aNumber > bNumber) return 1;
+      continue;
+    }
+    if (aNumeric) return -1;
+    if (bNumeric) return 1;
+    return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+function parseVersion(version, label = 'package') {
+  const identifier = '[0-9A-Za-z-]+';
+  const match = new RegExp(
+    `^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)` +
+    `(?:-(${identifier}(?:\\.${identifier})*))?` +
+    `(?:\\+${identifier}(?:\\.${identifier})*)?$`
+  ).exec(version);
+  const prerelease = match?.[4] ?? '';
+  const hasInvalidNumericIdentifier = prerelease
+    .split('.')
+    .some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0'));
+  if (!match || hasInvalidNumericIdentifier) {
+    throw new InstallationError(
+      `${label} has an invalid semantic version: ${JSON.stringify(version)}`
+    );
+  }
+  return {
+    numbers: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+    prerelease
+  };
 }
 
 try {
+  // Resolve and validate the implementation even for --version. Reporting the
+  // wrapper version alone used to hide partially-updated installations where
+  // this package was current but its nested CLI (and deploy stack) was stale.
+  const cli = resolveCli();
+
   if (process.argv[2] === '-v' || process.argv[2] === '--version') {
-    process.stdout.write(`${readPackageVersion()}\n`);
+    process.stdout.write(`${cli.version}\n`);
     process.exit(0);
   }
 
-  const { main } = await import('@agentworkforce/cli/dist/cli.js');
+  // Import the entry from the exact package whose version was checked above;
+  // do not ask the module resolver a second time and risk selecting a different
+  // hoisted or nested copy.
+  const { main } = await import(cli.entryUrl);
   await main();
 } catch (err) {
-  process.stderr.write(`${err?.stack ?? String(err)}\n`);
+  process.stderr.write(
+    `${err instanceof InstallationError ? err.message : (err?.stack ?? String(err))}\n`
+  );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworkforce",
-  "version": "4.1.27",
+  "version": "4.1.30",
   "private": false,
   "description": "Top-level installer for the Agent Workforce CLI (installs the `agentworkforce` command). Wraps @agentworkforce/cli.",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agentworkforce/cli": "4.1.27"
+    "@agentworkforce/cli": "4.1.30"
   },
   "repository": {
     "type": "git",