kylon-cli 0.3.9-next.688 → 0.3.9-next.691

package/README.md

@@ -121,20 +121,40 @@ The setting controls future automatic requests only. Turning it off does not
 cancel an upgrade whose drain has already started, and manual upgrades remain
 available.
 
-To upgrade manually:
+To upgrade manually, run the one upgrade command:
 
 ```bash
-npx --yes kylon-cli@latest gateway service upgrade
+kylon upgrade
 ```
 
-(`@next` on dev.) The daemon and the pinned agent `kylon` both run the
-installed bundle under `~/.kylon/bin`, which only this command (or a fresh
-`agent link`) refreshes: the freshly-resolved CLI installs its own bundle and
-drain-restarts the running daemon onto it, moving both in lockstep.
-`npm install -g` alone updates the operator's terminal binary and leaves the
-runtime service on the old build. The update notice the CLI prints for local
-runtimes uses exactly this command; `kylon gateway service repair` is the same
-reconciliation under its recovery-oriented name.
+It resolves the newest build on the channel this installation tracks
+(`latest` in production, `next` on dev), compares it with the **installed**
+bundle's recorded version, and picks the owner for the host's layout: on a
+gateway host the drained service upgrade described below, on a
+credential-only host the daemon-guarded self-pin, and on a host with only an
+npm global the `npm install -g` hint (that copy stays the operator's own).
+When the installed `kylon` is too old to know the command, or is not on PATH,
+spell the same thing through npx — `npx --yes kylon-cli@latest upgrade`
+(`@next` on dev) — and the freshly-resolved copy performs the install itself
+rather than downloading itself a second time. `--force` skips the drain (see
+the interrupts below). This is the command the CLI's update notice, `kylon
+gateway status`, and the unknown-command hint all print for managed installs.
+
+The mechanism underneath is `gateway service upgrade`:
+
+```bash
+npx --yes kylon-cli@<exact version> gateway service upgrade
+```
+
+It installs the running copy's *own* bundle under `~/.kylon/bin` and
+drain-restarts the daemon onto it, moving the daemon and the pinned agent
+`kylon` in lockstep — so it must be run by the target version, which is why
+it is spelled through `npx` with an exact version. Reach for it directly only
+when an exact version matters; the workspace's update notice, the remote
+upgrade button, and automatic updates all resolve to it with the exact version
+they want. `npm install -g` alone updates the operator's terminal binary and
+leaves the runtime service on the old build. `kylon gateway service repair`
+is the same reconciliation under its recovery-oriented name.
 
 `repair` goes one step further than `upgrade`: after reconciling the Kylon
 side it installs any provider CLI this machine's placements need but do not
@@ -156,8 +176,8 @@ The drain waits up to five minutes for in-flight agent work, and a drain that
 exhausts its window rolls the upgrade back — so a persistently busy host would
 never upgrade without an operator interrupt. Two are available:
 
-- `kylon gateway service upgrade --force` skips the drain, or escalates one
-  already in progress: in-flight assignments are aborted with the same
+- `kylon upgrade --force` (or `kylon gateway service upgrade --force`) skips
+  the drain, or escalates one already in progress: in-flight assignments are aborted with the same
   recovery semantics as a daemon crash (the durable inbox re-drives
   interrupted work on the restarted daemon), and the new version activates
   immediately.
@@ -658,7 +678,9 @@ npm dist-tag add kylon-cli@<last-good> latest   # move the channel back
 npm deprecate kylon-cli@<bad> "Broken release — use <last-good>."
 ```
 
-Operators on `@latest` pick up the re-pointed version the next time they run
-`npx --yes kylon-cli@latest gateway service upgrade` (the command the update
-notice prints for local runtimes); in-flight daemons keep their current pinned
-bundle until that drain-restart. Do not `npm unpublish`.
+Re-pointing the tag stops the bad build from spreading: hosts that have not
+upgraded yet resolve `<last-good>` on their next `kylon upgrade` or automatic
+update. It does not walk a host back that already runs `<bad>` — the install's
+direction guard keeps a newer installed bundle over an older invoked copy, and
+`kylon upgrade` reports such a host as already current — so the way back for
+those hosts is publishing a fixed, higher version. Do not `npm unpublish`.

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.9-next.688",
-  "fingerprint": "c786222ec89bf52b3804fa7a63dbf2f0e243e880b0fbc2b8b12065eb5d9f8bf0",
-  "source_commit": "c567347fd5dd361b38aa1f3c5316dfc3481bb96e"
+  "version": "0.3.9-next.691",
+  "fingerprint": "5a7cc86b8ad5a9f2ca1635d520c5732efa2c57e8cfd4795c16674a20c79bff55",
+  "source_commit": "70d75f85002e3433f31fec33ee3ff5724f74b1bb"
 }