@abelxiaoxing/cadence 2.0.4 → 2.0.5

package/README.md

@@ -3,12 +3,53 @@
 `@abelxiaoxing/cadence` is a shared Pi task workspace with two independently usable clients: native `/cadence` and a browser WebUI.
 One persistent service owns tasks, bounded subagent collaboration, real parent checks and retained history.
 Ordinary conversations, resource discovery and opening history never start work or a service.
-On Linux, Pi's user-scope install registers that service as a systemd user unit and starts its WebUI on the default address.
+`cadence server install` registers that service with the user's service manager and starts its WebUI on the default address.
 
 This is a trusted workflow assistant, **not a sandbox, certified executor or transactional application system**.
 Code workers edit the chosen working copy directly; recovery can require human work.
 Model prose, tool results and human Done do not certify checks or code.
 
+## Install
+
+Cadence needs Node `>=22.19.0` with npm and [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), installed and logged in to a model provider: the service reads Pi's `auth.json` and `models.json` and never creates its own login.
+
+```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`.
+It needs no install script: the postinstall only creates a missing `~/.pi/agent/cadence/.env` research template, and npm may skip it (npm 12 blocks install scripts by default) without any other effect.
+`cadence server install` registers and starts the background service for `~/cadence` on `http://127.0.0.1:17423`; `--workspace /absolute/project` selects another workspace.
+
+| Platform | Service                                                                                     | Starts                                       |
+| -------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Linux    | systemd user unit `~/.local/share/systemd/user/cadence.service`                             | At boot through linger, else at login        |
+| macOS    | LaunchAgent `~/Library/LaunchAgents/com.abelxiaoxing.cadence.plist`                         | At login                                     |
+| Windows  | `HKCU\…\CurrentVersion\Run\Cadence`, starting `%LOCALAPPDATA%\cadence-server\cadence.vbs`   | At login, without a console window           |
+
+On Linux, install enables linger without a prompt when logind allows it, and otherwise asks `loginctl enable-linger`, which may want your password; `--no-linger` (or `CADENCE_LINGER=0`) keeps the service to login.
+Open the printed private link once; the browser then keeps an HttpOnly cookie, and `http://127.0.0.1:17423/` alone only says how to get the link.
+For native `/cadence`, let Pi load the same copy: `pi install "$(npm root -g)/@abelxiaoxing/cadence"` records that path and loads it in place, so an npm upgrade updates both.
+
+```sh
+cadence server status
+cadence server restart     # after an upgrade or a models.json change
+cadence server stop
+cadence server uninstall   # before npm uninstall -g, which runs no Cadence script
+```
+
+Upgrade with `npm install -g @abelxiaoxing/cadence@latest`, then `cadence server restart`, which rewrites the service definition with the current Node and package paths.
+Restart, stop and uninstall go through the authenticated orderly Stop, so running work is stopped, not detached; on macOS and Windows a Stop that is not confirmed changes nothing.
+`stop` keeps the registration, so the service starts again at the next boot or login.
+Uninstall removes only the generated definition; workspace, history, linger and Pi sources stay.
+
+Pi's own package install (`pi install npm:@abelxiaoxing/cadence`) still loads the native client, but its copy has no `cadence` on `PATH`; register the service with `node ~/.pi/agent/npm/node_modules/@abelxiaoxing/cadence/src/service-cli.mjs server install`, the command Pi's startup warning names while no service is registered.
+Keep one copy: two copies drift apart on upgrade, and a native client refuses an owner whose service contract differs from its own.
+A unit registered by an earlier version's Pi install hook keeps running; `cadence server restart` from the copy you keep rewrites it, and `pi update` no longer restarts it.
+See [the background service](docs/service-management.md#background-service) for exact behavior and limits.
+
 ## Load and start explicitly
 
 The package can be loaded as a reviewed local package, extracted tarball or installed npm package through Pi's package mechanism.
@@ -25,31 +66,17 @@ Before using the shared owner, stop older Cadence sessions and choose one coordi
 No old records, databases, credentials or uncertain locks are imported, reset or cleaned.
 
 ```sh
-cadence-service start --workspace /absolute/project
-cadence-service status --workspace /absolute/project
-cadence-service token-link --workspace /absolute/project --reveal
+cadence start --workspace /absolute/project
+cadence status --workspace /absolute/project
+cadence token-link --workspace /absolute/project --reveal
 ```
 
-Use the installed `cadence-service` bin, or `node /absolute/cadence/src/service-cli.mjs` followed by those arguments.
+Use the installed `cadence` bin (or `cadence-service`), or `node /absolute/cadence/src/service-cli.mjs` followed by those arguments.
 Default binding is numeric loopback `127.0.0.1:17423`; `--foreground` is available for an explicitly configured supervisor.
 Start reads the existing Pi agent directory (or an explicit private configuration), never creates another login/profile.
 A directory that contains the private state home (the home directory and its ancestors, such as `C:\Users\<you>`) cannot be a workspace, so commands there use `~/cadence` instead of refusing; only `start` creates it, and `/cadence` started there attaches to that owner.
 See [service management](docs/service-management.md) for configuration, model/auth policy, Stop, diagnosis and informed recovery.
 
-### Linux autostart after `pi install`
-
-`pi install npm:@abelxiaoxing/cadence` (user scope) writes `~/.local/share/systemd/user/cadence.service`, enables it and starts the owner for `~/cadence` on `http://127.0.0.1:17423`.
-Set an existing absolute `CADENCE_WORKSPACE` at install to choose another workspace, or `CADENCE_AUTOSTART=0` to skip registration.
-That first registration also enables linger when logind allows it without any authorization prompt, so the service starts at boot instead of at login; `CADENCE_LINGER=0` skips it, and later updates keep `loginctl disable-linger`.
-Enter the WebUI once with the link from `cadence-service token-link --workspace ~/cadence --reveal`; installation prints that command, not the token.
-Each `pi update` restarts the unit through orderly Stop, so running work is stopped rather than detached; `systemctl --user disable --now cadence` or `mask` is kept across upgrades.
-Run `cadence-service autostart remove` before `pi remove`; after `remove`, a later `pi update` registers the unit again as a first registration, so keep it off with `disable` or `mask` instead.
-The npm client hides dependency install-script output, and with `strict-allow-scripts` it skips those scripts entirely.
-Approve Cadence once with `npm install-scripts approve @abelxiaoxing/cadence` inside `~/.pi/agent/npm` (or `npm config set allow-scripts=@abelxiaoxing/cadence --location=user`), or run `cadence-service autostart install --linger`, which may ask for your password.
-Pi's session-start card names that command (without `--linger` under `CADENCE_LINGER=0`) while Pi's copy has no unit on a systemd machine, and `loginctl enable-linger` while the enabled unit only starts at login.
-Until the optional SDK and Pi's `auth.json` exist, registration or start waits instead of quarantining an owner.
-See [the systemd user unit](docs/service-management.md#linux-systemd-user-unit) for exact behavior and limits.
-
 ### Native terminal
 
 In a trusted, idle Pi TUI, type `/cadence [goal]` using fresh native Enter.
@@ -140,7 +167,8 @@ Outbound provider proxy policy is independent of inbound HTTPS and refuses unsup
 - `skills/git-commit` requires an explicit commit request and deterministic audit; task review never commits.
 - Three pinned professional profiles in `agents/` provide readonly design/diagnosis and direct-edit implementation instructions, not execution authority.
 - `config/` contains optional research/check examples.
-  Missing-only user `.env` template creation and the Linux autostart refresh above are the only postinstall behaviors; no build/Git/provider operation runs.
+  Missing-only user `.env` template creation is the only postinstall behavior; it registers no service, and nothing depends on npm running it.
+  No build/Git/provider operation runs.
 - `node /absolute/cadence/src/operator-cli.mjs doctor|runs [workspace]` remains readonly and independent of service startup.
 
 ## Development and evidence
@@ -179,7 +207,7 @@ Historical logs are not runtime dependencies, and removing development tooling m
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
 | `src/index.ts`, `src/task-shell.ts`, `src/native-*.ts`                                                 | Nonactivating Pi entry, raw native consent, typed service attachment, paging and verified export; no embedded executor    |
 | `src/agent-panel.ts`, `src/agent-panel-model.ts`, `src/agent-panel-cadence.ts`                         | Readonly agent panel over Pi's `subagent:*` bus, fed with a running owner's children; never starts or cancels work        |
-| `src/service/host.ts`, `src/service/cli.ts`, `src/service/autostart.ts`                                | Real single-owner composition, explicit management and the generated Linux user unit; management entry stays SDK-free     |
+| `src/service/host.ts`, `src/service/cli.ts`, `src/service/{autostart,launchd,login-run}.ts`            | Single-owner composition, explicit management and generated per-user service definitions; management stays SDK-free       |
 | `src/service/{coordination,private-files,owner,recovery}.ts`                                           | Canonical overlap exclusion, exact locks, original-operation lifetime and informed local recovery                         |
 | `src/service/{admission,task-actions,graph,scheduler}.ts`                                              | Context-bound actions, actual current views, finite graph scheduling, check/review barriers                               |
 | `src/service/{model-config,model-context,model-choice,auth-network}.ts`, `src/sdk-network.ts`          | Existing Pi sources, explicit exact model/thinking, original OAuth writeback and strict shared network policy             |
@@ -326,12 +354,14 @@ Byte values are UTF-8/encoded bounds where specified; they are not targets to si
 | Invalid read proof or changed source/key                       | Refuse; never rebase or interpret budget exhaustion as absence                      |
 | Dirty/partial/extra compiled assets or unsafe archive          | Refuse in place; no source refill, wildcard serving or fallback build               |
 | Extension import outside Pi aliases declared only as a peer    | Exact production dependency; Pi's install omits peers and Pi fails to start         |
-| Install without the optional SDK or Pi `auth.json`             | No unit registration or start; Pi sources refuse unregistered, no SDK quarantines   |
+| Server install without the optional SDK or Pi `auth.json`      | No SDK: nothing written; no `auth.json`: registered, not started (no quarantine)    |
 | Package files hard-linked into a package manager's store (Bun) | Packaged reads ignore link count, bind exact bodies; other files stay single-link   |
 | Host refuses during startup                                    | Fixed code/stage only; unregistered exits `refused`, registered stays `quarantined` |
 | Workspace containing the private state home                    | Land on `~/cadence` (only start creates it); never move state into the working copy |
-| Upgrade changes the unit workspace or Node path                | Stop with the loaded unit definition before rewriting, not only SIGTERM             |
-| Install hook cannot prompt and npm hides its output            | Only a first registration tries passwordless linger; the startup card names the gap |
+| Restart changes the definition's workspace or Node path        | Stop with the loaded definition before rewriting, not only a signal                 |
+| npm skips or hides the install hook (`allow-scripts`)          | Nothing depends on it; only `cadence server install` registers a service            |
+| 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                            |
 
 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.
@@ -365,7 +395,7 @@ 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`: Pi user-scope gating, unit escaping, upgrade/disable/mask/foreign handling and orderly removal.
+- `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 postinstall that registers nothing.
 - `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.
@@ -374,6 +404,12 @@ 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.5 acceptance snapshot
+
+Full `verify` passed on the 2.0.5 release tree (`dce261b` 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 133-member pack audit, in the 2.0.3 environment below.
+On that host `cadence server status` read the live unit that 2.0.4's Pi install hook had registered as `active` and `enabled` with linger on, so earlier units stay manageable.
+The launchd and Windows Run backends ran only against injected launchctl, reg.exe and orderly-Stop fakes; real macOS and Windows registration remains unqualified.
+
 ### Release 2.0.4 acceptance snapshot
 
 Full `verify` passed on `3987f65` (the `max` thinking change): 1925 root tests in 78 files, 111 web tests, 5 real-browser scenarios and the 132-member pack audit, in the 2.0.3 environment below.

package/docs/service-management.md

@@ -1,20 +1,20 @@
 # Explicit service management
 
-The native `/cadence` view and browser are clients of the same owner, started explicitly or by the [Linux systemd user unit](#linux-systemd-user-unit).
-Opening either view, extension discovery and login do not start it.
+The native `/cadence` view and browser are clients of the same owner, started explicitly or by the [background service](#background-service).
+Opening either view, extension discovery, login and package installation do not start it.
 Use one coordination state-home for the checkout; a different state-home is not a recovery route.
 Stop older Cadence sessions before starting the shared service.
 
 ```sh
-cadence-service start --workspace /absolute/project
-cadence-service status --workspace /absolute/project
-cadence-service diagnose --workspace /absolute/project
-cadence-service token-link --workspace /absolute/project --reveal
-cadence-service token-rotate --workspace /absolute/project
-cadence-service stop --workspace /absolute/project
+cadence start --workspace /absolute/project
+cadence status --workspace /absolute/project
+cadence diagnose --workspace /absolute/project
+cadence token-link --workspace /absolute/project --reveal
+cadence token-rotate --workspace /absolute/project
+cadence stop --workspace /absolute/project
 ```
 
-The equivalent package-relative command is `node <cadence>/src/service-cli.mjs ...`.
+`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`.
 Defaults are loopback `127.0.0.1:17423`, normal Pi agent configuration, and detached service lifetime.
@@ -23,55 +23,82 @@ Missing/corrupt existing setup is preserved, not filled in or reset.
 A workspace that contains the private state home (the home directory and its ancestors, such as `C:\Users\<you>` with `%LOCALAPPDATA%` or `~` with `~/.local/state`) would expose private history and locks to change observation, so every command there uses `~/cadence` (`%USERPROFILE%\cadence`) instead of refusing.
 Only `start` creates it; `status` reports `absent` without creating it, an explicit `--workspace` adds one informational line, and JSON output names the effective `workspace` only when it differs.
 `/cadence` started in such a directory attaches to the same owner, and real project directories are never redirected.
-Apart from the Linux user unit below, there is no supervisor installation, provider login or credential migration.
-
-## Linux systemd user unit
-
-On Linux, Pi's user-scope install (`pi install npm:@abelxiaoxing/cadence`, npm in `<agent-dir>/npm`) and every `pi update` run the package postinstall, which calls `cadence-service autostart refresh`.
-Refresh acts only when the package is exactly Pi's managed user copy; checkouts, project (`-l`), temporary and global installs, other platforms and `CADENCE_AUTOSTART=0` are left alone.
-
-The first refresh writes `~/.local/share/systemd/user/cadence.service`, enables it for `default.target` and starts it.
-A user unit runs with the user manager, which starts at login unless logind lingers the user, so that first registration also asks logind to enable linger when it is off; `CADENCE_LINGER=0` at install skips it.
-It never prompts: it calls `SetUserLinger` through `busctl` with `interactive=false` and no interactive authorization (bounded to 15s), because `loginctl enable-linger` always requests an interactive check that a desktop polkit agent can turn into a password dialog even with `--no-ask-password`.
-Where polkit requires authorization for `set-self-linger` (older systemd defaults), the unit stays login-only and the result reports `"linger":"refused"`.
-Later refreshes do not change linger, so `loginctl disable-linger` is kept across upgrades.
-The workspace is `~/cadence` (created if missing) or an existing absolute `CADENCE_WORKSPACE`, which lands on `~/cadence` with a note when it contains the unit's state home; later refreshes keep the unit's workspace unless that variable is set again.
-The unit runs `start --foreground --workspace` without `--port`, so 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 the unit instead of falling back.
-It bakes the installer's PATH (minus npm lifecycle entries), LANG/LC_ALL, an absolute XDG_STATE_HOME and a custom PI_CODING_AGENT_DIR, so shell management sees the same state home and Pi sources.
-Proxy variables are not baked; add a validated pair with `systemctl --user edit cadence`.
-Browser entry still requires the explicitly revealed token link; installation prints the `token-link --reveal` command, never the token.
+Apart from the background service below, there is no supervisor installation, provider login or credential migration.
 
-An upgrade refresh stops an active unit with its loaded definition, rewrites the file and starts it again.
-`ExecStop` is the authenticated orderly Stop, so admitted work is stopped, not detached.
-A disabled unit is refreshed but not re-enabled, and restarted only if it was running; a masked unit is never enabled or started; a unit file Cadence did not generate is left unchanged.
-`KillMode=mixed` sends systemd's SIGTERM only to the management client.
-An owner still settling after `TimeoutStopSec=90` (for example a quarantined one) is SIGKILLed, which is not orderly Stop and can leave recovery fences.
-`Restart=on-failure` is bounded to three starts in five minutes; a restart never removes fences, so a crashed owner keeps refusing until informed recovery.
+## Background service
+
+```sh
+cadence server install [--workspace /absolute/project] [--no-linger]
+cadence server status
+cadence server restart
+cadence server stop
+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 postinstall only creates a missing research `.env` template, so npm skipping it (`allow-scripts`, npm 12's default) changes nothing else.
+`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`.
+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.
+`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.
+Because npm runs no uninstall script, uninstall the service before `npm uninstall -g`; a left-behind definition fails to start once its CLI path disappears.
+A definition Cadence did not generate is left unchanged (`foreign`), and `status` reports `absent` when none is registered.
 
 Pi's installer omits peers, so the standalone owner and workers load the Pi SDK (`pi-coding-agent`, `pi-ai`) from exact 0.84.3 optional dependencies.
 Package files may be hard links into the package manager's store (Bun's default install); Cadence binds their exact content, not their link count.
 Missing or unusable Pi sources refuse before an owner registers; a new owner without the SDK quarantines.
-Refresh therefore does not register the unit while the SDK is unresolvable (for example, optional dependencies omitted), and enables without starting it while `auth.json` is missing; the unit carries `ConditionPathExists=` for all three files.
-After logging in to Pi, start it with `systemctl --user start cadence`.
+`install` therefore writes nothing while the SDK is unresolvable (for example, optional dependencies omitted), and registers without starting while Pi's `auth.json` is missing (`waiting-for-pi-login`); log in to Pi, then run `cadence server restart`.
+
+While no service is registered, Pi's session-start card shows a separate warning naming `cadence server install` for an installed package copy (`node <copy>/src/service-cli.mjs server install` for Pi's managed copy, which puts no bin on `PATH`); a checkout loaded with `pi -e` stays quiet.
+It is a warning rather than part of the info card because Pi's TUI replaces one info status with the next.
+`/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`.
+
+### 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.
+A user unit runs with the user manager, which starts at login unless logind lingers the user, so install also enables linger when it is off.
+It first calls `SetUserLinger` through `busctl` with `interactive=false` and no interactive authorization (bounded to 15s), because `loginctl enable-linger` always requests an interactive check that a desktop polkit agent can turn into a password dialog even with `--no-ask-password`.
+Only where polkit requires authorization for `set-self-linger` (older systemd defaults) does it then run `loginctl enable-linger`, which may ask for your password; that comes after the start, so an interrupted prompt never leaves the owner stopped, and a refusal reports `"linger":"refused"` with a login-only unit.
+`--no-linger` or `CADENCE_LINGER=0` skips linger; `restart` never changes it, so `loginctl disable-linger` is kept.
+The unit bakes the installer's PATH (minus npm lifecycle entries), LANG/LC_ALL, an absolute XDG_STATE_HOME and a custom PI_CODING_AGENT_DIR, so shell management sees the same state home and Pi sources.
+Proxy variables are not baked; add a validated pair with `systemctl --user edit cadence`.
+It carries `ConditionPathExists=` for the CLI, `auth.json` and both SDK packages.
+
+`restart` stops an active unit with its loaded definition, rewrites the file and starts it, without enabling a disabled unit; a masked unit is never enabled or started.
+`ExecStop` is the authenticated orderly Stop, so admitted work is stopped, not detached; `stop` and `uninstall` (`disable --now`) use it too.
+`KillMode=mixed` sends systemd's SIGTERM only to the management client.
+An owner still settling after `TimeoutStopSec=90` (for example a quarantined one) is SIGKILLed, which is not orderly Stop and can leave recovery fences.
+`Restart=on-failure` is bounded to three starts in five minutes; a restart never removes fences, so a crashed owner keeps refusing until informed recovery.
 Without linger, user units start at login and stop at logout through the same Stop.
 Linger starts the user manager, with every enabled user unit, at boot and keeps it running after logout.
-Because npm hides the install guidance, Pi's session-start card names `autostart install --linger` while Pi's managed copy has no unit, and `loginctl enable-linger` while the enabled unit is login-only.
-A machine not booted with systemd (no `/run/systemd/system`), a disabled or masked unit (also `mask --runtime`) and `CADENCE_AUTOSTART=0` keep the card quiet; with `CADENCE_LINGER=0` in Pi's environment it never suggests linger and names `autostart install` without `--linger`.
+`status` reports `linger` as `on` or `off`, and Pi's startup card names `loginctl enable-linger` while an enabled unit is login-only; a disabled or masked unit (also `mask --runtime`) keeps it quiet.
+To keep the service off while Cadence stays installed, use `systemctl --user disable --now cadence` or `mask`.
 
-```sh
-cadence-service autostart install [--workspace /absolute/project] [--linger]
-cadence-service autostart status
-cadence-service autostart remove
-```
+### macOS LaunchAgent
 
-`install` registers, enables and starts the unit from any package location unless it is masked.
-With `--linger` it also runs `loginctl enable-linger`, which may ask for your password; it asks only after the unit has started again, so an interrupted prompt never leaves the owner stopped.
-`status` reports `linger` as `on` or `off`.
-`remove` disables it through `ExecStop` and deletes only the generated file; workspace, state home, history and Pi sources stay.
-Because npm runs no uninstall script, run `remove` before `pi remove`; a left-behind unit skips start once its CLI path disappears.
-`remove` is for uninstalling: without the generated file the next `pi update` is a first registration again (unit and linger).
-To keep the service off while Cadence stays installed, use `systemctl --user disable --now cadence` or `mask`.
+`install` writes `~/Library/LaunchAgents/com.abelxiaoxing.cadence.plist` with `RunAtLoad`, runs `launchctl enable` (undoing a `launchctl disable`) and loads it into `gui/<uid>` with `launchctl bootstrap`, which starts it; launchd loads it again at every login.
+It bakes the same PATH, LANG/LC_ALL, XDG_STATE_HOME and PI_CODING_AGENT_DIR as the Linux unit and logs to `~/Library/Logs/cadence.log`.
+Without `auth.json` the agent is written but not loaded.
+Because launchd stops a job only by signaling it, `restart`, `stop`, `uninstall` and a reinstall first stop the owner through the authenticated orderly Stop, and change nothing when that Stop is `unconfirmed`, `quarantined` or `unavailable`.
+Only then does Cadence unload (`bootout`) or replace the agent; `stop` leaves it loaded, and the finished job starts again at the next login.
+There is no `KeepAlive`: launchd has no start limit, and a restart never clears fences, so a failed owner stays down until `cadence server restart`.
+`restart` keeps a `launchctl disable` and reports `disabled` without loading.
+At logout or shutdown launchd signals the job, which is not orderly Stop and can leave recovery fences; run `cadence server stop` first while work is running.
+
+### Windows login Run entry
+
+`install` writes `%LOCALAPPDATA%\cadence-server\cadence.vbs`, beside rather than inside the private state home, and the per-user value `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\Cadence`, which runs it with `wscript.exe` at login; no administrator rights are needed.
+The launcher is UTF-16 with a byte-order mark, so non-ASCII paths work, and runs `start --workspace` with window style 0, so no console window appears; the detached owner keeps running after the launcher exits.
+It bakes only a custom PI_CODING_AGENT_DIR, because the login environment already carries PATH and `%LOCALAPPDATA%`.
+`install` also removes Task Manager's `StartupApproved` switch for the entry (undoing a disable there); `restart` keeps both the entry and that switch, and `status` reports a disabled entry.
+Without `auth.json` the entry is registered but nothing starts.
+Nothing supervises the detached owner, so a failed owner is not restarted, and every `restart`, `stop`, `uninstall` and reinstall first runs the authenticated orderly Stop and changes nothing unless it is confirmed; Cadence never kills a process.
+A `Cadence` Run value without Cadence's launcher is `foreign` and left unchanged; registry values are only tested for presence, because `reg.exe` prints them in the console code page.
+At sign-out or shutdown Windows ends the owner without orderly Stop, which can leave recovery fences; run `cadence server stop` first while work is running.
 
 ## Status, departure and Stop
 
@@ -95,7 +122,7 @@ To keep the service off while Cadence stays installed, use `systemctl --user dis
   `supportsMidConvoSystemMessages` from newer Pi is accepted because the pinned SDK has no system-role conversation message; other unknown fields refuse rather than being silently ignored.
   The owner model choice offers every thinking level the pinned SDK supports for a model, `off` through `xhigh` and `max`; a model whose `thinkingLevelMap` maps only `max` (as some DeepSeek configurations do) is chosen at `max`, and a child runs only at exactly that level.
   The owner loads `models.json` once at start: after it changes, the model catalog, the chosen model and the workspace view refuse as `stale` (credential changes in `auth.json` are read fresh).
-  Restart the service to reload it (`systemctl --user restart cadence`, or `stop` then `start`), then choose the owner model again.
+  Restart the service to reload it (`cadence server restart`, or `stop` then `start`), then choose the owner model again.
 - A foreground owner can be managed from another terminal.
   Ctrl-C, SIGTERM, machine crash or terminal destruction is **not** the authenticated orderly Stop route and can leave recovery fences.
   A recovered `stopped` registration means acknowledged fence release, not retroactive native closure certification.
@@ -138,8 +165,8 @@ Local fabricated-provider plain/gzip routing tests are not paid-provider, all-ad
 ## Informed local recovery
 
 ```sh
-cadence-service recover inspect --workspace /absolute/project
-cadence-service recover resolve --workspace /absolute/project
+cadence recover inspect --workspace /absolute/project
+cadence recover resolve --workspace /absolute/project
 ```
 
 Inspection is readonly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Shared Pi task workspace: native terminal and WebUI, persistent service, checks and human review.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "src/agent-panel-cadence.ts",
     "src/agent-panel-model.ts",
     "src/agent-panel.ts",
+    "src/cadence-service.mjs",
     "src/index.ts",
     "src/install-config.mjs",
     "src/native-build.ts",
@@ -150,6 +151,7 @@
     "@earendil-works/pi-coding-agent": "0.84.3"
   },
   "bin": {
-    "cadence-service": "./src/service-cli.mjs"
+    "cadence": "./src/service-cli.mjs",
+    "cadence-service": "./src/cadence-service.mjs"
   }
 }

package/src/cadence-service.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// `cadence-service`, the earlier name of `cadence`. Its own file: `bun pm pack`
+// writes a file once per bin name, and the package audit refuses duplicates.
+await import("./service-cli.mjs");

package/src/index.ts

@@ -26,10 +26,10 @@ export default function register(pi: ExtensionAPI): void {
         projectTrusted: ctx.isProjectTrusted(),
       });
       const shown = lines.length > 1 ? lines.slice(1) : lines;
