hermes-agent 0.22.2 → 0.22.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,21 +1,33 @@
1
- const { spawn, spawnSync } = require("node:child_process");
1
+ const { spawnSync } = require("node:child_process");
2
2
  const fs = require("node:fs");
3
3
  const path = require("node:path");
4
4
 
5
5
  const packageJson = require("../package.json");
6
- const { getRuntimeSourceDirectory } = require("./python-launcher");
6
+ const { provisionRuntime } = require("./provision");
7
+ const {
8
+ getRuntimeSourceDirectory,
9
+ resolveRuntimeSourceDirectory,
10
+ venvConsoleExecutable
11
+ } = require("./python-launcher");
7
12
  const {
8
13
  createUpstreamMigrationPlan,
9
14
  executeUpstreamMigration,
10
15
  getDefaultHermesHome
11
16
  } = require("./upstream-migration");
17
+ const { readUpstreamOwnership } = require("./upstream-ownership");
12
18
 
13
19
  const packageRoot = path.resolve(__dirname, "..");
14
20
  const npmRegistry = "https://registry.npmjs.org";
15
21
  const canonicalPackageName = packageJson.hermesAgent?.canonicalNpmPackage || packageJson.name;
16
22
 
17
- function npmCommand() {
18
- return process.platform === "win32" ? "npm.cmd" : "npm";
23
+ // Node refuses to spawn .cmd files without a shell (CVE-2024-27980), so on
24
+ // Windows npm is started through cmd.exe. Every argument passed here is a
25
+ // fixed token or a validated semver/package name.
26
+ function getNpmSpawnSpec(args, platform = process.platform, env = process.env) {
27
+ if (platform === "win32") {
28
+ return { command: env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "npm", ...args] };
29
+ }
30
+ return { command: "npm", args: [...args] };
19
31
  }
20
32
 
21
33
  function runGit(args, options = {}) {
@@ -50,6 +62,15 @@ function isReleasePinned(runtimeReady, runtimeCommit, packagedCommit, runtimeDir
50
62
  );
51
63
  }
52
64
 
