@abelxiaoxing/cadence 2.0.0 → 2.0.2

package/README.md

@@ -1,29 +1,24 @@
 # Cadence
 
 `@abelxiaoxing/cadence` is a shared Pi task workspace with two independently usable clients: native `/cadence` and a browser WebUI.
-One explicitly started service owns tasks, bounded subagent collaboration, real parent checks and retained history.
-Ordinary conversations, resource discovery, installation and opening history never start work or a service.
+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.
 
 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.
 
-## Upgrading from 1.x
-
-Version 2.0.0 replaces the four Abel workflow prompts (`/abel-init`, `/abel-design`, `/abel-implement`, `/abel-diagnose`) with native `/cadence` and the WebUI backed by one explicitly started service.
-This is a breaking change, not an in-place continuation of the 1.x workflow.
-Stop older Cadence sessions before switching; existing records and credentials are not imported, migrated, deleted or replayed automatically.
-Node `>=22.19.0` and the declared external peers, including Undici, are required; `ws` is now a production dependency.
-Installation still does not start the service or execute tasks; follow the loading and explicit startup instructions below.
-
 ## 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.
 For a local checkout, add its absolute or relative path to Pi's `packages` setting, or try `pi -e ./cadence`.
 Pi loads `src/index.ts`; the service, worker and readonly operator are ordinary JavaScript with no TypeScript/source-tree fallback.
-The manifest does not impose a Pi version range; public Pi peers stay external.
+The manifest does not impose a Pi version range; inside Pi the extension uses Pi's own public packages.
 Development pins, declared Node baseline (`>=22.19.0`) and actual tested runtime identities are separate facts, not universal compatibility promises.
-Required installed peers include public Pi packages, Typebox and Undici; `ws` is the sole production dependency.
+Required installed peers are public Pi packages and Typebox; `undici` and `ws` are exact production dependencies.
+Pi's package installer omits peers and supplies only its own packages and Typebox to the extension, so any other extension import must be a production dependency.
+The standalone owner and workers run outside Pi and import `pi-coding-agent`/`pi-ai` by bare name, so they load the exact tested copy (0.84.3) from optional dependencies; an install that omits optional dependencies cannot start an owner.
 Browser assets are prebuilt, not compiled by consumer postinstall.
 
 Before using the shared owner, stop older Cadence sessions and choose one coordination state-home for the checkout.
@@ -38,8 +33,21 @@ cadence-service token-link --workspace /absolute/project --reveal
 Use the installed `cadence-service` bin, 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.
+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`.
+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`; `/cadence` names that command while no unit is registered.
+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.
@@ -114,24 +122,20 @@ Outbound provider proxy policy is independent of inbound HTTPS and refuses unsup
 ## Development and evidence
 
 ```sh
-bun run verify                         # default fast verification; no browser
-bun run test                           # reviewed fast root regressions
-bun run test:target test/service-contract.test.ts
+bun run check
+bun run check:web
+bun run build:check
+bun run lint
+bun run check:agents
+bun run test:service
 bun run test:web
-bun run test:integration                # explicit slow SDK/PTY/history lane
-CADENCE_BROWSER_PATH=/absolute/existing/chromium bun run verify:full
+CADENCE_BROWSER_PATH=/absolute/existing/chromium bun run test:browser
+CADENCE_BROWSER_PATH=/absolute/existing/chromium bun run verify
 bun pm pack --destination /absolute/private-temp
 ```
 
 Build/verification use a fresh private directory with `TMPDIR`, `TEMP` and `TMP` set explicitly.