-      // npm hides the install hook's guidance; boot-start gaps surface here.
-      const autostart = autostartNotice();
-      if (autostart) shown.push(autostart);
       ctx.ui.notify(shown.join("\n"), "info");
+      // A later info status replaces this card in Pi's TUI; a warning stays.
+      const autostart = autostartNotice();
+      if (autostart) ctx.ui.notify(autostart, "warning");
     } catch {
       // Presentation only; shell lifecycle still runs.
     }

package/src/install-config.mjs

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import { closeSync, constants, mkdirSync, openSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -41,22 +40,8 @@ export function ensureUserConfig(home = homedir()) {
   }
 }
 
-/** Pi install/update hook. The management client decides whether this is Pi's
- * Linux user-scope install and refreshes the systemd user unit; only its human
- * guidance (stderr) reaches the installer. */
-export function refreshAutostart(run = spawnSync) {
-  if (process.platform !== "linux" || process.versions.bun) return;
-  run(
-    process.execPath,
-    [
-      fileURLToPath(new URL("./service-cli.mjs", import.meta.url)),
-      "autostart",
-      "refresh",
-    ],
-    { stdio: ["ignore", "ignore", "inherit"] },
-  );
-}
-
+// The only install hook behavior. npm may skip it (allow-scripts), so nothing
+// else depends on it; services are registered by `cadence server install`.
 if (
   process.argv[1] &&
   path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
@@ -71,12 +56,4 @@ if (
     );
     process.exitCode = 0;
   }
