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

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

@@ -0,0 +1,26 @@
+# 1.5.0-alpha.5
+
+本版本修复记忆访问、技能上下文恢复和工具发现的通用宿主问题，并提供 CLI/SDK 共用的工具执行指引。通过 `alpha` 通道交付，`latest` 保持不变。
+
+- **记忆按需读取**：保留 MEMORY.md 索引，取消启动及逐轮无条件扫描、相关性筛选和正文预取。用户或当前指令要求时，通过工具定向查找。记忆提取先判断是否有值得保存的信息，再读索引及相关主题核对；记忆内容仍需按实际来源判断准确性。
+- **技能发现与恢复**：普通子 agent 首次请求可获得有权限且受长度限制的技能目录；模型或上下文预算变化会刷新目录。按资源身份区分同名技能，保留实际来源和调用标识，修复压缩及会话恢复时的技能契约丢失。
+- **共享执行指引**：公开 SDK 导出 `getExecutionGuidance(toolNames)`，默认主助手、Explore 和 Plan 共用执行与调查的边界；保留岗位身份及用户定制。普通文件操作优先合适的专用工具，脚本等使用 Bash，允许获授权的缺工具回退。GitHub URL 不再强制使用 gh，PR 操作按依赖顺序执行。
+- **MCP 工具元数据**：SDK 将 `searchHint` 转发到工具发现元数据，并提供可选 `alwaysLoad` 以请求首轮展示工具定义；这些选项不授予操作权限。
+- **本地追踪记录**：修复关闭 OpenTelemetry exporter 时 Perfetto 请求、工具与权限记录因共享 span 身份而互相覆盖的问题。
+
+共享指引的组合方式见 [SDK API](../../sdk/API.md)。默认系统提示已经包含该指引；自管 `systemPrompt` 的应用可以显式追加。CLI 与 SDK 应固定为同一包版本，不另复制一套 preset，也不覆盖用户 persona。
+
+## 升级与兼容
+
+```sh
+npm install -g @margay/ccl-core@1.5.0-alpha.5
+ccl --version
+```
+
+SDK 应用更新 `@margay/ccl-core` 依赖后，重启实际运行进程。新增技能身份元数据只对包含该元数据的记录生效；旧记录缺少身份时不会猜测补齐，也不会重写旧会话。
+
+## 已知限制
+
+- 本版本不宣称彻底消除模型的多余探查，也没有证明稳定提速；#55 的行为问题继续跟踪。
+- `Agent(run_in_background: true)` 返回启动信息，不等于同一 SDK Session 已释放下一条输入。需要前台继续响应时，应用应维护独立 worker Session 并消费其结果。持久队列、重启恢复、取消和业务交付回执需要应用按实际入口接通并验收。
+- 不改动现有权限边界；专用工具被拒绝不能通过 Bash 或另一个接口绕过。指引存在不保证模型在所有任务中都遵循。

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

@@ -0,0 +1,15 @@
+# 1.5.0-alpha.6
+
+本版本包含 [alpha.5 的通用宿主修复](1.5.0-alpha.5.md)，并修复一条后台任务终态通知遗漏路径。
+
+后台 agent 可能先进入终态，再等待清理并发送完成通知。此前，`TaskOutput`
+在此期间读取结果，会抑制后续模型通知，却没有通知 SDK，导致消费者仍显示任务运行中。
+现在这条读取路径会补发一次结构化 SDK 终态，保留原工具调用 ID 和输出路径；
+失败仍为 `failed`，取消映射为 `stopped`，已通知或重复读取不会再次发送。
+
+SDK 应启用 `includeRaw: true` 消费 `task_started/task_progress/task_notification`。
+用法和失败边界见 [SDK API](../../sdk/API.md)。本次未新增持久任务查询、崩溃后重放
+或自动重派能力；任务状态也不代替业务核验和交付回执。
+
+CLI 与 SDK 应安装相同固定版本，重启需要使用新版本的进程。通过 `alpha` 标签交付，
+不更改 `latest`。本版本不宣称解决 #55 的全部工具绕路或证明稳定提速。

package/docs/releases/1.5.1-alpha.1.md

@@ -0,0 +1,11 @@
+# 1.5.1-alpha.1
+
+本预发布版包含 [1.5.1-alpha 的能力与限制](1.5.1-alpha.md)，并包含以下宿主改进。npm 安装使用明确版本或 `alpha` 标签；发布状态以 registry 为准，`latest` 不随本次预发布更新。
+
+- 后台权限通知在入队前与实际消费时核对原任务、工具调用和当前状态。已经批准、拒绝、取消或终态的旧请求不再要求重复决定，后续结果可以继续送达。TUI、SDK/headless 和 query 中途消费路径共用该规则。仍未批准的请求不自动放行；读取失败不视为已解决，事件历史与原身份保留。见[后台任务说明](../background-runs.md)。
+- 原生 Write 与工作流文件工具支持显式 create-only 写入：目标已存在时原子拒绝，不覆盖原文件。具体参数与平台限制见 [SDK API](../../sdk/API.md)。
+- 查询诊断关联输入、停止检查点和终态结果，便于区分主会话停止与后台任务状态；诊断不证明远端执行者当前仍存活。
+
+本次权限通知修复通过相关单元/集成测试，以及真实 SDK 和有头 TUI 模型场景：已决权限不再送入前台要求重复批准，原任务只发布一次并送达真实回执；未批准近邻保持等待。它不替代 Pepper 业务接入验收，不承诺所有模型措辞或历史 incomplete_stream 问题均已解决。
+
+升级时保持 CLI 与 SDK 使用同一版本。旧运行进程不会热更新；先核对原任务状态，正常结束并重启后采用新代码。不要因状态未知而换键重派写操作。Windows 和断电恢复等未验证边界沿用上一版说明。

