@margay/ccl-core 1.4.0-beta.0 → 1.4.5-rc.0

package/dist/sdk/errorDiagnostics.d.ts

@@ -1,4 +1,86 @@
+export declare function sanitizeErrorTextWithMetadata(text: string): {
+    text: string;
+    truncated: boolean;
+};
 export declare function sanitizeErrorText(text: string): string;
+/** Read facts without invoking user-supplied accessors or coercion hooks. */
+export declare function diagnosticField(value: unknown, key: string): unknown;
+/** Additive Gateway diagnostic: failed attempt facts, never a successful served identity. */
+export type UpstreamDiagnostic = {
+    schema_version: 1;
+    model?: string;
+    deployment?: string;
+    upstream_status?: number;
+    upstream_request_id?: string;
+    code?: string;
+    type?: string;
+    message?: string;
+    message_truncated?: boolean;
+    message_omitted_reason?: string;
+    classification?: string;
+};
+export declare function sanitizeUpstreamDiagnostic(value: unknown): UpstreamDiagnostic | undefined;
+export type RecoveryDiagnostic = {
+    upstream?: UpstreamDiagnostic;
+    schemaVersion: 1;
+    id: string;
+    observations: {
+        stopReason?: string;
+        upstreamStopReason?: string;
+        code?: string;
+        message?: string;
+        messageTruncated?: boolean;
+        httpStatus?: number;
+    };
+    assessment: {
+        category: string;
+        evidence: 'local_fact' | 'contract_report' | 'heuristic' | 'unknown';
+        scope: string;
+    };
+    execution: {
+        toolState: 'not_started' | 'executing' | 'completed' | 'unknown';
+    };
+    suggestions: {
+        action: string;
+        reason: string;
+    }[];
+    recovery: {
+        owner: 'agent' | 'cli' | 'caller' | 'none';
+        phase: 'detected' | 'recovering' | 'recovered' | 'blocked' | 'failed' | 'cancelled';
+        attempts: number;
+    };
+    budget?: {
+        requestedMaxTokens?: number;
+        maxTokens?: number;
+        outputLimit?: number;
+        contextLimit?: number;
+        estimatedInputTokens?: number;
+        thinkingBudget?: number;
+        contextSafetyMargin?: number;
+        budgetSource?: string;
+        limitSource?: string;
+        contextAccounting?: string;
+    };
+    cliVersion?: string;
+    turnId?: string;
+    model?: string;
+    servedModel?: string;
+    requestedModel?: string;
+    resolvedModel?: string;
+    sessionId?: string;
+    requestId?: string;
+    upstreamRequestId?: string;
+    servedDeployment?: string;
+    agentId?: string;
+    parentAgentId?: string;
+    origin?: string;
+    protocol?: string;
+    timestamp?: string;
+    logPath?: string;
+    logWriteFailed?: boolean;
+};
+/** A versioned, additive wire extension. Unknown fields never cross this boundary. */
+export declare function sanitizeRecoveryDiagnostic(value: unknown): RecoveryDiagnostic | undefined;
 export type RecoveryOutcome = {
     status: 'needs_user' | 'blocked_external';
     reason: string;

package/dist/sdk/errorDiagnostics.js

@@ -2,14 +2,17 @@
 const MAX_DETAIL = 4096;
 const MAX_SCAN = 65_536;
 // Credential syntax redaction, NOT semantic diagnosis or retry classification.
-export function sanitizeErrorText(text) {
-    return text.slice(0, MAX_SCAN)
+export function sanitizeErrorTextWithMetadata(text) {
+    const redacted = text.slice(0, MAX_SCAN)
         .replace(/\b(?:Bearer|Basic)\s+[^\s,;"'<>]+/gi, '[REDACTED]')
         .replace(/\bsk-[a-zA-Z0-9_-]+/g, '[REDACTED]')
         .replace(/\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g, '[REDACTED]')
         .replace(/((?:["']?)(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|password|secret|authorization|cookie)(?:["']?)\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s&,;]+)/gi, '$1[REDACTED]')
-        .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@')
-        .slice(0, MAX_DETAIL);
+        .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@');
+    return { text: redacted.slice(0, MAX_DETAIL), truncated: text.length > MAX_SCAN || redacted.length > MAX_DETAIL };
+}
+export function sanitizeErrorText(text) {
+    return sanitizeErrorTextWithMetadata(text).text;
 }
 function own(value, key) {
     // Accessors/custom toString/proxies must not break the error handler itself.
@@ -20,6 +23,119 @@ function own(value, key) {
         return undefined;
     }
 }
+/** Read facts without invoking user-supplied accessors or coercion hooks. */
+export function diagnosticField(value, key) {
+    return value && typeof value === 'object' ? own(value, key) : undefined;
+}
+export function sanitizeUpstreamDiagnostic(value) {
+    if (diagnosticField(value, 'schema_version') !== 1)
+        return undefined;
+    const result = { schema_version: 1 };
+    for (const name of ['model', 'deployment', 'upstream_request_id', 'code', 'type', 'classification', 'message_omitted_reason']) {
+        const raw = diagnosticField(value, name);
+        if (typeof raw !== 'string' || !raw || raw.length > (name === 'code' || name === 'type' ? 128 : 256))
+            continue;
+        if (!/^[a-zA-Z0-9._:/-]+$/.test(raw))
+            continue;
+        const cleaned = sanitizeErrorText(raw);
+        if (cleaned === raw)
+            result[name] = raw;
+    }
+    const status = diagnosticField(value, 'upstream_status');
+    if (typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599)
+        result.upstream_status = status;
+    const raw = diagnosticField(value, 'message');
+    if (typeof raw === 'string') {
+        if (/["']?(?:messages|system|tools|headers|request_body)["']?\s*[:=]\s*[\[{"']/i.test(raw)) {
+            result.message_omitted_reason = 'unsafe';
+        }
+        else {
+            const cleaned = sanitizeErrorText(raw).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+            result.message = cleaned.slice(0, 1024);
+            if (cleaned.length > 1024 || raw.length > 4096 || diagnosticField(value, 'message_truncated') === true)
+                result.message_truncated = true;
+        }
+    }
+    return result;
+}
+/** A versioned, additive wire extension. Unknown fields never cross this boundary. */
+export function sanitizeRecoveryDiagnostic(value) {
+    const field = diagnosticField;
+    const id = field(value, 'id');
+    const assessment = field(value, 'assessment'), execution = field(value, 'execution');
+    const recovery = field(value, 'recovery'), observations = field(value, 'observations');
+    const category = field(assessment, 'category'), evidence = field(assessment, 'evidence'), scope = field(assessment, 'scope');
+    const toolState = field(execution, 'toolState'), owner = field(recovery, 'owner'), phase = field(recovery, 'phase'), attempts = field(recovery, 'attempts');
+    if (field(value, 'schemaVersion') !== 1 || typeof id !== 'string' || !id ||
+        typeof category !== 'string' || typeof scope !== 'string' ||
+        !['local_fact', 'contract_report', 'heuristic', 'unknown'].includes(evidence) ||
+        !['not_started', 'executing', 'completed', 'unknown'].includes(toolState) ||
+        !['agent', 'cli', 'caller', 'none'].includes(owner) ||
+        !['detected', 'recovering', 'recovered', 'blocked', 'failed', 'cancelled'].includes(phase) ||
+        !Number.isSafeInteger(attempts) || attempts < 0 || !observations || typeof observations !== 'object')
+        return undefined;
+    const result = {
+        schemaVersion: 1, id: sanitizeErrorText(id), observations: {},
+        assessment: { category: sanitizeErrorText(category), evidence: evidence, scope: sanitizeErrorText(scope) },
+        execution: { toolState: toolState }, suggestions: [],
+        recovery: { owner: owner, phase: phase, attempts: attempts },
+    };
+    for (const key of ['stopReason', 'upstreamStopReason', 'code', 'message']) {
+        const raw = field(observations, key);
+        if (typeof raw !== 'string')
+            continue;
+        const cleaned = sanitizeErrorTextWithMetadata(raw);
+        result.observations[key] = cleaned.text;
+        if (key === 'message' && (cleaned.truncated || field(observations, 'messageTruncated') === true))
+            result.observations.messageTruncated = true;
+    }
+    const httpStatus = field(observations, 'httpStatus');
+    if (Number.isInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599)
+        result.observations.httpStatus = httpStatus;
+    const suggestions = field(value, 'suggestions');
+    let isSuggestionsArray = false;
+    try {
+        isSuggestionsArray = Array.isArray(suggestions);
+    }
+    catch { /* revoked proxies carry no usable facts */ }
+    if (isSuggestionsArray) {
+        // Indexed descriptors also avoid getters on array members.
+        const length = field(suggestions, 'length');
+        for (let i = 0; i < Math.min(typeof length === 'number' ? length : 0, 8); i++) {
+            const suggestion = field(suggestions, String(i));
+            const action = field(suggestion, 'action'), reason = field(suggestion, 'reason');
+            if (typeof action === 'string' && typeof reason === 'string')
+                result.suggestions.push({ action: sanitizeErrorText(action), reason: sanitizeErrorText(reason) });
+        }
+    }
+    const budget = field(value, 'budget');
+    if (budget && typeof budget === 'object') {
+        const safe = {};
+        for (const key of ['requestedMaxTokens', 'maxTokens', 'outputLimit', 'contextLimit', 'estimatedInputTokens', 'thinkingBudget', 'contextSafetyMargin']) {
+            const raw = field(budget, key);
+            if (typeof raw === 'number' && Number.isFinite(raw))
+                safe[key] = raw;
+        }
+        for (const key of ['budgetSource', 'limitSource', 'contextAccounting']) {
+            const raw = field(budget, key);
+            if (typeof raw === 'string')
+                safe[key] = sanitizeErrorText(raw);
+        }
+        if (Object.keys(safe).length)
+            result.budget = safe;
+    }
+    for (const key of ['model', 'servedModel', 'requestedModel', 'resolvedModel', 'sessionId', 'requestId', 'upstreamRequestId', 'servedDeployment', 'agentId', 'parentAgentId', 'origin', 'protocol', 'timestamp', 'logPath', 'cliVersion', 'turnId']) {
+        const raw = field(value, key);
+        if (typeof raw === 'string')
+            result[key] = sanitizeErrorText(raw);
+    }
+    const upstream = sanitizeUpstreamDiagnostic(field(value, 'upstream'));
+    if (upstream)
+        result.upstream = upstream;
+    if (field(value, 'logWriteFailed') === true)
+        result.logWriteFailed = true;
+    return result;
+}
 /** Optional wire extension. Omit invalid data; never spread arbitrary payloads. */
 export function sanitizeRecoveryOutcome(value) {
     if (!value || typeof value !== 'object')
@@ -57,6 +173,16 @@ export function describeError(value) {
                 parts.push(`${key}=${sanitizeErrorText(String(field))}`);
             }
         }
+        const upstream = sanitizeUpstreamDiagnostic(own(node, 'upstream'));
+        if (upstream) {
+            for (const key of ['model', 'deployment', 'upstream_status', 'upstream_request_id', 'code', 'type', 'message', 'message_omitted_reason']) {
+                if (upstream[key] !== undefined) {
+                    const detail = `upstream.${key}=${String(upstream[key])}`;
+                    if (!parts.some(part => part.includes(detail)))
+                        parts.push(detail);
+                }
+            }
+        }
         visit(own(node, 'error'), depth + 1);
         visit(own(node, 'cause'), depth + 1);
     }
@@ -69,6 +195,16 @@ export function errorDetailsList(errors) {
 }
 /** Preserve successful data and the wire shape; sanitize diagnostic fields only. */
 export function sanitizeErrorEnvelope(message) {
+    if (message.type === 'system' && diagnosticField(message, 'subtype') === 'error_diagnostic') {
+        const diagnostic = sanitizeRecoveryDiagnostic(diagnosticField(message, 'diagnostic'));
+        const result = { type: 'system', subtype: 'error_diagnostic', ...(diagnostic ? { diagnostic } : {}) };
+        for (const key of ['session_id', 'uuid', 'timestamp']) {
+            const raw = diagnosticField(message, key);
+            if (typeof raw === 'string')
+                result[key] = sanitizeErrorText(raw);
+        }
+        return result;
+    }
     const wire = message;
     if (wire.type === 'result' && wire.is_error === true) {
         return {

package/dist/sdk/index.d.ts

@@ -10,4 +10,5 @@ export { query, queryHandleWithTransport } from './queryHandle.js';
 export { createSdkMcpServer, tool, SdkMcpRegistry, type SdkMcpToolDefinition, type McpSdkServerConfigWithInstance, } from './mcpServer.js';
 export { defaultStoreDir, fileSessionStore } from './store.js';
 export { spawnCliTransport } from './transport.js';
+export type { RecoveryDiagnostic } from './errorDiagnostics.js';
 export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SessionStore, Transport, Usage, WireMessage, } from './types.js';

package/dist/sdk/query.js

@@ -26,7 +26,7 @@
  *   is deleted after it is applied.
  */
 import { existsSync, mkdtempSync, symlinkSync } from 'fs';
-import { describeError, errorDetailsList, sanitizeErrorText, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
+import { describeError, errorDetailsList, sanitizeErrorEnvelope, sanitizeErrorText, sanitizeRecoveryDiagnostic, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
 import { interactionResponseSchema } from './interactionResponseSchema.js';
 import { tmpdir } from 'os';
 import { dirname, join, resolve } from 'path';
@@ -87,6 +87,8 @@ export function buildCliArgs(options) {
     // (Anthropic raw message stream) deltas. Default off keeps the minimal event set unchanged.
     if (options.includePartialMessages)
         args.push('--include-partial-messages');
+    if (options.includeErrorDiagnostics)
+        args.push('--include-error-diagnostics');
     // slice sdk-input-external-mcp (G2): external MCP servers via --mcp-config (JSON string).
     if (options.mcpServers && Object.keys(options.mcpServers).length > 0) {
         args.push('--mcp-config', JSON.stringify({ mcpServers: options.mcpServers }));
@@ -321,7 +323,11 @@ export async function* queryWithTransport(prompt, options, transport) {
         }
         // slice sdk-observability-hooks-usage (G5): fire onSessionStart once, on the first session_id.
         let sessionStarted = false;
-        for await (const message of transport.read()) {
+        for await (const rawMessage of transport.read()) {
+            // Keep ordinary raw passthrough unchanged. Diagnostic payloads are an
+            // untrusted error boundary even when a host asks for raw wire events.
+            const message = rawMessage.type === 'system' && rawMessage.subtype === 'error_diagnostic'
+                ? sanitizeErrorEnvelope(rawMessage) : rawMessage;
             if (typeof message.session_id === 'string') {
                 lastSessionId = message.session_id;
                 if (!sessionStarted) {
@@ -333,6 +339,17 @@ export async function* queryWithTransport(prompt, options, transport) {
             if (options.includeRaw)
                 yield { type: 'raw', message };
             switch (message.type) {
+                case 'system': {
+                    if (message.subtype === 'error_diagnostic') {
+                        const diagnostic = sanitizeRecoveryDiagnostic(message.diagnostic);
+                        if (diagnostic)
+                            yield {
+                                type: 'error_diagnostic', diagnostic,
+                                sessionId: typeof message.session_id === 'string' ? message.session_id : undefined,
+                            };
+                    }
+                    break;
+                }
                 case 'assistant': {
                     const sessionId = message.session_id;
                     for (const block of contentBlocks(message.message)) {

package/dist/sdk/types.d.ts

@@ -112,7 +112,7 @@ export type QueryOptions = {
     execPath?: string;
     /** Escape hatch: extra argv appended verbatim. */
     extraArgs?: string[];
-    /** Emit `raw` passthrough events for every subprocess message. */
+    /** Emit raw wire events. Error diagnostics remain sanitized and allowlisted. */
     includeRaw?: boolean;
     /**
      * slice sdk-token-streaming (G3): emit `stream_event` deltas as they arrive (token-level
@@ -121,6 +121,12 @@ export type QueryOptions = {
      * unchanged behavior; the full-block `assistant_text` events are still emitted alongside.
      */
     includePartialMessages?: boolean;
+    /**
+     * Opt in to nonterminal recovery diagnostics from the CLI. Default off keeps
+     * the historical wire event surface. A diagnostic supplies observations and
+     * suggestions; it is neither a result nor an instruction for the host to retry.
+     */
+    includeErrorDiagnostics?: boolean;
     /**
      * slice sdk-json-schema-output (G4): a JSON Schema for structured output. When set, the CLI
      * validates the final result against it (retrying the model) and returns `structuredOutput` on
@@ -280,6 +286,10 @@ export type SDKEvent = {
     type: 'assistant_text';
     text: string;
     sessionId?: string;
+} | {
+    type: 'error_diagnostic';
+    diagnostic: import('./errorDiagnostics.js').RecoveryDiagnostic;
+    sessionId?: string;
 } | {
     type: 'tool_use';
     toolName: string;

package/docs/ccl-duo-agent.md

@@ -0,0 +1,132 @@
+# Duo：一个 CCL 界面中的对等双 Agent 协作
+
+> npm 包的公开命令为 `margay`。下文带日期、提交号和本机 `~/.local/bin/ccl` 的记录属于历史验收；该本机入口不是 npm 安装保证提供的命令，也不代表当前候选已通过回归。
+
+> 本文描述截至 2026-09-21 已审核的候选提交 `1387fdae`。npm `next` 仍是更早的 `1.4.1-beta-duo.0`，不包含此后的修复；版本号本身不能确认本机 CLI 身份。历史验收记录见源码检出中的 `docs/ccl-duo-ux-validation.md`（不随 npm 包分发）。
+
+> 2026-09-21 的 Buddy 化简与 Duo 生命周期修复已完成代码复核和干净检出核验，仍非 npm 发版验收。RC8/RC10/C790 保持 HOLD。
+
+Duo 让一个 Agent 执行任务，另一个独立检查结果。双方各有上下文，必须通过两个不同的实际模型发起请求。执行者也要检查审核者的工作：是否真正看过材料、是否做了声称的测试、结论是否成立。
+
+适用于代码、设计方案、实施计划、产品文档和测试报告。通常只需「执行 → 审查 → 修改或完成」，无需逐轮提交 RLL 的 PLAN 和共识记录。普通 `/buddy` 和 Team 入口继续可用。
+
+## 先进入，再给任务
+
+在 CCL 交互界面中进入 Duo；默认按当前路由偏好自动选择两个不同的可用具体模型：
+
+```text
+/duo-agent
+```
+
+`/duo` 是同一个入口的短名。此时可以没有目标，界面保持待命；不会用空任务启动两个 Agent。需要手动指定审核模型时，可以输入：
+
+```text
+/duo --reviewer-model <固定模型ID>
+```
+
+```text
+检查这份数据库迁移方案，重点确认老客户端兼容性和回滚步骤。先给出修订方案，再独立审核。
+```
+
+也可以一次写完：
+
+```text
+/duo --reviewer-model <固定模型ID> 修复解析器漏掉最后一个 token 的问题，补测试并独立审核
+```
+
+在主输入框直接输入 `启动双 Agent 协作` 或 `开启双 Agent 协作` 也会进入同一待命入口。粘贴的材料、引用、工具输出和队友消息不会取得启动或控制权限。
+
+两个角色必须解析为不同的具体模型 ID；`auto`、`default` 等选择项会在发出模型请求前解析。若没有两种可用模型或模型验证失败，原任务保留在待命状态并显示原因，可调整配置后重试。
+
+## 看懂角色状态
+
+状态区分别显示 Developer 与 Reviewer。`Auto selected: <模型> · Unconfirmed` 或 `Configured: <模型> · Unconfirmed` 是选择信息，不是请求已发出的证据。只有当前会话中该角色自己的 Agent 请求被观察到，才显示 `Responding:` 或 `Last:`。主会话或其它会话的请求不能确认 Duo 角色，`Last:` 也不等于审核通过或任务完成。
+
+## 一次协作怎样结束
+
+| 阶段 | 双方做什么 | 是否完成 |
+|---|---|---|
+| 执行 | 执行者完成工作并提交具体版本 | 否 |
+| 审查 | 审核者检查提交材料、验证相关证据，给出 PASS 或 NEEDS_WORK | 否 |
+| 修改 | 根据问题修改并重新提交；旧结论不能批准新内容 | 否 |
+| 反审 | 执行者检查审核是否真实、充分、正确；认可当前 PASS 后明确接受 | 满足全部条件才完成 |
+
+完成还要求两个不同角色的真实模型请求、审核者针对当前提交和要求版本的意见，以及执行者对该意见的核查与接受。单模型直接回答、旧版本 PASS 和模型自称“已审核”都不能算完成。变化后的要求或材料需要重新提交和审核；如果主动使用正式挑战，未解决时也不能接受。普通讨论和不改变要求的意见不需要逐条确认工具门禁。
+
+### 讨论与挑战有什么区别
+
+**讨论**是默认方式：双方通过 Team 消息比较方案、追问细节、提出反证并要求复审，不需要专门的挑战工具序列。
+
+**挑战**用于影响结论正确性的关键分歧，例如：
+
+- 审核者声称测试通过，却没有实际测试结果。
+- 审核遗漏了明确的验收条件。
+- 双方对某项缺陷是否成立存在足以改变下一步工作的分歧。
+
+正式挑战仍可用于需要明确记录的关键分歧。主动创建的正式挑战在解决前会阻止接受；发起方核对补充证据后才能解决或撤回，历史记录保留。
+
+## 工作中加入意见
+
+在主输入框直接补充内容，意见会记录到当前 Duo 任务，并交给双方处理；通常不需要先暂停。意见已记录、已送达和双方已处理是不同状态，收到消息不等于接受了意见。
+
+当前入口保守地把普通补充视为要求变更，使之前的验收结论失效。例如：
+
+```text
+还需要兼容上一版客户端，请补充兼容性测试。
+```
+
+如果只是建议，明确使用以下前缀：
+
+```text
+仅供讨论，无验收变更：可以比较一下按模块拆分文档是否更易读。
+```
+
+这样的建议不改变验收版本，可通过双方消息讨论，无需逐条 `acknowledge_input`。`@name` 私信和当前查看的队友输入保持原来的独立路由；要向双方补充意见，请回到主输入框。
+
+## 暂停、恢复、退出
+
+| 输入 | 效果 |
+|---|---|
+| `/duo pause` | 请求双方暂停，阻止新工作；可取消的当前操作收到取消请求 |
+| `/duo resume` | 等待当前工作停止后，明确恢复双方协作 |
+| `/duo exit` | 立即解除 Duo 输入状态并返回普通会话；尝试有界取消与团队清理，保留审查记录 |
+
+暂停过程中仍可补充意见，补充本身不会恢复运行。存在暂时不能取消的操作时，状态会保持“正在暂停”；等它结束后才是“已暂停”。暂停前发出的晚到结果不能推进旧轮次；已经产生或结果不明的外部副作用需要核对，不能假设撤销成功或自动重复执行。
+
+Duo 退出和任务完成不是一回事。任务被接受后 Duo 回到待命，可直接输入下一项任务；即使旧材料后来变化，仍可接新任务或使用 `/duo exit`。清理失败会显示原因，但不能锁住输入。普通 `/exit` 退出 CCL 会话。
+
+### 必要时由用户裁决
+
+有未解决的正式挑战时，先暂停并等待双方停止，再说明裁决理由：
+
+```text
+/duo pause
+/duo adjudicate 兼容旧客户端是本次必须满足的条件，请按此补实现与测试
+```
+
+裁决会记录用户理由、解决当前未解决挑战，仍保留任务未完成和暂停状态。它不冒充双方审核通过，也不会自动完成或恢复任务。检查后用 `/duo resume` 继续；后续仍需有效审查和执行者反审。
+
+## 代码与文本材料
+
+- **Git 工作目录**：提交时记录代码材料的审核收据；审核者可在普通工作区检查和运行测试，不被锁在快照目录。
+- **非 Git 目录**：采用文本材料，适合设计方案、计划和报告；不需要先创建仓库。提交正文保存为 `material.md`，可包含明确选择的附件。
+
+每次审查绑定具体材料和要求版本。不能把“模型说看过了”当作提交材料一致的证明，也不能用一份旧 PASS 批准后来修改的文件。
+
+提交材料的副本只用于绑定审核版本，不是审核者的默认 cwd 或文件工具白名单，也不提供同一操作系统用户下的恶意 Shell 隔离。当前不承诺关闭 CCL 后自动恢复正在进行的 Duo 任务。
+
+## IDE 和其他入口
+
+IDE 先通过集成终端运行同一个 CCL 界面。2026-09-17 已实测连接 VS Code；当前构建需要临时禁用 WebSocket 的可选原生 bufferutil 实现：
+
+```sh
+WS_NO_BUFFER_UTIL=1 ~/.local/bin/ccl --ide
+```
+
+前提是 IDE 已安装兼容扩展、打开同一项目，并与 CCL 使用同一配置目录。完整步骤、默认连接失败记录和连接范围见 [CCL 在 VS Code 中的使用说明](ccl-ide-usage.md)。此临时参数没有修复产品默认行为，也不涉及 Gateway 升级。
+
+`/ide` 接通编辑器能力，聊天仍在 CCL 终端。Claude Code、Codex 各自有官方原生聊天扩展；使用它们的聊天面板运行 CCL，以及迁移当前 Duo 会话，均尚未验证。专用 Duo 面板、tmux 中的完整版 RLL 和 SDK 多用户服务另行处理。
+
+普通 `/buddy` 先创建或复用 Team，再按返回的实际团队名启动 Agent；`/buddy --peer-review` 仍需固定审核模型和开发目标。两条 Buddy 路径与 Duo 的完成条件不同，详见[轻量开发审查说明](peer-development-review.md)。
+
+实现范围与历史测试合同见源码检出中的 `docs/ccl-duo-ux-tdd-plan.md` 和 `docs/ccl-duo-ux-validation.md`（不随 npm 包分发）。当前已审核候选通过 4,081 项源码测试、19 项跳过、102 项 Duo 定向测试、类型检查、36 项构建门禁与 5 项 smoke；隔离安装包的有头终端场景分别通过完整审核与接受 15/15 步、下一任务单模型答复未完成负例 18/18 步。它们使用确定性 provider，不代表真实模型判断质量或发版通过。

package/docs/ccl-ide-usage.md

@@ -0,0 +1,75 @@
+# 在 VS Code 中使用 CCL 与 Duo
+
+更新：2026-09-17。本机安装构建：`7a75f333`（版本显示 `1.4.0-beta.0`）。当前提供终端界面与 IDE 连接；尚未验证用原生聊天面板运行 CCL/Duo。
+
+## 当前验证到了哪里
+
+| 路径 | 状态 |
+|---|---|
+| 已安装 CCL 的终端 Duo | 三项 wezterm-gui 有头场景通过，详见[验收记录](ccl-duo-ux-validation.md) |
+| CCL → VS Code 编辑器连接 | 加临时环境变量后，已验证握手、服务能力及实际 TCP 连接 |
+| 默认 CCL → VS Code 连接 | 已复现 `bufferUtil.mask is not a function`，尚未修复 |
+| 在 VS Code 集成终端启动同一 CCL | 可按下文操作；本轮实际连接客户端运行在外部 WezTerm，未独立完成集成终端中的 Duo 全流程验收 |
+| Trae 连接 | 未实测，不由 VS Code 结果推定兼容 |
+| CCL/Duo 原生聊天面板、终端会话迁移 | 尚未验证，不承诺直接切换或保留正在运行的 Duo 状态 |
+
+## 在已打开的测试 VS Code 窗口使用
+
+1. 打开与 CCL 相同的项目目录。
+2. 如果另一个 CCL 已连接该 VS Code，先在那个 CCL 的 `/ide` 菜单选择 `None`，或退出该 CCL。当前界面提示同一 VS Code 一次连接一个 CCL。
+3. 在 VS Code 菜单中选择 **终端 → 新建终端**，运行：
+
+   ```sh
+   WS_NO_BUFFER_UTIL=1 ~/.local/bin/ccl --ide
+   ```
+
+4. 若需要手动选择连接，在 CCL 内执行 `/ide` 并选中 Visual Studio Code。自动连接设置可按个人偏好选择。
+5. 在同一 CCL 界面进入 Duo：
+
+   ```text
+   /model
+   /duo-agent
+   /duo --reviewer-model <固定模型ID>
+   ```
+
+   `/model` 选择执行模型，最后一行配置审核模型，然后直接输入任务。双方可用不同模型。暂停、恢复及反审规则见 [Duo 使用说明](ccl-duo-agent.md)。
+
+`WS_NO_BUFFER_UTIL=1` 让本次进程使用 WebSocket 的 JavaScript 实现，绕过已复现的可选原生模块错误。它不会永久修改环境或安装包；Gateway 不需要升级。
+
+## 扩展与配置目录
+
+本次连接使用官方 `anthropic.claude-code` 扩展 2.1.274 的 IDE 服务。CCL 默认在 `~/.ccl/ide` 发现服务，扩展需要随 IDE 启动时取得 `CLAUDE_CONFIG_DIR=~/.ccl`。如果自定义了 `CCL_CONFIG_DIR`，应使用那个实际目录。不要通过复制锁文件、token 或修改原始会话来拼接连接。
+
+为保留日常 VS Code 配置，本次测试使用独立目录：
+
+- IDE 用户数据：`~/.local/share/ccl/ide-vscode-session/user-data`
+- 扩展：`~/.local/share/ccl/ide-vscode-session/extensions`
+
+这两个目录中已完成扩展安装。重新打开同一个测试配置时，先进入项目目录，再执行：
+
+```sh
+CLAUDE_CONFIG_DIR="$HOME/.ccl" CCL_CONFIG_DIR="$HOME/.ccl" \
+  "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" \
+  --new-window \
+  --user-data-dir "$HOME/.local/share/ccl/ide-vscode-session/user-data" \
+  --extensions-dir "$HOME/.local/share/ccl/ide-vscode-session/extensions" \
+  "$PWD"
+```
+
+已运行的 IDE 进程可能沿用原环境；发现服务目录不一致时，先保存文件并关闭这个测试配置的窗口，再用上面的命令启动。无需关闭其他日常 VS Code 窗口。
+
+## 终端聊天与原生聊天面板
+
+`/ide` 接通编辑器服务，不会把终端聊天界面转换成图形聊天面板。
+
+- **Claude Code 官方扩展**有原生聊天面板，并与官方 Claude CLI 共享会话历史。这是官方 Claude Code 的能力，不能直接推定 CCL 的自定义 Duo 状态同样兼容。[官方文档](https://code.claude.com/docs/en/vs-code)
+- **Codex 官方扩展**有侧边栏聊天、文件/选区上下文和修改审查界面。[OpenAI 官方文档](https://developers.openai.com/codex/ide/)
+- 本机 Claude 扩展提供 `claudeCode.claudeProcessWrapper` 启动入口设置，但它是否足以接入 CCL、多模型与 Duo 的输入/暂停/挑战/恢复，需要单独验证。当前没有将原生面板后端切换为 CCL。
+
+后续可先验证复用已有面板的可行性，再判断是否需要专用扩展；这不是已交付功能。当前也没有把 CCL 会话复制进官方 Claude 或 Codex 的历史记录。
+
+## 证据与未完成项
+
+原 RLL 工作目录的 `.dual-agent/test-evidence/ccl-ide-manual-connection/` 保存默认失败和临时处理后的成功日志。成功握手耗时 25ms，服务为 `Claude Code VSCode MCP` 2.1.274，返回 `hasTools=true`；未逐个执行 IDE 工具或发送真实模型任务。
+
+待处理：默认 WebSocket `bufferutil` 兼容问题的产品修复、集成终端实际 Duo 流程验收、现有原生面板接 CCL 的可行性验证。Gateway/Margay 未因本次连接测试修改。

package/docs/dev-quickstart.md

@@ -0,0 +1,105 @@
+# CCL Developer Quick Start
+
+This guide is for developers validating a source checkout of CCL `1.3.1`. It is
+not a place to store shared credentials or production gateway details.
+
+## 1. Install Dependencies
+
+```bash
+git clone https://github.com/YW1975/ccl.git
+cd ccl
+npm install
+```
+
+## 2. Build And Smoke Check
+
+```bash
+npm run build
+node dist/cli.js --version
+node dist/cli.js --help
+```
+
+Expected version output:
+
+```text
+1.3.1 (CCL)
+```
+
+## 3. Optional Gateway Setup
+
+Use placeholders in local notes and docs. Never commit real tokens.
+
+```bash
+export CCL_GATEWAY_URL=<GATEWAY_URL>
+export CCL_GATEWAY_KEY=<GATEWAY_TOKEN>
+```
+
+Or configure through the TUI:
+
+```text
+ccl
+/gateway login <GATEWAY_URL> <GATEWAY_TOKEN>
+/gateway doctor
+```
+
+If a shell already has stale gateway variables, clear them before retesting:
+
+```bash
+unset CCL_GATEWAY_URL CCL_GATEWAY_KEY
+```
+
+## 4. Run Basic Checks
+
+```bash
+npm run typecheck
+npm test
+npm run test:smoke
+```
+
+For CLI-only validation:
+
+```bash
+node dist/cli.js --version
+node dist/cli.js --help
+node dist/cli.js -p "say hello" --max-turns 1
+```
+
+The final command requires valid authentication.
+
+## 5. Useful Developer Commands
+
+| Command | Purpose |
+|---|---|
+| `npm run build` | Build CLI and SDK outputs |
+| `npm run build:sdk` | Build SDK declarations and JS |
+| `npm run typecheck` | TypeScript no-emit check |
+| `npm test` | Vitest suite |
+| `npm run test:smoke` | Smoke test suite |
+| `node dist/cli.js --help` | Verify packaged CLI surface |
+| `node dist/cli.js doctor` | Diagnose a trusted checkout |
+
+## 6. Debugging
+
+```bash
+node dist/cli.js --debug --verbose
+node dist/cli.js --debug-file /tmp/ccl-debug.log
+```
+
+Keep debug logs out of public issues unless you have scrubbed:
+
+- API keys and gateway tokens.
+- Real gateway hosts that are not intended to be public.
+- User prompts, file paths, and tool inputs that may contain private data.
+
+## 7. Documentation Rule
+
+Developer docs must use safe placeholders:
+
+```text
+<GATEWAY_URL>
+<GATEWAY_TOKEN>
+<ANTHROPIC_API_KEY>
+```
+
+Do not reintroduce concrete public IP addresses, shared team keys, or historical
+gateway endpoint strings into current official documentation.