-  try {
-    refreshAutostart();
-  } catch (error) {
-    process.stderr.write(
-      `Cadence could not refresh its systemd user unit: ${error instanceof Error ? error.message : String(error)}\n`,
-    );
-    process.exitCode = 0;
-  }
 }

package/src/native-client.ts

@@ -2,7 +2,7 @@
 
 import { existsSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Agent, Dispatcher1Wrapper } from "undici";
 import { nativeBuild } from "./native-build.ts";
@@ -20,34 +20,59 @@ export const MANAGEMENT_GUIDANCE =
   "Cadence owner absent, unavailable or incompatible. Explicitly run cadence-service status --workspace <path>, cadence-service diagnose --workspace <path>, or cadence-service start --workspace <path>. Stop older Cadence sessions first. For retained fences use cadence-service recover inspect; resolve requires a local terminal and separate process, credential and storage acknowledgments. Never treat unavailable/quarantined as stopped. No service was started and no embedded executor is available.";
 
 const UNIT = "cadence.service";
+const LABEL = "com.abelxiaoxing.cadence";
 /** Exists only when systemd booted the machine (sd_booted); without it there
- * is no user manager, and `autostart install` reports unavailable. */
+ * is no user manager, and `server install` reports unavailable. */
 const SYSTEMD_BOOTED = "/run/systemd/system";
 const xdg = (value: string | undefined, fallback: string) =>
   value && isAbsolute(value) ? value : fallback;
