kylon-cli 0.3.9 → 0.3.10-next.696

package/README.md

@@ -67,16 +67,20 @@ hosted install script in `~/.kylon/server-url`, then production.
 `agent link` authenticates only the link operation with its embedded
 credential; it never creates a human CLI session. Linking mints or reuses an
 installation credential stored locally with mode `0600` and starts the local
-agent runtime. In release builds on supported environments a user-level
-`launchd` / `systemd --user` service is installed so the daemon survives
-terminal exit, reboot, and sleep/wake; otherwise the daemon runs in the
-foreground until `Ctrl+C`.
+agent runtime. In release builds a user-level service is installed so the
+daemon survives terminal exit, reboot, and sleep/wake: `launchd` on macOS,
+`systemd --user` on Linux, and on Windows a logon-triggered Scheduled Task
+named `Kylon Gateway` that runs `kylon gateway supervise`, a small loop that
+restarts `gateway run` after a crash and after a drained upgrade. When no
+service can be installed (a source build, or a Windows machine whose policy
+blocks scheduled tasks) the daemon runs in the foreground until `Ctrl+C`, and
+`connect` says so.
 
 The dist-tag tracks the environment: production uses `@latest`, dev uses
 `@next` (newest prerelease). To pin a specific build, use `kylon-cli@X.Y.Z`.
 
-Requirements: Linux / macOS only (Windows operators should use WSL). The
-hosted script needs no preinstalled Node.js; the `npx` spellings need
+Requirements: macOS, Linux, or Windows. The hosted `install.sh` needs no
+preinstalled Node.js; the Windows `install.ps1` and the `npx` spellings need
 Node.js 22.15.0+ (npm ships with Node).
 
 ### One managed `kylon` for humans and agents
@@ -117,20 +121,50 @@ 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 update manually, rerun the hosted install script — the same command that
+installed Kylon:
 
 ```bash
-npx --yes kylon-cli@latest gateway service upgrade
+curl -fsSL https://api.kylon.io/install.sh | sh
+```
+
+(`https://api.purework.ai/install.sh` on dev; Windows:
+`powershell -c "irm https://api.kylon.io/install.ps1 | iex"`.) On a machine
+that already has Kylon the script never overwrites the managed bundle. It
+repairs the environment around it — a vanished Node.js gets the private
+runtime, the launcher and PATH snippet are rewritten, the serving deployment
+is re-recorded — and then asks the installed CLI to update itself with
+`kylon upgrade`. This is the command the CLI's update notice, `kylon gateway
+status`, the unknown-command hint, and the workspace's update surfaces all
+print; each spells it for the deployment the machine was set up against.
+
+`kylon upgrade` is the engine underneath the script, and can be run on its
+own when the environment is known to be healthy. 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 it is already the resolved target
+— `npx --yes kylon-cli@latest upgrade` runs the newest copy — it installs
+in-process rather than downloading itself a second time. `--force` skips the
+drain (see the interrupts below).
+
+The mechanism underneath is `gateway service upgrade`:
+
+```bash
+npx --yes kylon-cli@<exact version> gateway service 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 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
@@ -152,8 +186,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.
@@ -289,7 +323,8 @@ workspace; sign in again to replace one with the per-installation flow.
 
 `gateway run` starts the local runtime service from this environment's saved
 connection. It is the command the installed `launchd` / `systemd --user`
-service execs; run it manually to keep connected agents available in the foreground.
+service execs, and the child the Windows `gateway supervise` loop keeps
+running; run it manually to keep connected agents available in the foreground.
 
 ```bash
 kylon gateway run
@@ -653,7 +688,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

@@ -0,0 +1,5 @@
+{
+  "version": "0.3.10-next.696",
+  "fingerprint": "9e15eb570382d949de77ec450b683579429f9d78cacfccac94285036f925ee22",
+  "source_commit": "89f378fab1a052a76a902c6054c74a7fe9307d01"
+}