@abelxiaoxing/cadence 2.0.6 → 2.0.7

package/README.md

@@ -16,14 +16,24 @@ Cadence needs Node `>=22.19.0` with npm and [Pi](https://www.npmjs.com/package/@
 ```sh
 npm install -g @abelxiaoxing/cadence
 cadence server install
-cadence token-link --workspace ~/cadence --reveal
 ```
 
 The global install puts `cadence` (and its alias `cadence-service`) on `PATH`.
 Cadence ships no install script, so npm 12 and Bun, which skip untrusted install scripts by default, change nothing.
 They may still report blocked scripts from the pinned Pi SDK's dependencies: `@google/genai`'s preinstall only echoes `no-op`, and `protobufjs`'s postinstall only warns about a dependent's version scheme, so neither needs approval.
 `cadence server install` registers and starts the background service for `~/cadence` on `http://127.0.0.1:17423`; `--workspace /absolute/project` selects another workspace.
-It also creates the research template `~/.pi/agent/cadence/.env` when missing; Pi's startup card names that path until it exists.
+It prints the private link to open, `http://127.0.0.1:17423/?token=…`.
+The port and that token live with the research settings in `~/.pi/agent/cadence/.env`.
+Install creates that file from the research template when missing (your own 0600 file; Pi's startup card names the path until it exists), and adds either line when it is missing, never changing an existing one:
+
+```sh
+CADENCE_PORT=17423
+CADENCE_TOKEN=<random 43 characters>
+```
+
+The token admits anyone who has it to the workspace, so keep the file and the link private; a token you choose needs at least 32 characters.
+To change either, edit the line and run `cadence server restart`, which prints the new link; old links and browser cookies stop working.
+A workspace that an earlier version started with a generated token switches to the file at that restart and keeps its history.
 
 | Platform | Service                                                                                     | Starts                                       |
 | -------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
@@ -116,7 +126,7 @@ For manual checks, `pi -e ./src/index.ts -e ./scripts/agent-panel-demo.ts` adds
 
 ### Browser
 
-Open the locally revealed token link.
+Open the private link that `cadence server install` printed, or that `cadence token-link --reveal` reveals.
 Valid bootstrap redirects to a token-free URL and uses an HttpOnly SameSite cookie for subsequent HTTP/WebSocket access; no localStorage token copy.
 The browser can create/plan/Start/Cancel, run exact configured checks and record human review without a live Pi terminal.
 A token grants workspace access, not action consent.
@@ -363,6 +373,8 @@ Byte values are UTF-8/encoded bounds where specified; they are not targets to si
 | npm 12 or Bun skips untrusted install scripts by default       | Ship none; `cadence server install` registers the service and creates the template  |
 | Service manager that only signals (launchd, Windows login)     | Orderly Stop first; an unconfirmed Stop changes nothing; no SIGTERM or `taskkill`   |
 | Pi's TUI replaces an info status with the next one             | The missing-service hint is its own warning notification                            |
+| Token source the user edits (`CADENCE_TOKEN` in `.env`)        | Read once before binding, never bound for the run: an edit cannot fence Stop        |
+| Saved port/token source differs from `.env`                    | Only when stopped, reselect just those under the reservation; running ones refuse   |
 
 Good: current context → explicit grant → durable acceptance → genuine original native/storage settlement → exact retained dependency → real checks → human review.
 Base: a client leaves and another reattaches to the same accepted run without launching it again.
@@ -396,7 +408,8 @@ Regression owners:
 - `agent-panel`, `agent-panel-model`, `agent-panel-cadence`: panel keys/rendering and readonly owner observation that never starts, cancels or replays work.
 - `test/web/`: adapted pure/SSR tests separately from actual built-browser contexts, HTTPS, mixed clients, focus/viewports and complete downloads.
 - `package-*`, `distribution`, `service-package`, `independence`: exact tar/member/body/import/notice closure and nonactivating discovery.
-- `service-autostart`, `install-config`: explicit `cadence server` registration on systemd, launchd and the Windows Run key, definition escaping, restart/disable/mask/foreign handling, orderly Stop before every change and a package without install scripts.
+- `service-autostart`, `install-config`: explicit `cadence server` registration on systemd, launchd and the Windows Run key, definition escaping, restart/disable/mask/foreign handling, orderly Stop before every change, the `.env` port and token lines and a package without install scripts.
+- `service-cli`: real owners started from the `.env` port and token, reselection of a stopped workspace, edits while running and rotation of the token line.
 - `workspace-landing`: home-directory redirection to `~/cadence` across management, native attach and observation.
 
 Regenerate operator/service/native/browser outputs only through their canonical builders; `--check` variants compare new private output without overwriting canonical bytes.
@@ -405,6 +418,16 @@ Review the independently enumerated package member list and every emitted body,
 Keep public Pi peers external for the extension, the exact Undici/ws runtime edges, the exact optional SDK pins for the standalone owner and all upstream/font/vendor notices.
 Preserve original license bytes through their precise Git attributes; line-ending normalization must not invalidate audited source/notice hashes.
 
+### Release 2.0.7 acceptance snapshot
+
+Full `verify` ran on the 2.0.7 release tree (`7973e23` plus the version bump), in the 2.0.3 environment below.
+It passed 1945 root tests in 78 files (27 Windows-only controls skipped on Linux); `service-history-projection`'s multisegment archive test hit its 45s budget under shared load and passed alone (24 tests, 27s).
+The 111 web tests, 5 real-browser scenarios and 132-member pack audit passed, and CI 40194654384 passed 12/12 on the candidate `7341cf6` (this commit before its snapshot).
+`cadence server install|restart|uninstall` ran end to end in an isolated home, with a fake `systemctl` that runs the unit's own ExecStart and ExecStop.
+The printed link entered the WebUI, and an earlier generated-token workspace was reselected to the `.env`.
+An edit while running applied only at restart, and rotation changed only the `CADENCE_TOKEN` line.
+Real systemd, launchd and Windows registration were not exercised for this release.
+
 ### Release 2.0.6 acceptance snapshot
 
 Full `verify` passed on the 2.0.6 release tree (`8d31512` plus the version bump): 1940 root tests in 78 files (27 Windows-only controls skipped on Linux), 111 web tests, 5 real-browser scenarios and the 132-member pack audit, in the 2.0.3 environment below.

package/docs/remote-access.md

@@ -23,6 +23,7 @@ Use a private0600 JSON file with actual absolute paths:
 }
 ```
 
+`tokenSource` is `generated`, `environment` (`CADENCE_WEB_TOKEN`), `file` (the whole `tokenFile` is the token) or `config` (`tokenFile` names an `.env` whose [`CADENCE_PORT` and `CADENCE_TOKEN`](service-management.md#port-and-token) apply; its port must equal `http.port`).
 Explicitly start with `cadence-service start --workspace /absolute/project --config /absolute/private-config.json`.
 The host refuses arbitrary forwarding chains, alternate authorities and non-loopback binding.
 Native/management capability traffic remains direct loopback, separate from browser credentials.
@@ -47,14 +48,14 @@ Audit any additional proxy-generated forwarding headers against the exact backen
 HTTP and WebSocket upgrade must use the same authenticated route; no public backend bypass or insecure credential-bearing HTTP.
 This example does not install Caddy, provision DNS/certificates, change a firewall or deploy a service.
 
-Use `cadence-service token-link --workspace /absolute/project --reveal` to reveal a private entry link deliberately.
+Use `cadence-service token-link --workspace /absolute/project --reveal` to reveal a private entry link deliberately; the background service prints its link at `cadence server install` and `restart`.
 Only root GET token entry accepts query credentials; subsequent private reads, exports and WS use the HttpOnly SameSite=Strict Secure cookie.
 Browser mutations/readonly POSTs require exact Origin and CSRF; access does not grant Start/check/review consent.
 A bad explicit token refuses even with an older cookie.
 Never put provider credentials in a browser or URL.
 
 `token-rotate` invalidates old links/cookies, pending grants, authenticated sockets and incomplete downloads without canceling admitted tasks.
-Environment-backed tokens require explicit Stop/restart with changed environment instead.
+Environment-backed tokens require explicit Stop/restart with changed environment instead; an `.env` token's rotation rewrites only its `CADENCE_TOKEN` line.
 Links may already exist in clipboard/history or external logs; redirecting cannot retract disclosure.
 Use [management and recovery](service-management.md) for Stop, uncertainty and exact local resolution.
 Loopback HTTPS/viewport tests are not physical-device or second-machine deployment qualification.

package/docs/service-management.md

@@ -16,7 +16,7 @@ cadence stop --workspace /absolute/project
 
 `cadence-service` is the same command, and the equivalent package-relative command is `node <cadence>/src/service-cli.mjs ...`.
 `--help` lists the finite interface.
-`start` also accepts `--foreground`, `--config`, `--agent-dir`, `--host` (loopback only), `--port`, `--token-file` and `--state-home`.
+`start` also accepts `--foreground`, `--config`, `--agent-dir`, `--host` (loopback only), `--port`, `--token-file`, `--server-config` ([port and token](#port-and-token)) and `--state-home`.
 Defaults are loopback `127.0.0.1:17423`, normal Pi agent configuration, and detached service lifetime.
 An explicit port0 selects and persists a positive port once; restart uses the selected configuration, not a fallback endpoint.
 Missing/corrupt existing setup is preserved, not filled in or reset.
@@ -37,11 +37,11 @@ cadence server uninstall
 
 Only these explicit commands register, change or remove the service; no package install, update hook, `/cadence` or browser visit does.
 The package has no install script, so npm 12 and Bun skipping untrusted scripts by default changes nothing; the pinned Pi SDK's blocked `@google/genai` preinstall only echoes `no-op`, and its `protobufjs` postinstall only warns about version schemes.
-`install` also creates the research template `~/.pi/agent/cadence/.env` when it is missing, never overwriting it, whatever the service result.
-`install` works from any package location and runs `start --foreground --workspace` (Linux, macOS) or `start --workspace` (Windows) from that copy with the installing Node, without `--port`.
+`install` also creates the research template `~/.pi/agent/cadence/.env` when it is missing, never overwriting it, whatever the service result, and adds its [port and token](#port-and-token) lines when they are missing.
+`install` works from any package location and runs `start --foreground --workspace <workspace> --server-config <file>` (Linux, macOS) or the same without `--foreground` (Windows) from that copy with the installing Node, without `--port`.
 The workspace is `~/cadence` (created if missing), an existing absolute `--workspace`, or on later installs the one the definition already runs; a workspace containing the service's state home lands on `~/cadence` with a note.
-A new workspace selects `http://127.0.0.1:17423`; a port saved by an earlier start of that workspace still wins, and an occupied endpoint fails instead of falling back.
-Browser entry still requires the explicitly revealed token link; install prints the `token-link --reveal` command, never the token.
+The `.env` [port and token](#port-and-token) select the endpoint (17423 by default) and the token; an occupied endpoint fails instead of falling back.
+Install and restart print the private entry link once the owner answers; the JSON result on stdout never carries the token.
 `restart` rewrites an existing definition with the current Node and package paths, keeping its workspace and the user's disable choices, and starts it; run it after an npm upgrade, a Node change or a `models.json` edit.
 `stop` stops the owner orderly and keeps the registration for the next boot or login.
 `uninstall` stops it orderly and deletes only what Cadence generated; workspace, state home, history, linger and Pi sources stay.
@@ -58,6 +58,33 @@ It is a warning rather than part of the info card because Pi's TUI replaces one
 `/cadence` names the same command when it finds no owner.
 A machine without a supported user service manager and `CADENCE_AUTOSTART=0` keep both quiet; with `CADENCE_LINGER=0` they suggest `--no-linger`.
 
+### Port and token
+
+The background service reads two lines of the research configuration `~/.pi/agent/cadence/.env`:
+
+```sh
+CADENCE_PORT=17423
+CADENCE_TOKEN=<at least 32 characters, no control or format characters>
+```
+
+The file keeps the research skills' syntax (`KEY=value` lines, `#` comments, one optional pair of quotes), and each of these keys may appear only once.
+`install` and `restart` create the file from the research template when it is missing, as your own 0600 file in a 0700 directory.
+They append a missing `CADENCE_PORT` (17423) or `CADENCE_TOKEN` (random, 43 characters) under a comment, in the file's own line endings, and never change an existing line.
+An unusable file (another owner, wider permissions, a symlink, a syntax error the research skills would also refuse, a duplicate key, a port outside 1-65535, a short token) makes them change nothing, naming only its path.
+A project's `.pi/cadence/.env`, which the research skills prefer, is never read for the service.
+`start --server-config <.env>` makes these lines authoritative.
+The host reads them once before binding, like an environment token, so editing them while the owner runs changes nothing and can never fence access or the orderly Stop; the next start applies them, and `cadence server restart` does both.
+A workspace whose token comes from the file follows it at every `start`, also without `--server-config`; a contradicting `--port`, `--token-file` or `CADENCE_WEB_TOKEN` refuses.
+`CADENCE_WEB_TOKEN` stays the separate process-environment source; sourcing the `.env` in a shell sets `CADENCE_PORT` and `CADENCE_TOKEN`, which Cadence never reads from its environment.
+The token never enters Cadence's state home, and status and diagnosis never print it.
+`token-rotate` replaces only the `CADENCE_TOKEN` line's value with a new random token, keeping every other byte, and invalidates old links and cookies without stopping work.
+It refuses without any effect when that token was edited since the start, so a pending edit is never overwritten.
+
+A stopped workspace selected earlier with a generated, environment or file token, or another port, is reselected to the file at its next `start --server-config`.
+Under the new owner reservation Cadence retires the previous token with a new access generation and replaces the selected port and token source; the history and every other selected setting stay.
+A different agent directory, host or proxy still conflicts, and a running owner refuses until it has stopped.
+An interrupted replacement keeps the reservation as a fence and is never repaired automatically, like any interrupted start.
+
 ### Linux systemd user unit
 
 `install` writes `~/.local/share/systemd/user/cadence.service`, enables it for `default.target` (also undoing a `disable`, never a `mask`) and starts it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Shared Pi task workspace: native terminal and WebUI, persistent service, checks and human review.",
   "license": "MIT",
   "type": "module",

package/src/service/coordination.ts

@@ -518,6 +518,9 @@ export class ServiceCoordination {
     input: OwnerConfig,
     resolvedEndpoint: string = input.endpoint,
     initializeNew?: () => void,
+    /** Replaces a stopped selection's host policy and access (given its
+     * selected host-config snapshot); only then may the identity change. */
+    reselectExisting?: (hostConfig: FileSnapshot) => void,
   ): OwnerLease {
     const config = decodeOwnerConfig(input);
     const bound = endpoint(resolvedEndpoint);
@@ -537,7 +540,8 @@ export class ServiceCoordination {
       if (old?.value && old.value.phase !== "stopped")
         throw new ContractError("quarantine");
       if (this.store.inspectLock()) throw new ContractError("conflict");
-      if (old && old.config.identity !== hash(encoded(config)))
+      const reselect = !!old && old.config.identity !== hash(encoded(config));
+      if (reselect && (!reselectExisting || !old?.hostConfig))
         throw new ContractError("conflict");
       // Reserve BEFORE root initialization/legacy acquisition. Any later failure
       // keeps the reservation and short lock as an explicit partial fence.
@@ -561,7 +565,26 @@ export class ServiceCoordination {
         }),
         REGISTRY_BYTES,
       );
-      this.initialize(config);
+      if (old?.hostConfig && reselect && reselectExisting) {
+        // Host policy and access first, then the config and its manifest; the
+        // registration below takes the new identity. Failures keep the fence.
+        reselectExisting(old.hostConfig);
+        const saved = this.files.replace(
+          this.path("config.json"),
+          old.config,
+          encoded(config),
+        );
+        this.files.replace(
+          this.path("format.json"),
+          old.manifest,
+          encoded({
+            schema: "cadence-service-format/1",
+            root: this.store.root,
+            stateHome: this.stateHome,
+            configIdentity: saved.identity,
+          }),
+        );
+      } else this.initialize(config);
       // Called only for genuinely absent selected metadata, under the registry
       // reservation and before registration. Failures preserve the partial fence.
       if (!old) initializeNew?.();