-const cliPath = () =>
-  JSON.stringify(fileURLToPath(new URL("./service-cli.mjs", import.meta.url)));
-/** CADENCE_LINGER=0 keeps the explicit command login-only, too. */
-const installCommand = (env: NodeJS.ProcessEnv) =>
-  `node ${cliPath()} autostart install${env.CADENCE_LINGER === "0" ? "" : " --linger"}`;
+/** The definition `cadence server install` writes, or undefined without a
+ * supported user service manager. */
+function definition(o: AutostartObservation): string | undefined {
+  switch (o.platform) {
+    case "linux":
+      return existsSync(o.systemd)
+        ? join(
+            xdg(o.env.XDG_DATA_HOME, join(o.home, ".local", "share")),
+            "systemd",
+            "user",
+            UNIT,
+          )
+        : undefined;
+    case "darwin":
+      return join(o.home, "Library", "LaunchAgents", `${LABEL}.plist`);
+    case "win32":
+      return join(
+        xdg(o.env.LOCALAPPDATA, join(o.home, "AppData", "Local")),
+        "cadence-server",
+        "cadence.vbs",
+      );
+    default:
+      return undefined;
+  }
+}
+const bootStart = (o: AutostartObservation) =>
+  o.platform === "linux" && o.env.CADENCE_LINGER !== "0";
+/** Pi's managed copy puts no `cadence` bin on PATH; CADENCE_LINGER=0 keeps
+ * the suggested command login-only, too. */
+const installCommand = (o: AutostartObservation) =>
+  `${piUserCopy(o) ? `node ${JSON.stringify(join(o.root, "src", "service-cli.mjs"))}` : "cadence"} server install${o.platform === "linux" && o.env.CADENCE_LINGER === "0" ? " --no-linger" : ""}`;
 