package/docs/releases/1.5.1-alpha.2.md

@@ -0,0 +1,17 @@
+# 1.5.1-alpha.2
+
+本预发布版在 [1.5.1-alpha.1](1.5.1-alpha.1.md) 的基础上修复 #60 的周期后台任务权限交接及通知恢复。安装使用明确版本或 `alpha` 标签；npm 实际发布状态以 registry 为准，`latest` 保持不变。
+
+- 新建后台 schedule 按任务保存创建会话的有效权限模式与可委派规则。共享 daemon 不因某项任务全局提权；执行时重新加载持久配置。真正需要审批的工具暂停并通知原会话，避免已授权动作因 SDK 回调路由而无声挂起。
+- 挂起先冻结执行、保存 transcript 和原调用凭据，再确认退出；断连不冒充用户拒绝。批准绑定原 occurrence、pending revision、requestId、toolUseId 与稳定 actionId。恢复上下文保留完整原参数，执行前继续严格校验，防止同名工具或参数变化误用批准。
+- TUI、持续运行的 SDK/headless 主循环接收原会话的待批及结果通知；离线后可恢复原会话补收。已有决定的旧审批在队列消费前再次核对，不反复询问。同一 pending 跨周期合并不会重复申请批准。
+- SDK 提供 occurrence 查询、事件分页、精确审批和取消；模型沿用 `BackgroundRun occurrence_id`。`CronCreate operation: reauthorize` 显式更新未来调度的授权及接收会话，既有待批 occurrence 不被新授权升级，也不吞掉新 revision 的触发。
+- 审批决定及恢复意图先持久化再启动执行；owner 崩溃后保留 interrupted 和原收据，不盲目重放结果未知的调用。
+
+入口、参数和模式差异见[后台任务说明](../background-runs.md)。旧 `daemon approve <id> allow` 缺少精确身份，改为返回迁移说明；消费者应使用 `approve-occurrence` 或 SDK `approveOccurrence`。actionId 由调用方生成并保存，同一决定重试复用，不需要用户填写。
+
+相关单元/集成测试、实际 CLI/SDK/daemon 调用、执行器强杀恢复及真实模型有头 TUI 流程已验证。真实模型曾在恢复时删掉原 Write 参数的尾部换行，严格守卫拒绝；补全原参数上下文后复测成功，未放松审批比较。测试证明这些观察到的行为，不保证任意模型始终遵从提示。
+
+升级保持 CLI/SDK 同版本。已有进程不会热更新；先查询原任务状态，正常结束后重启采用新代码。旧无委派任务保持原行为，可显式重交接；不要因状态未知更换任务键重派写操作。读取旧记录不等于允许新代码自动恢复它，原身份与当前权限仍须匹配。
+
+一次性 headless 退出后不承诺向关闭的输出流推送；外部消息送达、业务阶段恢复与最终验收由 assistant/产品负责。取消不能撤回已发生的外部效果，不承诺跨任意系统 exactly-once。TUI 强杀的全部交叉场景、Windows 与断电恢复未单独验证。#58 的宿主取消来源契约与 #59 的视觉预算恢复仍待处理，不包含在本次修复声明中。

package/docs/releases/1.5.1-alpha.md

@@ -0,0 +1,22 @@
+# 1.5.1-alpha
+
+以下描述 `1.5.1-alpha` 工件的能力和已知限制；安装时固定该版本，不用旧 alpha 标签包代替。发布是否完成以 npm registry 的版本与工件完整性记录为准。
+
+包含此前 alpha.6 的后台任务终态通知修复，并增加两项通用工具行为改进：
+
+- 显式启用 Read 去重时，只有原工具结果仍完整保留在当前上下文中，才省略重复正文。结果已清除、截断或恢复缓存缺少来源时，重新返回文件内容。默认去重开关不变。
+- 主助手、Explore/Plan 和 SDK 公开共享指引统一说明：参数已知、无结果依赖或副作用冲突的必要调用可同轮提出；依赖操作等待前一结果。保留权限限制和必要核验，不为组成批次增加无关操作。完整替换 system 的 SDK 调用方仍需显式追加共享指引。
+
+相关测试与有限真实模型案例已验证调用顺序、权限拒绝和产物；不保证所有模型无回归，也不宣称已经消除全部重复探查或获得稳定提速。
+
+#55 的通用宿主实现已增加 [持久后台任务](../background-runs.md)：独立执行者、按稳定键查询、事件分页补收、权限与取消记录，以及执行器退出后关联原工具操作的恢复入口。SDK、CLI 和模型工具共用同一核心；大量事件不再要求一次读完整历史，SDK 流式解码保留跨 stdout 字节块的 UTF-8 内容。原操作如何核对与重放见 [命令恢复](../command-tool-recovery.md) 和 [MCP 恢复](../mcp-tool-recovery.md)。
+
+已有 macOS 进程故障、ACK 丢失与原任务查回验证；本轮脚本化模型通过 SDK 和有头 TUI 验证后台运行时连续回答两条前台消息，前台退出后后台完成且未重复执行。它证明宿主机制，不代表真实模型提速或 Pepper 已接入新接口。Pepper 新入口业务验收、Windows 和断电恢复仍未完成；不会自动重跑整个 agent 或未知写操作。后台完成不等于业务成果通过核验。
+
+文件工具错误在普通终端模式保留具体原因，避免只显示“Error writing file”而隐藏“必须先读取”等原错误。升级须采用同一固定 CLI/SDK 版本。正在运行的旧进程不会热更新；先核对原任务状态，再正常退出并重启。旧 owner 不支持新提交接口时明确拒绝，不自动接管或重跑任务。
+
+记忆提取未完成提示保留 API/传输、轮次上限、工具结果、取消等实际失败类别；同类失败不刷屏，新类别仍可见。保留原保存确认和重试条件，不提高5轮上限、不增加全目录扫描。具体解释见 [错误恢复说明](../error-recovery-usage.md)。
+
+CCL 自建提示词不再默认引导到上游产品文档或内部反馈频道，请求正文 system 中的 `x-anthropic-billing-header` attribution 文本也已移除（不是 HTTP header）。真实协议字段、旧配置名与用户上下文保留。真实 `claude-*` 命名网关目标和直连 OAuth 的认证兼容性未验证，不能假设网关会剥离该文本或所有下游均不依赖它。
+
+已知限制：Operation 查询返回最后保存的状态，不证明远端任务仍存活；真实模型曾把这一快照误述为当前活性。未知效果须核对原操作，不靠换键重派解决。真实案例验证保留过迟执行、reviewer 工具错误和终端宏未正常收尾等失败，不以本版本发布声明这些业务行为已全部修复。

