@margay/ccl-core 1.5.0-alpha.0 → 1.5.1-alpha.2

package/docs/error-recovery-usage.md

@@ -1,6 +1,16 @@
 # 错误诊断与恢复：CLI / SDK 使用说明
 
-本文对应 `1.4.5-rc.1`。自主恢复实现已获独立评审共识，本机 `ccl` / `margay` 已升级并完成终端验证；npm 与网站未发布。交付范围及证据限制见 [版本说明](./releases/1.4.5-rc.1.md)。
+基础恢复行为自 `1.4.5-rc.1` 引入；任务独立纠错预算在 `1.5.0-alpha.3` 中引入。版本是否已发布须以实际安装版本和 npm registry 为准。当前交付范围见 [版本说明](./releases/1.5.0-alpha.4.md)。
+
+### 任务纠错预算（1.5.0-alpha.3）
+
+独立的父任务、子任务和兄弟任务各自计数。每项任务最多自动纠错两次；内部摘要、记忆等辅助工作计入所属任务的总额，每个执行作用域对同一原因最多纠错一次。首次正常请求不计为纠错；`maxTurns` 是另外的执行轮数上限，不是这里的纠错次数。`/btw` 是独立用户侧问，有自己的额度。
+
+宿主在派发时生成稳定任务 UUID。换执行者、前台转后台、恢复同一子任务都沿用该任务的额度。启用会话持久化时，计数和原因保存在 sidechain 旁的版本化记录中，先原子保存扣减，再允许额外请求；保存失败不放行重试。禁用会话持久化时只保留进程内记录。
+
+恢复旧版本任务时，如果没有纠错记录，历史消耗属于未知：仍可读取上下文并正常继续，但不自动追加纠错。已有身份记录对应的状态缺失、损坏或无法读取时会明确失败，不回零。这意味着升级前已运行的旧子任务恢复后可能没有自动纠错额度；换标题或重派相同失败操作不是合法的迁移办法。
+
+AI 指令要求保留完成的结果、回报阻塞，不通过新任务 ID 或父任务额度重复子任务已耗尽的操作。确有新证据、修复前置条件或明确追加授权时再决定如何继续，这些不会自行重置计数。宿主不靠标题或正文相似度判断任务是否相同，提示词也不是对所有语义绕行的强制保证。该机制没有新增全局资金/token 调度器或模型自行授额接口。
 
 ## 用户遇到错误时会发生什么
 
@@ -35,7 +45,7 @@
 
 无头 SDK 子进程继承宿主的环境，并合并 `query(..., { env: { CCL_MAX_OUTPUT_TOKENS: '16000' } })` 中的显式设置。修改终端变量不会改变已运行宿主的环境；应由宿主传入，或重启宿主使新配置生效。提高请求预算不保证能突破模型/网关上限，也不能修复不合法的显式 thinking 预算。npm 全局安装与宿主内嵌 CLI 可能是不同版本，应核实实际运行路径。
 
-输出截断沿用分阶段恢复与共享次数限制，保留已完成的工具结果；不会因新增恢复规则而获得无限重试。
+输出截断沿用分阶段恢复与所属任务的次数限制，保留已完成的工具结果；不会因新增恢复规则而获得无限重试。
 自动派生的原生模型 thinking 算术冲突可在限定条件下局部修正，显式配置冲突需用户选择，不能保证所有非法预算都能自动修复。
 
 网关内部 deployment fallback 与 CLI 切换模型/endpoint 是两层机制。
@@ -218,3 +228,21 @@ CCL 将响应读取中断与用户取消区分处理。半截响应尚未执行
 任务是否完成还取决于 `stop_reason` 和工具结果。
 恢复诊断包含网关 request ID、底层连接错误及恢复阶段。连续中断会停止自动恢复并返回失败，
 不会无限重试，也不声称修复了 VPN 或网关自身的连接问题。
+
+# 记忆提取未完成的提示
+
+以下提示适用于 `1.5.1-alpha`；正在运行的旧进程不会因为源码或安装更新而自动采用新提示，需要正常退出后重启。
+
+`Memory extraction did not complete (...); saving is not confirmed` 表示本次提取没有满足完整结束和工具结果确认条件，不能据此宣称这些输入已全部保存。括号里的原因来自实际分支，例如：
+
+- `api_error` / `transport_incomplete`：模型请求返回 API 错误，或响应未完整收到。
+- `max_turns`：达到记忆提取自身的 5 轮上限；不是父子任务共享纠错轮次。
+- `tool_error` / `tool_result_unconfirmed` / `tool_result_mismatch`：工具调用失败或被拒绝、缺少匹配成功结果，或调用与结果关联异常。可能已有部分成功写入，但整次尚未确认。
+- `output_limit` / `response_not_finished`：最终响应达到输出限制，或没有完整结束。
+- `system_blocked` / `interrupted` / `runtime_error`：系统阻断、取消中断，或提取处理抛出异常。后者没有足够信息细分时不猜测是网络或权限问题。
+
+同一失败期间不会重复显示相同原因，出现新的失败类别仍会提示。下一次符合提取条件的正常回合可重试原输入；这不是退出后必定重试的承诺。`Memory extraction checks have resumed` 只说明检查恢复，不说明历史所有信息都已保存；成功写入通知是另一个事件。
+
+原因提示不附加任意模型/工具正文、路径或异常文本；现有本地调试日志仍可能包含详细错误，不能把整份日志默认当成可对外公开的材料。此修复不提高预算、不新增全记忆扫描、不改变按需读索引和主题文件，也不使宿主记忆成为可靠业务账本。
+
+旧 `Memory lookup is incomplete...` 属于已移除的自动发现路径，与这里的提取提示不同。看到旧文本时应区分历史记录重绘与旧进程的新消息，核对实际安装和运行版本，不能靠新源码中没有这句话就判定运行中的进程已更新。

package/docs/features/business-facts.md

@@ -2,9 +2,7 @@
 
 本能力是本地业务记录器。启用后自动记录后续输入/公开回复的引用、真实工具执行及结果、恢复、运行终态和可观察的加载版本。查询和导出不调用模型、网关、analytics 或 op-hog；无需账号升级。业务结果的解释与跨来源分析交给 FDE。
 
