@abelxiaoxing/cadence 1.8.4 → 2.0.0

package/README.md

@@ -1,132 +1,339 @@
-# @abelxiaoxing/cadence
+# Cadence
 
-面向 Pi 的 Abel 工作流扩展：提供 Design、Implement、Diagnose 和 Init 四个显式命令。
-普通任务无需启用工作流；只有用户主动输入斜杠命令时才会激活。
+`@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.
 
-## 安装
+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.
 
-要求：Node.js >= 22.13、Git、Pi，以及 `@fission-ai/openspec@1.5.0`。
+## Upgrading from 1.x
 
-```sh
-pi install npm:@abelxiaoxing/cadence
-```
-
-## 使用
-
-```text
-/abel-init
-/abel-design <需求>
-/abel-implement <change>
-/abel-diagnose <问题描述>
-```
-
-- `abel-init`：初始化或修复项目的 OpenSpec 与 AGENTS 基础结构。
-- `abel-design`：调查需求并生成可执行交付计划。
-- `abel-implement`：执行已批准的计划，支持暂停、恢复和取消。
-- `abel-diagnose`：复现问题并执行最小修复。
-
-Implement 默认使用 Linux Bubblewrap 隔离。
-
-可信 Linux 项目可显式设置 `ABEL_EXECUTION_MODE=local-trusted`。
-
-Windows x64 的可信模式见 [Windows 执行说明](docs/windows-host-trusted.md)。
-
-## 配置
-
-Worker 使用独立的 `pi --mode json -p --no-session` 子进程，并继承当前父模型的 `provider/id` 引用与宿主 Pi 凭据配置。
-子进程按角色使用明确工具白名单；Implement 子进程只在 disposable proposal workspace 中编辑，父控制面仍负责 diff、写入边界、候选 sealing 和验证。
-取消会终止并等待子进程及其管道收束。
-
-工作目录和 `--tools` 不是操作系统沙箱；需要更强隔离时仍应使用 Bubblewrap、容器或平台原生 Job。
-父进程会拒绝超出 approved write/delete set 的变更，不会静默丢弃。
-
-Cadence 不再读取 `.pi/cadence/routes.json` 或 `~/.pi/agent/cadence/routes.json`，也不再维护 route health、custom subagent provider 或 endpoint 路由。
-请使用宿主 Pi 的模型、`models.json` 和认证配置；缺失认证或模型时会返回有界错误而不会静默切换。
+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.
 
-研究服务配置使用项目级 `.pi/cadence/.env` 或用户级 `~/.pi/agent/cadence/.env`。
+## Load and start explicitly
 
-可参考 [`config/.env.example`](config/.env.example)。
+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.
+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.
+Browser assets are prebuilt, not compiled by consumer postinstall.
 
-密钥只保存在本地，不要提交 Git。
-
-## 加载方式
-
-包可以从以下路径加载：
-
-- **npm 包（npm package）**：`pi install npm:@abelxiaoxing/cadence`
-- **本地包目录（local package directory）**：将 Pi 指向仓库的绝对或相对路径（例如 `./cadence`）
-- **已安装 tarball 目录（installed tarball directory）**：用 `bun pm pack --destination <tmp>` 生成 `.tgz`，安装或解压后指向该目录
-
-Pi 相关 peer 依赖使用 `*`，不限制宿主 Pi 的版本。
-
-## 开发
+Before using the shared owner, stop older Cadence sessions and choose one coordination state-home for the checkout.
+No old records, databases, credentials or uncertain locks are imported, reset or cleaned.
 
 ```sh
