@abelxiaoxing/cadence 2.0.9 → 2.0.11

package/README.md

@@ -36,13 +36,15 @@ The token admits anyone who has it to the workspace, so keep the file and the li
 To change either, edit the line and run `cadence server restart`, which prints the new link; old links and browser cookies stop working.
 A workspace that an earlier version started with a generated token switches to the file at that restart and keeps its history.
 
-| Platform | Service                                                                                     | Starts                                       |
-| -------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| 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.
+| Platform     | Service                                                                                   | Starts                                |
+| ------------ | ----------------------------------------------------------------------------------------- | ------------------------------------- |
+| Linux (root) | System unit `/etc/systemd/system/cadence.service`                                         | At boot, no linger                    |
+| Linux (user) | 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, root defaults to `--system` and never uses linger; ordinary accounts default to `--user`.
+In user scope, 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.
 
@@ -54,7 +56,7 @@ cadence server uninstall   # before npm uninstall -g, which runs no Cadence scri
 ```
 
 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.
+Restart, stop and uninstall go through the authenticated orderly Stop, so running work is stopped, not detached; system/root, macOS and Windows management refuse to signal or replace a service when its Stop is not confirmed.
 `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.
 
@@ -138,6 +140,32 @@ Its chrome follows pi-web-ui: a compact topbar with view tabs and icon actions,
 The interface is in English or Simplified Chinese: it follows the browser's first preferred language, and the topbar's globe chip (`中文` / `EN`) switches it, remembered only in that browser.
 Error codes, identifiers, commands and recorded content stay untranslated.
 
+### Root services and independent projects
+
+Linux can run Cadence as a system-level root service, without a user bus or linger:
+
+```sh
+sudo -H cadence server install --system --workspace /srv/project
+sudo -H cadence server status --system
+```
+
+Root defaults to `--system`; an ordinary account still defaults to `--user`, which retains the existing linger behavior.
+There is no automatic sudo or credential/profile copying: the root owner uses root's own Pi sources and private state, and has full host permissions, not a sandbox.
+Stop old owners before changing accounts or state homes; a different account's private namespace cannot coordinate the former owner's work.
+
+Open another existing folder explicitly, or create a new project directory:
+
+```sh
+cadence project open /absolute/project
+cadence project open /absolute/new-project --create
+```
+
+A new project selects an available loopback port once; reopening keeps its exact owner, port, cwd and history.
+The command prints its private WebUI entry link; it does not create a task, choose a model or Start execution, and existing projects' admitted work continues.
+Each project has its own WebUI entry and native `/cadence` attachment, not a global mutable cwd or a same-page cross-project router.
+For independent boot services, use `cadence server install --system --name api --workspace /srv/api --port 17424` as root, and manage it with the same `--system --name api` flags.
+See [service management](docs/service-management.md) for migration, named port/token files and limits.
+
 ## Execution, checks and review
 
 - Graphs contain 1–16 required assignments with explicit purposes/dependencies and exact model choice; no recursive spawning or autonomous retry.
@@ -217,22 +245,22 @@ Historical logs are not runtime dependencies, and removing development tooling m
 
 ### Source ownership and API boundaries
 