-本能力已于 2026-10-11 通过当前 RLL 协议 Lisa 的 R5 CODE 审核及 R6 技术收口。随后按用户要求将本机候选版本提升为 `1.4.5-rc.7`，用明确版本号区分此前的 rc.6；重启客户端后生效。当前为本机试用候选，尚未推送或发布。FDE 跨来源业务分析属于下游工作，不作为 CCL 技术收口的前置条件。版本调整后的构建与安装检查另有回执，历史审核摘要仅对应当时构建。
-
-后续复盘发现未知工具、执行前中断和排队终止可能绕过采集；已补修并完成定向验证，于 2026-10-11 获当前协议 Lisa R5 CODE PASS；本次结论覆盖这三条补修路径，不以历史审核代替新验证。补修候选 CLI SHA-256 为 `437428af802ac9b90d10f2029f6f096bfb4475b7ead9e447a63bc86309847256`。这些未执行路径记录请求与失败/取消，不产生 `tool_started`；取消状态保留 `cancelled:system_interrupted`、`cancelled:user_interrupted` 或 `cancelled:query_stopped` 等区别。旧导出的漏记不会自动补造。
+未知工具、执行前中断和排队终止也会进入采集。这些未执行路径记录请求与失败/取消，不产生 `tool_started`；取消状态保留 `cancelled:system_interrupted`、`cancelled:user_interrupted` 或 `cancelled:query_stopped` 等区别。旧导出的漏记不会自动补造。
 
 ## 启用
 
@@ -112,4 +110,4 @@ python3 <FDE工具根>/tracker.py --root <FDE项目> fde-query --project custome
 
 源码与产物已在 macOS/arm64 做隔离验证。WezTerm GUI 当时不可连接；实际 Ink TUI 的 slash 绑定/状态通过独立 PTY 验证，不能把它称为 GUI 验证或跨平台验收。真实模型演示使用本地测试网关和合成客户文件，没有发送客户生产提醒，也未完成跨来源业务语义联合验收。
 
-本能力不迁移既有 transcript，不改账号、网关或云端；回退旧客户端会保留新增账本。本机安装替换已按用户后续授权完成；发布及网关上线仍不在本次授权范围。
+本能力不迁移既有 transcript，不改账号、网关或云端；回退旧客户端会保留新增账本。

package/docs/hook-input-provenance.md

@@ -0,0 +1,120 @@
+# UserPromptSubmit input identity
+
+## Query and Stop correlation (1.5.1-alpha candidate)
+
+Native `Stop`, `SubagentStop` and `StopFailure` payloads can include an optional
+`query` observation. Check that it exists and that `query.record.version === 1`;
+older hosts provide no exact query association. A Stop is a **checkpoint before
+the loop may continue**, not a completion notification. `StopFailure` retains its
+failure semantics. Existing text and hook blocking behavior remain unchanged.
+
+The observation contains `record`, `persistence`, and `transcript_path`. The record
+has `session_id`, `query_id`, `event_id`, `sequence`, `phase`, `attempt`, `scope`,
+`agent_id`, `accepted_inputs`, `input_message_ids`, `input_association`, and
+`last_assistant_message_id`. Each independent query, including children and helpers,
+gets a new query ID. Retries, tool rounds and blocked Stop continuations retain that
+ID; every checkpoint gets its own event ID. Two identical answers are distinguishable
+without comparing their text. A copied parent context does not copy query identity.
+
+`accepted_inputs` lists the new input identities actually accepted into the query,
+with their recorded origin. `input_message_ids` is the subset handed to the host
+model adapter after the query's compaction/recovery selection. It does not prove
+remote receipt or understanding. Blocked/unvisited queued inputs are excluded;
+accepted inputs cancelled before dispatch are not in this subset. Earlier handoffs
+survive compaction. Unknown historical or transferred-query association stays
+`input_association: "unknown"`; do not substitute the latest user message. These
+identities grant no authority and do not turn host/agent reports into human input.
+
+The separate `system/query_lifecycle` stream reports `start`, `stop_attempt`,
+`stop_failure` and `terminal` observations. Only `terminal` has a status:
+`completed`, `failed`, `cancelled`, `stopped` or `interrupted`, with the raw
+`terminal_reason`. This is the end of that query loop, not business completion,
+delivery to a user, all background work finishing, or the outer SDK result.
+An API-error response can be `failed` even when a legacy raw reason is `completed`.
+Consumer closure records interruption/cancellation without yielding more events to
+that closed consumer. Process death can leave only a start/checkpoint, with no end.
+
+TUI stores these observations without displaying them or sending them to the model.
+Headless stream-json emits them; the SDK yields typed `query_lifecycle` events.
+Durable background run events retain their native envelopes without treating them
+as the run's final result. Observe the outer SDK result and validate the requested
+business outcome separately.
+
+Use the packaged SDK to read the **specified file and original query identity**,
+including when processing a delayed first-round hook after a second round ends:
+
+```js
+import { readQueryLifecycle } from '@margay/ccl-core/sdk'
+
+const observation = hookInput.query
+if (observation?.record.version === 1 && observation.transcript_path) {
+  const state = await readQueryLifecycle({
+    transcriptPath: observation.transcript_path,
+    sessionId: observation.record.session_id,
+    queryId: observation.record.query_id,
+  })
+  // state === found with completeness === complete exposes the original terminal.
+  // incomplete / not_found / unavailable never prove success or non-execution.
+}
+```
+
+The file format is JSONL metadata `{ "type": "query_lifecycle", "record": ... }`,
+separate from the conversation UUID/parent chain. The reader does not search other
+sessions, start a host/daemon, repair a log or replay tools. Exact repeated events
+are deduplicated; conflicting identities, invalid records and an unterminated tail
+are unavailable. A missing start, event sequence gap or absent terminal is incomplete.
+It streams the file with a 32 Mi-character per-line limit; exceeding that limit is
+unavailable, not a partial success. No matching record in a readable old file is
+`not_found`, not evidence that execution never occurred.
+
+Persistence is separate from execution: `saved` means the queued local write and
+flush succeeded (process-crash recovery, not power-loss durability); `unavailable`
+means persistence was disabled or the query has no transcript; `failed` means a
+write failed. A write exceeding two seconds returns `unknown/write_timeout` and
+stops further waits on that query writer. The OS write may still finish with the
+same event ID; read the original query later rather than replaying its tools.
+There is no automatic execution or permission replay when a terminal is absent.
+
+## Input provenance
+
+Introduced in 1.5.0-alpha.3: structured identity for native `UserPromptSubmit` hooks. Verify the actual host CLI version; older installations do not gain this behavior from a documentation update.
+
+```json
+{
+  "hook_event_name": "UserPromptSubmit",
+  "session_id": "current-session",
+  "prompt": "Read the synthetic material.",
+  "message_id": "stable-input-uuid",
+  "origin": {
+    "kind": "human",
+    "provenance": {
+      "version": 1,
+      "actor": "human",
+      "source": "repl_main_thread",
+      "session_id": "current-session"
+    }
+  }
+}
+```
+
+The usual base fields (`cwd`, `transcript_path`, permission mode and applicable agent identity) remain. `message_id` and `origin` are optional in the reading schema for older hosts; this producer supplies them. Missing or unfamiliar metadata is unknown provenance. Consumers must not infer human authority from XML-looking text, `type: user`, or the mere occurrence of a hook. Host metadata describes input origin, not permission to perform an action.
+
+`prompt` is the submitted text, after normal CLI paste expansion and trimming. For content-block input it is the existing text projection, not a serialization of images. `message_id` is the accepted input's UUID and matches the original transcript user message. Two identical requests submitted separately have separate IDs. A hook may run before its message is persisted, and a blocked/cancelled submission need not become an accepted transcript message; use the hook payload itself when recording the submission. Pair message identity with `session_id` when storing provenance across sessions.
+
+Keyboard input queued during startup or an active tool turn receives its own hook when consumed, before delivery to the model. Busy input keeps the mid-turn delivery behavior. Its original text and origin are persisted as a normal user message instead of being available only inside a preceding tool result. Multiple queued inputs run independently, and returned `additionalContext` is associated with its producing input through the attachment's `source_uuid`; model-facing context includes that same message ID. Persisting hook additional context on resume still follows the existing `CLAUDE_CODE_SAVE_HOOK_ADDITIONAL_CONTEXT` opt-in. This setting does not control original human-message persistence.
+
+Native task/agent completion notifications, coordinator inputs, and SessionStart/recovery automatic prompts do not run `UserPromptSubmit` as human submissions. Their native origin remains available in the transcript. Suppressing a human-input hook does not hide a task notification from the user: visibility is controlled independently by `isMeta`. A human literally quoting notification syntax remains human input.
+
+For SDK/control-channel consumers, these fields are present in the native `hook_callback.request.input` for `UserPromptSubmit`; the convenience SDK `onUserPromptSubmit` submission notification is a separate API and is not a substitute for this native hook event. Preserve the existing SDK input-provenance envelope when sending host/agent reports.
+
+A blocking hook excludes that input from model delivery; a continuation stop retains the current input, displays the hook's stop reason, and stops the turn. During mid-turn consumption, unvisited queued commands remain queued on cancellation or failure. Claimed inputs are not automatically re-fired after a hook has started. Resume loads previously persisted messages with their identities and does not re-run their submission hooks; new keyboard inputs receive new identities, and new SessionStart recovery work stays nonhuman. This is not an exactly-once guarantee for plugin side effects across a process crash. Plugins must handle their own durable deduplication and enforce the user's actual authority and scope.
+
+Main-agent `initialPrompt` is a separate automatic event (`source: agent-initial-prompt`, `actor: unknown`), not part of the human's original text. `unknown` here explicitly means it is not an authenticated human instruction; the named source identifies the configured producer. This reuses the existing provenance v1 contract: `host`/`agent` reports require a referenced human request, which startup work may not have. Configured startup slash commands still use the ordinary command loader and permission checks, and their original command text is preserved alongside expanded method content. TUI can process ordinary automatic and human startup messages in one model turn; headless retains the existing per-input turn lifecycle.
+
+Text-mode startup injects the configured agent prompt independently of the prompt argument. SDK stream input injects it after `initialize` has installed hooks and agent definitions; repeated `initialize` does not reinject it. A new process startup may create a new configured automatic event, including on resume; that is distinct from replaying a saved historical event. Historical records retain their existing identity. Source-unknown legacy history stays unknown and cannot be referenced as a verified human request.
+
+Public queue consumers do not infer human identity from an absent origin. Keyboard, voice, the SDK user-input API and authenticated bridge user-input boundaries supply explicit provenance; legacy SDK user envelopes retain their documented human-input API meaning, which is a host assertion, not independent authentication. Explicit synthetic/nonhuman metadata remains nonhuman. Timer and channel producers retain their own origins. Queue-operation records carry optional `message_id` and `origin` for matching enqueue/dequeue/remove to the input; old records without those fields remain readable and unclassified. A retry of an existing event retains its ID; submitting the same text as a new request receives a different ID.
+
+Between-turn batches now consider every accepted input: blocking one does not deliver its content or suppress a later accepted input; a hook continuation stop suppresses the batch's model call. Cancellation or a thrown processing failure retains untouched commands for later consumption with their IDs. A claimed input is not automatically replayed merely because its hook failed. Existing command-hook timeout policy is unchanged: timeout produces a cancelled hook outcome and does not by itself block the input. Observe command-hook lifecycle through `--print --verbose --output-format stream-json --include-hook-events`; input result success does not imply that every hook succeeded. Use an explicit blocking hook outcome where supported when policy requires blocking. Consumers remain responsible for durable side-effect deduplication.
+
+This is a generic host contract. Assistant applications bind principals, decide business authorization, maintain task/source ledgers and perform their own end-to-end acceptance. No assistant-specific text or business schema is recognized by this mechanism. A release/version and downstream integration must be verified separately; the current local source candidate is not a published upgrade.