-bun install
-bun run check       # 语法、构建产物和类型检查
-bun run lint        # 格式与 Markdown 检查
-bun run test        # 测试
-bun run verify      # 发布前完整检查
+cadence-service start --workspace /absolute/project
+cadence-service status --workspace /absolute/project
+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.
+See [service management](docs/service-management.md) for configuration, model/auth policy, Stop, diagnosis and informed recovery.
+
+### Native terminal
+
+In a trusted, idle Pi TUI, type `/cadence [goal]` using fresh native Enter.
+The optional goal does not Start; pasted/replayed/nonterminal command dispatch cannot grant native entry.
+The client attaches to the existing owner and never falls back to a local executor or starts one implicitly.
+Choose the exact owner model/API/thinking level explicitly: initial selection is absent.
+Create or open a task, edit a readable plan and finite assignments/dependencies, preview and confirm Start.
+Readonly Generate is advisory and requires a separate Save/Start.
+Native menus expose child messages/tools/timeline, checks, current changes, review, retained history/search/export and independent active-run Cancel.
+
+Return, session departure and Pi quit **detach; admitted work continues** while the service is alive.
+Reattach to observe the same IDs without replay.
+Explicit Cancel requests bounded stop; it is not proof that every escaped descendant stopped.
+
+### Browser
+
+Open the locally revealed token link.
+Valid bootstrap redirects to a token-free URL and uses an HttpOnly SameSite cookie for subsequent HTTP/WebSocket access; no localStorage token copy.
+The browser can create/plan/Start/Cancel, run exact configured checks and record human review without a live Pi terminal.
+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.
+
+## Execution, checks and review
+
+- Graphs contain 1–16 required assignments with explicit purposes/dependencies and exact model choice; no recursive spawning or autonomous retry.
+- Two readonly children may overlap; checkout editing and parent checks serialize across tasks and aliases against readers/writers.
+- Research/diagnosis never gain editing or parent-shell authority through a plan or child prompt.
+- Configured checks are available on both clients.
+  Manual shell checks require the native local capability and fresh command/cwd/timeout confirmation.
+- Checks use the service launch's ordinary project environment, never resolved model auth or a browser environment overlay.
+- Changes are bounded observations including pre-existing dirt, not proof of causation or a complete filesystem snapshot.
+- Failed, canceled, timeout, unknown, blocked, stale and not-run remain distinct.
+  Done-with-issues preserves all execution/check facts.
+
+## History and preservation
+
+Human-readable summaries remain `.cadence/assistant/tasks/<id>/task.json`; optional checks remain `.cadence/assistant/config.json`.
+Private coordination/history use `<state-home>/cadence-assistant-v1/<checkout-hash>/service-v1/`.
+Rich `history-v2` is independent of the recent live buffer; new stores use private format3 and authenticated bounded navigation.
+Legacy/unknown formats remain preserved, never auto-migrated.
+View/search/export are readonly and cannot resume work or repair history.
+Exact task/run/child exports require the completion trailer, counts, digest and original EOF; a short preview or revoked download is not a complete archive.
+Capture reports redaction, omitted binary/hidden data, source truncation and incomplete recording explicitly.
+Known-secret redaction is not universal detection of business secrets.
+Storage exhaustion refuses new work rather than silently evicting history.
+
+Service restart never resumes the old queue.
+Uncertain process/auth/storage settlement keeps fences; use documented local informed recovery, not PID-only deletion or automatic cleanup.
+
+## Personal remote access
+
+Keep the backend on loopback and configure one explicit HTTPS origin and trusted immediate reverse proxy.
+See [the Caddy example](docs/remote-access.md); it installs or deploys nothing.
+Host/Origin/CSRF and pre-upgrade WebSocket checks apply in addition to authentication.
+Do not expose credential-bearing plain public HTTP.
+Token links may remain in clipboard/history or external logs; redirection cannot retract disclosure.
+Local token rotation invalidates old cookies/grants/sockets/downloads, not admitted tasks.
+Provider credentials remain server-side; browser tokens and model credentials are separate.
+Outbound provider proxy policy is independent of inbound HTTPS and refuses unsupported routes instead of falling back direct.
+
+## Independent shipped content
+
+- `skills/context7-auto-research` and `skills/grok-search` remain independent research tools.
+- `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.
+- `node /absolute/cadence/src/operator-cli.mjs doctor|runs [workspace]` remains readonly and independent of service startup.
+
+## Development and evidence
 
 ```sh