-`verify` runs root/Web type checks, exact generated-byte checks, lint, Agent pins, fast root regressions, Web unit tests and the real pack audit.
-The fast root lane uses an explicit reviewed list in `test/fast.config.ts`, with at most four parallel workers; no test is selected from mutable timing caches.
-SDK/provider cycles, PTYs, large-history/native stress scenarios and real browsers are not part of the default command or fast CI matrix.
-`test:integration` selects the remaining root tests serially; new root tests stay there until explicitly promoted to the fast list.
-`verify:full` runs fast verification, those remaining tests and real-browser scenarios once each; it can take tens of minutes and must be requested explicitly.
-Fast verification is not full integration/browser qualification.
-Missing required browser in the full lane is non-green, never an automatic download.
-For a focused slow regression, pass its file to `test:target`; `test:service` and `test:browser` remain separate explicit lanes.
+`verify` includes native/unit tests, web tests, required real-browser scenarios and exact real-pack auditing; missing required browser is non-green, never an automatic download.
 Source/extracted PTYs, fabricated loopback providers and isolated HTTPS are distinct from physical humans/devices, paid accounts, package-manager installation and native Windows/macOS/ConPTY qualification.
 Those additional lanes remain unqualified unless their own receipts exist.
 No passing gate authorizes commit, push, publication, installation, deployment or cleanup.
@@ -149,7 +153,7 @@ Historical logs are not runtime dependencies, and removing development tooling m
 | Owner                                                                                                  | Responsibility                                                                                                            |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
 | `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/service/host.ts`, `src/service/cli.ts`                                                            | Real single-owner composition and explicit management; generated management entry stays SDK-free                          |
