hermes-agent 0.22.2 → 0.22.4

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.
package/README.md CHANGED
@@ -9,6 +9,32 @@
9
9
  [![Telegram chat](https://img.shields.io/badge/Telegram-chat-26A5E4?logo=telegram&logoColor=white)](https://t.me/+AoFg5hgLSlIyYTAy)
10
10
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
11
 
12
+ ## Important recent changes
13
+
14
+ - **npm 12 skips the install script.** npm 12 blocks dependency install
15
+ scripts by default, so a plain install leaves `hermes` without its runtime.
16
+ Starting with the first npm release after `0.22.2`, the first `hermes`
17
+ launch provisions the runtime itself, and `hermes-npm setup` does it ahead
18
+ of time. On `0.22.2` and earlier, install with
19
+ `npm install --global --allow-scripts=hermes-agent hermes-agent`.
20
+ See [npm 12 and install scripts](#npm-12-and-install-scripts).
21
+ - **Run `hermes-npm setup` before background use.** Run it once before you
22
+ register `hermes` with an MCP client or a gateway service, so the first
23
+ background launch does not spend 1-2 minutes on setup and hit a startup
24
+ timeout.
25
+ - **`hermes update` follows upstream `stable` by default.** Unconfigured
26
+ checkouts track the latest GitHub Release. The rolling `main` branch is
27
+ opt-in through `hermes update --set-channel main`. See
28
+ [Two update channels](#two-update-channels).
29
+ - **A native `hermes update` hands dependencies to upstream.** Upstream's
30
+ package manager then keeps its environment under `HERMES_HOME/installs` and
31
+ its launchers in `~/.local/bin` (or `HERMES_HOME\bin` on Windows).
32
+ `hermes-npm status` shows who owns the dependencies. An npm reinstall or a
33
+ same-version `hermes-npm update` takes them back. See
34
+ [Native upstream channel](#native-upstream-channel).
35
+ - **The runtime uses Python 3.14** since `0.21.6`, matching upstream. See
36
+ [Python 3.14 in release 0.21.6](#python-314-in-release-0216).
37
+
12
38
  > [!IMPORTANT]
13
39
  > **The deployment model changed in `0.20.0`.** Upstream Hermes Agent stopped
14
40
  > publishing new PyPI releases. This bridge now creates a package-local Git
@@ -27,9 +53,11 @@ by Nous Research.
27
53
 
28
54
  ## Contents
29
55
 
56
+ - [Important recent changes](#important-recent-changes)
30
57
  - [Choose an installation method](#choose-an-installation-method)
31
58
  - [Migration from pre-0.20](#migration-from-pre-020)
32
59
  - [Install](#install)
60
+ - [npm 12 and install scripts](#npm-12-and-install-scripts)
33
61
  - [Two update channels](#two-update-channels)
34
62
  - [Move from npm to an upstream-managed install](#move-from-npm-to-an-upstream-managed-install)
35
63
  - [Commands](#commands)
@@ -49,7 +77,7 @@ before copying an install command.
49
77
 
50
78
  | Method | Install | Code and venv | Updates | Removal |
51
79
  | --- | --- | --- | --- | --- |
52
- | npm-isolated (recommended for npm users) | Global: `npm install --global hermes-agent`; project: `npm install hermes-agent` | Inside the npm package | `hermes update` or `hermes-npm update` | Matching global/project `npm uninstall` |
80
+ | npm-isolated (recommended for npm users) | Global: `npm install --global hermes-agent`; project: `npm install hermes-agent` ([npm 12](#npm-12-and-install-scripts)) | Inside the npm package | `hermes-npm update` or `hermes update` | Matching global/project `npm uninstall` |
53
81
  | upstream-managed | [Official upstream installer](https://github.com/NousResearch/hermes-agent#quick-install) or the handoff below | User-scoped `$HERMES_HOME/hermes-agent` | `hermes update` | `hermes uninstall` |
54
82
  | manual development | [Upstream contributing guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Developer checkout with an external venv | Developer-managed Git and `uv` | Remove the selected checkout and venv |
55
83
 
@@ -112,7 +140,7 @@ Starting with `0.20.0`:
112
140
  metadata;
113
141
  - upstream source is checked out at the exact GitHub Release tag and commit;
114
142
  - dependencies are synchronized from upstream `uv.lock`;
115
- - `hermes update` remains the native upstream rolling updater;
143
+ - `hermes update` remains the native upstream updater;
116
144
  - `hermes-npm update` is the explicit npm Release updater.
117
145
 
118
146
  Upgrade globally with:
@@ -155,6 +183,14 @@ minutes. A Windows test installation of `0.20.0` occupied about 450 MB after
155
183
  the temporary dependency cache was removed; size varies by platform and future
156
184
  upstream dependencies.
157
185
 
186
+ If npm skipped the install script (npm 12 does by default, as does
187
+ `--ignore-scripts`), the first `hermes` or `hermes-agent` launch performs the
188
+ same provisioning before starting Hermes, or you can run it explicitly:
189
+
190
+ ```bash
191
+ hermes-npm setup
192
+ ```
193
+
158
194
  > [!WARNING]
159
195
  > Stop running Hermes gateways and agents before an npm reinstall or npm-channel
160
196
  > update. npm may replace the package-local checkout and virtual environment.
@@ -165,16 +201,73 @@ upstream dependencies.
165
201
  > can delete the package-local runtime without removing the npm package. Use
166
202
  > `npm uninstall hermes-agent` or `npm uninstall --global hermes-agent`.
167
203
 
204
+ ## npm 12 and install scripts
205
+
206
+ npm 12 blocks dependency install scripts by default. A plain
207
+ `npm install --global hermes-agent` then installs only the command shims and
208
+ prints `install scripts blocked`. The bridge handles this itself: the first
209
+ `hermes` (or `hermes-agent`, or `npx hermes`) launch runs the package's own
210
+ installer, prints a one-line note to stderr, and continues once the runtime is
211
+ ready. This is a one-time download that usually takes 1-2 minutes; concurrent
212
+ first launches wait for a single setup. You can also provision ahead of time:
213
+
214
+ ```bash
215
+ hermes-npm setup
216
+ ```
217
+
218
+ > [!IMPORTANT]
219
+ > Run `hermes-npm setup` once before you register `hermes` with an MCP client,
220
+ > a gateway service, or any other program that starts it in the background.
221
+ > Otherwise the first background launch spends 1-2 minutes on setup before
222
+ > Hermes writes anything to stdout, and the client may give up on a startup
223
+ > timeout. Do the same after any `npm install` or `npm update` that replaced
224
+ > the package without running its install script; `hermes-npm update` already
225
+ > provisions the new release before it returns.
226
+
227
+ To let npm run the install script as on npm 11 and earlier:
228
+
229
+ ```bash
230
+ # global, once
231
+ npm install --global --allow-scripts=hermes-agent hermes-agent
232
+
233
+ # global, every future install
234
+ npm config set allow-scripts=hermes-agent --location=user
235
+ ```
236
+
237
+ For a project dependency, npm 12 rejects `--allow-scripts` and records the
238
+ approval in `package.json` instead:
239
+
240
+ ```bash
241
+ npm install hermes-agent
242
+ npm install-scripts approve hermes-agent
243
+ npm rebuild hermes-agent
244
+ ```
245
+
246
+ By default `approve` pins the entry to the installed version
247
+ (`"allowScripts": {"hermes-agent@<version>": true}`), so every version bump
248
+ needs a new approval. `npm install-scripts approve --no-allow-scripts-pin hermes-agent`
249
+ writes a name-only entry instead. Without any approval, `hermes-npm setup` or
250
+ the first launch provisions the runtime.
251
+
252
+ `hermes-npm update` does not depend on npm running the script either: after
253
+ npm installs the checked release, it runs the new package's installer directly
254
+ when the runtime is missing. On npm 11 and earlier nothing changes, because
255
+ npm has already provisioned the runtime by then.
256
+
257
+ Set `HERMES_NPM_AUTO_SETUP=0` to turn off provisioning on launch; `hermes` then
258
+ exits with an error that points to `hermes-npm setup`.
259
+
168
260
  ## Two update channels
169
261
 
170
262
  The bridge intentionally exposes two independent update channels.
171
263
 
172
264
  | Channel | Command | Source | Result |
173
265
  | --- | --- | --- | --- |
174
- | Native rolling | `hermes update` | Upstream Git branch, normally `main` | Runs the unmodified upstream updater |
175
266
  | npm Release | `hermes-npm update` | Latest published `hermes-agent` npm version | Returns to the latest GitHub Release pinned by npm |
267
+ | Native upstream | `hermes update` | Upstream `stable` channel by default: the latest GitHub Release, forward only | Runs the unmodified upstream updater |
268
+ | Native rolling (opt-in) | `hermes update --set-channel main`, then `hermes update` | Upstream `main` branch | Runs the unmodified upstream updater on the rolling branch |
176
269
 
177
- ### Native rolling channel
270
+ ### Native upstream channel
178
271
 
179
272
  ```bash
180
273
  hermes update --check
@@ -185,17 +278,73 @@ These arguments are passed directly to the official upstream console
185
278
  entrypoint. The bridge does not replace `cmd_update`, set `HERMES_MANAGED`, or
186
279
  translate the command into npm operations.
187
280
 
188
- After a native update, the source checkout can be newer than both the npm
189
- package version and the latest upstream GitHub Release. This is expected. npm
190
- integrity and provenance still cover the bridge package, but no longer attest
191
- to source subsequently fetched by the native updater.
192
-
193
- The upstream updater may also install its own managed tools, dependencies, or
194
- runtime files according to upstream behavior. In the current upstream release,
195
- that includes a managed `uv` under `HERMES_HOME/bin` (normally `~/.hermes/bin`)
196
- and may include checkout-local runtime-repair files. This is outside the npm
197
- release-pinned boundary and is the explicit tradeoff for keeping native update
198
- behavior unchanged.
281
+ Since upstream `v0.21.6`, an official checkout with no configured channel
282
+ tracks `stable`: `hermes update --check` prints `Update channel: stable`, and
283
+ `hermes update` moves only forward to the latest upstream GitHub Release. The
284
+ package-local checkout counts as such a checkout. The rolling `main` branch is
285
+ opt-in through `hermes update --set-channel main` (`--set-channel stable`
286
+ returns). Because the bridge publishes each upstream Release to npm, the
287
+ native stable channel usually reaches a new Release before `hermes-npm update`
288
+ does, and lands on the same commit.
289
+
290
+ After a native update, the source checkout can be newer than the npm package
291
+ version, and on the `main` channel newer than the latest upstream GitHub
292
+ Release. This is expected. npm integrity and provenance still cover the bridge
293
+ package, but no longer attest to source subsequently fetched by the native
294
+ updater.
295
+
296
+ The upstream updater also manages its own tools and environments according to
297
+ upstream behavior. In upstream `v0.22.x` it unshallows the package-local Git
298
+ checkout, builds a new dependency environment with its own managed Python and
299
+ `uv` under `HERMES_HOME/installs` and `HERMES_HOME/tools`, writes an
300
+ `install-stamp.json` into the checkout, and can publish `hermes` launchers
301
+ outside npm: `~/.local/bin` on macOS and Linux, and `HERMES_HOME\bin` added to
302
+ the user `PATH` on Windows. These are outside the npm release-pinned boundary
303
+ and are the explicit tradeoff for keeping native update behavior unchanged.
304
+
305
+ After a native update, upstream owns the dependency environment and the
306
+ launchers:
307
+
308
+ - Upstream records the environment it built under
309
+ `HERMES_HOME/installs/<key>`, where the key is derived from the checkout
310
+ path, marks the checkout as self-managed with an untracked
311
+ `install-stamp.json`, and selects that environment at startup instead of the
312
+ package's own `venv`. `hermes-npm status` reports this as
313
+ `dependencies: upstream package manager` (`dependenciesOwner: "upstream-pm"`
314
+ in `--json`, with the selected environment in `dependencyEnvironment`) and
315
+ does not report the `npm-release` channel. The record lives in
316
+ `~/.hermes/installs` (`%LOCALAPPDATA%\hermes\installs` on Windows) unless
317
+ `HERMES_HOME` points outside that directory, in which case it lives in
318
+ `HERMES_HOME/installs` (or `<root>/installs` for a `<root>/profiles/<name>`
319
+ home); `<key>` is the first 16 hex digits of the SHA-256 of the
320
+ `runtime source` path that `hermes-npm status` prints.
321
+ - npm takes the dependencies back whenever the bridge puts the checkout back
322
+ on the commit pinned by the npm package: after `npm install` replaces the
323
+ package (or `hermes-npm update` installs a newer one) and provisions a fresh
324
+ checkout, and when a same-version `hermes-npm update` resets the checkout in
325
+ place. The installer then removes that `installs/<key>` directory and the
326
+ checkout's `install-stamp.json`, prints what it removed, and upstream falls
327
+ back to the package `venv`. Nothing else under `HERMES_HOME` is touched, so
328
+ upstream's shared tools under `HERMES_HOME/tools` and all user data stay.
329
+ `hermes-npm setup` and `npm rebuild` for the same version keep the existing
330
+ checkout and therefore keep a native update, dependencies included. The
331
+ installer uses the `HERMES_HOME` of the shell it runs in; run it with the
332
+ same `HERMES_HOME` as `hermes update`.
333
+ - The launchers upstream publishes in `~/.local/bin` execute files inside the
334
+ npm package (`runtime/hermes-agent/.hermes/bin`). They stop working once npm
335
+ reinstalls or removes the package; if `~/.local/bin` comes before the npm
336
+ prefix in `PATH`, `hermes` then fails instead of reaching the npm shim.
337
+ Remove those three files (`hermes`, `hermes-agent`, `hermes-acp`) if they
338
+ point into the npm package. Setting `cli.expose_on_path: false` in
339
+ `HERMES_HOME/config.yaml` stops upstream from publishing them on macOS and
340
+ Linux; it has no effect on Windows, where upstream publishes its launchers
341
+ in the `bin` directory it adds to the user `PATH`.
342
+
343
+ To return fully to npm ownership after a native update, run `hermes-npm update`
344
+ or reinstall the package, and remove those launchers yourself; the bridge does
345
+ not remove files outside the npm package other than that `installs/<key>`
346
+ directory. User configuration, sessions, and skills elsewhere in `HERMES_HOME`
347
+ are not affected.
199
348
 
200
349
  ### npm Release channel
201
350
 
@@ -206,6 +355,17 @@ hermes-npm status
206
355
  hermes-npm status --json
207
356
  ```
208
357
 
358
+ `runtimeChannel` is `npm-release` only when the checkout is clean at the commit
359
+ pinned by the npm package and npm owns its dependencies. It is
360
+ `upstream-native` when the source has moved, when upstream's package manager
361
+ has recorded a dependency environment for the checkout
362
+ (`dependenciesOwner: "upstream-pm"`, read from
363
+ `<root>/installs/<key>/facts.json` exactly where upstream looks), or when the
364
+ checkout carries an untracked `install-stamp.json` with
365
+ `updateMechanism: "self"` (`upstreamSelfManagedStamp`), which hands it to
366
+ upstream's package manager on its next launch. `hermes-npm status` reads only
367
+ the record for the active Hermes root, the one upstream itself selects first.
368
+
209
369
  Check the npm registry:
210
370
 
211
371
  ```bash
@@ -228,13 +388,16 @@ npm install --global --registry=https://registry.npmjs.org hermes-agent@<checked
228
388
  npm install --registry=https://registry.npmjs.org hermes-agent@<checked-version>
229
389
  ```
230
390
 
231
- An npm update intentionally replaces native rolling changes with the exact
232
- checkout pinned by the npm Release. If npm is already at the latest version but
233
- the live checkout has moved, `hermes-npm update` directly reprovisions that
234
- same release commit. This discards tracked source changes in the package-local
235
- checkout; upstream user configuration under `HERMES_HOME` is unaffected.
236
- Running `npm rebuild` for the same package version instead
237
- preserves an existing native-updated checkout and only resynchronizes its
391
+ An npm update intentionally replaces source moved by a native update with
392
+ the exact checkout pinned by the npm Release. If npm is already at the latest version but
393
+ the live checkout has moved, or upstream's package manager owns its
394
+ dependencies, `hermes-npm update` directly reprovisions that same release
395
+ commit. This discards tracked source changes in the package-local checkout and
396
+ returns dependency selection to the package `venv` as described under
397
+ [Native upstream channel](#native-upstream-channel); upstream user
398
+ configuration under `HERMES_HOME` is unaffected.
399
+ Running `hermes-npm setup` (or `npm rebuild`) for the same package version
400
+ instead preserves an existing native-updated checkout and only resynchronizes its
238
401
  environment.
239
402
 
240
403
  ### Python 3.14 in release 0.21.6
@@ -300,7 +463,7 @@ Configuration, credentials, sessions, memories, skills, and other user state
300
463
  under `HERMES_HOME` are preserved. The command refuses a non-Git target, a Git
301
464
  target with an unexpected origin or uncommitted files, a `HERMES_HOME` inside
302
465
  the npm package, or a runtime that has moved off its packaged Release. Run
303
- `hermes-npm update` first if native rolling changes need to be reset before
466
+ `hermes-npm update` first if native update changes need to be reset before
304
467
  handoff. Existing upstream checkout changes must be committed, stashed, or
305
468
  removed explicitly; the bridge never answers an upstream restore prompt.
306
469
 
@@ -347,6 +510,7 @@ then install the exact checked canonical version.
347
510
  | `hermes-npm status [--json]` | Report npm identity, exact live Git commit, channel, dirty state, and install scope |
348
511
  | `hermes-npm check [--json]` | Read the canonical npm Release channel without changing files |
349
512
  | `hermes-npm update` | Install the checked exact npm version or reset the current runtime to its packaged Release |
513
+ | `hermes-npm setup` | Install or repair the isolated runtime of the installed npm version (alias: `provision`) |
350
514
  | `hermes-npm methods [--json]` | List supported installation/ownership models for users and automation |
351
515
  | `hermes-npm migrate upstream [--json]` | Show the one-way upstream handoff plan without changing files |
352
516
  | `hermes-npm migrate upstream --yes` | Execute, verify, and finish the upstream handoff |
@@ -354,7 +518,10 @@ then install the exact checked canonical version.
354
518
 
355
519
  ## How installation works
356
520
 
357
- `scripts/postinstall.js` performs the following without invoking a shell:
521
+ `scripts/postinstall.js` performs the following without invoking a shell. npm
522
+ runs it as the package install script; when npm skips that script, the first
523
+ launch, `hermes-npm setup`, and `hermes-npm update` run the same file directly
524
+ with the current Node.js under a lock file in the package directory.
358
525
 
359
526
  1. Validates the upstream repository, Release tag, and full commit SHA stored
360
527
  in `package.json`.
@@ -386,7 +553,9 @@ macOS/Linux: runtime/hermes-agent/venv/bin/hermes
386
553
  ```
387
554
 
388
555
  Arguments, current working directory, standard streams, exit code, and native
389
- upstream update handling are preserved.
556
+ upstream update handling are preserved. When the console script is missing,
557
+ the launcher provisions the runtime first and sends that output to stderr, so
558
+ the command's stdout stays clean.
390
559
 
391
560
  ## Runtime layout and isolation
392
561
 
@@ -438,7 +607,8 @@ non-prerelease upstream GitHub Release once and then:
438
607
  6. publishes through npm trusted publishing with provenance.
439
608
 
440
609
  Polling follows GitHub Releases, not PyPI and not the tip of `main`. Native
441
- `hermes update` remains independent and may advance between Releases.
610
+ `hermes update` remains independent; it follows Releases by default and the
611
+ `main` branch only after `hermes update --set-channel main`.
442
612
 
443
613
  ## Security and privacy
444
614
 
@@ -462,10 +632,13 @@ npm install --ignore-scripts ./hermes-agent-*.tgz
462
632
  After review:
463
633
 
464
634
  ```bash
465
- npm rebuild hermes-agent
635
+ hermes-npm setup
466
636
  ```
467
637
 
468
- Use `npm rebuild --global hermes-agent` for a global installation.
638
+ `npm rebuild hermes-agent` (`npm rebuild --global hermes-agent` for a global
639
+ installation) does the same on npm 11 and earlier, and on npm 12 once the
640
+ install script is allowed. Running `hermes` before the review also provisions
641
+ the runtime; set `HERMES_NPM_AUTO_SETUP=0` while auditing to prevent that.
469
642
 
470
643
  ## Troubleshooting
471
644
 
@@ -478,17 +651,22 @@ Git is required for the native 'hermes update' channel
478
651
  Install Git, confirm `git --version`, and run:
479
652
 
480
653
  ```bash
481
- npm rebuild hermes-agent
654
+ hermes-npm setup
482
655
  ```
483
656
 
484
657
  ### Runtime is not ready
485
658
 
486
- If installation was performed with `--ignore-scripts`, provision it explicitly:
659
+ If npm skipped the install script (npm 12 by default, or `--ignore-scripts`),
660
+ the first `hermes` launch provisions the runtime. If that failed or was
661
+ disabled with `HERMES_NPM_AUTO_SETUP=0`, provision it explicitly:
487
662
 
488
663
  ```bash
489
- npm rebuild hermes-agent
664
+ hermes-npm setup
490
665
  ```
491
666
 
667
+ For a root-owned global npm prefix, run it with the same privileges used for
668
+ `npm install --global`.
669
+
492
670
  ### Native and npm versions differ
493
671
 
494
672
  This is expected after `hermes update`. Inspect both identities with:
@@ -506,10 +684,10 @@ package runtime, then retry the npm update.
506
684
 
507
685
  ### `hermes uninstall` broke an npm installation
508
686
 
509
- Rebuild or reinstall the npm package:
687
+ Re-provision or reinstall the npm package:
510
688
 
511
689
  ```bash
512
- npm rebuild hermes-agent
690
+ hermes-npm setup
513
691
  # or
514
692
  npm install --global hermes-agent@latest
515
693
  ```
package/SECURITY.md CHANGED
@@ -14,8 +14,9 @@ updates.
14
14
 
15
15
  Security fixes in upstream Hermes Agent become available to this channel after
16
16
  upstream publishes a GitHub Release and the matching npm bridge passes its
17
- release checks. The native rolling channel can receive upstream commits sooner,
18
- with the different trust boundary described below.
17
+ release checks. The native upstream updater can apply a Release sooner, and
18
+ upstream `main` commits when switched to the rolling channel, with the
19
+ different trust boundary described below.
19
20
 
20
21
  ## Reporting a vulnerability
21
22
 
@@ -43,7 +44,9 @@ This policy covers:
43
44
 
44
45
  - the npm command shims and `hermes-npm` release-channel commands;
45
46
  - the explicit `hermes-npm migrate upstream` handoff and its preflight checks;
46
- - npm lifecycle provisioning in `scripts/postinstall.js`;
47
+ - npm lifecycle provisioning in `scripts/postinstall.js`, including its
48
+ direct execution on first launch, by `hermes-npm setup`, and by
49
+ `hermes-npm update` when npm skipped the install script;
47
50
  - `uv` asset selection, download, checksum verification, and extraction;
48
51
  - GitHub Release metadata synchronization and npm publishing workflows;
49
52
  - confinement of npm lifecycle installer-created files to the installed npm
@@ -64,11 +67,12 @@ The bridge is intended to preserve these properties:
64
67
  4. Release installation fetches the recorded Git tag and verifies that it
65
68
  resolves to the full commit SHA recorded in `package.json`.
66
69
  5. npm lifecycle installer deletion/replacement targets must resolve inside
67
- the npm package.
70
+ the npm package. The only exception is the upstream install state named in
71
+ invariant 12.
68
72
  6. Python, the virtual environment, the Git checkout, and temporary caches
69
73
  created by npm lifecycle installation remain inside the npm package.
70
74
  7. `hermes update` is passed to the upstream console entrypoint unchanged; the
71
- bridge does not falsely represent rolling source as npm-attested source.
75
+ bridge does not falsely represent natively updated source as npm-attested source.
72
76
  8. A release-channel reset returns tracked upstream source to the commit pinned
73
77
  by npm without deleting untracked files with `git clean`.
74
78
  9. npm publication is blocked unless Windows, macOS, and Linux runtime smoke
@@ -77,6 +81,19 @@ The bridge is intended to preserve these properties:
77
81
  A handoff requires `migrate upstream --yes`, uses the script from the
78
82
  verified Release checkout, pins the same full commit, verifies the new
79
83
  checkout/venv, and removes npm ownership only after that verification.
84
+ 11. When npm skips the install script, the bridge provisions only by running
85
+ the installed package's own `scripts/postinstall.js` with the current
86
+ Node.js, with the same verification and package-local boundary as the
87
+ npm lifecycle. It never passes `--allow-scripts` to npm or changes npm
88
+ configuration.
89
+ 12. Under `HERMES_HOME`, the installer deletes only `<root>/installs/<key>`,
90
+ the install state upstream's package manager keeps for this package's
91
+ checkout, with `<root>` from upstream's `get_default_hermes_root` and
92
+ `<key>` from its `install_key`, and only after it has replaced or reset
93
+ the checkout to the pinned commit. The key must be 16 hex digits and
94
+ neither `installs` nor the target may be a symbolic link. Inside the
95
+ package it additionally deletes only the checkout's untracked
96
+ `install-stamp.json`. Every removed path is printed.
80
97
 
81
98
  A change that violates one of these invariants is security-relevant even if no
82
99
  exploit has yet been demonstrated.
@@ -94,6 +111,18 @@ Lifecycle scripts execute with the installing user's permissions. Review the
94
111
  package before installation when that is not an acceptable trust decision; the
95
112
  audit procedure below avoids lifecycle execution.
96
113
 
114
+ npm 12 blocks dependency install scripts by default, so `npm install` may leave
115
+ only the command shims. The same `scripts/postinstall.js` then runs when the
116
+ user first starts `hermes` or `hermes-agent`, runs `hermes-npm setup`, or
117
+ updates with `hermes-npm update`. It runs with the permissions of that user,
118
+ in the package directory, under a lock file
119
+ (`.hermes-agent-provision.lock`) that serializes concurrent first launches.
120
+ Starting a Hermes command is treated as consent to provision it; set
121
+ `HERMES_NPM_AUTO_SETUP=0` to require an explicit `hermes-npm setup` instead.
122
+ Allowing the script in npm (`--allow-scripts=hermes-agent` for global installs,
123
+ `npm install-scripts approve hermes-agent` for projects) restores provisioning
124
+ during installation.
125
+
97
126
  ## Exact install behavior
98
127
 
99
128
  `scripts/postinstall.js` and `lib/uv-installer.js`:
@@ -107,7 +136,8 @@ audit procedure below avoids lifecycle execution.
107
136
  supported architecture and Linux libc variants;
108
137
  5. enforce compressed and extracted size limits, verify SHA-256, and extract
109
138
  only `uv`/`uv.exe` with Node.js;
110
- 6. provision managed Python 3.11 under `runtime/python/`;
139
+ 6. provision the managed Python version pinned in the package metadata
140
+ (`hermesAgent.pythonVersion`, currently 3.14) under `runtime/python/`;
111
141
  7. create `runtime/hermes-agent/venv/` and run
112
142
  `uv sync --frozen --extra all --no-dev` using upstream project configuration
113
143
  and `uv.lock`;
@@ -136,7 +166,7 @@ The bridge deliberately provides two update channels.
136
166
  registry. When a newer package exists, `hermes-npm update` installs the exact
137
167
  version that was checked from that same registry; it does not perform a second
138
168
  mutable `@latest` resolution. If the npm package is already current, the command
139
- resets a clean rolling checkout in place to the tag/commit pinned by the
169
+ resets a clean natively updated checkout in place to the tag/commit pinned by the
140
170
  installed npm version. A dirty or damaged checkout is replaced transactionally
141
171
  with rollback where possible.
142
172
 
@@ -144,13 +174,40 @@ npm integrity and provenance cover the bridge tarball and its pinned Release
144
174
  identity. They do not include dependencies downloaded during lifecycle
145
175
  execution.
146
176
 
147
- ### Native rolling channel
177
+ ### Native upstream channel
148
178
 
149
179
  `hermes update` and `hermes update --check` run the unmodified upstream updater.
150
- The updater normally follows upstream `main`, mutates the package-local checkout
151
- and venv, and may install managed tools under `HERMES_HOME` (currently a managed
152
- `uv` under `HERMES_HOME/bin`). After a rolling update, npm provenance no longer
153
- attests to the live upstream source.
180
+ Since upstream `v0.21.6`, an official checkout with no configured channel,
181
+ including the package-local one, follows upstream's `stable` channel: the
182
+ latest GitHub Release, forward only. `hermes update --set-channel main` opts
183
+ into the rolling `main` branch. The updater mutates the package-local checkout
184
+ (including unshallowing it), builds its own dependency environments and managed
185
+ tools under `HERMES_HOME`, writes `install-stamp.json` into the checkout, and
186
+ can publish launchers outside npm (`~/.local/bin` on macOS and Linux, a
187
+ `HERMES_HOME\bin` user `PATH` entry on Windows). After a native update, npm
188
+ provenance no longer attests to the live upstream source.
189
+
190
+ The dependency environment the native updater builds is recorded under
191
+ `HERMES_HOME/installs/`, keyed by the checkout path, and upstream selects it at
192
+ startup. `hermes-npm status` reports this case as
193
+ `dependenciesOwner: "upstream-pm"` and does not report the `npm-release`
194
+ channel while upstream's record or a self-managed install stamp is present.
195
+
196
+ When the installer puts the checkout back on the commit pinned by npm (a fresh
197
+ checkout after npm reinstalls or replaces the package, or an in-place reset by
198
+ `hermes-npm update`), it takes dependency selection back: it removes exactly
199
+ `<root>/installs/<key>` for this checkout, where `<root>` and `<key>` are
200
+ computed the way upstream computes them, and the checkout's untracked
201
+ `install-stamp.json`, and prints each removed path. It refuses a key that is
202
+ not 16 hex digits, a path that is not `<root>/installs/<key>`, and an
203
+ `installs` directory or install-state directory that is a symbolic link. A
204
+ removal failure is reported and leaves the installation in place;
205
+ `hermes-npm status` then still shows upstream ownership. When the installer
206
+ keeps an existing checkout (`hermes-npm setup` or `npm rebuild` for the same
207
+ version), it removes nothing, so a native update stays in effect. Launchers
208
+ published to `~/.local/bin` point into the npm package and break when npm
209
+ replaces or removes it; the bridge does not remove them. The README describes
210
+ how to remove them.
154
211
 
155
212
  Use `hermes-npm status --json` to distinguish `npm-release`, `upstream-native`,
156
213
  and `missing` runtime states. Use `hermes-npm update` to return to the npm
@@ -214,6 +271,9 @@ runtime/python/
214
271
  runtime/hermes-agent/
215
272
  ```
216
273
 
274
+ Provisioning also creates the transient `.hermes-agent-provision.lock` while
275
+ it runs.
276
+
217
277
  It does not modify system Python, shell profiles, the global `PATH` beyond
218
278
  normal npm command shims, services, scheduled tasks, or Git configuration.
219
279
 
@@ -282,9 +342,10 @@ and impact; these examples are not automatic ratings.
282
342
  - The commit pin prevents tag retargeting from silently changing a published
283
343
  npm version, but this bridge does not independently verify a Git tag's GPG or
284
344
  SSH signature.
285
- - Native rolling updates intentionally follow a mutable upstream branch and
286
- can move beyond reviewed Releases or create files outside the npm package
287
- under `HERMES_HOME`.
345
+ - Native updates are upstream's trust domain: by default they move the
346
+ checkout to the latest upstream Release before the bridge has published and
347
+ smoke-tested it, on the opt-in `main` channel they follow a mutable branch
348
+ beyond reviewed Releases, and they create files outside the npm package.
288
349
  - Host compromise, malicious npm/Git configuration, or write access to the
289
350
  installed package can invalidate local guarantees.
290
351
  - Only the latest npm bridge release is maintained; users must update to
@@ -331,14 +392,18 @@ package/lib/upstream-migration.js
331
392
  ```
332
393
 
333
394
  Compare `hermesAgent.upstreamGitTag` and `hermesAgent.upstreamCommit` with the
334
- official upstream Release. After review, provision with:
395
+ official upstream Release. Starting `hermes` provisions the runtime, so keep
396
+ `HERMES_NPM_AUTO_SETUP=0` set until the review is done. After review, provision
397
+ with:
335
398
 
336
399
  ```bash
337
- npm rebuild hermes-agent
338
- # or, for a global installation:
339
- npm rebuild --global hermes-agent
400
+ hermes-npm setup
340
401
  ```
341
402
 
403
+ `npm rebuild hermes-agent` (or `npm rebuild --global hermes-agent`) is
404
+ equivalent on npm 11 and earlier, and on npm 12 once the install script is
405
+ allowed.
406
+
342
407
  Security scanners are expected to flag the lifecycle script. Treat that as a
343
408
  prompt to review the explicit download, verification, and execution boundary,
344
409
  not as proof that the lifecycle step is safe or malicious by itself.