-| 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/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,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             |
-| `src/worker-public.mjs` and `.d.mts`, `src/service-contract.ts`                                        | One portable core/domain/capture codec with matching declarations and facade; TS core/domain/capture modules re-export it |
-| `src/service/contracts/`, `src/service-client.ts`, `src/service-wire.ts`, `src/service-http-client.ts` | Closed DTOs, typed named operations, reply correlation, transport bounds and one projection tracker                       |
-| `src/subagent-process.ts`, `src/sdk-worker.mjs`, `src/worker-{capture,redaction,tools}.mjs`            | Same native worker/check launcher, genuine SDK capture, incremental sanitizer and bounded no-raw-spill bash adapter       |
-| `src/history/{writer,run-state,publication}.ts`                                                        | One committed sequence authority, shared semantic reducers and expected-byte strict-v1 summaries                          |
-| `src/history/` readers/proof/search/export/live modules                                                | Original-source integrity, bounded retained navigation, exact search and complete nonblocking exports                     |
-| `src/task-store.ts`, `src/task-types.ts`, `src/task-diff.ts`                                           | Literal workspace identity, bounded plain summaries/configuration and honest change observation                           |
-| `web/src/`                                                                                             | Reused presentation and thin shared-client adapters, not SDK/session/execution ownership                                  |
-| `scripts/`, `provenance/`, `licenses/`                                                                 | Reproducible builds, exact package/body/reference/notice audits and pinned reuse                                          |
+| 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/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,system-service,launchd,login-run}.ts` | Single-owner composition, explicit project launch and generated system/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              |
+| `src/worker-public.mjs` and `.d.mts`, `src/service-contract.ts`                                            | One portable core/domain/capture codec with matching declarations and facade; TS core/domain/capture modules re-export it  |
+| `src/service/contracts/`, `src/service-client.ts`, `src/service-wire.ts`, `src/service-http-client.ts`     | Closed DTOs, typed named operations, reply correlation, transport bounds and one projection tracker                        |
+| `src/subagent-process.ts`, `src/sdk-worker.mjs`, `src/worker-{capture,redaction,tools}.mjs`                | Same native worker/check launcher, genuine SDK capture, incremental sanitizer and bounded no-raw-spill bash adapter        |
+| `src/history/{writer,run-state,publication}.ts`                                                            | One committed sequence authority, shared semantic reducers and expected-byte strict-v1 summaries                           |
+| `src/history/` readers/proof/search/export/live modules                                                    | Original-source integrity, bounded retained navigation, exact search and complete nonblocking exports                      |
+| `src/task-store.ts`, `src/task-types.ts`, `src/task-diff.ts`                                               | Literal workspace identity, bounded plain summaries/configuration and honest change observation                            |
+| `web/src/`                                                                                                 | Reused presentation and thin shared-client adapters, not SDK/session/execution ownership                                   |
+| `scripts/`, `provenance/`, `licenses/`                                                                     | Reproducible builds, exact package/body/reference/notice audits and pinned reuse                                           |
 
 The native path is `index → shell → native client → service → scheduler/process/history`.
 `src/task-controller.ts` remains a legacy regression subject, not a reachable or shipped production executor.
@@ -245,6 +273,11 @@ Use their current declarations rather than copying DTO parsing, reducers, a seco
 ### Admission, execution and original lifetimes
 
 - One canonical checkout/state-home domain has one persistent owner, including while idle.
+  Explicit project launch uses a new port only for a new checkout selection; reopened projects retain exact cwd/port/history, and no project navigation changes another owner's execution.
+  Root Git observations require Git's own ownership check: reset `safe.directory` exceptions per command, drop inherited `SUDO_UID` and disable fsmonitor, without configuration writes or ownership changes.
+  Merely selecting a foreign-owned repository cannot grant permission to run its clean/process filters; use its owning account instead.
+  Ordinary-user Git trust behavior remains unchanged.
+  System services require uid0, bypass user managers/logind entirely and require confirmed native Stop before manager stop or definition replacement; changed state-home inputs, old user units and detached running owners refuse implicit adoption.
   Registry reservation atomically rejects canonical ancestor/descendant overlaps, including nested Git roots and aliases; a different state-home does not coordinate arbitrary other owners.
 - Native entry requires fresh raw Enter within1500ms, trusted/idle TUI, no pending modal/messages and no child guard.
   Browser authentication grants access, not task consent; normal mutation ingress also requires independently built compatible client/service/assets identities.
@@ -302,6 +335,8 @@ Never await a run's own settlement from inside its awaited subscriber.
 Sanitize known literals, structured sensitive values and terminal controls before stdout and again before owner persistence.
 Preserve split UTF-8, escaped literals, surrogate pairs and possible secret prefixes across chunks; independent per-chunk string replacement is insufficient.
 Tool-start is an SDK observation, not proof of native execution; tool error is not a parent check result.
+A prompt/preflight/non-success terminal response is labeled `worker-failure: prompt`, not `capture`; the recorded message stop reason, actual exit and cleanup facts stay independent.
+A browser settlement timeout must retain its last receipt/active-roster facts before fixture teardown: a later Stop and its uncertain publication are not evidence that capture caused the original wait failure.
 Hidden thinking, signatures, provider envelopes and binary/media bodies remain explicitly omitted.
 Known-secret sanitation is not universal business-secret detection or an OS privacy sandbox.
 
@@ -309,6 +344,9 @@ 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.
+Live task/run/child views share an already observed containing snapshot only within one notification drain, retaining its exact context and committed watermark.
+Narrowing requires the requested parent/child to be present; a historical run outside the task horizon still takes its independent reader, and no observation is cached into the next drain or used as renewed action consent.
+Transient reuse keeps at most one page-sized source per viewer, rather than retaining every unobserved run ring.
 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.
@@ -379,6 +417,7 @@ Byte values are UTF-8/encoded bounds where specified; they are not targets to si
 | Token source the user edits (`CADENCE_TOKEN` in `.env`)        | Read once before binding, never bound for the run: an edit cannot fence Stop        |
 | Saved port/token source differs from `.env`                    | Only when stopped, reselect just those under the reservation; running ones refuse   |
 | User-made `.env` (0755/0644, umask 002, dotfiles links)        | Like Pi's sources: ownership only, links followed; each refusal names its reason    |
+| Credential value inside a provider/model ID (Ollama `ollama`)  | Withhold and count only that catalog entry; choosing it refuses; others selectable  |
 
 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.
@@ -395,6 +434,8 @@ Read affected source and adjacent tests, identify the actual owner of a contract
 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.
+`vitest run --config test/fast.config.ts` selects only its reviewed short-test allowlist, without inheriting root projects; `test/integration.config.ts` selects the exact complement and retains the serial projects.
+`test/test-selection.test.ts` compares the runner's actual file discovery across all three configurations, rejecting duplicates, overlap, omissions and moved serial files; new tests belong to integration until explicitly promoted.
 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.
@@ -412,18 +453,44 @@ Regression owners:
 - `agent-panel`, `agent-panel-model`, `agent-panel-cadence`: panel keys/rendering and readonly owner observation that never starts, cancels or replays work.
 - `test/web/`: adapted pure/SSR tests separately from actual built-browser contexts, HTTPS, mixed clients, focus/viewports and complete downloads.
 - `package-*`, `distribution`, `service-package`, `independence`: exact tar/member/body/import/notice closure and nonactivating discovery.
-- `service-autostart`, `install-config`: explicit `cadence server` registration on systemd, launchd and the Windows Run key, definition escaping, restart/disable/mask/foreign handling, orderly Stop before every change, the `.env` port and token lines and a package without install scripts.
+- `service-autostart`, `project-start`, `install-config`: explicit `cadence server` registration on systemd (root system scope without linger, legacy user scope), launchd and the Windows Run key, separate named service definitions and directory owners, definition escaping, restart/disable/mask/foreign handling, orderly Stop before every change, the `.env` port and token lines and a package without install scripts.
 - `service-cli`: real owners started from the `.env` port and token, reselection of a stopped workspace, edits while running and rotation of the token line.
 - `workspace-landing`: home-directory redirection to `~/cadence` across management, native attach and observation.
 
 Regenerate operator/service/native/browser outputs only through their canonical builders; `--check` variants compare new private output without overwriting canonical bytes.
 WebUI text is keyed by its English source: fixed text goes through `useT().t`, whose type requires a `web/src/i18n/zh.ts` entry with the same `{name}` marks, and run-time status words or kept notices through `tx`, which passes unknown text and codes through.
 The timeline client takes the chosen language from its bridge and is remounted on a switch; browser scenarios pin `locale: "en-US"` so English assertions do not follow the host's `LANG`.
+The browser is conversation-first: the left panel groups the current service project, the actual active roster and retained task conversations, with run/subagent children under their task.
+One service still exposes one checkout; the project section is not a cross-project registry, Pi session importer or cwd switcher.
+The center shows retained message text as Markdown by default; tools/context/timeline/run facts and export/link actions live under Details, while the collapsible right inspector remains bound to the task's current plan/check/change/review context even when viewing a child.
+Historical child links bind exact scope and watermark.
+Bounded history and Back never silently rebase; running conversations offer an explicit new-activity update, and source limitations/progress stay visible even when complete-record metadata is folded.
+Cancel uses the independent active roster (including the fallback strip when workspace discovery fails); navigation, project selection and hiding panels never cancel or authorize execution.
+
 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 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.11 acceptance snapshot
+
+Full `verify` passed on the 2.0.11 release candidate before this evidence-only paragraph: 1976 root tests in 80 files (27 skipped on Linux), 122 web tests, 5 real-browser scenarios and the 132-member pack audit.
+Observed environment: Linux x86_64, Node26.7.0, Bun1.3.14, Pi SDK0.84.3 and existing Chrome for Testing151.0.7922.34.
+The root Git regressions use real Git with simulated ownership mismatch, and system service management uses isolated filesystem/manager adapters; no real root/systemd installation, new CI matrix, macOS or Windows qualification is claimed.
+
+This release adds explicit directory project launch and independent named Linux system/root services, and a conversation-first WebUI with retained task/run/subagent navigation.
+Root observation no longer automatically trusts foreign Git repositories; inactive service definitions cannot stop or adopt detached owners, including through restart or uninstall.
+Fast/integration test selection is checked against actual Vitest discovery, and provider prompt failures remain separate from capture failures.
+Live task/run/child views reuse only an already observed containing snapshot within one notification drain, never a previous round's action context.
+
+### Release 2.0.10 acceptance snapshot
+
+Full `verify` passed on the 2.0.10 release tree (`4843334` plus the version bump), in the 2.0.3 environment below.
+It ran 1949 root tests in 78 files (27 Windows-only controls skipped on Linux), 116 web tests, 5 real-browser scenarios and the 132-member pack audit, and CI 40278386880 passed 12/12 on the candidate `3cd94f4` (this commit before its snapshot).
+That CI run's first Windows Node 22 `parallel` attempt failed only `workspace-landing`'s cleanup (EBUSY removing the just-stopped landing workspace), as in 2.0.6's first run; the job passed when rerun.
+The fix answers a 2.0.9 report: an Ollama `"apiKey": "ollama"` under a provider named `ollama` made the whole model catalog refuse `unsupported-context`.
+An isolated owner with that `models.json` beside a second provider reproduced the refusal on 2.0.9; on 2.0.10 Chromium listed the second provider's models and explained the one withheld entry in English and Chinese.
+
 ### Release 2.0.9 acceptance snapshot
 
 Full `verify` passed on the 2.0.9 release tree (`0e720a1` plus the version bump), in the 2.0.3 environment below.

package/docs/reuse-and-distribution.md

@@ -8,9 +8,9 @@ Repository `provenance/webui-reuse.json` records source/destination hashes and e
 
 | Source family                        | Package adaptation                                                       |
 | ------------------------------------ | ------------------------------------------------------------------------ |
-| 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           |
+| App, TopBar, panels, layout, drawers | Conversation-first workspace, project/session sidebar and phone drawers  |
+| conv-groups, PlanBoard               | Active/history task and subagent tree, finite graph and explicit consent |
+| MessageList, Message, ToolCallBlock  | Default Markdown transcript, folded metadata and bounded retained detail |
 | Markdown, StreamMarkdown, copy       | Sanitized Markdown/math/code, no script/external-image execution         |
 | FilePreview, SCM presentation        | Readonly observed changes, no Git/file mutation API                      |
 | GlobalSearchModal, search, deep link | Literal durable search, exact versioned hits and scoped export           |

package/docs/service-management.md

@@ -23,12 +23,41 @@ 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.
+A directory inside `cadence-assistant-v1` is never an engineering workspace, even for root or `project open --create`.
 Apart from the background service below, there is no supervisor installation, provider login or credential migration.
 
+## Open a project directory
+
+```sh
+cadence project open /absolute/existing-project
+cadence project open /absolute/new-project --create
+# Optional explicit sources, without copying them:
+cadence project open /srv/project --agent-dir /root/.pi/agent --state-home /root/.local/state
+```
+
+Without a path, `project open` uses the current directory; a missing directory refuses unless `--create` was supplied.
+The project may be a Git checkout or an ordinary directory, including spaces and Unicode names; it need not be inside `~/cadence` or the package directory.
+The command explicitly starts a detached owner, or observes the already running exact owner; it never creates a task, chooses a model, renews a grant or starts a worker.
+New projects bind port0 and retain the resulting positive port, avoiding the default17423 collision; existing selections keep their exact port, cwd, agent sources and history.
+The JSON result reports the canonical workspace, actual task cwd and endpoint; the private entry link is printed separately to stderr, like `server install`.
+Keep that link private.
+Open Pi in the same project and use `/cadence` for the native client; explicit `cadence stop --workspace <path>` stops only that project.
+Opening another project never changes the cwd or cancels work in the former one.
+Each project has its own browser entry and owner; this is not a same-page cross-project browser router.
+Git subdirectories and aliases resolve to the same checkout, while overlapping parent/child owners still refuse.
+An unknown, quarantined or inaccessible selection is never treated as a new project or recovered by choosing another state home.
+
+When run as root, Git observation requires a repository Git recognizes as root-owned: Cadence clears `safe.directory` exceptions per command, removes inherited `SUDO_UID` and disables fsmonitor.
+A foreign-owned repository refuses even if a global `safe.directory=*` would allow it; selecting a path is not consent to execute its configured clean/process filters.
+Use the repository's owning account instead, or deliberately provision a root-owned checkout outside Cadence; no Git configuration edit, `chown`, credential import or permission reset is performed.
+Ordinary-user Git trust behavior remains intact.
+Trusted repositories can still carry executable Git configuration; root is not an isolation or sandbox guarantee.
+Changing to root changes the effective account and its private namespace: stop all old Cadence owners before doing so, since different accounts/state homes do not coordinate each other's original work.
+
 ## Background service
 
 ```sh