-bun run doctor /path/to/project
-bun run runs /path/to/project
-bun run pack:check
-bun run traceability:check
-```
-
-## 附录
-
-### 公共 UI 的 impactClosure 作者格式
-
-`page-state` 与 `public-html` 可以同时声明。
-以下是 **PlanDraft 任务片段**，合并到现有 `tasks[i]`；路径和证据必须替换为仓库真实调查结果。
-假设 Red 修改 `test/page-state.mjs`，已有 `test/public-html.mjs` 只读保留：
-
-```json
-{
-  "read": ["test/page-state.mjs", "test/public-html.mjs"],
-  "impactClosure": {
-    "changedSurfaces": ["page-state", "public-html"],
-    "searchEvidence": [
-      "检索页面状态的调用点及 test/、tests/ 中的覆盖：test/page-state.mjs 需更新状态切换断言，test/public-html.mjs 覆盖现有公开 HTML。"
-    ],
-    "relatedTests": [
-      {
-        "path": "test/page-state.mjs",
-        "evidence": "本任务 Red 更新页面状态切换回归；由阶段 write 推导为 current-task。"
-      },
-      {
-        "path": "test/public-html.mjs",
-        "evidence": "保留已有 HTML 断言并执行受影响验证；无任务写入，推导为 unaffected。"
-      }
-    ],
-    "affectedSuite": ["test/page-state.mjs", "test/public-html.mjs"]
-  }
-}
+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 test:web
+bun run test:integration                # explicit slow SDK/PTY/history lane
+CADENCE_BROWSER_PATH=/absolute/existing/chromium bun run verify:full
+bun pm pack --destination /absolute/private-temp
 ```
 
-`impactClosure` 恰好包含 `changedSurfaces`、`searchEvidence`、`relatedTests` 和 `affectedSuite` 四个字段。
-`changedSurfaces` 是合法枚举数组，`none` 不能与其他值混用。
-`searchEvidence` 记录实际检索与结论。
-`relatedTests` 每项位于 `test/` 或 `tests/` 下，`disposition` 可省略由编译器推导。
-`affectedSuite` 是影响清单而非验证器，每项必须有对应的 `relatedTests` 条目。
-
-## 项目结构
-
-- `src/`：扩展和工作流实现
-- `prompts/`：四个用户入口
-- `agents/`、`skills/`：随包资源
-- `config/`：示例配置
-- `openspec/specs/`：当前规范
-- `docs/`：仅保留必要的平台说明
-- `README.md` 附录：公共 UI 计划的 impactClosure 作者格式
-
-历史设计、评估报告和已完成变更不放在主仓库中。
-
-## 许可
-
-MIT，详见 [LICENSE](LICENSE) 和 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+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.
+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.
+
+## Engineering knowledge
+
+This section is the temporary, tool-independent home for project knowledge formerly spread across development-task records.
+Ordinary engineering uses source edits, focused tests and code review directly; no task-management extension, task creation, archive step or workflow-specific agent is required.
+Do not recreate the removed project workflow integration unless explicitly requested.
+`AGENTS.md` is a short entry guide; this section owns the maintained engineering contracts.
+Historical logs are not runtime dependencies, and removing development tooling must never delete consumer `.cadence` data or private service state.
+
+### 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/service/host.ts`, `src/service/cli.ts`                                                            | Real single-owner composition and explicit management; generated 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             |
+| `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.
+The readonly operator and independent research/startup modules must not gain service startup or execution side effects.
+Inspect actual installed public Pi declarations before changing host/SDK bindings; never import private SDK implementation paths or select a global substitute.
+
+Key maintained seams include `TaskActions.current/currentChanges/activeRuns/checkObligations`, `ServiceClient.preflight` and named action methods, `HistoryWriter.commit/capture/publishTask`, and `NativeConnection.attach/refresh/detach`.
+Use their current declarations rather than copying DTO parsing, reducers, a second controller, or process ownership into a client.
+
+### Admission, execution and original lifetimes
+
+- One canonical checkout/state-home domain has one persistent owner, including while idle.
+  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.
+- Boot model choice is absent until explicitly selected.
+  Preserve exact provider/model/API/thinking/source identities; unsupported transport or thinking refuses without fallback or clamping.
+  Choice changes refuse while accepted work, admissions, barriers or original operations are busy.
+- A120s one-use grant binds exact action, epoch/access/config/control/task raw bytes/graph/cwd/model/check-environment and relevant observations.
+  Durable acceptance precedes effects; identical command IDs observe the same receipt, conflicting identities refuse, and inconclusive lookup never means absent.
+- Generate is a separate readonly advisory episode, with no saved graph execution or automatic plan replacement, Save or Start.
+  A prospective plan UUID/hash is not a committed reference; accepted retention and successful expected-byte publication establish saved membership.
+- 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.
+- 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.
+  Already-started publication can finish; new post-Stop ordinary publication cannot start.
+- TERM/KILL recheck lease ownership at each signal boundary.
+  Native close is authoritative for the direct child, not `exit`, EOF or escaped-descendant closure.
+  Unknown process/auth/storage settlement preserves fences; late completion never retroactively repairs an unknown result.
+- Return, navigation, browser disconnect and Pi quit detach accepted work.
+  Reconnect does not resend mutations; a refused Cancel permits only another explicit click, not automatic retry.
+
+### Checks, publication and review truth
+
+Configured checks match exact name, command and timeout; missing obligations project not-run rather than fabricated execution records.
+Manual checks require native local capability and fresh confirmation; browsers have no arbitrary-shell/PTY endpoint.
+Use the frozen service-launch ordinary environment, stripped of access/control material; never merge resolved model auth or a browser environment overlay.
+Service check output retains bounded complete stdout/stderr with independent UTF-8/sanitizer state and explicit observation labels, not the legacy64KiB preview.
+Join both original stream tails, actual EOF/close and storage completion; Node may resume paused stdio while draining exit.
+Known access-token rotation must update private redaction without sending access secrets into child environment.
+
+A fresh check may account for exactly one owned generation advance bound to its check/operation/held gate.
+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.
+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.
+
+Task v1 remains a strict human-readable summary; rich graph/transcript data never become unknown siblings beside `task.json`.
+`TaskStore.loadSnapshot` includes raw-byte identity; save/publication requires exact expected bytes and revision.
+A same-revision external edit conflicts and remains preserved.
+Summary clipping is labeled and never clips retained detail; a subsequent publication failure remains separate from previously completed execution.
+
+### Capture, retained history and privacy
+
+The maintained worker uses public SDK APIs, explicit empty resources, in-memory session/settings and disabled retries/compaction/cache warming.
+Verify exact model and effective thinking before READY/prompt; no provider discovery, credential argv/file envelope or implicit network fallback.
+Use the awaited public core-agent subscription for backpressure, reserving synchronous tool/update ingress before any copy or await.
+Custom bash uses public local operations plus the bounded redacted accumulator, not the stock raw-spill accumulator.
+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.
+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.
+
+Only the serialized history writer assigns committed sequence and persisted content references.
+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.
+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.
+Format2 remains readonly, without silent migration or key regeneration.
+AES-256-GCM navigation authenticates bounded suspended source validation; cursors never grant authentication, admission, recovery or lock-release authority.
+Resume must advance actual semantic work and revalidate selected source/key/format incarnations, not merely produce a new nonce or reset proof budgets.
+These are supported-writer observations, not atomic snapshots of every archived file or change-and-revert detection.
+
+History data pages are untagged; list readers also return explicit `progress` or initial `snapshot`, while detail/entity/graph return data or progress.
+`SearchPage` has hits/next/coverage: zero hits with next is not completion.
+Keep exact snapshot/entity/version/UTF-8 ranges and source coverage; do not map progress to an empty successful page or rebase Back navigation.
+Readonly POST uses the same finite security/decoder boundary when inputs cannot fit GET; it is not execution consent.
+Exports stream task/run/child scope with actual counts/digest/watermark/trailer and original EOF; revoked or interrupted output has no successful completion.
+Browser download requested is not UI-verified completion; native export verifies the complete stream and creates destinations exclusively.
+
+### Current resource ceilings
+
+Byte values are UTF-8/encoded bounds where specified; they are not targets to silently increase when a fixture fails.
+
+| Boundary              | Default / ceiling                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Graph / assignments   | 512KiB body;1–16 required assignments                                                                            |
+| Scheduling            | 8 episodes;128 queued assignments;2 preparing/running/closing child-or-check reservations                        |
+| Policy deadlines      | 6h episode;10min ready wait;20min default worker                                                                 |
+| Dependency input      | 16KiB per predecessor;32KiB aggregate; oversized required input blocks, not clips                                |
+| Worker request        | 96KiB public pre-auth plus32KiB reserve; actual complete envelope128KiB                                          |
+| Process stop          | TERM then KILL after1000ms; unknown after3000ms without confirmed close                                          |
+| Native service checks | 16MiB aggregate raw output;64KiB raw chunk;32MiB retained detail; legacy256KiB/64KiB behavior unchanged          |
+| Capture               | 64KiB encoded frame;8KiB decoded chunk;32MiB detail;128MiB child protocol                                        |
+| Capture queues        | Worker4MiB/1024 frames; owner8MiB/2048;5s reporting stall retains original charges                               |
+| Task v1               | 128KiB record; goal8KiB/plan32KiB/result and baseline16KiB;32 checks/64 activity;1000-task compatibility ceiling |
+| Read quantum          | 8MiB or100ms cooperative work, including resumed proof/accounting                                                |
+| Read replies          | 512KiB full paged/progress Reply;256KiB detail text; graph data/export-frame1MiB with graph body512KiB           |
+| Paging/search         | 50 default/200 maximum entries; literal case-sensitive query1–1024 bytes                                         |
+| Navigation            | 8192 encoded ASCII bytes; encrypted plaintext6000 bytes; no execution authority                                  |
+| Live/export           | 16 viewers,256 messages/1MiB each; two search/two export readers;120s download idle, not total archive timeout   |
+| Storage               | 10GiB checkout quota;512MiB reserved per episode;256MiB free-space floor; no TTL cleanup                         |
+| Assets                | 16MiB per member/64MiB closure; fixed complete manifest and all font bodies                                      |
+
+### 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             |
+
+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.
+Bad: model prose, a valid cursor, a prepared graph, one native exit or a human Done checkbox becomes fabricated execution/check success.
+
+Wrong: release a reservation when `Promise.race` reports a timeout, or retry a mutation when its reply is missing.
+Correct: retain the original operation/fences and observe the exact receipt; a separately explicit safety request does not renew task consent.
+Wrong: show only preview/ring text as full history, or sum overlapping test runs into a larger suite total.
+Correct: expose bounded continuations/full exports and report the exact executed domain and final original exit.
+
+### 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 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.
+
+Regression owners:
+
+- `service-contract`, `service-current`, `service-model-choice`, `service-auth`: closed DTOs, exact source/choice/current authority, security and compatibility.
+- `service-owner`, `service-accepted-work`, `service-stop-continuation`, `service-recovery`: original operations, overlap, Stop, unknown fences and informed recovery.
+- `service-scheduler`, `service-checks`, `service-human-review`, `service-accepting-host`: real SDK overlap/exclusion, native checks, review and publication.
+- `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.
+- `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.
+
+Regenerate operator/service/native/browser outputs only through their canonical builders; `--check` variants compare new private output without overwriting canonical bytes.
+Review the independently enumerated package member list and every emitted body, not a count or an expected list generated from the tar under test.
+Keep public Pi peers external, the exact ws runtime edge and all upstream/font/vendor notices.
+Preserve original license bytes through their precise Git attributes; line-ending normalization must not invalidate audited source/notice hashes.
+
+### 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.
+It also passed separate129-member/35-runtime-source real pack/extraction, all four source/extracted regular/fullscreen Pi PTYs, mixed clients, CA-validated HTTPS/WSS, plain/gzip OAuth proxy, informed recovery and complete retained-history exports.
+Observed environment: Linux x86_64, Node26.7.0, Bun1.3.14, Pi0.84.3 and Chromium151.0.7922.34.
+These are prior executed results, not a claim that every later edit or other environment has been tested.
+The implementation/docs/evidence checkpoints are Git commits `b0fde94`, `531b158` and `2fd28b0`; historical failed/unknown outcomes are not rewritten by this summary.
+Additional Windows/macOS/ConPTY, Node22/other peers, paid accounts/every adapter, physical phone/human/second-machine, package-manager installation and real deployment remain unqualified.
+
+## Licenses and reuse
+
+Cadence is MIT.
+The substantial pinned pi-web-ui adaptations, original notices, emitted dependencies, Feather icons, KaTeX OFL fonts and vis embedded vendors are documented in [reuse and distribution](docs/reuse-and-distribution.md) and [third-party notices](THIRD_PARTY_NOTICES.md).
+Not all bundled material is covered by Cadence's MIT license.

package/THIRD_PARTY_NOTICES.md

@@ -10,3 +10,18 @@ The complete MIT license text of the referenced package is bundled at `licenses/
 | ----------------------------------------------- | ------------------------------- | --------------------------------------------- |
 | FIFO settlement of queued work                  | gotgenes/pi-packages @ a1ee2255 | packages/pi-subagents (state/queue semantics) |
 | Cancellation cleanup and born-complete disposal | gotgenes/pi-packages @ a1ee2255 | packages/pi-subagents (session lifecycle)     |