+| `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/{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             |
@@ -186,6 +190,7 @@ Use their current declarations rather than copying DTO parsing, reducers, a seco
 - Independent readonly assignments may overlap; writers and native parent checks exclude readers and other writers across tasks.
   Reserve bounded slots/bytes before copying/auth/effects; dependencies use exact committed predecessor content only after actual native and recording settlement.
   Overflow, stale dependencies, first failure or wait expiry closes admission without retry; independent already-running siblings retain their own outcomes.
+  Each assignment or check observes the working copy at its baseline, immediately before its native launch and after exit; the steps between recheck ownership, sources and definitions without another Git/file capture.
 - Register the original accepted control flow before its first effect, in addition to separate native/auth/storage originals.
   Reporting timeout, a caught promise, PID absence or an empty roster cannot release resources.
   Stop publishes one shared attempt, quiesces all admissions, requests stops before awaiting children and joins permitted original continuation/safety writes.
@@ -209,6 +214,7 @@ A fresh check may account for exactly one owned generation advance bound to its
 Do not replace this proof with a general before≤after comparison.
 Changes to files, definitions, epoch/cwd/environment or a foreign generation stale the current obligation without rewriting historical native exit or PASS.
 Human Review binds exact selected run/graph/check/change identities and recaptures under a short exclusive barrier only after confirmation, not throughout the human modal.
+One accepted Review folds its fixed committed snapshot (plan proof, selected run, check results) once; every barrier validation still rechecks raw task bytes, changes, configuration, choice and active work.
 Acknowledgment permits reviewed-with-issues, never changes failed/partial/canceled/native/recording/check facts or revives blocked execution.
 Unavailable concurrent views may display conservative stale status but cannot advance authoritative review revisions and invalidate an otherwise unchanged accepted Review.
 
@@ -235,6 +241,13 @@ Only the serialized history writer assigns committed sequence and persisted cont
 Commit actual admission/auth/launch/result facts in order; an index, observer callback or candidate reducer cannot authorize effects.
 Quota/exhaustion/refusal stops unsafe work without eviction; torn tails retain a verified prefix and visible gaps, while interior corruption refuses affected ranges.
 Derived indexes are optional accelerators: readers validate original batches/artifacts, use bounded fallback and never repair on view.
+Current/plan/review reads replay a task's batches, so per-file cost bounds them: on a slow host (Windows Node 22) that replay once exceeded the 100ms read quantum after review, leaving the task `unavailable`.
+`PrivateFiles` reuses a directory walk only within one synchronous `DirectoryWalks` scope (a read budget or lease check), after re-observing that directory's identity; an await or later call walks again, and the quantum is never raised instead.
+When a batch settles a task's publication, the owner writer remembers in process memory that task's fold state (check facts, latest run, plan/lineage progress with original admission locators) under its chain head's sequence and hash, a bounded number of tasks and states.
+Readers in that process resume from the newest remembered state at or before the snapshot whose chain link still matches and fold only newer original batches; an evicted, restarted, foreign-process or diverged miss folds the original chain, and nothing is persisted, authenticated or repaired.
+A quantum that makes no semantic progress because its wall-clock time ran out (a host stall: GC, scheduling, scanning) is repeated with a fresh quantum at most twice before its refusal stands; byte exhaustion and every other refusal stay final, and no progress is ever faked.
+The wall-clock quantum belongs only to client-facing cooperative reads: owner-internal authority reads (current views, admission, publication, Review and receipt facts) are bounded by the same bytes but never by time, so host speed cannot turn an owner's own decision into a refusal.
+Plan proofs and Review selections read their small plan text through its content/part indexes under the validated snapshot, verifying the original chunk batches, artifacts and aggregate hash; absent or faulty indexes fall back to the complete validated-prefix scan, which no longer runs per current view.
 Prepared journal heads avoid redundant mutable legacy hints; no-root compatibility and its original integrity checks remain.
 
 New history uses private format3 at `service-v1/history-v2/`, with exclusive private read-proof key creation before the final format marker.
@@ -276,16 +289,22 @@ Byte values are UTF-8/encoded bounds where specified; they are not targets to si
 
 ### Validation and regression lessons
 
-| Condition                                                      | Required behavior                                                                 |
-| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Missing/unsafe/corrupt/partial selected state                  | Absent or fixed refusal; no bootstrap, adoption, repair or cleanup on observation |
-| Native exit0 with recording/stdin/final/cleanup failure        | Preserve native zero independently; no workflow success                           |
-| Stale grant, selected task bytes or model/source identity      | Refuse and require fresh observation/confirmation                                 |
-| Unknown original stop/auth/storage or changed lease            | Retain fences/charges; no guessed process signaling or automatic release          |
-| Failed/unrun/stale check, partial child or incomplete coverage | Explicit issues review; preserve independent recorded outcomes                    |
-| Lost reply or detached view                                    | Observe original receipt/run; no mutation replay or implicit Cancel               |
-| 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             |
+| Condition                                                      | Required behavior                                                                   |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Missing/unsafe/corrupt/partial selected state                  | Absent or fixed refusal; no bootstrap, adoption, repair or cleanup on observation   |
+| Native exit0 with recording/stdin/final/cleanup failure        | Preserve native zero independently; no workflow success                             |
+| Stale grant, selected task bytes or model/source identity      | Refuse and require fresh observation/confirmation                                   |
+| Unknown original stop/auth/storage or changed lease            | Retain fences/charges; no guessed process signaling or automatic release            |
+| Failed/unrun/stale check, partial child or incomplete coverage | Explicit issues review; preserve independent recorded outcomes                      |
+| Lost reply or detached view                                    | Observe original receipt/run; no mutation replay or implicit Cancel                 |
+| 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   |
+| 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             |
 
 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.
@@ -299,9 +318,8 @@ Correct: expose bounded continuations/full exports and report the exact executed
 ### Development and verification practice
 
 Read affected source and adjacent tests, identify the actual owner of a contract, then make the smallest coherent change.
-Use ordinary source editing and directly affected checks while developing; run the fast `verify` command at stable boundaries.
-Request the explicit integration/browser lanes when those capabilities need qualification; do not silently start the entire suite after a local edit or a publication request.
-Keep fast-check results separate from real native/SDK/browser evidence, and never replace a required integration result with unit mocks or citation counts.
+Use ordinary source editing and directly affected checks while developing; independently review complete capabilities and run full `verify` at stable integration boundaries.
+Do not run the entire suite after every local edit, but do not replace final integration with unit mocks or citation counts.
 On this development host create fresh0700 disk roots under `/home/mirako/abel` and explicitly set TMPDIR/TEMP/TMP; `/tmp` is inode-exhausted.
 Use fabricated credentials, isolated browser/profile/state roots and local fixtures; never personal credentials, automatic downloads or unknown process cleanup.
 Outer command budgets must cover whole suites and preserve original runner waits; existing SDK20s/child15s, PTY90s/interaction15s and browser120s/action15s fixture budgets are not increased to obtain green.
@@ -316,11 +334,13 @@ Regression owners:
 - `service-history-*`: durable ordering, cold/no-index/restarted proof/search/export, corruption/torn/quota and expected-byte publication.
 - `lightweight-shell`, `native-client`, `native-history`, `terminal-integration`: native consent, shared service, Unicode/paging, detach/cancel and actual source/extracted PTYs.
 - `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 installation/discovery.
