fix: recover oversized briefings through files / 超大 briefing 文件恢复

INSTALL.md

@@ -41,6 +41,38 @@ node packages/cli/lib/bin.js install subject_<32 lowercase hex characters> --hos
 
 Replace the subject id with the exact value returned by Distilly. Profile installation writes only the self-contained Profile and its digest manifest.
 
+## Recover a briefing that exceeds the host limit
+
+If `distilly_pending` returns `briefing_too_large`, the research is still stored and pending. Raising the model context setting does not change a verified MCP transport limit. For a complete briefing within the engine's limits, use the explicit local file workflow from a checkout containing this command:
+
+```bash
+node packages/cli/lib/bin.js recover job_<32 lowercase hex characters> --output /absolute/path/to/new-recovery-directory
+```
+
+Use the exact job ID from `distilly_pending` with `action: "list"`. Run the command with the same home directory as the installed Plugin so it opens the same `~/.distilly` store. The output directory must be new, with an existing parent. It will contain private research; choose a local location you intend to use for that data.
+
+Keep the command running. It writes the complete `briefing.json`, `commit-tool-schema.json`, and `README.txt`, then waits for a response. Read the entire briefing, its instructions, evidence rules, and baseline before preparing a patch. The patch schema is the `patch` property of `commit-tool-schema.json`; the command supplies all commit identity fields itself.
+
+Write a temporary JSON file with exactly `briefingSha256` (the digest in `README.txt`) and `patch` (your DistillPatch object). Rename the finished file to `response.json` in that directory. The command checks the digest and submits the patch through the same session and lease. It does not call a model or generate a patch. An empty patch is a deliberate decision to consume the briefing without adding or changing claims; do not use one merely to clear the error.
+
+The default wait is 20 minutes. `--timeout-seconds` accepts 1 through 1500 seconds, below the 30-minute lease lifetime. Timeout, Ctrl+C, SIGTERM, malformed responses, and validation errors attempt to release the lease and leave research available for another attempt. A force-killed process leaves its lease to expire. Another session's active lease is never taken over. Retry with a new directory and a fresh briefing; an older response will not match the new digest.
+
+A successful submission writes `submission.json` and `result.json`. The result can be current or suspended for review; a suspended result still needs the normal review workflow. If the command says the commit succeeded but its result file could not be written, use the printed version and request IDs to inspect the result. Do not resubmit blindly. An unknown commit outcome requires the same inspection before retrying.
+
+This path transfers a complete briefing through local files, with a maximum of 4 MiB and 999 material references. It does not raise a host's verified MCP limit or establish that a model can read that much context. Responses are limited to 256 KiB on disk; the existing 64 KiB canonical patch limit still applies. There is no truncation, automatic splitting, or deletion of stored research. Briefings above the engine limits still fail explicitly. Recovery directories are not removed automatically.
+
+### 超出宿主限制后的本地恢复
+
+出现 `briefing_too_large` 时，调研资料仍保存在库中并等待处理。调整模型上下文不会改变已验证的 MCP 传输限制。可在包含此命令的源码构建目录中运行上面的 `recover` 命令；job ID 从 `distilly_pending` 的 `action: "list"` 结果取得。命令必须使用与 Plugin 相同的 home，才能访问同一个 `~/.distilly`。输出目录必须尚不存在，且父目录已存在；其中包含私人资料，请选择适合保存这些资料的本地位置。
+
+保持命令运行，完整阅读 `briefing.json`、证据规则和已有基线，再按 `commit-tool-schema.json` 的 `patch` 字段定义准备结果。先写临时 JSON 文件，只包含 `README.txt` 中的 `briefingSha256` 和你的 `patch`，完成后再将其重命名为 `response.json`。命令会校验摘要，并通过同一会话和租约提交。它不调用模型，也不自动生成结果。空 patch 表示明确决定处理完本次资料但不增改任何 claim，请勿仅为消除报错而提交空 patch。
+
+默认等待 20 分钟，`--timeout-seconds` 可设置为 1 至 1500 秒。超时、Ctrl+C、SIGTERM、响应格式错误或校验失败时，命令会尝试释放租约，供后续重试；强制杀死进程则需要等待租约过期。命令不会接管其他会话的有效租约。重试须使用新目录和新 briefing，旧响应无法通过摘要校验。
+
+成功提交后会保留 `submission.json` 与 `result.json`；结果若为 suspended，仍需正常审核。若提示提交成功但回执写入失败，请用输出中的版本 ID 和请求 ID 查询结果，不要直接重复提交。提交结果不明确时也应先核实。
+
+本地文件路径支持最多 4 MiB 的完整 briefing 和 999 个资料引用，不代表宿主 MCP 限制已提高，也不保证模型具备相应上下文容量。响应文件最多 256 KiB，原有 canonical patch 的 64 KiB 上限继续生效。不会裁剪、自动拆分或删除已存资料；超出引擎上限仍会明确失败。恢复目录不会自动清理。
+
 ## Remove the host integration
 
 ```bash

docs/architecture.md

@@ -99,3 +99,5 @@ authority     SQLite/WAL metadata + immutable blobs   LSN projections / exports
 ```
 
 Signatures, field lists, and host pitfalls stay in the design chapters. This page only orients.