package/docs/runtime-resources.md

@@ -0,0 +1,137 @@
+# Runtime resource discovery (v1)
+
+Introduced in 1.5.0-alpha.3. Verify the version and runtime response of the actual CLI used by the host.
+
+CCL exposes `runtime_resources` in the `system/init` event and the `initialize`
+control response. A repeated `initialize` resolves a fresh snapshot without
+resetting the conversation or reapplying initial hooks/system prompts. The JS SDK
+exposes the field through `initializationResult()` and `reinitialize()`:
+
+```ts
+import { RuntimeResourcesSchema } from '@margay/ccl-core/sdk'
+
+// `query` is an existing, still-live Query handle.
+const response = await query.reinitialize()
+const parsed = RuntimeResourcesSchema.safeParse(response.runtime_resources)
+if (!parsed.success || parsed.data.status !== 'available') {
+  // Discard old resource information; keep the normal permission UI.
+} else {
+  // Bind to this trusted connection, current session and host account generation.
+  // Describe the resources in UI; do not add their paths to an allowlist.
+  const resources = parsed.data.resources
+}
+```
+
+`initializationResult()` returns a cached response; it is not a freshness check.
+The existing Query lifetime applies: after a single query's result, use the next
+live handle rather than invoking control methods on an ended query. Direct
+stream-json hosts may send another `initialize` while the connection remains open.
+Hosts already consuming raw `system/init` can read the same field there; REPL
+bridge initialization uses the same builder. Ordinary terminal use is unchanged.
+
+Use `@margay/ccl-core@1.5.0-alpha.4` or a later release that includes this
+contract. The interface was introduced in alpha.3, which was withdrawn from npm;
+alpha.4 retains it with corrected package contents. Published alpha.2 does not
+include it. Upgrade the CLI actually launched by the host and start a new backend
+process, then check the response field and schema version. Updating a separate
+global CLI does not update a Desktop application's bundled dependency.
+
+## Meaning of the fields
+
+| Field | Meaning |
+| --- | --- |
+| `schema_version` | `1`; missing/unknown versions require the existing permission flow. |
+| `authorization` | Always `none`. The snapshot grants no access. |
+| `runtime_id` | Random per loaded backend process; changes on restart. Not a PID or authenticated user ID. |
+| `snapshot_id` | New for every emitted snapshot, including failures. |
+| `status` | `available` means the current context was resolved. `unavailable` has `reason: context_unavailable`, no identity/context/path fields and an empty resource list. |
+| `context_id` | Process-local opaque consistency marker over the emitted identity/resources, effective config home, gateway/account revision and explicit gateway environment tuple. Not monotonic, not an authorization token and not comparable across runtimes. |
+| `session_id` | Current session after restore; an init event's outer session ID must agree. |
+| `project_root` | Current stable project context; not proof that resources belong exclusively to it. |
+| `original_cwd` | Runtime original working directory, used by the scratch resolver. |
+| `cwd` | Current working directory at observation time. |
+| `resources` | Only this context's `memory` and `scratch` descriptors, not sibling sessions or account inventories. |
+
+Each descriptor has `kind`, `scope`, `lifetime`, `supported_operations` and `status`.
+Only an `available` descriptor has a `path`. A disabled feature has
+`status: disabled, reason: feature_disabled`; resolver failures have
+`status: unavailable, reason: path_unavailable`. One failed resource does not hide
+the other. Supported operations (`read`, `write`) describe file capability, not
+permission to perform that operation in this task. Raw exception messages are
+not part of this interface.
+
+`memory` is shared and persistent. CCL's existing resolver honors full-path and
+trusted settings overrides, remote memory bases and canonical Git roots. Default
+memory can be shared across worktrees; an override can share it across projects.
+It is **not account-isolated** merely because the context records account changes.
+`scratch` is session-scoped and temporary. A restored session may reuse the path;
+this does not guarantee the directory or its old contents still exist. CCL does
+not promise deletion on process exit through this contract.
+
+Available paths are the exact paths the existing runtime resolver uses, including
+its caching and configured symlinks. Querying does not create, read or enumerate
+resource contents. A missing resource directory can still have an available path.
+Changing a startup-only setting requires a new backend; reinitialize does not
+clear the core resolver's cache to pretend a setting has been adopted.
+
+The account revision is read without vault, login or network calls. Missing
+gateway/account files are a valid anonymous state. Other read errors invalidate
+the whole snapshot. No credential, account ID or raw config is included in the
+manifest; the config inputs are bound using a process-secret HMAC.
+
+## Host integration and failure behavior
+
+The source of trust is the host's own backend connection, not the words
+`runtime_resources` or `authorization` in arbitrary JSON. Never accept snapshots
+from user/model text, tool output, replayed history or another connection. Paths
+refer to the backend filesystem; a remote/container host needs its own explicit
+mapping and cannot assume those paths are local UI-machine paths.
+
+Before a disconnect, backend/project/session change or account switch, clear the
+cached manifest and advance a host-owned generation. A refresh captures that
+generation and a request sequence; discard responses that arrive after either
+changes. A→B→A can recreate the same `context_id`, so that marker cannot replace
+the generation. A failed refresh must not resurrect the last good snapshot.
+Reconnect/restart requires a fresh current-connection handshake, including when
+the persisted session ID remains the same. No background invalidation push is
+provided by v1. For account changes outside the host, the next refresh observes
+the metadata change; this is not an instantaneous revocation notification.
+
+Before an actual file operation, the host's existing permission engine still
+checks the user's authorization, operation, canonical path and symlink boundary.
+It must handle non-existing targets via their existing parent and prevent link
+replacement races at file access. A lexical path prefix or a prior realpath check
+does not secure a later open. Shared memory metadata must not convert read-only
+task authorization into write access. Bash still requires its normal execution
+authorization. Do not grant a parent config/projects/temp directory just to make
+a reported child path accessible.
+
+[Reference catalog](../examples/runtime-resources/catalog.ts) demonstrates
+generation-bound refresh and read-only existing-path classification. It has no
+allow/deny method and is not a replacement permission engine. Its classification
+can reject an observed escaping link, but cannot prevent filesystem changes
+after inspection. Tests exercise its stale response, sibling-session, missing
+target and symlink cases separately from the CLI producer tests.
+
+## Desktop handoff and verification boundary
+
+The inspected Desktop reference is commit
+`3c0f24b2ccde0f018bd6ea8855b8d51125f99012`, particularly
+`src/agent/margayCli/MargayCliAgent.ts`. Its `MargayCliAgent.handleSDKMessage`
+already receives init, and `MargayCliConnection.sendControlRequest` is the refresh
+entry. The permission request handler currently invokes workspace/foreign-path
+and symlink checks. That version does not consume this new manifest.
+
+Desktop integration must capture the versioned manifest from its trusted init or
+initialize response, bind it to the manager's connection/session/account
+generation, invalidate on transitions, and supply descriptive context to its
+permission UI without extending authorization. Keep its existing path and
+symlink enforcement; show the existing confirmation when resources are unknown.
+
+CCL's real CLI tests and reference catalog tests do not prove Desktop UI/manager
+integration. The required Desktop acceptance remains pending until its consumer
+is implemented and run with the candidate bundle: default/custom directories,
+restore/reconnect/account switch, authorized resource reads, shared-memory write
+limits, sibling sessions, escaping links and late/unknown responses. Record the
+actual Desktop commit, candidate bundle hash, tool/permission frames and UI
+result. Do not close #53 as end-to-end complete using only the producer tests.