+- `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.
+- `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.
 Review the independently enumerated package member list and every emitted body, not a count or an expected list generated from the tar under test.
-Keep public Pi peers external, the exact ws runtime edge and all upstream/font/vendor notices.
+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.
 
 ### Prior integrated acceptance snapshot

package/docs/reuse-and-distribution.md

@@ -35,7 +35,8 @@ Provisioned official notice bodies were reused locally; builds never download li
 ## Runtime/package closure
 
 Only the native extension's explicit import closure, maintained SDK worker/shared JS capture modules, generated management/host/operator executables, Agents, independent skills/configuration, documentation, notices and complete built assets ship.
-Service/worker execution uses ordinary Node with declared external Pi/Typebox/Undici peers and exact production `ws`; no source-tree or TypeScript fallback, SDK bundle or consumer compilation.
+Service/worker execution uses ordinary Node with exact production `undici` and `ws` and the Pi SDK (`pi-coding-agent`, `pi-ai`) from exact 0.84.3 optional dependencies, because Pi's installer omits peers; no source-tree or TypeScript fallback, SDK bundle or consumer compilation.
+Pi's package installer omits peers and aliases only its own packages and Typebox, so every other runtime import reachable from `src/index.ts` must be a production dependency; otherwise Pi fails to load the extension at startup.
 The retired shell-local controller is not a shipped competing executor.
 
 `provenance/package-members.json` is a reviewed source/import/asset policy, not generated from the archive being tested.

package/docs/service-management.md

@@ -1,7 +1,7 @@
 # Explicit service management
 
-The native `/cadence` view and browser are clients of the same explicitly started owner.
-Opening either view, extension discovery, installation and login do not start it.
+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.
 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.
 
@@ -20,7 +20,47 @@ The equivalent package-relative command is `node <cadence>/src/service-cli.mjs .
 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.
-There is no login autostart, supervisor installation, provider login or credential migration.
+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.
+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.
+
+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.
+
+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`.
+Without linger, user units start at login and stop at logout through the same Stop; `loginctl enable-linger` keeps the owner running and starts it at boot.
+
+```sh
+cadence-service autostart install [--workspace /absolute/project]
+cadence-service autostart status
+cadence-service autostart remove
+```
+
+`install` registers, enables and starts the unit from any package location unless it is masked.
+`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.
 
 ## Status, departure and Stop
 
@@ -34,6 +74,13 @@ There is no login autostart, supervisor installation, provider login or credenti
 - `unconfirmed` means startup/Stop acknowledgment or settlement was not established within its reporting bound.
   It is not permission to restart, kill a guessed PID or remove a lock.
   `quarantined` preserves uncertain process/auth/storage work and prevents unsafe writers.
+- A host that refuses during `start` reports `{"status":"refused","error":<code>,"stage":<stage>}` and exits without registering an owner.
+  Stages are `package` (installed web assets or Agent profiles), `pi-agent-directory`, `pi-auth`, `pi-models` and `service`; stderr names the selected Pi source to fix.
+  `quarantined` with stage `pi-runtime` or `service` means the owner registered first; it keeps its fences for informed recovery.
+  Reports carry fixed codes and stages only, never paths, configuration bytes or OS error text.
+- The selected Pi agent directory must be a real directory owned by you with mode 0700; `auth.json` and `models.json` must be your own single-link regular files with mode 0600.
+  `models.json` may use only fields the pinned SDK supports.
+  `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.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Shared Pi task workspace: native terminal and WebUI, persistent service, checks and human review.",
   "license": "MIT",
   "type": "module",