-cadence server install [--workspace /absolute/project] [--no-linger]
+cadence server install [--workspace /absolute/project] [--system|--user] [--no-linger]
 cadence server status
 cadence server restart
 cadence server stop
@@ -37,6 +66,11 @@ cadence server uninstall
 
 Only these explicit commands register, change or remove the service; no package install, update hook, `/cadence` or browser visit does.
 The package has no install script, so npm 12 and Bun skipping untrusted scripts by default changes nothing; the pinned Pi SDK's blocked `@google/genai` preinstall only echoes `no-op`, and its `protobufjs` postinstall only warns about version schemes.
+Linux server commands accept `--system` or `--user` after the action; root defaults to system scope and other accounts to user scope.
+`--system` requires root and never runs sudo itself; `--user` explicitly selects the legacy per-user manager, even when invoked by root.
+Linux also accepts `--name <name>` on every server command to select `cadence-<name>.service`, and `install` accepts `--port <1-65535>` for a missing port setting.
+Names must start with a letter or digit and contain only letters, digits, `_` and `-` (at most48characters).
+
 `install` also creates the research template `~/.pi/agent/cadence/.env` when it is missing, never overwriting it, whatever the service result, and adds its [port and token](#port-and-token) lines when they are missing.
 `install` works from any package location and runs `start --foreground --workspace <workspace> --server-config <file>` (Linux, macOS) or the same without `--foreground` (Windows) from that copy with the installing Node, without `--port`.
 The workspace is `~/cadence` (created if missing), an existing absolute `--workspace`, or on later installs the one the definition already runs; a workspace containing the service's state home lands on `~/cadence` with a note.
@@ -51,7 +85,7 @@ A definition Cadence did not generate is left unchanged (`foreign`), and `status
 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.
-`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`.
+`install` therefore writes no service definition 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.
@@ -88,9 +122,53 @@ Under the new owner reservation Cadence retires the previous token with a new ac
 A different agent directory, host or proxy still conflicts, and a running owner refuses until it has stopped.
 An interrupted replacement keeps the reservation as a fence and is never repaired automatically, like any interrupted start.
 
+### Linux systemd system/root unit (no linger)
+
+```sh
+# Root must already have its own usable Pi credentials and SDK installation.
+sudo -H cadence server install --system --workspace /srv/project
+sudo -H cadence server status --system
+sudo -H cadence server restart --system
+sudo -H cadence server stop --system
+sudo -H cadence server uninstall --system
+```
+
+Use an absolute Node and package CLI path with `sudo -H` if `cadence` is not on root's PATH.
+These commands generate `/etc/systemd/system/cadence.service` with `User=root` and `WantedBy=multi-user.target`, and use `systemctl --system`.
+They never consult or change linger, require no logged-in user manager and start at boot independently of root login.
+The definition freezes HOME, PATH, LANG/LC_ALL, an explicit XDG_STATE_HOME and custom PI_CODING_AGENT_DIR; root must own its selected Pi sources, and no normal-user profile or credentials are copied.
+Root runs the agent and approved checks with full root privileges: browser authentication remains access, not permission to Start, and this is not a sandbox.
+Status and install output identify system scope; Pi's root startup hint recommends `--system`, never `loginctl enable-linger`.
+
+A prior user-scope definition of the same name causes `scope-conflict`, never automatic migration.
+For a root account's older user unit, explicitly run `cadence server uninstall --user` first, then install `--system`; this preserves its workspace, private history, credentials and linger setting.
+For another account's service, first stop/uninstall it as that account; root must not silently import its private state or assume its owners are absent.
+A detached owner already running in the target directory causes `project-running`; stop it explicitly before installing a different supervisor.
+An old but inactive unit does not own a subsequently detached owner: install, restart, stop and uninstall also refuse in that case, without sending Stop to it, and changing the requested target does not bypass the old directory's check.
+An unconfirmed or quarantined Stop, changed generated file, changed HOME/XDG state selection, a mask or a foreign unit prevents replacement/adoption.
+`restart`, `stop` and `uninstall` await the authenticated original owner Stop before invoking systemctl, so manager timeouts are never used as proof of settlement.
+Restart keeps disablement and does not unmask anything; uninstall removes only the generated definition, never data or linger.
+Direct systemctl shutdown still has the unit's ExecStop and timeout behavior described below; it is not an alternative recovery mechanism.
+
+### Independent named Linux services
+
+```sh
+sudo -H cadence server install --system --name api --workspace /srv/api --port 17424
+sudo -H cadence server install --system --name web --workspace /srv/web --port 17425
+sudo -H cadence server status --system --name api
+sudo -H cadence server restart --system --name web
+```
+
+The units, ports, access tokens, working directories and owner lifetimes are separate; restarting or stopping one does not touch another.
+A named service uses `~/.pi/agent/cadence/servers/<name>.env` under its effective account, never a copy of the default token or research/provider configuration.
+A new named configuration requires `--port`; existing port/token lines are preserved, and a conflicting `--port` refuses instead of rewriting them.
+Edit the selected named file explicitly and restart that same `--name` to change its port.
+An occupied port still refuses rather than silently falling back; use `project open` when an automatically selected detached port is preferable.
+All projects still share one coordination state home for their account, retaining canonical overlap checks and uncertain fences.
+
 ### 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.
+`install --user` 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.
@@ -152,6 +230,9 @@ At sign-out or shutdown Windows ends the owner without orderly Stop, which can l
   `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.
   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.
+  A model whose provider or model ID contains a known credential value is withheld from the catalog, since showing the ID would reveal that value; the catalog says how many models are withheld, and the rest stay selectable.
+  Credential values are `auth.json` keys, `models.json` `apiKey` and header values (and the variables they name) and service-environment variables whose names contain `KEY`, `TOKEN`, `SECRET`, `PASS`, `AUTH` or `COOKIE`.
+  The common Ollama placeholder `"apiKey": "ollama"` under a provider named `ollama` is such a case: give the placeholder a value that matches no provider or model ID (for example `"local-no-auth"`), then restart the service.
   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 (`cadence server restart`, or `stop` then `start`), then choose the owner model again.
 - A foreground owner can be managed from another terminal.

package/package.json

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

package/src/native-build.ts

@@ -2,5 +2,5 @@
 export const nativeBuild = {
   kind: "native",
   contractHash:
-    "ff017feffc6b6b4521e470d82514d0ca008e15472fa1442ec498b243b0f7cf87",
+    "c2bb81519387005a71e88a64364dff47d5c39dab17812833ca898bc51055e59d",
 } as const;

package/src/native-client.ts

@@ -32,12 +32,14 @@ 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,
-          )
+        ? o.uid === 0
+          ? join(o.systemUnitDirectory ?? "/etc/systemd/system", UNIT)
+          : 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`);
@@ -52,11 +54,11 @@ function definition(o: AutostartObservation): string | undefined {
   }
 }
 const bootStart = (o: AutostartObservation) =>
-  o.platform === "linux" && o.env.CADENCE_LINGER !== "0";
+  o.platform === "linux" && (o.uid === 0 || 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" : ""}`;
+  `${piUserCopy(o) ? `node ${JSON.stringify(join(o.root, "src", "service-cli.mjs"))}` : "cadence"} server install${o.platform === "linux" && o.uid === 0 ? " --system" : o.platform === "linux" && o.env.CADENCE_LINGER === "0" ? " --no-linger" : ""}`;
 
 /** Name the explicit command while no background service is registered.
  * Reads paths only. */