+
+The Preview CLI also provides explicit `recover <job-id> --output <new-directory>` file recovery for briefings above a host transport limit. It exports the complete briefing within existing engine limits, binds a manually supplied patch to that exact export and lease, and uses the normal evidence-checked commit path. See [INSTALL.md](../INSTALL.md#recover-a-briefing-that-exceeds-the-host-limit) for deadlines, private artifacts, and failure recovery. This does not change verified host capacity.

docs/design/system-v3.md

@@ -2089,6 +2089,8 @@ brief / renew / release 都是单独的 SQLite mutation：
 binary 升级后若仍支持 lease 固定的 grouping/prompt/draft versions，旧 lease 可正常完成；缺少 pinned implementation 返回 schema_unsupported，要求显式 release / 重新 brief，不能按当前默认值静默重算。
 ### 12.5 不静默裁剪
 
+Preview CLI 的显式 `recover <job-id> --output <new-directory>` 为已录入且超出宿主传输上限的任务提供完整本地文件恢复：使用 `sdk_explicit` 文件预算，在现有引擎上限内导出完整 briefing；命令保持同一会话与 lease，接收绑定导出文件 SHA-256 的 patch 后走原有 commit 校验。默认等待 20 分钟，最多 25 分钟，不自动生成空 patch、续租、拆分或裁剪。取消或校验失败时尝试释放自己的 lease；强制终止则等待过期。回执写入失败不能被报告成提交未发生。目录须原子创建且权限为 0700，命令写入的文件为 0600；保留资料供用户处理，不自动删除。此 SDK 文件预算不修改 verified host fixture，也不证明模型上下文容量。具体操作见 INSTALL.md。
+
 BriefingService 只使用 ClientSessionContext 中经过可信 preflight 的 BriefCapacity；模型不能在 pending 输入里自报或放大。HostPreflight 的 success capacity 是 HostDistillBriefing 经过实际宿主 tool-result 路径后仍可完整交付给模型的**净预算**。`source=host_handshake` 只允许可信宿主 API 直接给出当前 surface 的净 input/result envelope budget；maxContextTokens、maxToolResultBytes、字符阈值、token 阈值或其它 gross field 不能靠减一个固定 wrapper 常量转换成 capacity。`source=binding_fixture` 只允许匹配 §17.1 exact host/version/surface/release/wire/skill tuple、并在真实 structured/text 双结果序列化路径上对公告的 exact net budget 通过真实宿主 transport 测试的保守净值；它不必探出宿主真实失败极限，但不得公告超过实测完整值的 capacity。当前 OpenClaw/Hermes 记录使用隔离 clean CLI home、固定 `openai-codex/gpt-5.4` 与 deterministic synthetic fixture server；“真实宿主测试”指真实 executable、模型调用和 MCP transport，不指真实产品 Engine、用户材料或所有模型/session 的剩余上下文。canonical tool descriptor、host advertised-schema projection、serializer、manifest、canonical skill 或 tuple 任一改变都使 fixture 失效；OpenClaw/Hermes 的 projection 变化必须重新运行对应真实宿主测试，即使五工具名称和 canonical descriptor digest 没变。fixture 文件保留 canonical `toolContractDigest`，并在使用 `schemaProfile` 时另外绑定实际公告面的 `advertisedToolContractDigest` 与 probe 的 `probeContractDigest`；后两者是 loader/verifier 的内部不可变元数据，不扩展 HostPreflight/MCP wire evidence。没有可信净 handshake 或完全匹配 fixture 时，preflight 返回 host_unsupported，外层不得创建 host client；普通 SDK 则必须在打开 client 时显式给 `source=sdk_explicit` 的 capacity。ClientSessionContext 没有 capacity 时 brief 同样 host_unsupported，不创建 lease。
 
 内部常量固定为 maximumBriefingBytes=4,194,304、maximumMaterialRefs=999、maximumOutputBytes=65,536；最后一项就是 accepted DistillPatch compact canonical JSON 的 UTF-8 bytes budget，不是让模型返回任意 65,536 字节文本。commit 在打开写事务前对 schema-validated canonical patch bytes 计数；`<= 65,536`（恰好等于也允许），`65,537` 返回 invalid_input 并零写入。brief 容量算法先构造包括 limits 在内的完整 HostDistillBriefing，然后求 fixed point：令 estimatedInputTokens 从 0 开始，反复把它写回对象并计算 compact canonical JSON 的 UTF-8 byte length，直到新值等于字段值；该稳定值就是 estimatedInputTokens，采用保守的 1 UTF-8 byte = 1 token。最终**完整 briefing** 的 serializedBytes 必须同时 `<= 4,194,304`、`<= capacity.maximumToolResultBytes`，estimatedInputTokens 必须 `<= capacity.maximumInputTokens`，refs 必须 `<= 999`；等于上限允许。

docs/design/v3/12-briefing-and-lease.md

@@ -129,6 +129,8 @@ brief / renew / release 都是单独的 SQLite mutation：
 binary 升级后若仍支持 lease 固定的 grouping/prompt/draft versions，旧 lease 可正常完成；缺少 pinned implementation 返回 schema_unsupported，要求显式 release / 重新 brief，不能按当前默认值静默重算。
 ### 12.5 不静默裁剪
 
+Preview CLI 的显式 `recover <job-id> --output <new-directory>` 为已录入且超出宿主传输上限的任务提供完整本地文件恢复：使用 `sdk_explicit` 文件预算，在现有引擎上限内导出完整 briefing；命令保持同一会话与 lease，接收绑定导出文件 SHA-256 的 patch 后走原有 commit 校验。默认等待 20 分钟，最多 25 分钟，不自动生成空 patch、续租、拆分或裁剪。取消或校验失败时尝试释放自己的 lease；强制终止则等待过期。回执写入失败不能被报告成提交未发生。目录须原子创建且权限为 0700，命令写入的文件为 0600；保留资料供用户处理，不自动删除。此 SDK 文件预算不修改 verified host fixture，也不证明模型上下文容量。具体操作见 INSTALL.md。
+
 BriefingService 只使用 ClientSessionContext 中经过可信 preflight 的 BriefCapacity；模型不能在 pending 输入里自报或放大。HostPreflight 的 success capacity 是 HostDistillBriefing 经过实际宿主 tool-result 路径后仍可完整交付给模型的**净预算**。`source=host_handshake` 只允许可信宿主 API 直接给出当前 surface 的净 input/result envelope budget；maxContextTokens、maxToolResultBytes、字符阈值、token 阈值或其它 gross field 不能靠减一个固定 wrapper 常量转换成 capacity。`source=binding_fixture` 只允许匹配 §17.1 exact host/version/surface/release/wire/skill tuple、并在真实 structured/text 双结果序列化路径上对公告的 exact net budget 通过真实宿主 transport 测试的保守净值；它不必探出宿主真实失败极限，但不得公告超过实测完整值的 capacity。当前 OpenClaw/Hermes 记录使用隔离 clean CLI home、固定 `openai-codex/gpt-5.4` 与 deterministic synthetic fixture server；“真实宿主测试”指真实 executable、模型调用和 MCP transport，不指真实产品 Engine、用户材料或所有模型/session 的剩余上下文。canonical tool descriptor、host advertised-schema projection、serializer、manifest、canonical skill 或 tuple 任一改变都使 fixture 失效；OpenClaw/Hermes 的 projection 变化必须重新运行对应真实宿主测试，即使五工具名称和 canonical descriptor digest 没变。fixture 文件保留 canonical `toolContractDigest`，并在使用 `schemaProfile` 时另外绑定实际公告面的 `advertisedToolContractDigest` 与 probe 的 `probeContractDigest`；后两者是 loader/verifier 的内部不可变元数据，不扩展 HostPreflight/MCP wire evidence。没有可信净 handshake 或完全匹配 fixture 时，preflight 返回 host_unsupported，外层不得创建 host client；普通 SDK 则必须在打开 client 时显式给 `source=sdk_explicit` 的 capacity。ClientSessionContext 没有 capacity 时 brief 同样 host_unsupported，不创建 lease。
 
 内部常量固定为 maximumBriefingBytes=4,194,304、maximumMaterialRefs=999、maximumOutputBytes=65,536；最后一项就是 accepted DistillPatch compact canonical JSON 的 UTF-8 bytes budget，不是让模型返回任意 65,536 字节文本。commit 在打开写事务前对 schema-validated canonical patch bytes 计数；`<= 65,536`（恰好等于也允许），`65,537` 返回 invalid_input 并零写入。brief 容量算法先构造包括 limits 在内的完整 HostDistillBriefing，然后求 fixed point：令 estimatedInputTokens 从 0 开始，反复把它写回对象并计算 compact canonical JSON 的 UTF-8 byte length，直到新值等于字段值；该稳定值就是 estimatedInputTokens，采用保守的 1 UTF-8 byte = 1 token。最终**完整 briefing** 的 serializedBytes 必须同时 `<= 4,194,304`、`<= capacity.maximumToolResultBytes`，estimatedInputTokens 必须 `<= capacity.maximumInputTokens`，refs 必须 `<= 999`；等于上限允许。