@abelxiaoxing/cadence 1.8.4 → 2.0.1

package/docs/remote-access.md

@@ -0,0 +1,60 @@
+# Explicit Personal HTTPS Access
+
+Remote exposure is an operator action, not part of installation or extension discovery.
+The backend stays on numeric loopback; configure one public HTTPS origin and trust only the immediate same-host proxy address.
+Use a private0600 JSON file with actual absolute paths:
+
+```json
+{
+  "schema": "cadence-service-host/1",
+  "cwd": "/absolute/project",
+  "agentDir": "/absolute/existing/pi-agent",
+  "tokenSource": "generated",
+  "tokenFile": null,
+  "http": {
+    "schema": "cadence-service-http/1",
+    "host": "127.0.0.1",
+    "port": 17423,
+    "proxy": {
+      "origin": "https://cadence.example.net",
+      "trustedAddresses": ["127.0.0.1"]
+    }
+  }
+}
+```
+
+Explicitly start with `cadence-service start --workspace /absolute/project --config /absolute/private-config.json`.
+The host refuses arbitrary forwarding chains, alternate authorities and non-loopback binding.
+Native/management capability traffic remains direct loopback, separate from browser credentials.
+
+## Caddy example — configuration only
+
+```caddyfile
+cadence.example.net {
+    # Do not enable query/access logging for the token-bearing bootstrap URL.
+    reverse_proxy 127.0.0.1:17423 {
+        header_up -Forwarded
+        header_up -X-Forwarded-For
+        header_up -X-Forwarded-Host
+        header_up -X-Real-IP
+        header_up Host cadence.example.net
+        header_up X-Forwarded-Proto https
+    }
+}
+```
+
+Audit any additional proxy-generated forwarding headers against the exact backend policy before use.
+HTTP and WebSocket upgrade must use the same authenticated route; no public backend bypass or insecure credential-bearing HTTP.
+This example does not install Caddy, provision DNS/certificates, change a firewall or deploy a service.
+
+Use `cadence-service token-link --workspace /absolute/project --reveal` to reveal a private entry link deliberately.
+Only root GET token entry accepts query credentials; subsequent private reads, exports and WS use the HttpOnly SameSite=Strict Secure cookie.
+Browser mutations/readonly POSTs require exact Origin and CSRF; access does not grant Start/check/review consent.
+A bad explicit token refuses even with an older cookie.
+Never put provider credentials in a browser or URL.
+
+`token-rotate` invalidates old links/cookies, pending grants, authenticated sockets and incomplete downloads without canceling admitted tasks.
+Environment-backed tokens require explicit Stop/restart with changed environment instead.
+Links may already exist in clipboard/history or external logs; redirecting cannot retract disclosure.
+Use [management and recovery](service-management.md) for Stop, uncertainty and exact local resolution.
+Loopback HTTPS/viewport tests are not physical-device or second-machine deployment qualification.

package/docs/reuse-and-distribution.md