package/docs/index.md

@@ -1,105 +1,39 @@
-# CCL Official Documentation Index
+# CCL / Margay documentation
 
-This index defines the current authoritative documentation set for CCL
-`1.4.5-rc.4` source candidate (locally validated; not published to npm in this delivery). If another markdown file disagrees with the files linked here, treat
-the linked file or the source code as authoritative and update the stale file.
+## Installation and use
 
-## Authority Order
+- [Quick start](../QUICKSTART.md)
+- [Installation and upgrades](cli-installation.md)
+- [CLI features](../README.md)
+- [Gateway setup](gateway-quickstart.md)
+- [Error recovery and task budgets](error-recovery-usage.md)
+- [IDE integration](ccl-ide-usage.md)
+- [Duo agents](ccl-duo-agent.md) and [peer review](peer-development-review.md)
+- [Context checkpoints and daemon](context-checkpoints-and-daemon.md)
+- [Copy on select](features/copy-on-select.md)
 
-1. Runtime source and generated CLI output: `package.json`, `dist/cli.js
-   --help`, command sources under `commands/`, SDK sources under `sdk/`.
-2. Current official docs linked from this page.
-3. Historical reports under `docs/` that are not linked here.
+## Host integration
 
-Historical reports can explain past decisions, but they are not current setup
-instructions.
+- [SDK overview](../sdk/README.md) and [API contract](../sdk/API.md)
+- [Durable background tasks and assistant handoff (1.5.1-alpha)](background-runs.md)
+- [Command recovery](command-tool-recovery.md) and [MCP recovery](mcp-tool-recovery.md)
+- [Runtime resources](runtime-resources.md)
+- [Hook input provenance](hook-input-provenance.md)
+- [Shared skill resources](shared-skill-resources.md)
+- [Assistant example](../examples/assistant/README.md)
+- [Operations integration](operations-client-integration.md)
 
-## Start Here
+## Analytics and development
 