-/** Linux: npm may skip or hide the Pi install hook that registers the user
- * unit, so name the explicit command when it is absent. Reads two paths only. */
-export function autostartHint(): string {
-  if (process.platform !== "linux" || !existsSync(SYSTEMD_BOOTED)) return "";
-  const data = xdg(
-    process.env.XDG_DATA_HOME,
-    join(homedir(), ".local", "share"),
-  );
-  if (existsSync(join(data, "systemd", "user", UNIT))) return "";
-  return `\nTo run the shared service and WebUI (default http://127.0.0.1:17423) ${process.env.CADENCE_LINGER === "0" ? "at login" : "at boot"}: ${installCommand(process.env)}`;
+/** Name the explicit command while no background service is registered.
+ * Reads paths only. */
+export function autostartHint(
+  o: AutostartObservation = hostObservation(),
+): string {
+  const path = definition(o);
+  if (!path || existsSync(path)) return "";
+  return `\nTo run the shared service and WebUI (default http://127.0.0.1:17423) ${bootStart(o) ? "at boot" : "at login"}: ${installCommand(o)}`;
 }
 
 export interface AutostartObservation {
   platform: NodeJS.Platform;
   env: NodeJS.ProcessEnv;
   home: string;
-  /** Package root; only Pi's managed user copy registers itself. */
+  /** Package root; installed copies, not checkouts, get the startup notice. */
   root: string;
   /** logind keeps one flag file per lingering user name. */
   lingerFile: string;
@@ -95,26 +120,27 @@ function piUserCopy(o: AutostartObservation): boolean {
     return false;
   }
 }
-/** Startup-card line while boot start of the Linux user unit needs a human
- * step. Path observations only: nothing is created, spawned or started. A
- * machine without systemd, a disabled or (also runtime-)masked unit and
- * CADENCE_AUTOSTART=0 are quiet; CADENCE_LINGER=0 never suggests linger. */
+/** An npm or Pi package copy; a checkout loaded with `pi -e` is explicit by design. */
+function installedCopy(o: AutostartObservation): boolean {
+  return piUserCopy(o) || resolve(o.root).split(sep).includes("node_modules");
+}
+/** Startup-card warning while the background service needs a human step.
+ * Path observations only: nothing is created, spawned or started. A machine
+ * without a supported user service manager, a disabled or (also runtime-)
+ * masked Linux unit and CADENCE_AUTOSTART=0 are quiet; CADENCE_LINGER=0 never
+ * suggests linger. */
 export function autostartNotice(
   o: AutostartObservation = hostObservation(),
 ): string | undefined {
-  if (
-    o.platform !== "linux" ||
-    o.env.CADENCE_AUTOSTART === "0" ||
-    !existsSync(o.systemd)
-  )
-    return;
-  const data = xdg(o.env.XDG_DATA_HOME, join(o.home, ".local", "share"));
-  const config = xdg(o.env.XDG_CONFIG_HOME, join(o.home, ".config"));
-  const boot = o.env.CADENCE_LINGER !== "0";
-  if (!existsSync(join(data, "systemd", "user", UNIT)))
-    return piUserCopy(o)
-      ? `Cadence服务：未注册${boot ? "开机" : ""}自启（npm 可能跳过或隐藏了安装脚本）。注册并${boot ? "开机" : "登录后"}启动：${installCommand(o.env)}`
+  if (o.env.CADENCE_AUTOSTART === "0") return;
+  const path = definition(o);
+  if (!path) return;
+  if (!existsSync(path))
+    return installedCopy(o)
+      ? `Cadence服务：后台服务未安装，WebUI（默认 http://127.0.0.1:17423）不会运行。安装并${bootStart(o) ? "开机" : "登录后"}自启：${installCommand(o)}`
       : undefined;
+  if (o.platform !== "linux") return;
+  const config = xdg(o.env.XDG_CONFIG_HOME, join(o.home, ".config"));
   const user = join(config, "systemd", "user");
   const runtime = o.env.XDG_RUNTIME_DIR;
   if (