@@ -71,12 +71,10 @@
     "postinstall": "node src/install-config.mjs",
     "pack:check": "node scripts/pack-check.mjs",
     "traceability:check": "node scripts/traceability-check.mjs",
-    "verify": "bun run check && bun run check:web && bun run build:web:check && bun run lint && bun run check:agents && bun run test && bun run test:web && bun run pack:check",
-    "verify:full": "bun run verify && bun run test:integration && bun run test:browser",
+    "verify": "bun run check && bun run check:web && bun run build:web:check && bun run lint && bun run check:agents && bun run test && bun run test:web && bun run test:browser && bun run pack:check",
     "check": "node scripts/check-syntax.mjs && bun scripts/build-operator.mjs --check && bun scripts/build-service.mjs --check && tsc --noEmit",
     "lint": "biome check . && rumdl check .",
-    "test": "vitest run --config test/fast.config.ts --reporter=dot",
-    "test:integration": "vitest run --config test/integration.config.ts --reporter=verbose",
+    "test": "vitest run --no-file-parallelism",
     "test:target": "vitest run",
     "check:agents": "node scripts/check-agents.mjs",
     "doctor": "node src/operator-cli.mjs doctor",
@@ -97,19 +95,15 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@earendil-works/pi-ai": "*",
-    "undici": "^8.9.0"
+    "@earendil-works/pi-ai": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
-    "@earendil-works/pi-coding-agent": "0.84.3",
     "@earendil-works/pi-tui": "0.84.3",
     "@types/node": "^22.15.3",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8",
-    "@earendil-works/pi-ai": "0.84.3",
-    "undici": "8.9.0",
     "@types/ws": "8.18.1",
     "react": "19.3.0",
     "react-dom": "19.3.0",
@@ -145,8 +139,13 @@
     "url": "https://github.com/abelxiaoxing/cadence/issues"
   },
   "dependencies": {
+    "undici": "8.9.0",
     "ws": "8.21.3"
   },
+  "optionalDependencies": {
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3"
+  },
   "bin": {
     "cadence-service": "./src/service-cli.mjs"
   }

package/src/install-config.mjs

@@ -1,3 +1,4 @@
+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";
@@ -40,6 +41,22 @@ 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"] },
+  );
+}
+
 if (
   process.argv[1] &&
   path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
@@ -54,4 +71,12 @@ 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

@@ -1,6 +1,10 @@
 /** Native attachment only. No SDK/auth resolution, worker or storage mutation. */
 
-import { Agent } from "undici";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Agent, Dispatcher1Wrapper } from "undici";
 import { nativeBuild } from "./native-build.ts";
 import { ServiceCoordination } from "./service/coordination.ts";
 import { ServiceClient } from "./service-client.ts";
@@ -10,10 +14,27 @@ import {
   type SessionBootstrap,
 } from "./service-contract.ts";
 import { HttpServiceTransport } from "./service-http-client.ts";
+import { effectiveWorkspace } from "./task-store.ts";
 
 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.";
 