-| Need | Document |
-|---|---|
-| First install and first session | [QUICKSTART.md](../QUICKSTART.md) |
-| Full package entry point and feature map | [README.md](../README.md) |
-| Margay website account and manual gateway setup | [docs/gateway-quickstart.md](./gateway-quickstart.md) |
-| Source checkout validation | [docs/dev-quickstart.md](./dev-quickstart.md) |
-| Legacy intent gateway migration note | [INTENT-GATEWAY-GUIDE.md](../INTENT-GATEWAY-GUIDE.md) |
-| SDK overview | [sdk/README.md](../sdk/README.md) |
-| SDK API contract | [sdk/API.md](../sdk/API.md) |
-| Recovery prompts, output limits, and external blockers | [Recovery guide](./error-recovery-usage.md) |
-| Candidate delivery and local upgrade | [1.4.5-rc.4 release notes](./releases/1.4.5-rc.4.md) |
-| What analytics can currently show/control, and remaining gaps | [Current capability report](./analytics-capabilities-2026-10-08.md) |
-| Local event upload, statistics UI and feature switches | [Local analytics guide](./local-analytics-quickstart.md) |
-| Event schemas, typed queries and validation limits | [Product events and queries](./self-hosted-product-events.md) |
-| Historical documentation inventory | `docs/official-docs-coverage-matrix.json` (source checkout only; omitted from npm) |
+- [Local analytics](local-analytics-quickstart.md)
+- [Product events](self-hosted-product-events.md)
+- [Business facts](features/business-facts.md)
+- [Build from source](dev-quickstart.md)
 
-## Feature Coverage Map
+## Release notes
 
-| Feature Area | Current Source |
-|---|---|
-| Package version, install, runtime requirements | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), `package.json` |
-| Interactive TUI and slash commands | [README.md](../README.md), `commands/` |
-| Non-interactive CLI, `--print`, JSON and stream JSON | [README.md](../README.md), `dist/cli.js --help` |
-| Authentication: gateway, OAuth, API key | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), [docs/gateway-quickstart.md](./gateway-quickstart.md) |
-| Gateway registration, login, status, doctor, logout | [docs/gateway-quickstart.md](./gateway-quickstart.md), `commands/gateway/` |
-| Model, endpoint, priority, effort controls | [README.md](../README.md), [QUICKSTART.md](../QUICKSTART.md), `commands/model/`, `commands/endpoint/`, `commands/priority/`, `commands/effort/` |
-| Permissions and tool allow/deny controls | [README.md](../README.md), `commands/permissions/`, CLI help |
-| Session resume, continue, fork, compact, rewind, clear | [README.md](../README.md), CLI help, `commands/resume/`, `commands/compact/`, `commands/rewind/`, `commands/clear/` |
-| Workflows | [README.md](../README.md), `commands/workflows/`, CLI `workflow` command |
-| MCP, plugins, skills, hooks | [README.md](../README.md), `commands/mcp/`, `commands/plugin/`, `commands/skills/`, `commands/hooks/` |
-| Agents, subagents, buddy, branch/fork | [README.md](../README.md), `commands/agents/`, `commands/buddy/`, `commands/branch/` |
-| Remote control, remote sessions, remote env | [README.md](../README.md), `commands/bridge/`, `commands/session/`, `commands/remote-env/` |
-| IDE, Chrome, desktop, mobile, terminal and web setup | [README.md](../README.md), matching command sources under `commands/` |
-| Review, security review, PR comments, commit helpers | [README.md](../README.md), `commands/review*`, `commands/security-review.ts`, `commands/pr_comments/`, `commands/commit*` |
-| Usage, cost, stats, rate limits, extra usage | [README.md](../README.md), matching command sources under `commands/` |
-| SDK query, permission interception, pending approvals, resume, usage store | [sdk/README.md](../sdk/README.md), [sdk/API.md](../sdk/API.md), `sdk/` |
-| Output-budget clamps and agent recovery consent | [Recovery guide](./error-recovery-usage.md), [gateway guide](./gateway-quickstart.md), [SDK API](../sdk/API.md) |
-| Local telemetry, analytics.query gate and typed analytics | [User guide](./local-analytics-quickstart.md), [contract and evidence](./self-hosted-product-events.md) |
-| Developer build and validation | [docs/dev-quickstart.md](./dev-quickstart.md), `package.json` scripts |
+- [1.5.0-alpha.4](releases/1.5.0-alpha.4.md)
+- [Host fixes included from alpha.3](releases/1.5.0-alpha.3.md)
 
-## Agent Instruction Files
-
-The following files affect agent behavior and must be treated as documentation,
-but with different audiences:
-
-| File | Classification | Audience |
-|---|---|---|
-| `AGENTS.md` | internal agent/runtime instruction | Agents operating in this repository |
-| `CLAUDE.md` | compatibility instruction | Claude-family agents and RLL role routing |
-| `CODEX.md` | compatibility instruction | Codex-family agents and RLL role routing |
-| `CCL.md` | project-local memory/instruction candidate | Agents operating in this checkout |
-
-Public user docs should link to these only when explaining repository-local
-agent operation. They are not end-user setup guides.
-
-## Safety And Staleness Policy
-
-Current official docs must not contain:
-
-- Real API keys, gateway tokens, shared team keys, or admin tokens.
-- Concrete production IP addresses unless explicitly approved for public docs.
-- Legacy endpoint strings presented as current setup.
-- Version claims that disagree with `package.json`.
-
-Use placeholders:
-
-```text
-<GATEWAY_URL>
-<GATEWAY_TOKEN>
-<ANTHROPIC_API_KEY>
-<INVITE_CODE>
-```
-
-## Coverage Matrix
-
-The historical machine-readable inventory (generated 2026-07-06) is
-`docs/official-docs-coverage-matrix.json` (source checkout only; omitted from npm).
-Each markdown file in the official audit scope is classified as one of:
-
-- `keep`
-- `rewrite`
-- `split`
-- `archive`
-- `delete`
-
-The matrix is a dated planning and audit artifact, not a fresh audit of rc.1. It does not make archived reports
-authoritative.
+Use `ccl --version` to check the installed version. Updating an installation does
+not replace an already running CLI process.

package/docs/local-analytics-quickstart.md

@@ -1,10 +1,6 @@
 # 本地埋点、统计和功能控制
 
-先了解范围：[现在能看到什么、能控制什么、还缺什么](analytics-capabilities-2026-10-08.md)。
-
-2026-10-08 本机已将 `ccl` 入口升级到已评审的分析功能构建，`margay` 入口保持原版本。本页命令直接使用 `ccl`；从源码工作区运行时，可将它替换为 `node dist/cli.js`。本轮本机候选版本为 `1.4.5-rc.4`，仅更新 `ccl`；`margay` 保持原安装。安装记录以实际 CLI 哈希为准，待用户手工测试通过并明确通知后才推送发布。
-
-当前平台仅在本机隔离环境运行。升级不修改已有登录/网关，不自动开启采集。上传和查询需要本地分析网关 `http://127.0.0.1:19803` 已登记的测试网站账号；普通聊天密钥或生产网站账号不会自动获得本地分析权限。不要为了测试覆盖日常配置；使用独立配置与获授权的本地账号。平台凭据、测试账号和配置文件不应发到聊天或文档中。
+本页介绍本地分析命令。网关服务须另外配置；安装 CLI 不会自动部署服务或开启采集。
 
 ## 三种控制各管什么
 
