@ycodium-ai/plugin-browser-workbench 0.2.2700 → 0.2.2729

package/README.md

@@ -10,16 +10,29 @@ you already run.
 The first time you open the workbench, the plugin:
 
 1. Asks you to confirm the VS Code Server license terms.
-2. Downloads the official `code` CLI if it is not already in the plugin data
-   directory.
+2. Downloads the official `code` CLI if a verified copy is not already in the
+   plugin data directory. The version is pinned in `src/cliRelease.ts` together
+   with each platform's archive SHA-256 from the VS Code update service; the
+   archive is checked before it is unpacked and discarded on a mismatch. A CLI
+   without a matching `bin/cli-verified.json` (for example one installed by an
+   older plugin) is never run; it is downloaded again. **update** installs the
+   pinned version and is a no-op when that verified version is already there.
 3. Starts `code serve-web` on `127.0.0.1` with a random port.
 4. Waits until the VS Code server payload has finished downloading (the CLI
    does that lazily on the first HTTP request).
 5. Registers the port with Ycodium.
 
-After that, the process stays up until you stop it, disable the plugin, or
-shut down the server. A later **Open** reuses the running instance. Progress
-for install and start is a stream named `progress`.
+A later **Open** reuses the running instance. If Ycodium restarts while its
+VS Code server is still up, **Open** reconnects to the saved port instead of
+starting a second server. Ownership is decided by the port and the connection
+token, never by the saved process id (ids get reused): a server that accepts the
+token and rejects a wrong one is ours. While the server is still downloading it
+answers every request with 202 whatever the token, so the plugin treats that as
+"possibly ours", reconnects and waits for the download to finish, then checks the
+token. A saved port that listens but never answers (5xx, 404, not HTTP) is waited
+on for 30 seconds and then forgotten, and **Open** starts a fresh server. A saved
+port with nothing listening, or one that lets a wrong token through, is forgotten
+at once. Progress for install and start is a stream named `progress`.
 
 If you already run code-server yourself, set its loopback port on the settings
 card or call **attach**. The plugin does not start, stop, or authenticate that
@@ -28,12 +41,18 @@ token.
 
 ## Requirements
 
-A Ycodium server with plugin API version 2, including `process.spawn` for
+A Ycodium server with plugin API version 3, including `process.spawn` for
 `data:bin/code` and `data:bin/code.exe` (at most two processes at once) and
 `ports.register`. The
 machine needs outbound HTTPS to `update.code.visualstudio.com` (and the CDN it
 redirects to) the first time the CLI is installed, unless you attach an
-external code-server instead.
+external code-server instead. Download failures say which step stopped: the
+connection, an HTTP status from a proxy or firewall, a cut-off transfer, or a
+checksum mismatch.
+
+To move to another CLI version, change `PINNED_CLI_VERSION` and replace the five
+hashes in `src/cliRelease.ts` with the `sha256hash` values from
+`https://update.code.visualstudio.com/api/versions/<version>/cli-<platform>/stable`.
 
 Supported CLI download platforms: Linux x64/arm64, macOS x64/arm64, Windows
 x64. Other combinations fail with a download error rather than guessing.
@@ -45,8 +64,16 @@ ycodium plugin add @ycodium-ai/plugin-browser-workbench
 ```
 
 The plugin ships enabled with Ycodium as `core.browser-workbench`. Disabling it
-stops the managed `serve-web` process and unregisters its port. The downloaded
-CLI, server data, and license acceptance stay in the plugin data directory.
+unregisters the port and stops the CLI process when this plugin run still owns
+its process handle; a server that is still up is left recorded so the next
+activation can reconnect. **Stop** ends the process this run started. A server
+this run did not start (found again after a restart, or a server process that
+outlived its CLI) cannot be proven safe to end, and the plugin never signals a
+process using only a saved PID. For those, **Stop** lets go instead: it forgets
+the record, stops showing the workbench as running, and tells you the port,
+because the old server may still be running. End it yourself if you need it gone;
+**Open** starts a fresh one. The downloaded CLI,
+server data, and license acceptance stay in the plugin data directory.
 Uninstalling writes a removal onto the home patch so a restart or upgrade does
 not bring the plugin back; it still does not delete that data directory.
 Reinstalling the unversioned bundled package restores the same entry without
@@ -76,8 +103,10 @@ ycodium plugin add @ycodium-ai/plugin-browser-workbench@<version>
 ```
 
 Installing a newer plugin version replaces the running one without restarting
-the server. Updating the VS Code CLI is a separate **update** command and
-requires the workbench to be stopped first.
+the Ycodium server. Updating the VS Code CLI is a separate **update** command
+and requires the workbench to be stopped first. Because **Stop** also lets go of
+a reconnected server, **Update** is never blocked by a server the plugin cannot
+end.
 
 ## Developing
 
@@ -88,14 +117,16 @@ vp run --filter @ycodium-ai/plugin-browser-workbench test
 
 The package builds its own code into `dist/index.js`. The host supplies the
 shared `@ycodium-ai/plugin-api` at runtime. The plugin requires plugin API
-version 2. Language catalogs live in `locales/`; only English is authored here.
+version 3. Language catalogs live in `locales/`; only English is authored here.
 
 The CLI lands at `bin/code.exe` on Windows and `bin/code` elsewhere; Windows
 cannot start an executable without its extension.
 
 Known limits: Server download progress is the size of `cli-data/serve-web/`
-because the CLI does not report bytes. The host does not auto-start the
-workbench after a server restart.
+because the CLI does not report bytes. The plugin does not auto-start a
+workbench after a Ycodium server restart; the next **Open** checks the saved
+port and token before reconnecting. A server that was let go of while still
+running keeps its port and its VS Code state until you end it.
 
 ## License