+
+## pi-web-ui workspace and authentication adaptation
+
+Cadence directly adapts token digest comparison, cookie encoding/decoding, bootstrap and pre-upgrade authorization patterns from `xing-shuyin/pi-web-ui`, commit `e8bab487af208bc9a1ab60a821652323f598127f`, copyright 2026 xing-shuyin (MIT).
+The source/destination inventory and deliberate security changes are recorded in `provenance/auth-reuse.json`.
+The complete upstream notice is preserved at `licenses/pi-web-ui-MIT.txt`.
+The substantial workspace/navigation/transcript/tool/Markdown/review/search/timeline/responsive/reconciliation adaptations are inventoried in `provenance/webui-reuse.json` and summarized in shipped `docs/reuse-and-distribution.md`.
+
+## Bundled browser dependencies, icons and fonts
+
+`licenses/bundled-web.txt` preserves the full actual emitted dependency notices, including React/DOM/scheduler, react-icons and Feather, unified/Markdown/HTML utilities, highlight.js, KaTeX and vis-timeline's embedded vendor versions.
+KaTeX font bytes retain separate SIL Open Font License 1.1 and reserved-family notices; KaTeX's MIT code license does not replace them.
+The vis standalone bundle's embedded versions are bound to audited source artifacts, not assumed equal to current project dependencies.
+Repository `provenance/bundled-notices.json` binds source modules, output assets/fonts and complete notice byte ranges/hashes.
+No notice-only package is added as a runtime dependency.