@@ -78,6 +80,9 @@ export interface AutostartObservation {
   lingerFile: string;
   /** Exists only on a systemd-booted machine. */
   systemd: string;
+  uid?: number;
+  /** Only supplied by readonly observation tests. */
+  systemUnitDirectory?: string;
 }
 function hostObservation(): AutostartObservation {
   let user = "";
@@ -93,6 +98,7 @@ function hostObservation(): AutostartObservation {
     root: fileURLToPath(new URL("..", import.meta.url)),
     lingerFile: user ? join("/var/lib/systemd/linger", user) : "",
     systemd: SYSTEMD_BOOTED,
+    uid: process.getuid?.(),
   };
 }
 /** Same selection as Pi's getAgentDir: PI_CODING_AGENT_DIR or ~/.pi/agent. */
@@ -139,7 +145,7 @@ export function autostartNotice(
     return installedCopy(o)
       ? `Cadence服务：后台服务未安装，WebUI（默认 http://127.0.0.1:17423）不会运行。安装并${bootStart(o) ? "开机" : "登录后"}自启：${installCommand(o)}`
       : undefined;
-  if (o.platform !== "linux") return;
+  if (o.platform !== "linux" || o.uid === 0) 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;

package/src/operator-cli.mjs

@@ -210,15 +210,19 @@ function readBounded(path, max, packaged = false) {
   }
 }
 function gitEnvironment() {
+  const root = process.getuid?.() === 0;
   return {
-    ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_"))),
+    ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_") && !(root && name === "SUDO_UID"))),
     GIT_OPTIONAL_LOCKS: "0",
     LC_ALL: "C"
   };
 }