@@ -16,11 +12,11 @@
 
 `DISABLE_TELEMETRY=1` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 优先关闭非必要采集，但不禁止已获授权的统计查询。手工模型凭据/显式环境覆盖可以用于聊天，不作为网站账号上传或查询身份。
 
-本地 gate 设置属于当前 CLI 配置目录，在账号切换后继续生效。它只收紧功能，不授予任何账号权限。客户端登记了 analytics.query、analytics.report、analytics.report.layout、cli.session；保留网关只登记 analytics.query。并非所有旧 CLI 功能都已接上新远端门；旧本地 capability 行为保留。
+本地 gate 设置属于当前 CLI 配置目录，在账号切换后继续生效。它只收紧功能，不授予任何账号权限。客户端登记了 analytics.query、analytics.report、analytics.report.layout、cli.session；实际可用范围取决于服务端登记。并非所有旧 CLI 功能都已接上新远端门；旧本地 capability 行为保留。
 
-### 本机候选版通用功能门入口
+### 功能门入口
 
-`1.4.5-rc.4` 候选版包含 `features` 命令，安装后可直接运行：
+通过 `features` 命令查看和控制本地功能门：
 
 ```sh
 ccl features list
@@ -31,11 +27,11 @@ ccl features auto analytics.query
 
 `list` 列出 CCL 已登记的消费点及本地设置，不联网核验远端权限；`status` 检查生效决策，不计曝光。`off` 和 `auto` 与旧 `analytics gate` 共用 analytics.query 的设置，切号后仍保留；没有强制 `on`。远端拒绝时 auto 也不能放行。新 `features status` 在无法取得有效决策时显示 `source=unavailable` 并退出 1，便于脚本判断；旧 `analytics gate status` 的退出行为保留。
 
-当前源码目录包含 analytics.query、analytics.report、analytics.report.layout 和可选会话结果采集 cli.session；本机保留网关目前仍只登记 analytics.query。不能在平台随意新建一个旗标就改变尚未接入的 CCL 功能；新增消费点还需要客户端声明及业务调用、服务端登记。没有采集同意时实验使用不带分组的基线，查看状态不会产生实验曝光。真实服务的 A/B 分组、曝光和结果已通过隔离联调；这不等于保留网关已登记新能力，upsell 不作为前置条件。
+当前源码目录包含 analytics.query、analytics.report、analytics.report.layout 和可选会话结果采集 cli.session；本机保留网关目前仍只登记 analytics.query。不能在平台随意新建一个旗标就改变尚未接入的 CCL 功能；新增消费点还需要客户端声明及业务调用、服务端登记。没有采集同意时实验使用不带分组的基线，查看状态不会产生实验曝光。服务端必须另行登记所需能力。
 
-候选版提供 `ccl analytics report definition.json`，把与 query 相同的授权查询结果输出为可读报告。它需要服务端登记并允许 analytics.report，也必须通过原 analytics.query 权益校验。`features off analytics.report` 会禁止报告，不改变原 JSON 查询或聊天。
+CLI 提供 `ccl analytics report definition.json`，把与 query 相同的授权查询结果输出为可读报告。它需要服务端登记并允许 analytics.report，也必须通过原 analytics.query 权益校验。`features off analytics.report` 会禁止报告，不改变原 JSON 查询或聊天。
 
-analytics.report.layout 控制完整布局或紧凑预览（最多五行，明确显示省略行数）；实验暂停、异常、无同意或本地关闭均回到正常完整布局，不产生实验分组事件。报告不会根据少量样本宣布胜者。采集已同意时，实际报告调用记录曝光、调用及成功/失败/取消结果；布局票据只进入校验过的事件，不打印到报告。当前已验证客户端逻辑和本地命令，尚不能把这一节理解为保留平台的新旗标已配置完成。
+analytics.report.layout 控制完整布局或紧凑预览（最多五行，明确显示省略行数）；实验暂停、异常、无同意或本地关闭均回到正常完整布局，不产生实验分组事件。报告不会根据少量样本宣布胜者。采集已同意时，实际报告调用记录曝光、调用及成功/失败/取消结果；布局票据只进入校验过的事件，不打印到报告。客户端支持这些命令不代表服务端已经完成旗标配置。
 
 ## 上传与状态
 
@@ -46,13 +42,11 @@ ccl analytics flush
 ccl analytics disable
 ```
 
-启用后，真实会话产生 session_started；候选版会在 cli.session 远端允许时记录会话调用与实际终态，旧网关不支持时维持原行为。允许的实际统计查询产生功能曝光/调用/完成事件。help、version、开关和 gate status 不造使用事件。不上传对话、工具参数、文件路径或凭据。队列有体积、数量和时间上限；status 显示 pending、retryAt 和丢弃分类。flush 的 accepted 表示网关持久接收，不代表统计已可见；retry 表示留队等待重试，disabled 表示当前不上传。网络超时最多等待 3 秒；正常会话退出的最后一次 flush 最多等 1 秒后取消。
+启用后，真实会话产生 session_started；CLI 会在 cli.session 远端允许时记录会话调用与实际终态，旧网关不支持时维持原行为。允许的实际统计查询产生功能曝光/调用/完成事件。help、version、开关和 gate status 不造使用事件。不上传对话、工具参数、文件路径或凭据。队列有体积、数量和时间上限；status 显示 pending、retryAt 和丢弃分类。flush 的 accepted 表示网关持久接收，不代表统计已可见；retry 表示留队等待重试，disabled 表示当前不上传。网络超时最多等待 3 秒；正常会话退出的最后一次 flush 最多等 1 秒后取消。
 
 ## 查看统计
 