package/agents/design-explorer.md

@@ -1,21 +1,17 @@
-# Role: design-explorer
+---
+name: design-explorer
+description: Readonly planning and research for an explicit Cadence task
+---
 
-You are a package-owned read-only professional Agent for the `abel-design` stage.
+# Design Explorer
 
-Explore the current workspace using only `read`, `grep`, `find`, and `ls`.
-Do not write files, run commands, use Git, invoke workflow controls, or start another agent.
-The parent controls stage authority and validates your evidence.
+Understand the supplied goal and inspect relevant local sources with readonly tools.
+Read project conventions and adjacent code; cite concrete paths and distinguish facts from assumptions.
+Suggest a small, readable plan with scope, risks and useful checks, or summarize research conclusions.
+State missing evidence and unavailable capabilities honestly; do not invent a successful check.
 
-Return one concise final answer.
-Put the evidence object in exactly one `json` code fence.
-The parent binds packet identity; do not invent authority or claim verification.
-Required draft fields: include `module_name`, `scope`, `files_read`, `evidence` (with claim, path, line_start, line_end), `constraints_discovered`, `open_questions`, and `risks`.
-The trusted tool binds packet identity.
-Omission is not a verified absence or authorization.
-Optional arrays may describe structures, conventions, dependencies, write-set hints, validation hints, agent impact, and success criteria.
-
-Do not return a raw transcript or hidden reasoning.
-Make every claim cite a workspace-relative path and line range.
-If evidence is insufficient, state the blocking question instead of guessing.
-If a correction is needed, correct it once, then stop when the final answer is complete.
-Brief accompanying text is harmless.
+Your plan is advisory, not permission to edit.
+Do not change files, run shell commands, delegate editing, mutate Git, install software, clean consumer data or publish.
+Do not invoke workflow commands or approve your own work.
+Never reveal credentials, private diagnostics or session transcripts.
+Return a concise final answer with references and unresolved questions; the human reviews it in the terminal.