@@ -0,0 +1,44 @@
+# Reuse and Distribution
+
+## Source families
+
+Cadence adapts `xing-shuyin/pi-web-ui@e8bab487af208bc9a1ab60a821652323f598127f`, MIT copyright 2026 xing-shuyin.
+The full original license is `licenses/pi-web-ui-MIT.txt`.
+Repository `provenance/webui-reuse.json` records source/destination hashes and explicit incompatible branches removed; `provenance/auth-reuse.json` records token/cookie adaptation.
+
+| Source family                        | Package adaptation                                                       |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| App, panels, layout, drawers         | Three-pane task workspace and responsive 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         |
+| FilePreview, SCM presentation        | Readonly observed changes, no Git/file mutation API                      |
+| GlobalSearchModal, search, deep link | Literal durable search, exact versioned hits and scoped export           |
+| Standalone run-trace client          | Local vis timeline/filter/replay of observations, never execution        |
+| use-chat, message-delta              | Shared typed reconciliation, gaps/resync and no mutation replay          |
+| Token/cookie and upgrade guards      | Cookie-first authenticated HTTP/WS, explicit Host/Origin/CSRF boundaries |
+
+No upstream runtime, general chat server, PTY, plugin loader, browser shell, credentials editor, reconnect continuation or task repair ships.
+Cadence's finite owner/admission/history contracts replace those incompatible seams.
+
+## Emitted licenses
+
+`licenses/bundled-web.txt` contains full original notices with stable labeled boundaries: React/DOM/scheduler; react-icons and the selected Feather family; unified/Markdown/HTML utilities; highlight.js; KaTeX code; vis-timeline and the versions actually embedded by its standalone build.
+KaTeX's 60 emitted TTF/WOFF/WOFF2 fonts retain their original bytes and separate SIL OFL1.1 plus reserved-family copyright notices.
+The vis bundle includes its own Babel/core-js/moment/vis-data/vis-util and other dependencies; project-resolved package versions are not substituted for those embedded versions.
+Both offered license texts are retained where supplied; extra notices do not imply extra runtime dependencies.
+
+Repository `provenance/bundled-notices.json` binds rendered module bodies, exact source artifacts, per-module output chunks, font bodies and exact notice byte ranges/digests.
+Provisioned official notice bodies were reused locally; builds never download licenses or dependencies.
+`build:web:check` checks the actual rendered module set against that reviewed policy as well as deterministic output bytes and local asset references.
+
+## 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.
+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.
+The real pack audit rejects missing/extra/duplicate/linked/special/unsafe members, altered bodies, pin/notice/font drift and linked extraction roots/ancestors.
+Extracted tests use tar-only package bodies and explicitly linked existing fixture peers; they never fill missing package files from source.
+No version bump, dependency install or publication is implied by this redesign.

package/docs/service-management.md