package/docs/self-hosted-product-events.md

@@ -1,8 +1,6 @@
-# Self-hosted product events — local development preview
+# Self-hosted product events
 
-The CLI persists and uploads `session_started` and the real `analytics.query` exposure/invocation/completion lifecycle to its authenticated Margay gateway. `analytics query <definition.json>` queries the isolated self-hosted platform through that gateway. `analytics gate off|auto|status` combines a local restriction with the fresh remote decision. See the [local quickstart](local-analytics-quickstart.md). This remains a local development preview. The basic SDK employee passed R14; the user deferred further automation and full analytics expansion. Current priorities are CLI stability, bounded collection/statistics and remote/local control.
-
-For the locally upgraded analytics build, use `ccl` as below. From this source checkout, build with `npm run build` and replace `ccl` with `node dist/cli.js`. The retained `margay` launcher was not upgraded to this analytics build:
+The CLI persists and uploads `session_started` and the real `analytics.query` exposure/invocation/completion lifecycle to its authenticated Margay gateway. `analytics query <definition.json>` queries the isolated self-hosted platform through that gateway. `analytics gate off|auto|status` combines a local restriction with the fresh remote decision. See the [local quickstart](local-analytics-quickstart.md).
 
 ```sh
 ccl analytics enable
@@ -21,22 +19,7 @@ Only an exact authenticated durable-acceptance ACK deletes sent records. Lost AC
 
 Legacy GrowthBook/Datadog/1P and other legacy background traffic remain suppressed by `CCL_DISABLE_LEGACY_NONESSENTIAL_TRAFFIC`. The CLI no longer overwrites the user's explicit NONESSENTIAL setting. `isClientTelemetryDisabled` checks the original user privacy signals; the old privacy helpers continue suppressing old routes. Optional Anthropic preconnect and official-registry fetch now honor that boundary as well.
 
-The analysis gateway is local-only at `127.0.0.1:19803`, with a fixed synthetic-account allowlist; the earlier event-only gateway at `127.0.0.1:19802` remains available. The new gateway evaluates primary membership, native rollout and emergency denial, and independently authorizes each analysis before and after the native query. Its experimental assignment verifier is implemented, but this CLI query entrypoint uses only the registered boolean `analytics.query` gate. A CLI opt-in is not durable server-side consent. Durable server consent, deletion/retention policy, HMAC rotation and relay behavior remain open. Environment `local` is currently a client-side namespace, not client authority to choose the server project.
-
-## Evidence and reproduction
-
-`python3 deploy/analytics/cli_upload_admission.py` uses the retained owned gateway and platform. It runs production-bundle management commands, and compiles the real CLI entrypoint with an explicitly test-only credential-store adapter (`tests/fixtures/analytics-cli-entry.ts`), avoiding changes to the OS keychain. Account JWT validation, accountGatewayFetch, actual HTTP/outbox/capture and independent platform reads remain real. Its network guard rejects non-local traffic and records origins/paths without credentials. No model provider is called: the synthetic account's conversational command exits with insufficient quota; this is not a successful-model or business-outcome test.
-
-Latest full result: `.local/analytics/evidence/cli-upload/20261007T210524Z/result.json`. It proves a real session event, a real gateway 202 discarded before the uploader receives it, durable pending data across CLI process exit, a fresh `analytics flush` with the identical event ID, one resulting platform UUID on three forced reader queries, opt-out with no new event, fast paths without events, and actual logout removing the spool. The original OS credential-store adapter itself is outside this test's boundary.
-
-`logout-regression.log` has 115 passing targeted account/upload tests, including three real writer processes preserving 45 distinct queued events. The earlier `unit-final.log` additionally covers contract/privacy/capacity and existing byte-budget tests; `selected-bun-final.log` contains the graph-selected ten registry cases. `build-complete.log` is the full successful CLI+SDK build and existing gate-presence check. Full TypeScript checking still reports 11 pre-existing errors; a clean HEAD archive with the same dependency tree produces exactly the same diagnostics (`typecheck-baseline.log` vs `typecheck-final.log`).
-
-Failures are retained: the first upload test used a wrongly shaped JWT fixture (corrected to its actual helper signature); the first two live runs exposed an optional Anthropic preconnect that ignored the privacy boundary. The preconnect now checks it, with focused tests and a successful real CLI run showing only local gateway requests. No external request was allowed by the fixture guard.
-
-The R10 evidence above is historical. R13 added actual query lifecycle validation, R14 verified the basic SDK employee, R15 verified local/remote controls and ordinary CLI fault isolation, and R16 confirmed the current bounded local scope. Full analytics coverage, OS-vault E2E for this analytics fixture, production account-policy migration and complete automation remain deferred gaps; they are not newly imposed completion gates.
-
-
-## Querying analytics (R13)
+## Querying analytics
 
 Use an active website account for the configured local analysis gateway. Collection is optional: querying works with collection disabled and with either explicit privacy environment setting. No native platform key is stored by this client.
 
@@ -44,14 +27,14 @@ Use an active website account for the configured local analysis gateway. Collect
 ccl analytics query definition.json
 ```
 