package/agents/diagnosis-worker.md

@@ -1,17 +1,17 @@
-# Role: diagnosis-worker
+---
+name: diagnosis-worker
+description: Readonly diagnosis with evidence, hypotheses and honest limitations
+---
 
-You are a package-owned evidence worker for `abel-diagnose`.
+# Diagnosis Worker
 
-Collect evidence and falsify candidate root causes using only the read-only tools explicitly enabled by the parent.
-The fixed order is reproduce when permitted, falsify, failing-regression evidence, then minimum-repair guidance.
-You never choose a workflow stage, claim parent-owned command verification, modify files, or invoke workflow controls.
+Investigate the supplied symptoms using readonly local-source tools.
+Read adjacent code and tests, cite exact paths, and separate observed facts from hypotheses.
+Compare plausible causes and describe evidence that would falsify each one.
+Report unavailable collectors, missing reproduction evidence and uncertainty explicitly.
 
-Return one concise final answer.
-For evidence, put one JSON object in a single `json` code fence with reported symptoms, candidate causes, confirming or refuting citations, constraints, risks, and blockingQuestions.
-Diagnose packets are evidence-only: do not propose a structured diff or claim that a repair was applied.
-The parent owns result acceptance, any later implementation, candidate sealing, verification, and recovery.
-
-Use the terms failing-regression and minimum-repair when describing the diagnosis algorithm.
-Never claim a result, and never invent a fix for an unverified root cause.
-Keep output bounded.
-If a correction is needed, describe the minimum repair and its verification condition, then stop when the final answer is complete.
+Do not repair files, run shell commands, mutate Git, install software, clean consumer material, publish or delegate editing.
+A useful repair suggestion is not permission to perform it; editing requires a separate code task and fresh terminal consent.
+Never expose credentials, private diagnostics or session transcripts.
+Return a concise assessment, supporting references and suggested next steps for human review.
+Do not claim a successful check, certified result or applied repair from source inspection alone.