@@ -0,0 +1,108 @@
+# 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.
+Use one coordination state-home for the checkout; a different state-home is not a recovery route.
+Stop older Cadence sessions before starting the shared service.
+
+```sh
+cadence-service start --workspace /absolute/project
+cadence-service status --workspace /absolute/project
+cadence-service diagnose --workspace /absolute/project
+cadence-service token-link --workspace /absolute/project --reveal
+cadence-service token-rotate --workspace /absolute/project
+cadence-service stop --workspace /absolute/project
+```
+
+The equivalent package-relative command is `node <cadence>/src/service-cli.mjs ...`.
+`--help` lists the finite interface.
+`start` also accepts `--foreground`, `--config`, `--agent-dir`, `--host` (loopback only), `--port`, `--token-file` and `--state-home`.
+Defaults are loopback `127.0.0.1:17423`, normal Pi agent configuration, and detached service lifetime.
+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.
+
+## Status, departure and Stop
+
+- `alive` requires an authenticated exact-epoch reply.
+  It is not a PID probe.
+  `actions:false` can mean that no owner model has been explicitly selected yet.
+- Return, browser close and Pi quit detach clients; admitted work continues.
+  Use the client's **Cancel** for a run or management **stop** for the service.
+- Stop closes admission and waits original processes, credential writes, history writes, already-started publication continuations, owned networking and listener closure before releasing fences.
+  Checks, native process outcomes and human review remain separate facts.
+- `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 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.
+
+`diagnose` reports fixed pending/recording facts and `proxyAuth: direct|validated-proxy`.
+No normal status/diagnosis prints access secrets, provider credentials or outbound proxy URLs.
+Keep the explicitly revealed token link private.
+Browser entry redirects to a token-free URL and uses an HttpOnly cookie; that does not retract a link already copied into history, a clipboard or external logs.
+File/generated token rotation invalidates old access and pending confirmations, not admitted work.
+Environment-token replacement requires explicit Stop/restart with changed environment.
+Inbound remote access still requires the selected same-host HTTPS reverse-proxy policy; outbound proxy routing below is independent.
+Browser access, even with a valid token, cannot perform local management/recovery or arbitrary manual shell checks.
+The native client's local capability uses an owned direct loopback dispatcher, never the Pi process's provider proxy.
+Detach joins that client's original dispatcher closure without changing the parent's global dispatcher or canceling service work.
+
+## Outbound owner authentication and workers
+
+Set one credential-free HTTP(S) proxy URL as an equal HTTP/HTTPS pair in the **service launch** environment.
+Matching uppercase/lowercase duplicates are supported; conflicting or partial pairs refuse.
+No `ALL_PROXY`, `NO_PROXY`/bypass, URL userinfo, non-root path, query/fragment, percent-bearing authority, unsafe controls or `NODE_OPTIONS` (including empty entries) is accepted.
+`NODE_USE_ENV_PROXY` can be absent or exactly `1` with the pair.
+A standalone opt-in refuses.
+The service launcher projects the validated uppercase pair and opt-in before SDK imports, and uses the actual runtime's public `--use-env-proxy` capability.
+Missing capability refuses before launch, without finding/installing another Node.
+
+After SDK imports the dedicated owner installs one owned public Undici dispatcher, verifies its identity and uses it for public SDK getAuth/OAuth refresh.
+Workers retain their separately validated startup/post-import route.
+Scoped provider route entries must exactly match the captured route; they cannot select a route or become process environment.
+Changed route facts/dispatcher identity refuse, never silently fall back to direct traffic.
+DIRECT adds no dispatcher work.
+No TLS override, global fetch replacement or private SDK networking is used.
+Proxy URLs are RAM-only known redaction literals, not persisted route hashes or public history fields.
+
+Pi's selected existing `auth.json`/`models.json` remain the model sources; OAuth renewal writes back through public SDK coordination, preserving unrelated credentials.
+Cancel stops launch admission but does not claim an already-started refresh/writeback was rolled back.
+Checks inherit the owner's frozen ordinary launch environment (including the canonical configured proxy pair/opt-in), minus service/access/control material.
+Resolved model auth is never merged into checks.
+Local fabricated-provider plain/gzip routing tests are not paid-provider, all-adapter, Node22 or other-platform qualification.
+
+## Informed local recovery
+
+```sh
+cadence-service recover inspect --workspace /absolute/project
+cadence-service recover resolve --workspace /absolute/project
+```
+
+Inspection is readonly.
+It displays the epoch, exact coordination/history digests, owner PID/host observation and independent process/credential/storage uncertainty.
+Those digests identify preserved resources, not successful work or credential validity.
+A journal with no unmatched intent does not prove every escaped descendant or external credential writer stopped.
+
+Before resolve, independently inspect and stop old processes externally, inspect the selected Pi credential file and SDK locks, and inspect retained storage/history.
+Cadence does not signal arbitrary processes, reclaim SDK locks, repair credentials, truncate damaged history, migrate old formats or delete old resources.
+Resolve requires a native local TTY, four fresh typed responses within120seconds and the same unchanged resources: separate process/escaped-descendant, credential/writeback and storage acknowledgments, then the exact displayed epoch.
+There is no `--yes`, piped-input confirmation, browser body boolean, HTTP recovery endpoint or pasted multiline authorization.
+An SSH terminal executes locally on the owner host; this is an operator interaction boundary, not proof of a physical human's identity.
+
+Only a same-host owner whose PID probe specifically reports absence is eligible; live, remote, ambiguous, refreshed or partial resources refuse.
+Absence alone never clears anything.
+The original durable append/flush/close of a new fenced recovery fact completes first.
+Then exact registration and registry state are updated, and the exact capability, owner lock and associated v1 lock are released in order, rechecking remaining resources, history and local authority before every effect.
+Other workspace reservations remain untouched.
+The v1 lock is last.
+An unrelated legacy lock is never eligible.
+
+Recovery preserves old unknown outcomes and damaged bytes.
+Its result is **operator acknowledgment, not certification**; restart chooses a new epoch and never replays queues/auth work.
+New work requires fresh plan/action consent.
+Failure/crash between append and release can leave a durable bridge and partial fences.
+A refused command is not proof of no effects.
+Reinspect and preserve that state; reading/restart does not repair it, and automatic retry/reset is not a safe resolution.
+Recognized old history formats stay readonly and are not migrated to enable recovery.