-Example for the retained synthetic admission dataset (these names and dates must match your gateway's registered scope):
+Example only: replace event names and dates with your gateway's registered scope.
 
 ```json
 {
   "protocolVersion": 1,
   "kind": "funnel",
   "dateRange": {"from": "2026-09-27T00:00:00Z", "to": "2026-09-30T12:00:00Z"},
-  "steps": [{"event": "ccl_admit_start"}, {"event": "ccl_admit_complete"}],
+  "steps": [{"event": "example_started"}, {"event": "example_completed"}],
   "windowMinutes": 5
 }
 ```
@@ -71,16 +54,4 @@ Every command evaluates a fresh boolean decision; there is no persisted permissi
 
 The result envelope strips unexpected native fields and verifies that the returned definition matches the request after defaults. Feature responses must match issuer/account/environment and TTL, and be internally consistent. Feature HTTP is limited to 5 seconds/16 KiB; analysis HTTP to 45 seconds/1 MiB; aborts cancel body reading. These client checks supplement the server's fresh authorization; they do not grant authority themselves.
 
-Reproduction on the retained isolated runtime:
-
-```sh
-python3 deploy/analytics/cli_analysis_admission.py \
-  --gateway-runtime "$PWD/.local/analytics/ccl-gateway-runtime-ysf2jl8i" \
-  --baseline ../margay-gateway-feature-analytics-agent/.dual-agent/analytics/runtime-20261007T215031Z/result.json
-```
-
-The owned synthetic JWT must still be valid. This driver never prints or refreshes it automatically. It uses the same explicit private vault adapter as R10, isolates HOME/TMP/config/process groups and allows only the local gateway. It temporarily expires only the owned synthetic membership and restores its exact prior expiry in `finally`. The driver itself uses a separate native reader to verify counts.
-
-`evidence/cli-analysis/20261007T221035Z-live/result.json` under `.local/analytics` is PASS: seven real compiled-CLI queries match R12 (funnel 10→4/6, retention 10/4/0 vs 10/0/0, paths and endpoint weights, A/B 504/109 vs 496/294 samples/conversions). Each of three lifecycle names has count=distinct UUIDs=7 on three forced native reads. One real 202 is lost, three persisted events survive process exit, and a fresh CLI flush preserves their IDs without duplicate rows. Privacy overrides/collection disabled still return results without new events; primary membership expiry rejects before invocation; invalid JSON schema/FIFO fail; logout removes the spool.
-
-Two live driver failures remain recorded: stdout/stderr mixed a Node punycode warning with the JSON answer, then the same warning accompanied the error JSON on stderr. The driver now captures both streams separately and requires exactly one structured JSON record. An earlier output-directory collision failed before any owned subprocess or temporary root was started and is explicitly recorded as a reconstructed note. These were harness parsing failures, not accepted product runs.
+Server deployment and query admission must be validated against your own gateway environment. The client contract does not imply that the server has enabled every query kind.

package/docs/shared-skill-resources.md

@@ -0,0 +1,50 @@
+# Shared skill resources: identity, updates and session binding
+
+Introduced in 1.5.0-alpha.3. Check the actual CLI build/version and returned command metadata; earlier local candidates sharing an old version string are not evidence that an installed package supports this contract.
+
+Use the existing `pluginDirs` or `skillsDirs` entry points. `MARGAY_SKILLS_DIR` alone is not the supported SDK contract. Explicit plugins use a stable `.claude-plugin/plugin.json` name and relative `skills` paths, or the standard `skills/` directory. The SDK adapts `skillsDirs` through that same plugin loader.
+
+## Selecting a resource
+
+Discover through `initialize`, `reload_plugins`, or the skill catalog. Preserve `invocation_id`, `internal_name`, `display_name`, `source`, `origin`, `loaded_from`, `version`, and availability. `origin` identifies the actual skill directory when available. These fields are metadata, not authorization. A directory can be visible but its tools still require permission.
+
+Prefer `invocation_id` when the host explicitly selects a method. Resolution checks the exact ID, then a unique internal name, then a unique display name/alias. Conflicts are errors; an old ID does not fall back to an unrelated display name. Friendly descriptions remain available for agent selection.
+
+An invocation ID identifies a source/location, not immutable bytes or business permission. `version: null` means unknown. A plugin package version is not automatically a skill content version. Renaming display text does not change location identity; moving to a different physical version directory does. The host must rediscover and explicitly update a saved binding when moving a resource.
+
+The candidate SDK gives each canonical skills root a deterministic plugin name while keeping each wrapper directory private to one transport. Repeated sessions on the same actual root have stable names/IDs. Rediscover plugin skill IDs once when upgrading: adding canonical skill origins changes previous IDs, and old random SDK wrapper names are not aliases for the new identity. Custom explicit plugin names continue to work. Direct callers of `prepareSkillsWrappers` own and must remove their returned wrappers; managed SDK transports remove only wrappers they created, after exit/close or failed construction. They never remove caller plugin roots or skill contents.
+
+## Publishing and consuming versions
+
+For concurrently shared resources, publish complete immutable version directories. Keep the active directory and every version referenced by a running or resumable session intact. Prepare changes outside the active version, validate the entire package, then activate a completed version through the publisher's established protocol. Do not rewrite files underneath running readers.
+
+```mermaid
+flowchart LR
+  W[Resource publisher] -->|prepare and validate| V2[Immutable version V2]
+  W -->|activate completed version| A[Active entry]
+  A -->|discovery resolves actual directory| N[New runtime binding]
+  O[Existing runtime binding] --> V1[Retained immutable version V1]
+  N --> V2
+```
+
+The runtime resolves a skill's actual directory before loading its body. The resulting body, base-directory guidance and `CLAUDE_SKILL_DIR` remain bound to that directory. A subsequent active-link switch must not redirect an already loaded object's scripts or references. This is path binding under the immutable-version precondition, not a filesystem snapshot or protection against a publisher rewriting the bound directory.
+
+Explicit plugin roots are resolved before reading their manifest, so subsequent component discovery uses that same plugin version. Independently activated child roots are separate resources; discovery is not a transaction across multiple roots. Skills supplied through SDK `skillsDirs` should reference their resources through `CLAUDE_SKILL_DIR`. Their generated `CLAUDE_PLUGIN_ROOT` is a temporary adapter and is not a persistent resume path; use an explicit retained plugin directory when a package needs plugin-root-relative assets.
+
+Explicit `reload_plugins` refreshes discovery and related caches. Await its response and use its returned metadata before dispatching a newly selected method. Old messages remain history; their old body is not evidence that a fresh invocation loaded the old version. A resumed process must be given the intended retained resource roots and rediscover them. Native transcript resume alone is not a resource-version registry.
+
+If the host requires a session to stay on V1, pass the concrete V1 root, retain it, and avoid replacing that session's bindings with V2 on reload. If it intends an upgrade, perform it at an explicit task boundary, rediscover, compare the resolved source/version, and update the binding. Do not silently reinterpret a missing old ID as a same-named newer skill.
+
+## Mutation, recovery and readiness ownership
+
+CCL currently does **not** expose a shared Desktop/CLI publication transaction, lock, or `ready/recovering` state protocol. `runtime_resources` is a memory/scratch location contract and does not supply that capability. The runtime does not inspect private Desktop lock files or recover Desktop transactions.
+
+One publisher must own mutations and recovery of a shared root, or all writers must agree on the same protocol. A recovery worker must not roll back an active writer; elapsed time alone is insufficient to take ownership. Invalid/incomplete publication records must remain unavailable to new consumers until the publisher repairs them. Keep an already published version usable while a replacement is staged. These are publisher obligations and are not claimed as implemented by the read-only loader.
+
+The publisher/host should resolve readiness before handing the runtime a version root. Missing directories are errors at the SDK boundary. Loader diagnostics and missing catalog entries are observable failure facts, not proof that a transaction was recovered or a resource is globally deleted. The host should show the actual failure and allow retry after recovery. It must not present mere directory existence or a registered command as installation success.
+
+A publisher that must update in place needs a shared read/write coordination protocol covering discovery, body/script/reference reads and resume. A writer-only mutex is insufficient. That protocol and Desktop adaptation require joint implementation and testing; this candidate does not claim them.
+
+## Integration acceptance
+
+Use one synthetic resource package through both hosts. Verify exact command selection despite display-name collisions; same-root restart identity; changed-root rediscovery; V1 body and reference consumption while V2 is staged/activated; explicit reload to V2; retained-root resume; missing or corrupt publication refusal; live-writer/recovery concurrency and interrupted publication. Record which checks exercise CCL and which exercise the publisher/Desktop implementation. CLI fixture success is not Desktop UI or natural-model routing acceptance.

package/examples/background-runs/agents/background-reviewer.md

@@ -0,0 +1,6 @@
+---
+name: background-reviewer
+description: Independently inspect the actual task and produced files.
+tools: Read, Glob, Grep
+---
+Read the user's task and the actual source and output files. Check the facts and requested behavior independently; the worker's conclusion is not evidence. State concrete discrepancies and remaining uncertainties. Do not edit files, approve permissions, rerun the worker or send external messages.

package/examples/background-runs/agents/background-worker.md

@@ -0,0 +1,6 @@
+---
+name: background-worker
+description: Execute the explicitly delegated file task and preserve actual artifacts.
+tools: Read, Write, Glob, Grep
+---
+Read the original task and relevant source files. Work only within its authorized scope. Save the requested artifact and report its path. Retain tool failures and permission denials in your account of the outcome. Do not substitute a new task for an uncertain original execution. Do not send external messages.

package/examples/background-runs/worker-reviewer.mjs

@@ -0,0 +1,42 @@
+import { createBackgroundClient } from '../../dist/sdk/index.js'
+import { resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+// Copy agents/*.md to the task project's .ccl/agents/ before running this example.
+// Usage: node worker-reviewer.mjs PROJECT CLI_PATH STABLE_TASK_KEY ARTIFACT_PATH
+// The project contains task.md (the user's bounded work request).
+const [project, cliPath, taskKey, artifact] = process.argv.slice(2)
+if (!project || !cliPath || !taskKey || !artifact) throw new Error('Expected PROJECT CLI_PATH STABLE_TASK_KEY ARTIFACT_PATH')
+const client = createBackgroundClient({ cwd: resolve(project), cliPath: resolve(cliPath),
+  launch: { extraArgs: ['--allowed-tools', 'Read,Write,Glob,Grep'] } })
+async function wait(runId) {
+  const deadline = Date.now() + 10 * 60_000
+  let cursor
+  while (Date.now() < deadline) {
+    let page
+    do {
+      if (Date.now() >= deadline) throw new Error(`Observation deadline elapsed; query original run ${runId}.`)
+      page = await client.readRunEvents({ runId, cursor })
+      // This demo only observes. A real assistant handles this page's events
+      // and persists its cursor after its own processing succeeds.
+      cursor = page.nextCursor
+    } while (page.hasMore)
+    const view = await client.getRun({ runId })
+    if (view.status !== 'found') throw new Error(`Original run unavailable: ${runId}`)
+    if (view.snapshot.state === 'waiting_permission') throw new Error(`Explicit permission needed; inspect ${runId}. No approval was invented.`)
+    if (['succeeded','completed_with_issues','failed','interrupted','cancelled'].includes(view.snapshot.state)) return view
+    if (view.snapshot.state !== 'queued' && view.observation.executorLock === 'free') throw new Error(`Executor unavailable: ${runId}; query its recorded operations before continuing`)
+    await delay(1000)
+  }
+  throw new Error(`Observation deadline elapsed; the run may still be executing. Query original run ${runId}.`)
+}
+const worker = await client.submitRun({ requestKey: `${taskKey}:worker`, spec: { agent: 'background-worker', maxTurns: 12,
+  prompt: `Working directory: ${resolve(project)}. Read ${resolve(project, 'task.md')} and perform its authorized work. Save the requested artifact at ${resolve(project, artifact)}. Report actual results and tool failures honestly.` } })
+console.log(JSON.stringify({ accepted: worker.runId, sessionId: worker.sessionId }))
+const work = await wait(worker.runId)
+const reviewer = await client.submitRun({ requestKey: `${taskKey}:reviewer`, spec: { agent: 'background-reviewer', maxTurns: 8,
+  prompt: `Independently review the task in working directory ${resolve(project)}. Read ${resolve(project, 'task.md')} and the actual artifact ${resolve(project, artifact)}; compare the requested facts with the files. Do not accept the worker's prose as evidence. Worker execution facts: ${JSON.stringify({ runId: worker.runId, state: work.snapshot.state, toolErrors: work.snapshot.toolErrors, deniedToolUseIds: work.snapshot.deniedToolUseIds })}. Start with these supplied paths and the source files named by the task. Keep investigation within this task directory unless concrete task evidence requires another location; do not search parent directories for hypothetical evidence. Report what you verified, actual discrepancies, and limits of the available evidence. A missing before-run baseline limits a historical claim; it is not itself evidence that the source was modified and does not require a filesystem-wide investigation. Do not change files or send external messages.` } })
+if (reviewer.sessionId === worker.sessionId) throw new Error('Worker and reviewer unexpectedly share a session')
+const review = await wait(reviewer.runId)
+// This is the reviewer's result, not a claim that an external recipient received it.
+console.log(JSON.stringify({ worker: work, reviewer: review }, null, 2))

package/examples/command-recovery/durable-server.mjs

@@ -0,0 +1,44 @@
+import { mkdirSync, realpathSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { z } from 'zod/v4'
+import { createDurableCommandAdapter, createOperationHost, createSdkMcpServer, tool } from '../../dist/sdk/index.js'
+
+/**
+ * Persistent local-file example. The embedding assistant supplies its CURRENT
+ * permission callback; no historical allow decision is reused after restart.
+ * Run after building the SDK, or use the copy shipped in the npm package.
+ */
+export function durableCommandRecoveryServer(root, authorize) {
+  if (typeof authorize !== 'function') throw new Error('Supply the current host authorization callback')
+  mkdirSync(root, { recursive: true, mode: 0o700 })
+  const directory = realpathSync(root)
+  const identity = () => {
+    const stat = statSync(directory)
+    if (!stat.isDirectory()) throw new Error('Example target is no longer a directory')
+    return `${directory}:${stat.dev}:${stat.ino}`
+  }
+  const script = fileURLToPath(new URL('./receipt-command.mjs', import.meta.url))
+  const host = createOperationHost({ storeDir: join(directory, 'operations'), scope: directory, authorize,
+    resolveAdapter: async ref => ref === 'local-example' ? createDurableCommandAdapter({
+      adapterId: ref, adapterVersion: '1', targetIdentity: identity(),
+      execute: { cmd: process.execPath, args: [script, join(directory, 'effects'), 'execute'], cwd: directory, timeoutMs: 5000 },
+      query: { cmd: process.execPath, args: [script, join(directory, 'effects'), 'query'], cwd: directory, timeoutMs: 5000 },
+      verifyIdentity: async () => ({ targetIdentity: identity(), adapterVersion: '1' }),
+      // Query after an unknown effect. Do not advertise an external service's
+      // replay guarantee merely because this local demonstration deduplicates.
+    }) : undefined,
+  })
+  return createSdkMcpServer({ name: 'durable-commands', tools: [
+    tool('execute', 'Accept and execute a local example; preserve operationId even if its reply is unknown',
+      { input: z.json(), requestKey: z.string().min(1) }, async (args, extra) => {
+        const accepted = await host.submitOperation({ requestKey: args.requestKey, adapterRef: 'local-example', input: args.input })
+        return host.executeOperation({ operationId: accepted.operationId, expectedRevision: accepted.revision, signal: extra.signal })
+      }),
+    tool('get', 'Read saved execution and result, including after the original host exits',
+      { operationId: z.string() }, args => host.getOperation(args), { annotations: { readOnlyHint: true } }),
+    tool('query', 'Query the original effect and save its verified receipt; never repeat the write',
+      { operationId: z.string(), expectedRevision: z.number().int(), actionId: z.string().min(1) },
+      (args, extra) => host.reconcileOperation({ ...args, signal: extra.signal })),
+  ] })
+}

package/examples/command-recovery/receipt-command.mjs

@@ -0,0 +1,40 @@
+// Deterministic local example, not a production business service.
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises'
+import { join } from 'node:path'
+const [root, action] = process.argv.slice(2)
+let raw = ''
+for await (const chunk of process.stdin) raw += chunk
+const request = JSON.parse(raw)
+if (action === 'identity') {
+  process.stdout.write(JSON.stringify({ targetIdentity: root, adapterVersion: '1' }))
+  process.exit(0)
+}
+const key = createHash('sha256').update(`${request.targetIdentity}:${request.requestKey}`).digest('hex')
+const dir = join(root, key)
+const path = join(dir, 'receipt.json')
+const reply = body => process.stdout.write(JSON.stringify({ ...request, input: undefined, ...body }))
+const existing = async () => {
+  try {
+    const record = JSON.parse(await readFile(path, 'utf8'))
+    if (record.inputDigest !== request.inputDigest) return reply({ status: 'unknown', reason: 'Key/input mismatch' })
+    reply({ status: 'applied', receipt: record.receipt, result: record.result })
+  } catch { reply({ status: 'unknown', reason: 'No complete receipt; an old action may still be running' }) }
+}
+await mkdir(root, { recursive: true })
+if (action === 'query') await existing()
+else if (action === 'execute') {
+  try { await mkdir(dir) } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    await existing()
+    process.exit(0)
+  }
+  // Exclusive mkdir is the example service's deduplication claim. An interrupted claim
+  // without a receipt stays unknown; it never authorizes another write.
+  const record = { inputDigest: request.inputDigest, receipt: { key, writes: 1 }, result: request.input }
+  await writeFile(join(dir, 'effect.json'), JSON.stringify(request.input))
+  await writeFile(join(dir, 'receipt.tmp'), JSON.stringify(record))
+  await rename(join(dir, 'receipt.tmp'), path)
+  if (request.input?.loseReply) process.exit(9)
+  await existing()
+} else throw new Error('Expected execute or query')

package/examples/runtime-resources/catalog.ts

@@ -0,0 +1,68 @@
+// Reference consumer only. Production hosts must bind this object to their own
+// authenticated connection/account lifecycle and retain their permission engine.
+// This source-tree fixture is imported by the tests. When copying it into a host,
+// import RuntimeResourcesSchema/RuntimeResources from '@margay/ccl-core/sdk'.
+import { RuntimeResourcesSchema, type RuntimeResources } from '../../sdk/runtimeResources.js'
+import { realpathSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+type Available = Extract<RuntimeResources, { status: 'available' }>
+
+export class RuntimeResourceCatalog {
+  private generation = 0
+  private request = 0
+  private snapshot: Available | undefined
+  private runtimeId: string | undefined
+
+  /** Call BEFORE switching accounts/projects, restoring a session or disconnecting. */
+  invalidate(): void {
+    this.generation++
+    this.snapshot = undefined
+    this.runtimeId = undefined
+  }
+
+  /** `read` must query the current trusted backend, never model/tool text. */
+  async refresh(read: () => Promise<unknown>, expectedSession: string): Promise<boolean> {
+    const generation = this.generation, request = ++this.request
+    this.snapshot = undefined
+    try {
+      const parsed = RuntimeResourcesSchema.safeParse(await read())
+      if (generation !== this.generation || request !== this.request) return false
+      if (!parsed.success || parsed.data.status !== 'available' || parsed.data.session_id !== expectedSession) return false
+      if (this.runtimeId && parsed.data.runtime_id !== this.runtimeId) return false
+      this.runtimeId = parsed.data.runtime_id
+      this.snapshot = parsed.data
+      return true
+    } catch {
+      // A failed/old query never restores the previous snapshot.
+      return false
+    }
+  }
+
+  /** A description for UI/policy context. No allow/deny result is produced. */
+  resource(kind: 'memory' | 'scratch') {
+    const resource = this.snapshot?.resources.find(r => r.kind === kind)
+    return resource?.status === 'available' ? { ...resource } : undefined
+  }
+
+  /**
+   * Read-only classification for an existing target. Missing paths stay unknown.
+   * This is NOT a secure file-open operation: a host must still authorize the
+   * requested action and prevent link races at the actual access boundary.
+   */
+  describeExistingPath(target: string) {
+    if (!isAbsolute(target)) return undefined
+    const within = (root: string, path: string) => {
+      const suffix = relative(root, path)
+      return suffix === '' || (suffix !== '..' && !suffix.startsWith('..' + sep) && !isAbsolute(suffix))
+    }
+    for (const kind of ['memory', 'scratch'] as const) {
+      const resource = this.resource(kind)
+      if (!resource || !within(resolve(resource.path), resolve(target))) continue
+      try {
+        if (within(realpathSync(resource.path), realpathSync(target))) return resource
+      } catch { /* An unresolved target is not an identified resource. */ }
+    }
+    return undefined
+  }
+}