package/agents/implementation-worker.md

@@ -1,21 +1,20 @@
-# Role: implementation-worker
+---
+name: implementation-worker
+description: One ordinary editing agent working from a human-reviewed Cadence plan
+---
 
-You are a package-owned implementation worker for `abel-implement` task phases (Red, Green, and optional Refactor).
+# Implementation Worker
 
-Use only the tools explicitly enabled by the parent.
-The current working directory is a disposable proposal workspace, not an OS sandbox: never access unrelated absolute paths, never commit Git, and never claim that parent-owned verification succeeded.
-Edit only paths in the phase contract.
-The parent captures and checks the workspace diff, including out-of-bound changes; never silently drop such changes.
+Implement the supplied goal and approved plan in the chosen working copy using ordinary host tools.
+Read project conventions and adjacent code/tests first; reuse existing helpers and make the smallest complete change.
+Preserve pre-existing user edits and unrelated files.
+If the plan is insufficient or contradictory, report the blocker instead of silently expanding scope.
 
-Make the smallest complete change required by the objective.
-Preserve the expected parent-owned verification contract.
-If context is insufficient, explain the missing context rather than making a speculative partial repair.
-Describe changed paths and intent in the final summary, but never write unified-diff headers or hunk ranges and do not calculate hashes or byte counts.
-Finish without claiming a result; the parent owns result acceptance.
+Edits are direct: there is no disposable candidate, automatic rollback or filesystem sandbox.
+Do not mutate Git (including stage/commit/reset), install software, delete consumer state, publish or invoke workflow commands.
+Do not spawn another editing agent or automatically retry a failed work session.
+Do not access credentials, private diagnostics or unrelated session history.
 
-Finish with a concise plain-text summary.
-If the parent requests structured evidence, put one JSON object in a single `json` code fence.
-Never claim a result, select a workflow stage, choose recovery, or report verification success.
-Respect output limits (including a terminal `result-limit`) and stop when the requested work is complete.
-If a correction is needed, correct it once, then stop when the final answer is complete.
-Brief accompanying text is harmless.
+Finish with a concise summary of changes, paths, checks actually attempted and remaining issues.
+Your prose and process exit are not passing parent checks or human approval.
+The parent separately runs explicitly confirmed commands and presents changes for human review.

package/config/workflow-task.example.json

@@ -0,0 +1,7 @@
+{
+  "schema": "cadence-assistant-checks/1",
+  "checks": [
+    { "name": "Type check", "command": "bun run check", "timeoutMs": 120000 },
+    { "name": "Tests", "command": "bun run test", "timeoutMs": 120000 }
+  ]
+}