+/** 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 one path only. */
+export function autostartHint(): string {
+  if (process.platform !== "linux") return "";
+  const data = process.env.XDG_DATA_HOME;
+  const unit = join(
+    data && isAbsolute(data) ? data : join(homedir(), ".local", "share"),
+    "systemd",
+    "user",
+    "cadence.service",
+  );
+  if (existsSync(unit)) return "";
+  const cli = fileURLToPath(new URL("./service-cli.mjs", import.meta.url));
+  return `\nTo run the shared service and WebUI (default http://127.0.0.1:17423) at login: node ${JSON.stringify(cli)} autostart install`;
+}
+
 export class NativeConnection {
   private transport?: HttpServiceTransport;
   private network?: Agent;
@@ -28,10 +49,17 @@ export class NativeConnection {
     // Failed detach keeps its exact transport/slot. Explicit re-entry may retry
     // detach, but never forget it and allocate a replacement on uncertainty.
     await this.detach();
-    const access = new ServiceCoordination(cwd).localAccess();
+    // Pi started in the home directory attaches to the ~/cadence landing owner,
+    // the same one the management client starts there. Observation only.
+    const access = new ServiceCoordination(
+      effectiveWorkspace(cwd).workspace,
+    ).localAccess();
     this.epoch = access.epoch;
     const network = new Agent();
     this.network = network;
+    // Node 22/24 built-in fetch bundles undici 6/7, whose legacy handlers an
+    // undici 8 Agent rejects. The public wrapper adapts them on every line.
+    const dispatcher = new Dispatcher1Wrapper(network);
     this.transport = new HttpServiceTransport({
       origin: access.endpoint,
       localCapability: access.capability,
@@ -43,7 +71,7 @@ export class NativeConnection {
       // process routes provider auth through a proxy. Public per-request Node
       // dispatcher only: never replace/restore the parent's global dispatcher.
       fetch: (url, init) =>
-        globalThis.fetch(url, Object.assign({}, init, { dispatcher: network })),
+        globalThis.fetch(url, Object.assign({}, init, { dispatcher })),
     });
     const client = new ServiceClient(this.transport);
     this.client = client;

package/src/operator-cli.mjs

@@ -136,11 +136,8 @@ function safeDirectory(path, create = false, inspectExisting) {
     at = join(at, part);
     let existing;
     try {
-      const st = lstatSync(at);
-      if (!st.isDirectory())
-        throw new Error("Unsafe directory");
       const checked = lstatSync(at);
-      if (checked.isSymbolicLink() || inspectExisting && !checked.isDirectory())
+      if (!checked.isDirectory() || checked.isSymbolicLink())
         throw new Error("Unsafe directory");
       existing = checked;
     } catch (error) {
@@ -154,7 +151,8 @@ function safeDirectory(path, create = false, inspectExisting) {
         if (!object(mkdirError) || mkdirError.code !== "EEXIST")
           throw mkdirError;
       }
-      if (!lstatSync(at).isDirectory() || lstatSync(at).isSymbolicLink())
+      const created = lstatSync(at);
+      if (!created.isDirectory() || created.isSymbolicLink())
         throw new Error("Unsafe directory");
     }
     if (existing)
@@ -162,13 +160,29 @@ function safeDirectory(path, create = false, inspectExisting) {
   }
   return true;
 }
-function readBounded(path, max) {
+var transientWindows = new Set(["EPERM", "EACCES", "EBUSY"]);
+function retryWindowsFileOperation(operation, recheck) {
+  if (process.platform !== "win32")
+    return operation();
+  const deadline = performance.now() + 2000;
+  for (let delay = 2;; delay = Math.min(delay * 2, 50)) {
+    try {
+      return operation();
+    } catch (error) {
+      if (!object(error) || !transientWindows.has(String(error.code)) || performance.now() >= deadline)
+        throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+      recheck?.();
+    }
+  }
+}
+function readBounded(path, max, packaged = false) {
   if (!safeDirectory(dirname(path)))
     return;
   let fd;
   try {
     const st = lstatSync(path);
-    if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || st.size > max)
+    if (!st.isFile() || st.isSymbolicLink() || !packaged && st.nlink !== 1 || st.size > max)
       throw new Error("Unsafe or oversized file");
     fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
   } catch (error) {
@@ -178,7 +192,7 @@ function readBounded(path, max) {
   }
   try {
     const st = fstatSync(fd);
-    if (!st.isFile() || st.nlink !== 1 || st.size > max)
+    if (!st.isFile() || !packaged && st.nlink !== 1 || st.size > max)
       throw new Error("Unsafe or oversized file");
     const buffer = Buffer.alloc(max + 1);
     let size = 0;
@@ -256,6 +270,23 @@ function canonicalAmbientRoot(path) {
     return join(canonicalAmbientRoot(parent), full.slice(parent.length));
   }
 }
+function privateRootFor(canonicalRoot, stateHome) {
+  return join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1", createHash("sha256").update(canonicalRoot).digest("hex"));
+}
+function contains(root, path) {
+  const within = relative(root, resolve(path));
+  return !within || !within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within);
+}
+function stateHomeInside(root, stateHome = defaultStateHome()) {
+  const canonical = realpathSync(root);
+  return contains(canonical, privateRootFor(canonical, stateHome));
+}
+var LANDING_WORKSPACE = "cadence";
+function effectiveWorkspace(requested, stateHome, home = homedir()) {
+  if (!stateHomeInside(resolveWorkspace(requested).root, stateHome))
+    return { workspace: requested, redirected: false };
+  return { workspace: join(home, LANDING_WORKSPACE), redirected: true };
+}
 
 class TaskStore {
   root;
@@ -264,9 +295,8 @@ class TaskStore {
   constructor(root, stateHome = defaultStateHome()) {
     this.root = realpathSync(root);
     this.tasks = join(this.root, ".cadence", "assistant", "tasks");
-    this.privateRoot = join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1", createHash("sha256").update(this.root).digest("hex"));
-    const within = relative(this.root, resolve(this.privateRoot));
-    if (!within || !within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within))
+    this.privateRoot = privateRootFor(this.root, stateHome);
+    if (contains(this.root, this.privateRoot))
       throw new Error("Private state home must be outside the working copy");
   }
   get lockPath() {
@@ -318,7 +348,7 @@ class TaskStore {
     };
     let fd;
     try {
-      fd = openSync(this.lockPath, "wx", 384);
+      fd = retryWindowsFileOperation(() => openSync(this.lockPath, "wx", 384));
     } catch {
       throw new Error("Checkout busy or unresolved lock; inspect and explicitly recover only a dead owner");
     }
@@ -338,7 +368,7 @@ class TaskStore {
     if (lock.pid !== process.pid || lock.host !== hostname())
       throw new Error("Only the owning process may release a lock");
     this.assertOwner(lock);
-    unlinkSync(this.lockPath);
+    retryWindowsFileOperation(() => unlinkSync(this.lockPath), () => this.assertOwner(lock));
   }
   recover(expected, acknowledgeEscapedProcesses) {
     if (!acknowledgeEscapedProcesses || expected.host !== hostname())
@@ -418,7 +448,12 @@ class TaskStore {
       const latest = readBounded(join(dir, "task.json"), MAX_RECORD_BYTES);
       if ((latest ? contentIdentity(latest) : undefined) !== expectedIdentity)
         throw new Error("Task content changed; replacement preserved without overwrite");
-      renameSync(temporary, join(dir, "task.json"));
+      retryWindowsFileOperation(() => renameSync(temporary, join(dir, "task.json")), () => {
+        this.assertOwner(lock);
+        const now = readBounded(join(dir, "task.json"), MAX_RECORD_BYTES);
+        if ((now ? contentIdentity(now) : undefined) !== expectedIdentity)
+          throw new Error("Task content changed; replacement preserved without overwrite");
+      });
       return next;
     } finally {
       if (!held)
@@ -459,8 +494,9 @@ class TaskStore {
 var TASK_CONFIG_SCHEMA = "cadence-assistant-checks/1";
 
 // src/operator-tools.ts
+var observed = (cwd) => resolveWorkspace(effectiveWorkspace(cwd).workspace);
 function inspectConsumer(cwd) {
-  const workspace = resolveWorkspace(cwd);
+  const workspace = observed(cwd);
   const store = new TaskStore(workspace.root);
   const tasks = store.list();
   const checks = store.checks();
@@ -481,7 +517,7 @@ function inspectConsumer(cwd) {
   };
 }
 function inspectRuns(cwd) {
-  const workspace = resolveWorkspace(cwd);
+  const workspace = observed(cwd);
   const store = new TaskStore(workspace.root);
   return {
     ok: true,