65
+ // The release channel needs both the pinned source and npm's own dependency
66
+ // environment. Once upstream's package manager has recorded an environment
67
+ // for the checkout, or stamped it as self-managed, upstream decides what runs
68
+ // even when the commit still matches the npm Release.
69
+ function getRuntimeChannel(runtimeReady, releasePinned, upstreamManaged) {
70
+ if (!runtimeReady) return "missing";
71
+ return releasePinned && !upstreamManaged ? "npm-release" : "upstream-native";
72
+ }
73
+
53
74
  function findNodeModulesOwner(startPath) {
54
75
  let current = path.resolve(startPath);
55
76
  while (true) {
@@ -69,13 +90,25 @@ function pathsReferToSameInstallLocation(left, right, platform = process.platfor
69
90
  : left === right;
70
91
  }
71
92
 
93
+ // Node.js loads modules from their real path, while 'npm root --global' can
94
+ // report a path through a symlink (macOS /var -> /private/var, symlinked
95
+ // prefixes), so compare real paths.
96
+ function realPathOrSelf(target) {
97
+ try {
98
+ return fs.realpathSync.native(target);
99
+ } catch {
100
+ return target;
101
+ }
102
+ }
103
+
72
104
  function detectInstallContext() {
73
- const result = spawnSync(npmCommand(), ["root", "--global"], {
105
+ const npm = getNpmSpawnSpec(["root", "--global"]);
106
+ const result = spawnSync(npm.command, npm.args, {
74
107
  encoding: "utf8",
75
108
  windowsHide: true
76
109
  });
77
- const globalRoot = result.status === 0 ? path.resolve(result.stdout.trim()) : null;
78
- const packageParent = path.dirname(packageRoot);
110
+ const globalRoot = result.status === 0 ? realPathOrSelf(path.resolve(result.stdout.trim())) : null;
111
+ const packageParent = realPathOrSelf(path.dirname(packageRoot));
79
112
  const isGlobal = pathsReferToSameInstallLocation(packageParent, globalRoot);
80
113
  return {
81
114
  isGlobal,
@@ -187,6 +220,22 @@ function readRuntimeStatus() {
187
220
  runtimeDirtyPaths
188
221
  );
189
222
  const context = detectInstallContext();
223
+ const venvDirectory = path.join(sourceDirectory, "venv");
224
+ const ownership = readUpstreamOwnership(sourceDirectory, {
225
+ isTracked: (file) => {
226
+ const tracked = runGit(["-C", sourceDirectory, "ls-files", "--", file]);
227
+ return tracked === null ? null : tracked !== "";
228
+ }
229
+ });
230
+ const upstreamOwnsDependencies = ownership.dependenciesOwner === "upstream-pm";
231
+ const runtimeChannel = getRuntimeChannel(
232
+ runtimeReady,
233
+ releasePinned,
234
+ upstreamOwnsDependencies || ownership.selfManagedStamp
235
+ );
236
+ let dependenciesOwner = null;
237
+ if (upstreamOwnsDependencies) dependenciesOwner = "upstream-pm";
238
+ else if (runtimeReady) dependenciesOwner = "npm";
190
239
 
191
240
  return {
192
241
  installation: "npm",
@@ -197,19 +246,28 @@ function readRuntimeStatus() {
197
246
  packagedCommit,
198
247
  runtimeCommit,
199
248
  runtimeSourceDirectory: sourceDirectory,
200
- runtimeVenvDirectory: path.join(sourceDirectory, "venv"),
249
+ runtimeVenvDirectory: venvDirectory,
201
250
  runtimeBranch: branch || null,
202
251
  runtimeDirty: runtimeDirtyPaths === null ? null : runtimeDirtyPaths.length > 0,
203
252
  runtimeDirtyPaths,
204
253
  runtimeReady,
205
- runtimeChannel: releasePinned ? "npm-release" : runtimeReady ? "upstream-native" : "missing",
206
- runtimeModifiedByNativeUpdate: runtimeReady ? !releasePinned : null,
254
+ runtimeChannel,
255
+ runtimeModifiedByNativeUpdate: runtimeReady ? runtimeChannel !== "npm-release" : null,
256
+ dependenciesOwner,
257
+ dependencyEnvironment: upstreamOwnsDependencies
258
+ ? ownership.dependencyEnvironment
259
+ : dependenciesOwner === "npm" ? venvDirectory : null,
260
+ dependencyRecordError: ownership.factsError,
261
+ upstreamInstallState: ownership.installStateDirectory,
262
+ upstreamInstallStamp: ownership.installStamp,
263
+ upstreamSelfManagedStamp: ownership.selfManagedStamp,
207
264
  nativeUpdateCommand: "hermes update",
208
265
  nativeCheckCommand: "hermes update --check",
209
266
  releaseUpdateCommand: getReleaseUpdateCommand(),
210
267
  releaseCheckCommand: "hermes-npm check",
211
268
  installMethodsCommand: "hermes-npm methods --json",
212
269
  hermesHome,
270
+ hermesRoot: ownership.hermesRoot,
213
271
  upstreamHandoffTarget: path.join(hermesHome, "hermes-agent"),
214
272
  installScope: context.isGlobal ? "global" : "local"
215
273
  };
@@ -242,11 +300,31 @@ function printStatus(status) {
242
300
  console.log(`runtime source: ${status.runtimeSourceDirectory}`);
243
301
  console.log(`HERMES_HOME: ${status.hermesHome}`);
244
302
  console.log(`runtime channel: ${status.runtimeChannel}`);
303
+ if (status.dependenciesOwner === "upstream-pm") {
304
+ console.log(`dependencies: upstream package manager (${status.dependencyEnvironment || "no environment recorded"})`);
305
+ console.log(`upstream record: ${status.upstreamInstallState}`);
306
+ } else if (status.dependenciesOwner === "npm") {
307
+ console.log(`dependencies: npm package venv (${status.dependencyEnvironment})`);
308
+ }
309
+ if (status.upstreamSelfManagedStamp) {
310
+ console.log(`install stamp: ${status.upstreamInstallStamp.path} (updateMechanism: self, untracked)`);
311
+ }
245
312
  console.log(`native update: ${status.nativeUpdateCommand}`);
246
313
  console.log(`release update: ${status.releaseUpdateCommand}`);
314
+ if (status.dependencyRecordError) {
315
+ console.log(`warning: ${status.dependencyRecordError}`);
316
+ }
317
+ if (status.dependenciesOwner === "upstream-pm") {
318
+ console.log("note: upstream's package manager selects the dependency environment, not the npm package venv.");
319
+ } else if (status.upstreamSelfManagedStamp) {
320
+ console.log("note: the install stamp hands the checkout to upstream's package manager on its next launch.");
321
+ }
247
322
  if (status.runtimeModifiedByNativeUpdate) {
248
323
  console.log("note: npm reinstall/update will return the runtime to the latest release-pinned build.");
249
324
  }
325
+ if (status.runtimeChannel === "missing") {
326
+ console.log("note: the runtime is not installed; run 'hermes-npm setup' (or start 'hermes', which sets it up on first launch).");
327
+ }
250
328
  }
251
329
 
252
330
  function getInstallMethods() {
@@ -257,9 +335,13 @@ function getInstallMethods() {
257
335
  id: "npm-isolated",
258
336
  install: "npm install --global hermes-agent",
259
337
  projectInstall: "npm install hermes-agent",
338
+ npm12Install: "npm install --global --allow-scripts=hermes-agent hermes-agent",
339
+ npm12ProjectApproval: "npm install-scripts approve --no-allow-scripts-pin hermes-agent",
340
+ setup: "hermes-npm setup",
341
+ setupNote: "npm 12 blocks dependency install scripts by default; 'hermes-npm setup' or the first 'hermes' launch provisions the runtime instead",
260
342
  commands: "hermes, hermes-agent, hermes-npm",
261
343
  sourceLocation: "inside the installed npm package",
262
- updateOwner: "hermes update (rolling) or hermes-npm update (npm Release)",
344
+ updateOwner: "hermes-npm update (npm Release) or hermes update (native upstream updater, stable channel by default)",
263
345
  uninstall: "npm uninstall --global hermes-agent",
264
346
  projectUninstall: "npm uninstall hermes-agent"
265
347
  },
@@ -295,7 +377,10 @@ function printMethods() {
295
377
  npm-isolated (recommended when npm should own the deployment)
296
378
  global: npm install --global hermes-agent
297
379
  project: npm install hermes-agent
298
- update: hermes update (rolling) or hermes-npm update (npm Release)
380
+ npm 12: install scripts are blocked by default; the first 'hermes'
381
+ launch or 'hermes-npm setup' provisions the runtime, or allow
382
+ the script: npm install --global --allow-scripts=hermes-agent hermes-agent
383
+ update: hermes-npm update (npm Release) or hermes update (native)
299
384
  uninstall: matching global/project npm uninstall
300
385
 
301
386
  upstream-managed (official source layout and native ownership)
@@ -320,12 +405,16 @@ function printHelp(topic) {
320
405
  if (topic === "update") {
321
406
  console.log(`Update commands
322
407
 
323
- hermes update --check Check the upstream native rolling channel
324
- hermes update Update the live checkout from upstream
325
408
  hermes-npm check Check the npm Release channel
326
409
  hermes-npm update Install/reset to the checked npm Release
327
-
328
- Native rolling changes are replaced by the next npm Release update.`);
410
+ hermes update --check Check the native upstream channel
411
+ hermes update Move the live checkout with the upstream updater
412
+
413
+ The native updater follows upstream's "stable" channel (GitHub Releases) by
414
+ default; 'hermes update --set-channel main' switches it to the rolling main
415
+ branch. Source moved by a native update is replaced by the next npm Release
416
+ update. With npm 12, 'hermes-npm update' provisions the new release itself
417
+ because npm skips the package install script.`);
329
418
  return;
330
419
  }
331
420
  if (topic === "migrate") {
@@ -360,11 +449,12 @@ Commands:
360
449
  status [--json] Show the npm release and live upstream runtime state
361
450
  check [--json] Check the npm registry release channel
362
451
  update Update through npm and return to the release channel
452
+ setup Install or repair the isolated runtime (alias: provision)
363
453
  methods [--json] List supported installation and ownership models
364
454
  migrate upstream Show a one-way handoff plan; add --yes to execute it
365
455
  help [topic] Show help (install, update, migrate, uninstall)
366
456
 
367
- The native rolling channel remains available through 'hermes update'.
457
+ The native upstream updater remains available through 'hermes update'.
368
458
  Run 'hermes-npm help install' before choosing a deployment model.`);
369
459
  }
370
460
 
@@ -389,45 +479,101 @@ User configuration and state under HERMES_HOME are preserved. Stop gateways,
389
479
  agents, and Desktop first. Re-run with '--yes' to execute this one-way handoff.`);
390
480
  }
391
481
 
392
- function applyReleaseUpdate(version) {
393
- const context = detectInstallContext();
482
+ function getUpdatedPackageRoot(context, packageName = canonicalPackageName) {
483
+ if (context.isGlobal) return path.join(path.dirname(packageRoot), packageName);
484
+ return path.join(context.projectRoot || process.cwd(), "node_modules", packageName);
485
+ }
486
+
487
+ function readInstalledPackage(root) {
488
+ try {
489
+ return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
490
+ } catch {
491
+ return null;
492
+ }
493
+ }
494
+
495
+ function installedRuntimeIsReady(root, installedPackage, platform = process.platform) {
496
+ const sourceDirectory = resolveRuntimeSourceDirectory(
497
+ root,
498
+ installedPackage.hermesAgent?.runtimeDirectory || "runtime/hermes-agent"
499
+ );
500
+ if (!fs.existsSync(venvConsoleExecutable(path.join(sourceDirectory, "venv"), "hermes", platform))) return false;
501
+ try {
502
+ const marker = JSON.parse(fs.readFileSync(path.join(root, ".hermes-agent-runtime.json"), "utf8"));
503
+ return marker.npmVersion === installedPackage.version;
504
+ } catch {
505
+ return false;
506
+ }
507
+ }
508
+
509
+ // npm <= 11 runs the new package's postinstall during 'npm install', so the
510
+ // runtime is already in place and this is a no-op. npm 12 blocks dependency
511
+ // install scripts by default and leaves only the shims, so run the freshly
512
+ // installed package's own installer directly. '--allow-scripts' is not used:
513
+ // npm 12 rejects that flag for project installs.
514
+ function ensureUpdatedRuntime(root, version, helpers = {}) {
515
+ const installedPackage = readInstalledPackage(root);
516
+ if (!installedPackage || installedPackage.version !== version) {
517
+ console.warn(
518
+ `npm finished, but ${canonicalPackageName}@${version} was not found at ${root}. ` +
519
+ "If 'hermes' reports that the runtime is not ready, run 'hermes-npm setup'."
520
+ );
521
+ return 0;
522
+ }
523
+ if (installedRuntimeIsReady(root, installedPackage)) return 0;
524
+
525
+ console.log("npm did not run the hermes-agent install script (npm 12 blocks dependency install scripts by default).");
526
+ console.log("Setting up the isolated runtime directly (one-time download, usually 1-2 minutes)...");
527
+ const result = (helpers.provisionRuntime || provisionRuntime)({
528
+ packageRoot: root,
529
+ postinstallScript: path.join(root, "scripts", "postinstall.js"),
530
+ isReady: () => installedRuntimeIsReady(root, installedPackage),
531
+ stdio: "inherit",
532
+ onWait: () => console.log("Waiting for another Hermes Agent setup to finish...")
533
+ });
534
+ if (result.error || result.status !== 0) {
535
+ console.error(`Runtime setup failed${result.error ? `: ${result.error}` : ` with exit code ${result.status}`}.`);
536
+ console.error("Retry with 'hermes-npm setup'.");
537
+ return result.status || 1;
538
+ }
539
+ return 0;
540
+ }
541
+
542
+ function applyReleaseUpdate(version, helpers = {}) {
543
+ const context = (helpers.detectInstallContext || detectInstallContext)();
394
544
  assertReleaseUpdateAllowed(version, context);
395
- const args = getReleaseUpdateArgs(version, context);
396
- const child = spawn(npmCommand(), args, {
545
+ const npm = getNpmSpawnSpec(getReleaseUpdateArgs(version, context));
546
+ const result = (helpers.spawnSync || spawnSync)(npm.command, npm.args, {
397
547
  cwd: context.projectRoot || process.cwd(),
398
548
  stdio: "inherit",
399
549
  windowsHide: false
400
550
  });
401
- child.on("exit", (code, signal) => {
402
- if (signal) {
403
- process.kill(process.pid, signal);
404
- return;
405
- }
406
- process.exit(code ?? 1);
407
- });
408
- child.on("error", (error) => {
409
- console.error(`Failed to start npm: ${error.message}`);
410
- process.exit(1);
411
- });
551
+ if (result.error) {
552
+ console.error(`Failed to start npm: ${result.error.message}`);
553
+ return 1;
554
+ }
555
+ if (result.signal) {
556
+ console.error(`npm was stopped by ${result.signal}.`);
557
+ return 1;
558
+ }
559
+ if (result.status !== 0) return result.status ?? 1;
560
+ return ensureUpdatedRuntime(getUpdatedPackageRoot(context), version, helpers);
412
561
  }
413
562
 
414
- function resetCurrentRelease() {
415
- const child = spawn(process.execPath, [path.join(packageRoot, "scripts", "postinstall.js"), "--force-release"], {
416
- cwd: packageRoot,
563
+ function runSetup(helpers = {}) {
564
+ const result = (helpers.provisionRuntime || provisionRuntime)({
565
+ packageRoot: helpers.packageRoot || packageRoot,
566
+ args: helpers.args,
417
567
  stdio: "inherit",
418
- windowsHide: false
419
- });
420
- child.on("exit", (code, signal) => {
421
- if (signal) {
422
- process.kill(process.pid, signal);
423
- return;
568
+ onWait: (lock) => {
569
+ console.log(`Waiting for another Hermes Agent setup to finish${lock?.pid ? ` (pid ${lock.pid})` : ""}...`);
424
570
  }
425
- process.exit(code ?? 1);
426
- });
427
- child.on("error", (error) => {
428
- console.error(`Failed to reset the npm release runtime: ${error.message}`);
429
- process.exit(1);
430
571
  });
572
+ if (result.error) {
573
+ console.error(`Unable to set up the Hermes Agent runtime: ${result.error}`);
574
+ return result.status || 1;
575
+ }
576
+ return result.status;
431
577
  }
432
578
 
433
579
  async function runNpmChannel(args) {
@@ -482,6 +628,15 @@ async function runNpmChannel(args) {
482
628
  }
483
629
  return;
484
630
  }
631
+ if (command === "setup" || command === "provision") {
632
+ if (args.length > 1) {
633
+ console.error(`Unknown setup option: ${args[1]}`);
634
+ process.exitCode = 2;
635
+ return;
636
+ }
637
+ process.exitCode = runSetup();
638
+ return;
639
+ }
485
640
  if (command === "status") {
486
641
  const status = readRuntimeStatus();
487
642
  if (json) console.log(JSON.stringify(status, null, 2));
@@ -520,13 +675,13 @@ async function runNpmChannel(args) {
520
675
  }
521
676
  const comparison = compareSemver(latestVersion, packageJson.version);
522
677
  if (comparison > 0) {
523
- applyReleaseUpdate(latestVersion);
678
+ process.exitCode = applyReleaseUpdate(latestVersion);
524
679
  } else {
525
680
  const status = readRuntimeStatus();
526
681
  if (status.runtimeChannel === "npm-release") {
527
682
  console.log(`The npm release channel is already at ${packageJson.version}.`);
528
683
  } else {
529
- resetCurrentRelease();
684
+ process.exitCode = runSetup({ args: ["--force-release"] });
530
685
  }
531
686
  }
532
687
  } catch (error) {
@@ -543,18 +698,25 @@ async function runNpmChannel(args) {
543
698
 
544
699
  module.exports = {
545
700
  assertReleaseUpdateAllowed,
701
+ applyReleaseUpdate,
546
702
  detectInstallContext,
547
703
  compareSemver,
704
+ ensureUpdatedRuntime,
548
705
  fetchLatestNpmVersion,
549
706
  findNodeModulesOwner,
550
707
  getAliasMigrationCommands,
551
708
  getInstallMethods,
709
+ getNpmSpawnSpec,
552
710
  getReleaseUpdateArgs,
553
711
  getReleaseUpdateCommand,
712
+ getRuntimeChannel,
713
+ getUpdatedPackageRoot,
714
+ installedRuntimeIsReady,
554
715
  isReleasePinned,
555
716
  parseGitStatusPorcelain,
556
717
  pathsReferToSameInstallLocation,
557
718
  printHelp,
558
719
  readRuntimeStatus,
559
- runNpmChannel
720
+ runNpmChannel,
721
+ runSetup
560
722
  };
@@ -0,0 +1,177 @@
1
+ const { spawnSync } = require("node:child_process");
2
+ const fs = require("node:fs");
3
+ const path = require("node:path");
4
+
5
+ const LOCK_FILE_NAME = ".hermes-agent-provision.lock";
6
+ // Names the lock a parent already holds for the installer it spawned, so the
7
+ // child does not wait on its own parent.
8
+ const HELD_LOCK_ENV = "HERMES_NPM_PROVISION_LOCK";
9
+ // A lock whose PID is alive is honored: provisioning on a slow network can take
10
+ // well over an hour. Only a lock this old is treated as left over from a crash
11
+ // whose PID has since been reused.
12
+ const STALE_LOCK_MS = 6 * 60 * 60 * 1000;
13
+ // A lock file that cannot be parsed is only treated as stale after this grace
14
+ // period, so a holder that has created but not yet written it keeps the lock.
15
+ const UNREADABLE_LOCK_GRACE_MS = 30 * 1000;
16
+ const DEFAULT_WAIT_TIMEOUT_MS = 45 * 60 * 1000;
17
+ const WAIT_POLL_MS = 500;
18
+
19
+ function sleepSync(milliseconds) {
20
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
21
+ }
22
+
23
+ function processIsAlive(pid) {
24
+ if (!Number.isInteger(pid) || pid <= 0) return false;
25
+ try {
26
+ process.kill(pid, 0);
27
+ return true;
28
+ } catch (error) {
29
+ return error.code === "EPERM";
30
+ }
31
+ }
32
+
33
+ function getProvisionLockPath(packageRoot) {
34
+ return path.join(packageRoot, LOCK_FILE_NAME);
35
+ }
36
+
37
+ function readProvisionLock(lockPath) {
38
+ try {
39
+ const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
40
+ return lock && typeof lock === "object" ? lock : null;
41
+ } catch {
42
+ return null;
43
+ }
44
+ }
45
+
46
+ function provisionLockIsStale(lockPath, now = Date.now(), isAlive = processIsAlive) {
47
+ let stats;
48
+ try {
49
+ stats = fs.statSync(lockPath);
50
+ } catch {
51
+ return false;
52
+ }
53
+ const lock = readProvisionLock(lockPath);
54
+ if (!lock) return now - stats.mtimeMs > UNREADABLE_LOCK_GRACE_MS;
55
+ const startedAt = Date.parse(lock.startedAt);
56
+ if (Number.isFinite(startedAt) && now - startedAt > STALE_LOCK_MS) return true;
57
+ return !isAlive(lock.pid);
58
+ }
59
+
60
+ function acquireProvisionLock(lockPath, options = {}) {
61
+ const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
62
+ const pollMs = options.pollMs ?? WAIT_POLL_MS;
63
+ const deadline = Date.now() + timeoutMs;
64
+ let waited = false;
65
+
66
+ while (true) {
67
+ try {
68
+ const fd = fs.openSync(lockPath, "wx");
69
+ try {
70
+ fs.writeSync(fd, `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`);
71
+ } finally {
72
+ fs.closeSync(fd);
73
+ }
74
+ return { waited, release: () => releaseProvisionLock(lockPath) };
75
+ } catch (error) {
76
+ if (error.code !== "EEXIST") throw error;
77
+ }
78
+
79
+ if (provisionLockIsStale(lockPath)) {
80
+ fs.rmSync(lockPath, { force: true });
81
+ continue;
82
+ }
83
+ if (!waited) {
84
+ waited = true;
85
+ options.onWait?.(readProvisionLock(lockPath));
86
+ }
87
+ if (Date.now() >= deadline) {
88
+ throw new Error(`Timed out waiting for another Hermes Agent setup to finish (lock: ${lockPath})`);
89
+ }
90
+ sleepSync(pollMs);
91
+ }
92
+ }
93
+
94
+ function releaseProvisionLock(lockPath) {
95
+ const lock = readProvisionLock(lockPath);
96
+ if (lock && lock.pid !== process.pid) return;
97
+ fs.rmSync(lockPath, { force: true });
98
+ }
99
+
100
+ // Called by scripts/postinstall.js. A lifecycle run from npm takes the lock so a
101
+ // concurrent first launch waits for it instead of starting a second installer;
102
+ // a run spawned by provisionRuntime already holds it through its parent.
103
+ function holdProvisionLockForInstaller(packageRoot, options = {}) {
104
+ const lockPath = getProvisionLockPath(path.resolve(packageRoot));
105
+ const env = options.env || process.env;
106
+ if (env[HELD_LOCK_ENV] && path.resolve(env[HELD_LOCK_ENV]) === lockPath) {
107
+ return { waited: false, release() {} };
108
+ }
109
+ return acquireProvisionLock(lockPath, options);
110
+ }
111
+
112
+ function describeLockError(error, packageRoot) {
113
+ if (["EACCES", "EPERM", "EROFS"].includes(error.code)) {
114
+ return `Cannot write to the npm package directory ${packageRoot}. ` +
115
+ "Run 'hermes-npm setup' as the account that owns this npm installation " +
116
+ "(for a root-owned global prefix, with the same privileges used for 'npm install --global').";
117
+ }
118
+ return error.message;
119
+ }
120
+
121
+ // Runs the package's own scripts/postinstall.js under a lock in the package
122
+ // root. npm 12 blocks dependency install scripts by default, so the launcher,
123
+ // 'hermes-npm setup' and 'hermes-npm update' call this directly instead of
124
+ // relying on the npm lifecycle.
125
+ function provisionRuntime(options) {
126
+ const packageRoot = path.resolve(options.packageRoot);
127
+ const postinstallScript = options.postinstallScript || path.join(packageRoot, "scripts", "postinstall.js");
128
+ const lockPath = getProvisionLockPath(packageRoot);
129
+ const spawn = options.spawnSync || spawnSync;
130
+
131
+ let lock;
132
+ try {
133
+ lock = acquireProvisionLock(lockPath, {
134
+ onWait: options.onWait,
135
+ pollMs: options.pollMs,
136
+ timeoutMs: options.timeoutMs
137
+ });
138
+ } catch (error) {
139
+ return { status: 1, provisioned: false, error: describeLockError(error, packageRoot) };
140
+ }
141
+
142
+ try {
143
+ if (options.isReady?.()) {
144
+ return { status: 0, provisioned: false, waited: lock.waited };
145
+ }
146
+ options.onStart?.();
147
+ const result = spawn(process.execPath, [postinstallScript, ...(options.args || [])], {
148
+ cwd: packageRoot,
149
+ env: { ...(options.env || process.env), [HELD_LOCK_ENV]: lockPath },
150
+ stdio: options.stdio || "inherit",
151
+ windowsHide: true
152
+ });
153
+ if (result.error) {
154
+ return { status: 1, provisioned: true, error: `Unable to start the runtime installer: ${result.error.message}` };
155
+ }
156
+ if (result.signal) {
157
+ return { status: 1, provisioned: true, error: `The runtime installer was stopped by ${result.signal}` };
158
+ }
159
+ return { status: result.status ?? 1, provisioned: true, waited: lock.waited };
160
+ } finally {
161
+ lock.release();
162
+ }
163
+ }
164
+
165
+ module.exports = {
166
+ HELD_LOCK_ENV,
167
+ LOCK_FILE_NAME,
168
+ STALE_LOCK_MS,
169
+ acquireProvisionLock,
170
+ getProvisionLockPath,
171
+ holdProvisionLockForInstaller,
172
+ processIsAlive,
173
+ provisionLockIsStale,
174
+ provisionRuntime,
175
+ readProvisionLock,
176
+ releaseProvisionLock
177
+ };