+function gitArguments(args) {
+  return process.platform !== "win32" && process.getuid?.() === 0 ? ["-c", "safe.directory=", "-c", "core.fsmonitor=false", ...args] : args;
+}
 function resolveWorkspace(cwd) {
   const actual = realpathSync(cwd);
-  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+  const result = spawnSync("git", gitArguments(["rev-parse", "--show-toplevel"]), {
     cwd: actual,
     env: gitEnvironment(),
     encoding: "utf8",
@@ -281,8 +285,13 @@ function stateHomeInside(root, stateHome = defaultStateHome()) {
   const canonical = realpathSync(root);
   return contains(canonical, privateRootFor(canonical, stateHome));
 }
+function privateWorkspace(requested, stateHome = defaultStateHome()) {
+  return contains(join(canonicalAmbientRoot(stateHome), "cadence-assistant-v1"), canonicalAmbientRoot(requested));
+}
 var LANDING_WORKSPACE = "cadence";
 function effectiveWorkspace(requested, stateHome, home = homedir()) {
+  if (privateWorkspace(requested, stateHome))
+    throw new Error("Private state cannot be a workspace");
   if (!stateHomeInside(resolveWorkspace(requested).root, stateHome))
     return { workspace: requested, redirected: false };
   return { workspace: join(home, LANDING_WORKSPACE), redirected: true };
@@ -294,6 +303,8 @@ class TaskStore {
   privateRoot;
   constructor(root, stateHome = defaultStateHome()) {
     this.root = realpathSync(root);
+    if (privateWorkspace(this.root, stateHome))
+      throw new Error("Private state cannot be a workspace");
     this.tasks = join(this.root, ".cadence", "assistant", "tasks");
     this.privateRoot = privateRootFor(this.root, stateHome);
     if (contains(this.root, this.privateRoot))

package/src/sdk-worker.mjs

@@ -63,6 +63,8 @@ const fail = (where, category) => {
   failure ??= { stage: where, class: category };
   process.exitCode = 1;
   if (first) {
+    // Prompt/preflight/terminal failure is distinct from a capture failure.
+    // A normal provider error can have a completely retained error message.
     if (
       emitter?.state.position.workerSeq &&
       !emitter.state.position.final &&
@@ -77,7 +79,9 @@ const fail = (where, category) => {
                 ? "cleanup"
                 : where === "network"
                   ? "network"
-                  : "capture",
+                  : ["prompt", "preflight", "assistant-final"].includes(where)
+                    ? "prompt"
+                    : "capture",
           })
           .catch(() => {});
       } catch {

package/src/service/contracts/models.ts

@@ -43,6 +43,9 @@ export interface ModelCandidate {
 export interface ModelCatalog extends ModelChoiceState {
   status: "complete" | "capacity";
   entries: ModelCandidate[];
+  /** Models left out because a provider/model ID contains a known credential
+   * literal or control characters; never their identifiers. */
+  withheld: number;
 }
 export interface ChooseModelRequest {
   expected: ChoiceVersion;
@@ -119,11 +122,19 @@ export function decodeModelCandidate(value: unknown): ModelCandidate {
 }
 export function decodeModelCatalog(value: unknown): ModelCatalog {
   canonicalJson({ kind: "ok", value }, LIMITS.pageBytes);
-  const o = closed(value, ["version", "selected", "status", "entries"]);
+  const o = closed(value, [
+    "version",
+    "selected",
+    "status",
+    "entries",
+    "withheld",
+  ]);
   const entries = list(o.entries, LIMITS.maxPageEntries, decodeModelCandidate);
   const status = oneOf(o.status, ["complete", "capacity"]);
+  const withheld = integer(o.withheld, 0, LIMITS.maxPageEntries);
   if (
-    (status === "capacity" && entries.length) ||
+    (status === "capacity" && (entries.length || withheld)) ||
+    entries.length + withheld > LIMITS.maxPageEntries ||
     new Set(entries.map((e) => canonicalJson([e.provider, e.model]))).size !==
       entries.length
   )
@@ -133,5 +144,6 @@ export function decodeModelCatalog(value: unknown): ModelCatalog {
     selected: nullable(o.selected, decodeModelSelection),
     status,
     entries,
+    withheld,
   };
 }