-本地平台浏览器入口为 [http://localhost:19800/login](http://localhost:19800/login)；路径终点辅助界面为 `http://127.0.0.1:19801`。使用本机已有的隔离平台账号。浏览器登录请使用 `localhost`：实测同一账号在 `127.0.0.1` 登录接口返回200后仍未保持登录态，而 `localhost` 成功进入项目首页、当前用户接口返回200。不要把这种地址/会话问题误判为密码错误；本地页面仍可能显示未配置TLS的提示。已保存的合成验收分析可以查看和编辑；数据不代表真实运营表现。
-
-在平台的 Activity / Events 中筛选 `session_started`、`feature_exposed`、`feature_invoked`、`feature_completed` 查看事件；在 Product analytics / Insights 中查看或编辑漏斗、留存和路径，在 Experiments 中查看实验。菜单名称可能随界面语言不同；路径终点编辑使用上面的辅助界面。
+使用管理员提供的分析平台地址与账号查看事件和统计。平台的事件、漏斗、留存、路径及实验页面只展示已持久接收且已处理的数据；命令返回成功不表示统计立即可见。
 
 ```sh
 ccl analytics gate status
@@ -65,7 +59,7 @@ gate status 在 auto 模式下新鲜查询远端，显示 enabled、source、rea
 
 ## 控制远端功能门
 
-本地部署的 Feature flags 中，`analytics.query` 对应旗标 `ccl-runtime-ba2997c30177-analysis`（ID 10）。这是当前保留实例的具体名称，重建实例时应查网关登记映射，不照抄旧ID。
+在平台 Feature flags 中查找网关为 `analytics.query` 登记的实际旗标映射，不照抄其他环境的名称或 ID。
 
 可在此调整启停和投放规则。实际查询还需满足网关的账号名单、会员和紧急拒绝规则；平台开启不是授予账号权限。当前没有统一的网关权限管理界面，不应把平台旗标当作会员管理入口。
 
@@ -82,15 +76,4 @@ gate status 在 auto 模式下新鲜查询远端，显示 enabled、source、rea
 | source=unavailable | 当前未取得可用远端决策；检查网关及账号，不能解释为一定没有购买权限 |
 | forbidden / not_entitled | 查询被服务端权限拒绝；本地auto不能强制放行 |
 
-## 数字员工和后续升级
-
-基础员工位于相邻网关工作区 `src/client-operations/employee.ts`，已通过实际 SDK 查询、预授权测试灰度、独立读回和报告验证。它默认不运行，不进入正常 CLI 启动路径，不常驻调度。运行配置固定 SDK/CLI 哈希；构建升级后旧配置会拒绝启动，需要操作者核对新产物后更新固定版本，不能默默使用变更的二进制。
-
-目前无真实运营需求，保留现有入口与证据即可。完整 gap 和升级触发条件见主协作仓库 `docs/feature-gate-gap-and-upgrades-2026-10-08.md`。
-
-
-## 本轮开发联调边界（2026-10-08）
-
-开发构建已在独立账号/数据库/网关实例完成真实上传、两种报告布局消费、漏斗/留存/路径读回及远端/本地关闭检查，本轮仅更新本机 CLI，保留网关 19803 未升级。小样本 significant:null 的网关兼容修复已在独立网关仓提交并通过隔离验证；保留网关尚未加载该修复，因此其相关实验查询仍可能 unavailable。测试数据不能代表真实运营表现。
-
-新增功能的实际步骤、协议和限制见 [客户端接入规范](operations-client-integration.md)。普通会话终态已完成开发版隔离 CLI 验证；保留网关未登记 cli.session，独立协议接入样例已提供在 examples/operations，生产 SDK 和平台准入仍待后续。
+协议与客户端消费边界见 [接入规范](operations-client-integration.md)。

package/docs/mcp-tool-recovery.md

@@ -0,0 +1,82 @@
+# 【公开】MCP 工具失败与恢复
+
+本页描述 `1.5.1-alpha` 的 MCP 恢复接口。C3 操作级持久查询/恢复及主、子助手与 CLI/SDK 消费链已完成限定范围的独立审核；这不代表 #55 整体完成。正常 MCP 工具不需要新配置。共用工具执行器会保存操作身份、派发及实际结果；可选适配器进一步提供跨进程回执查询和受控恢复。独立后台执行使用 [BackgroundRun](background-runs.md)，不能把保存操作记录当作后台任务已经接管。
+
+## 为什么不能遇到断线就重跑
+
+工具可能已经发出消息、写入文件或完成订单，随后回执丢失。连接断开只说明没有得到可靠结果，不能说明动作没执行。CCL 会让失效连接退出缓存，后续独立调用仍可重连；原动作是否重放另行判断。
+
+错误会保留实际原因及 operationId/attemptId。`effect=not_dispatched` 表示这次操作没有进入工具派发；`effect=unknown` 表示可能已有副作用。后者应通过工具已有的查询能力或真实产物核对，不凭助手记忆推断失败，也不换一个工具名重复同样动作。
+
+取消请求不等于远端已经停止。调用后超时、取消、鉴权失败和工具 `isError` 都可能是 unknown。调用前取消则明确未派发，不能回报成功。
+
+主助手 SDK 的工具错误 envelope 在 `mcpMeta._meta['ccl/recovery']` 中携带宿主事实；现有 SDK 事件消费会将它并入 `tool_use_result._meta`。子 agent 的现有 envelope 不透传 mcpMeta，错误文本仍携带身份和 unknown；不能声称子 agent 已得到同样的结构化接口。服务器不能覆盖宿主保留字段，普通服务器 _meta 保留。
+
+## 可选自动重试
+
+默认不自动重放未知操作。工具提供者若具有可靠的只读或相同输入幂等契约，可由宿主维护者在已有 MCP 配置内设置 `toolRecovery`。该配置只控制自动重试，不改变工具权限，不注入新的 MCP 参数。
+
+每个精确工具名绑定 `adapterVersion`、`targetDigest`、`inputSchemaDigest` 和 `replay`（read_only 或 idempotent）。摘要算法由 `services/mcp/recovery.ts` 的 `mcpRecoveryDigest`/`mcpRecoveryTargetDigest` 定义：递归排序对象键、保留数组顺序、移除 undefined 对象值，对 JSON UTF-8 编码作 SHA-256；目标摘要不含 scope/toolRecovery，本地进程环境和动态账户还有运行时检查。摘要是配置绑定，不能证明外部系统的幂等语义或身份真实性。
+
+初版仅接受 user/local/managed/enterprise 中显式维护的策略；项目文件、插件附带或动态模型配置不会自动成为重放依据。服务器 hints 必须与策略一致，但单独 hints 不够。OAuth、动态 headersHelper、无法核对运行时账户的连接不会因此得到自动重放能力；这些工具的正常调用仍然可用。需要动态幂等有效期、额外远端查回或进程外账户凭据核验的工具，等待后续适配器接口，不靠声明强行开启。
+
+重连后重新检查工具 schema、连接配置、能力和现有权限。参数包括原幂等键必须保持不变。最多两次实际调用，session 恢复与 URL 授权共用一次重放预算；完成 URL 授权不代表有权重做原写操作。底层 SDK 在 tools/call 的 401/403 后也不能绕过该规则自动重发，但连接初始化/发现的原鉴权流程保留。
+
+## 前台退出或执行器崩溃
+
+经 CCL 共用工具执行器调用的 MCP 操作会在派发前建立持久记录；错误和成功结果元数据关联同一个 operationId。可以用 `ccl operations get <operationId> --json` 读取已保存事实，不必 resume 原聊天。旧 transcript 或绕过宿主执行器直接调用底层客户端，不因此获得持久恢复承诺。前台断开但独立执行器仍在运行，与执行器本身崩溃是不同情况。
+
+## 注册跨进程查询
+
+宿主维护者在配置目录（默认 `~/.ccl`）的 `operation-adapters.json` 注册 `mcpAdapters`。模型只选择已注册的引用，不能提交命令、回执或配置路径来改写恢复规则。下面的示意值必须替换成实际工具名、账户/版本及 schema 摘要：
+
+```json
+{
+  "schemaVersion": 1,
+  "mcpAdapters": {
+    "orders": {
+      "server": "orders",
+      "adapterVersion": "1",
+      "targetIdentity": "tenant-42",
+      "execute": { "name": "start", "inputSchemaDigest": "<sha256>", "handlePath": ["job", "id"] },
+      "identity": {
+        "name": "whoami", "inputSchemaDigest": "<sha256>", "arguments": {},
+        "targetPath": ["account"], "versionPath": ["version"]
+      },
+      "query": {
+        "name": "status", "inputSchemaDigest": "<sha256>",
+        "inputs": { "requestKey": ["requestKey"] },
+        "operationInputs": { "jobId": "remoteHandle" },
+        "statusPath": ["status"], "appliedStatus": "complete",
+        "receiptPath": ["receipt"], "resultPath": ["result"],
+        "bindings": [{ "response": ["requestKey"], "input": ["requestKey"] }]
+      },
+      "replay": "never",
+      "credentialRef": "orders-primary",
+      "credentialHeaders": ["Authorization"]
+    }
+  }
+}
+```
+
+`inputSchemaDigest` 使用完整 `tools/list` inputSchema 的规范 JSON 摘要（对象键递归排序、数组顺序保留、SHA-256），不是描述文本摘要。普通 execute 参数保持原样。`query.inputs` 从原获准输入取值；`constants` 可提供固定查询参数；`operationInputs` 只可使用宿主保存的 operationId、requestKey 或 remoteHandle。路径用字符串数组，空数组表示整个对象。字段缺失不会猜值；远端句柄尚未保存时不能按一个新句柄重建原任务。
+
+`identity` 是现有的只读身份查询，必须返回当前实际账户和版本；首次执行及恢复都核验。`query.bindings` 把回执中的业务标识与原输入逐项对应，错配保持 unknown。只有配置的完成状态和匹配回执才确认效果。状态值可为字符串、数字或布尔值，`appliedStatus` 默认 `applied`，`inProgressStatus` 默认 `in_progress`。查询返回运行中时，可用 `handlePath` 保存原任务句柄；业务是否达到用户要求仍由 assistant 判断。
+
+`replay` 默认 `never`。确有只读契约时可声明 `read_only`；确有相同输入幂等契约时可声明 `idempotent` 并提供 `idempotency: {scope, retentionMs}`。CCL 保留原输入和业务键，超过保留期不能据旧声明重放。该声明必须由外部服务兑现，不能仅凭模型建议或 server hint 添加。
+
+凭据保留在现有 MCP 配置中。`credentialHeaders`/`credentialEnv` 仅声明哪些凭据值可以刷新；引用名、名单、普通环境、URL/命令、schema 或映射改变均改变绑定。同一账户的凭据刷新可恢复；切换账户不能。首次调用的活连接与当前配置不一致时需先刷新工具，不能用新连接的身份核验替旧连接背书。仍沿用当前 MCP 配置策略、禁用状态及原工具权限；查询和身份工具也需要各自的当前许可。
+
+CLI 支持 `get`、`events`、`reconcile`、`resume`、`cancel`，也可显式 `submit --adapter mcp:orders --request-key <key> --input <json>` 接受新操作。执行另用 `resume <operationId> --revision <当前revision> --action-id <稳定动作ID>`。`reconcile` 使用同样的 revision/action-id 参数。CLI 非交互模式未获许可时保留等待状态；许可可通过现有 `--allowed-tools` 规则传入，不默认放行。`Operation` 模型工具使用相同核心。取消只请求停止，不能证明远端副作用已撤销。
+
+普通 MCP 调用返回后，宿主另外给模型提供操作引用；原始工具结果保持不变。主助手、子助手和恢复会话都可据此查询。SDK 的 `tool_result` 事件及 `onToolUse` 回调提供可选 `operationReference: {operationId, revision, toolUseId}`；CLI stream-json 对应字段是 `operation_reference`，与具体 tool-use ID 绑定。它来自宿主记录，不从服务端 `_meta` 或业务 JSON 推导。只有已被宿主持久接受的调用才有此引用，旧版本和其他工具可以不提供。
+
+`revision` 是引用生成时的版本，恢复动作前应先 `get` 获取当前版本。`get/events` 是读取最后已提交的记录，`running/dispatching` 不能证明远端现在仍存活；需要当前状态时，仅在 `allowedActions` 支持时显式 `reconcile`。拿到引用或远端句柄都不等于业务完成。
+
+若调用来自 [持久后台任务](background-runs.md)，assistant 可在原会话退出后，先按稳定业务键取回原 run，再读取 `operationReferences` 查询这些操作。宿主在真正派发工具前保存关联；关联保存失败会阻止派发。已有旧版本未捕获的调用不能追溯补齐，空引用不证明外部效果不存在。MCP 服务没有可信 query/幂等契约时，CCL 仍保留 unknown，不为提高“完成率”自动重试写入。后台事件分页只解决执行记录补收，不代替外部服务回执或 assistant 的真实业务送达记录。
+
+## 当前验证
+
+真实环回 HTTP/stdio MCP 服务先记录副作用，再丢回执/退出；测试经过 CCL 动态工具调用，比较实际请求及磁盘计数。旧 HTTP 路径复现两次副作用，旧调用前取消复现成功 `{data:undefined}`；修复后对应行为有回归用例。主/子助手公共 query/toolExecution envelope 使用脚本化模型验证，不冒充真实模型业务验收。
+
+用例入口：`__tests__/integration/mcp-recovery.test.ts`、`__tests__/integration/mcp-recovery-envelope.test.ts`、`__tests__/unit/mcp-recovery-policy.test.ts`。执行时须使用隔离 HOME/config/TMPDIR 与测试拥有的进程，不连接真实业务 MCP。本片不是 #55 完成声明。

package/docs/operations-client-integration.md

@@ -63,15 +63,11 @@ outcome 为 succeeded/failed/cancelled/incomplete；durationBucket 为 lt_100ms
 
 前三类使用 dateRange 与允许的过滤属性；每个项目范围由服务端附加，客户端不能通过改输入越界。结果保留 null 和不足样本原因，不将 null 解释为 false、胜出或失败；报告明确 `watermark=unverified`、`causality=not_established`。
 
-2026-10-08 真实联调发现：原网关拒绝 PostHog 的 `significant:null`，小样本实验查询返回 503 unavailable。CCL 与独立网关工作树现已同时兼容这个合法空值，保留严格类型校验。修复后的隔离真实 CLI 查询已通过：人数/完成数与同一原生实验一致，不足样本与 null 原样保留；不是增加伪样本或改成 false。保留运行实例未升级，因此这一结论仅覆盖开发构建与隔离联调。
-
 ## 新产品验收要求与当前缺口
 
 新产品必须明确自己的稳定身份、项目和环境隔离、同意撤回、存储与生命周期适配，再运行相同协议验收。不得直接复用 CCL 的账号命名空间或复制平台管理凭据。
 
-目前已经在隔离环境实际验证：12 个账号使用两种布局、跨 CLI 进程分组不变、首次曝光去重、重复使用保留完成事件、真实漏斗/留存/路径读回、本地 off、远端拒绝、无同意零上传。样本是测试账号的真实 CLI 操作，不能证明真实运营效果或统计显著。
-
-独立最小协议样例已提供，见 [Python 标准库样例](../examples/operations/README.md)，已在真实隔离服务验证同一 v1 接缝。仍待可发布的多产品 SDK、保留平台/生产准入。普通会话终态已接入并完成隔离真实 CLI 检查，新的 cli.session 远端登记尚未部署到保留实例。数字员工沿用已有基本 SDK 查询/授权动作/报告接缝，完整自动化不作为本阶段门槛。部署、产品管理和运营界面任务在独立仓开展；本次网关兼容修复已在独立工作树验证，尚未部署。
+独立最小协议样例见 [Python 标准库样例](../examples/operations/README.md)。产品上线前仍须验证服务端登记、权限与生产环境准入；示例不替代通用生产 SDK。
 
 
 ## 会话终态能力（开发版）
@@ -97,6 +93,4 @@ print 的真实 SDK result.is_error=false 才记 succeeded，true 记 failed。S
 
 ### 2026-10-08 完整隔离链路复验
 
-修复后的真实 CLI 查询、报告、独立样例与两项目隔离共51条命令通过（协作仓证据 `live-report-20261008T101908Z`）。同一次实验在读回时为compact5人/6次完成、control7人/9次完成；这是测试身份的实际操作，不是运营成效。漏斗12→12，留存与路径均可查。
-
 远端关闭原生layout旗标时，决策接口返回503 feature_unavailable（与分析接口的unavailable不同），CLI显示无分组的完整报告，实验事件不增加；本地off和撤回采集同意仍分别有效。重新开启原生旗标可能增加providerVersion，当前配置会保守拒绝旧版本，不能把直接切回active称为已支持无缝恢复；须按独立平台的版本登记流程处理。

package/docs/peer-development-review.md

@@ -2,7 +2,6 @@
 
 > npm 包的公开命令为 `margay`。下文带日期、提交号和本机 `~/.local/bin/ccl` 的记录属于历史验收；该本机入口不是 npm 安装保证提供的命令，也不代表当前候选已通过回归。
 
-> P1 已完成开发、Lisa 代码与修复审核，以及 C1–C12 全部门禁。验收范围见 源码检出中的历史实施与验证记录 `docs/ccl-peer-dual-agent-p1-validation.md`（不随 npm 包分发）。
 
 在 CCL 的一个界面中，由两个保留独立上下文的 Agent 完成「开发 → 审查 → 修改或完成」。本文的受保护模式是 `/buddy --peer-review`：开发者写代码，审查者检查独立提交副本、运行测试并给出结论。开发者可以质疑结论，但不能自行覆盖审查者的否决。Duo 的当前 v2 审核者则可在普通工作区检查，完成还需执行者核查并接受当前 PASS 和双模型实际请求；详见 [Duo 指南](ccl-duo-agent.md)。
 

package/docs/releases/1.5.0-alpha.3.md

@@ -0,0 +1,17 @@
+# 1.5.0-alpha.3
+
+本版修复通用 CLI/SDK 宿主的输入来源、运行资源、任务存活判断及纠错预算。通过 `alpha` 标签发布；不改变 `latest` 标签。
+
+- **运行资源发现（#53）**：`system/init` 和 initialize 返回版本化 `runtime_resources`；SDK 可重新读取资源快照，不必重建会话。见 [资源协议](../runtime-resources.md)。
+- **人工输入与 Hook 来源（#54）**：UserPromptSubmit 获得稳定输入身份和原始人工内容；自动启动任务、技能展开、工具结果与调度消息不伪装成人工输入。混合启动批次保留各自身份，停止或取消时保留尚未处理的输入。见 [输入来源协议](../hook-input-provenance.md)。
+- **派发阶段 watchdog（#34）**：在异步前处理之前领取查询所有权并开始本次计时，避免把上一轮空闲时间算成本次卡住；旧 owner 的收尾不释放新 owner。保留等待工具、用户响应及真正停滞时的处理。
+- **共享技能资源（#44 的宿主部分）**：明确精确调用身份；稳定 SDK wrapper 名称；实际加载目录绑定到固定版本路径，防止技能正文和引用在链接切换后串版本；SDK 进程结束清理本次临时 wrapper。见 [共享资源契约](../shared-skill-resources.md)。
+- **独立任务纠错预算**：父、子和兄弟任务各自计数；同任务换执行者、前后台切换与恢复保持额度，内部辅助仍计入所属任务。修复子任务刚结束就恢复时，异步 transcript 尚未写入导致误报无记录的问题。见 [错误恢复说明](../error-recovery-usage.md)。
+
+自动纠错与执行 `maxTurns` 不同。本版没有新增模型自行授额、全局资金调度或基于任务正文相似度的判定。恢复指令禁止为刷新额度重派同一失败操作，提示词不能保证阻止所有语义绕行。
+
+旧版本子任务没有纠错历史记录时，恢复可以正常继续，但不会自动追加未知额度；已知记录损坏或缺失会明确失败。保留已有结果，先确认实际阻塞条件，不应靠改名或重建相同失败任务重试。
+
+验证包括选定单元/集成回归、真实 CLI/SDK 原生恢复、localhost provider 的调用与副作用断言、真实终端 watchdog 轨迹，以及真实模型的任务恢复行为用例。部分早期夹具与原生即时恢复曾失败，均保留红转绿记录；不以旧候选测试替代有变化的最终路径验证。
+
+本版不宣称完成 Desktop 的整体资源发布事务、Windows 联验或全部 #44。宿主仍需遵守固定版本目录及明确更新/重载契约。安装新的 CLI 不会替换正在运行的旧进程；新建 CLI 进程或按宿主自己的升级机制使用新版本。

package/docs/releases/1.5.0-alpha.4.md

@@ -0,0 +1,16 @@
+# 1.5.0-alpha.4
+
+修正 npm 发布内容，保留 [alpha.3 的宿主修复](1.5.0-alpha.3.md)。
+
+- 清理 CLI 构建产物中的本机源码路径，包含软链接依赖的真实目录。
+- npm 包保留运行文件、公开使用指南、SDK 契约和示例；移除内部研究导航、实施记录及历史审核报告。
+- `docs/README.md` 改为公开指南入口。
+
+`1.5.0-alpha.3` 已从 npm 撤下。已安装该版本的用户请升级：
+
+```sh
+npm install -g @margay/ccl-core@1.5.0-alpha.4
+ccl --version
+```
+
+通过 `alpha` 标签发布；`latest` 不变。升级后请新建 CLI 进程，已有会话不会自动切换执行文件。