@abelxiaoxing/cadence 2.0.1 → 2.0.3

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,23 @@ 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.
+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.
@@ -54,6 +64,27 @@ Return, session departure and Pi quit **detach; admitted work continues** while
 Reattach to observe the same IDs without replay.
 Explicit Cancel requests bounded stop; it is not proof that every escaped descendant stopped.
 
+### Background agent panel
+
+A readonly panel in the Pi TUI follows background agents: the child runs of Cadence's running owner and any agents another extension announces on Pi's shared event bus.
+Every TUI session, not only `/cadence`, looks for the owner already running for its workspace half a second after start and every 15s while none answers; it never starts, recovers or selects one, skips an incompatible owner and only detaches on departure.
+That observation holds one of the owner's viewer attachments, so departure (including Pi quit) waits up to 1.5s for the detach to reach the owner rather than leaving the slot to its idle expiry; `/cadence` departs the same way.
+`CADENCE_AGENT_PANEL=off` turns that observation off.
+It reads the active roster every 5s, and every 2s together with the task's snapshot while it follows an episode, announcing each child of the active episodes: its assignment ID as label, purpose as kind, lifecycle or latest tool as activity, and completed, canceled or any other outcome (with its reason) as done, cancelled or error.
+A child whose outcome the session can no longer observe (no compatible owner a whole retry after losing it, or no settled row five looks after its run left the roster) ends as an error that says so; `/cadence` History keeps the actual outcome.
+Elapsed time counts from when the session first observed a child (`—` for one first seen settled); no tokens are shown because the owner records no usage.
+Opening a child reads its retained messages, tool calls and results through the history readers, up to 64KiB per field; complete fields, search and export stay in `/cadence` History.
+A retained `edit` call shows its call and result without Pi's diff preview, which would compare against the file as it is now.
+Producers emit `subagent:start {id,label,kind,startedAt}`, `subagent:message {id,message,streaming?}`, `subagent:activity {id,activity,tokensIn?,tokensOut?}`, `subagent:stats {id,tokensIn,tokensOut?}` and `subagent:end {id,status,endedAt,error?}` with status `done`, `error` or `cancelled`; `startedAt: null` marks an unobserved start.
+A message has the main session's message shape; `streaming: true` marks a snapshot that the next message replaces.
+The panel emits `subagent:view {id}` (`id: null` when none) so a producer loads only the shown agent's messages.
+Nothing is mounted until the first agent arrives (`CADENCE_AGENT_PANEL=always` keeps `● main` visible).
+Then a launched/finished block sits above the input and one row per agent below it: at most six recently active rows plus `+K more`.
+With an empty input, ↓ moves focus to the rows; ↑/↓ or Ctrl+P/N select, Enter shows that agent's transcript in place of the main view, PgUp/PgDn, Ctrl+U/D and Home/End scroll it, and Esc returns to the main view and then to the input.
+Every other input key, including Enter, Shift+Tab and Ctrl+J, stays Pi's; each agent view remembers its scroll position.
+The panel never starts, cancels or keeps an agent or Pi alive, and keeps nothing across restarts.
+For manual checks, `pi -e ./src/index.ts -e ./scripts/agent-panel-demo.ts` adds `/agents-demo [count]`, which plays fake agents (the second fails) and runs nothing.
+
 ### Browser
 
 Open the locally revealed token link.
@@ -63,6 +94,7 @@ A token grants workspace access, not action consent.
 Every mutation needs its own context-bound preview/confirmation; stale/duplicate/lost replies do not silently replay work.
 The WebUI provides task/run/assignment navigation, long retained messages and tool detail, exact literal search, timeline and complete scoped NDJSON/Markdown downloads.
 Desktop panes and phone drawers retain cancellation and keyboard controls.
+Its chrome follows pi-web-ui: a compact topbar with view tabs and icon actions, a sectioned task sidebar, pill inspector tabs, transcript/tool cards and a bottom statusbar; phones wrap the topbar into an action row and an icon tab row.
 
 ## Execution, checks and review
 
@@ -108,30 +140,27 @@ 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 is the sole postinstall behavior; no service/build/Git/provider operation runs.
+  Missing-only user `.env` template creation and the Linux autostart refresh above are the only postinstall behaviors; 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
 
 ```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.
+Build/verification use a fresh private directory with `TMPDIR`, `TEMP` and `TMP` set explicitly, on the checkout's disk filesystem rather than a nearly full tmpfs.
+`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.
+It needs a Node with TypeScript type stripping (official builds; a distro Node built without it fails `build:web:check`) and NSS `certutil` for the isolated HTTPS browser scenario.
 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 +178,8 @@ 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/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/{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 +216,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 +240,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 +267,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 +315,23 @@ 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             |
+| Install hook cannot prompt and npm hides its output            | Only a first registration tries passwordless linger; the startup card names the gap |
 
 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,10 +345,11 @@ 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.
-On this development host create fresh0700 disk roots under `/home/mirako/abel` and explicitly set TMPDIR/TEMP/TMP; `/tmp` is inode-exhausted.
+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.
+`bun run test` runs unit files in parallel, then `serialProcessFiles` (real PTY/SDK process flows) and `serialScanFiles` (>8MiB cold scans) from `vitest.config.ts` one at a time; a file belongs there only when it measurably exceeds its own waits under shared CPU.
+Create a fresh 0700 root on the checkout's disk filesystem and explicitly set TMPDIR/TEMP/TMP to it; a nearly full tmpfs `/tmp` makes owners refuse at their free-space floor (`receipt-inconclusive`) and `web/dist` publication fail with EXDEV.
+A test waits for the event it needs (both providers contacted, a row settled), not a wall-clock guess at how long process starts take; fixed waits stay only where time is the contract.
 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.
 Preserve failed attempts; correct a demonstrated cause before rerunning, and never assign old failures a retrospective cause without evidence.
@@ -315,14 +362,27 @@ Regression owners:
 - `worker-*`, `lightweight-sdk`, `lightweight-process-diff`: genuine SDK/tool capture, split redaction, no-spill bounds and original native facts.
 - `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.
+- `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 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.
+Publish `web/dist` from Node: Vite run under Bun lays out its preload helper differently, so a Bun build fails a Node `build:web:check`.
 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.
 
+### Release 2.0.3 acceptance snapshot
+
+Full `verify` passed on `c27b8ca`: 1924 root tests in 78 files (27 Windows-only controls skipped on Linux), 111 web tests in 8 files, 5 real-browser scenarios in 3 files and the 132-member real pack audit.
+Observed environment: Linux x86_64, official Node 22.22.1, Bun 1.3.14, the pinned Pi SDK 0.84.3 and Chrome for Testing 153.0.8010.12; later commits change only tests and this section.
+The GitHub matrix (Windows and Ubuntu × Node 22/24 × `parallel`, `serial-process`, `serial-scan`) runs on the separate CI branch.
+A real Pi 1.4.0 user-scope install of the packed candidate, installed into Pi's own npm layout, registered and enabled the unit, enabled linger without a prompt and, on upgrade, stopped the old owner in order before starting the new one.
+That owner started with the agent directory Pi had created at 0775 and served the built WebUI to Chromium at 1440, 390 and 320px widths.
+No model-backed task ran there (no Pi provider login); macOS, physical phones, paid accounts and every adapter, and a second machine remain unqualified.
+
 ### Prior integrated acceptance snapshot
 
 Before removal of development-workflow tooling, the integrated redesign passed full `verify`:1839 root tests/69 files,110 web tests/8 files and5 real-browser scenarios/3 files, with27 existing Windows-only controls skipped on Linux.

package/docs/reuse-and-distribution.md

@@ -8,7 +8,7 @@ Repository `provenance/webui-reuse.json` records source/destination hashes and e
 
 | Source family                        | Package adaptation                                                       |
 | ------------------------------------ | ------------------------------------------------------------------------ |
-| App, panels, layout, drawers         | Three-pane task workspace and responsive phone navigation                |
+| App, TopBar, panels, layout, drawers | Three-pane workspace, pi topbar/statusbar chrome and phone navigation    |
 | conv-groups, PlanBoard               | Task/run/child tree, editable finite graph and separate confirmations    |
 | MessageList, Message, ToolCallBlock  | Paged transcript, stable tool associations and retained detail           |
 | Markdown, StreamMarkdown, copy       | Sanitized Markdown/math/code, no script/external-image execution         |
@@ -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,58 @@ 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.
+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.
+
+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.
+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`.
+
+```sh
+cadence-service autostart install [--workspace /absolute/project] [--linger]
+cadence-service autostart status
+cadence-service autostart remove
+```
+
+`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`.
 
 ## Status, departure and Stop
 
@@ -34,6 +85,14 @@ 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 (not a symlink) owned by you; `auth.json` and `models.json` must be your own single-link regular files.
+  Their mode bits are not checked: Pi creates its agent directory with your umask (0755, or 0775 under umask 002), and Cadence's own state stays 0700 regardless.
+  `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.1",
+  "version": "2.0.3",
   "description": "Shared Pi task workspace: native terminal and WebUI, persistent service, checks and human review.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,9 @@
     "skills",
     "config",
     "agents",
+    "src/agent-panel-cadence.ts",
+    "src/agent-panel-model.ts",
+    "src/agent-panel.ts",
     "src/index.ts",
     "src/install-config.mjs",
     "src/native-build.ts",
@@ -71,12 +74,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",
     "test:target": "vitest run",
     "check:agents": "node scripts/check-agents.mjs",
     "doctor": "node src/operator-cli.mjs doctor",
@@ -101,13 +102,11 @@
   },
   "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",
     "@types/ws": "8.18.1",
     "react": "19.3.0",
     "react-dom": "19.3.0",
@@ -146,6 +145,10 @@
     "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"
   }