@margay/ccl-core 1.4.5-rc.9 → 1.5.0-alpha.0

package/dist/sdk/session.d.ts

@@ -0,0 +1,53 @@
+import type { Query, QueryOptions, SDKEvent, SDKUserMessage, SessionLifecycleEvent, Transport } from './types.js';
+export type TurnResult = Extract<SDKEvent, {
+    type: 'result';
+}>;
+export type SessionControls = Omit<Query, keyof AsyncGenerator<SDKEvent, void, unknown>>;
+export type SessionOptions = QueryOptions & {
+    /** Maximum accepted but not yet completed turns, including the active turn. */
+    maxPendingTurns?: number;
+    /** Events are delivered as they arrive; Session does not retain an event history. */
+    onEvent?: (event: SDKEvent) => void;
+    /** Deterministic queue/dispatch/permission/terminal observations. No model call.
+     * Keep observers fast; thrown errors are isolated from execution. */
+    onLifecycle?: (event: SessionLifecycleEvent) => void;
+};
+export interface Turn {
+    readonly id: string;
+    readonly result: Promise<TurnResult>;
+    cancel(): Promise<void>;
+}
+/** One CLI process, sequential turns, and a bounded host-side input queue. */
+export declare class Session {
+    readonly pid: number | undefined;
+    /** Existing SDK controls, including initialization, model and task controls. */
+    readonly controls: SessionControls;
+    private readonly handle;
+    private readonly limit;
+    private readonly options;
+    private queue;
+    private active?;
+    private wake?;
+    private accepting;
+    private closed;
+    private drainWaiters;
+    private readonly pumping;
+    private sessionId?;
+    constructor(options?: SessionOptions, transport?: Transport);
+    prompt(content: SDKUserMessage['message']['content']): Turn;
+    followUp(content: SDKUserMessage['message']['content']): Turn;
+    /** Interrupt the active turn; correction runs before queued follow-ups. */
+    steer(content: SDKUserMessage['message']['content']): Turn;
+    private enqueue;
+    private inputs;
+    private consume;
+    private observe;
+    private fail;
+    private notifyDrained;
+    interrupt(): Promise<void>;
+    private cancel;
+    /** Stop accepting inputs and drain accepted turns, keeping controls alive. */
+    endInput(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createSession(options?: SessionOptions): Session;

package/dist/sdk/session.js

@@ -0,0 +1,222 @@
+import { randomUUID } from 'node:crypto';
+import { queryHandleWithTransport } from './queryHandle.js';
+import { spawnForOptions } from './query.js';
+/** One CLI process, sequential turns, and a bounded host-side input queue. */
+export class Session {
+    pid;
+    /** Existing SDK controls, including initialization, model and task controls. */
+    controls;
+    handle;
+    limit;
+    options;
+    queue = [];
+    active;
+    wake;
+    accepting = true;
+    closed = false;
+    drainWaiters = [];
+    pumping;
+    sessionId;
+    constructor(options = {}, transport) {
+        this.limit = options.maxPendingTurns ?? 32;
+        if (!Number.isSafeInteger(this.limit) || this.limit < 1) {
+            throw new RangeError('ccl-sdk: maxPendingTurns must be a positive integer');
+        }
+        if (options.pendingDecision)
+            throw new Error('ccl-sdk: resume a pending decision before creating a Session');
+        this.options = options;
+        this.sessionId = options.sessionId ?? options.resume;
+        const owned = transport ?? spawnForOptions(options);
+        this.pid = owned.pid;
+        this.handle = queryHandleWithTransport(this.inputs(), { ...options, hooks: {
+                ...options.hooks,
+                onUserPromptSubmit: async (event) => {
+                    if (this.active && !this.active.started) {
+                        this.active.started = true;
+                        this.observe({ type: 'turn_started', turnId: this.active.turn.id });
+                    }
+                    await options.hooks?.onUserPromptSubmit?.(event);
+                },
+                onSessionStart: async (event) => {
+                    this.sessionId = event.sessionId;
+                    await options.hooks?.onSessionStart?.(event);
+                },
+            } }, owned);
+        this.controls = this.handle;
+        this.pumping = this.consume();
+    }
+    prompt(content) {
+        return this.enqueue(content, false);
+    }
+    followUp(content) {
+        return this.enqueue(content, false);
+    }
+    /** Interrupt the active turn; correction runs before queued follow-ups. */
+    steer(content) {
+        const turn = this.enqueue(content, true);
+        if (this.active)
+            void this.interrupt().catch(error => this.fail(error));
+        return turn;
+    }
+    enqueue(content, priority) {
+        if (!this.accepting || this.closed)
+            throw new Error('ccl-sdk: session input is closed');
+        if (this.queue.length + (this.active ? 1 : 0) >= this.limit) {
+            throw new Error(`ccl-sdk: session queue is full (${this.limit} pending turns)`);
+        }
+        const id = randomUUID();
+        let resolve;
+        let reject;
+        const result = new Promise((yes, no) => { resolve = yes; reject = no; });
+        // It is valid to enqueue follow-ups and observe their results later.
+        void result.catch(() => { });
+        const turn = { id, result, cancel: () => this.cancel(id) };
+        const entry = { turn, resolve, reject, input: {
+                type: 'user', uuid: id, message: { role: 'user', content },
+            } };
+        if (priority)
+            this.queue.unshift(entry);
+        else
+            this.queue.push(entry);
+        this.observe({ type: 'turn_queued', turnId: id });
+        this.wake?.();
+        return turn;
+    }
+    async *inputs() {
+        while (!this.closed) {
+            if (this.active) {
+                await new Promise(resolve => { this.wake = resolve; });
+                this.wake = undefined;
+                continue;
+            }
+            const entry = this.queue.shift();
+            if (entry) {
+                this.active = entry;
+                yield entry.input;
+            }
+            else {
+                await new Promise(resolve => { this.wake = resolve; });
+                this.wake = undefined;
+            }
+        }
+    }
+    async consume() {
+        try {
+            for await (const event of this.handle) {
+                if ('sessionId' in event && event.sessionId)
+                    this.sessionId = event.sessionId;
+                const correlated = { ...event, turnId: event.turnId ?? (event.type === 'result' || event.origin === 'background' ? undefined : this.active?.turn.id) };
+                // Observability callbacks must not terminate the agent or strand work.
+                try {
+                    this.options.onEvent?.(correlated);
+                }
+                catch { /* host observer */ }
+                if (event.type === 'permission_request') {
+                    this.observe({ type: 'permission_waiting', turnId: correlated.turnId, requestId: event.requestId,
+                        toolUseId: event.toolUseId, toolName: event.toolName });
+                }
+                else if (event.type === 'permission_resolved') {
+                    this.observe({ type: 'permission_resolved', turnId: correlated.turnId, requestId: event.requestId,
+                        toolUseId: event.toolUseId, behavior: event.behavior });
+                }
+                if (event.type === 'result' && event.turnId !== undefined && this.active) {
+                    if (event.turnId !== this.active.turn.id)
+                        throw new Error('ccl-sdk: mismatched turn result');
+                    const entry = this.active;
+                    this.active = undefined;
+                    this.observe({ type: 'turn_finished', turnId: entry.turn.id,
+                        outcome: event.isError ? entry.cancelRequested ? 'interrupted' : 'failed' : 'succeeded',
+                        ...(event.isError ? { reason: event.subtype } : {}) });
+                    entry.resolve(event);
+                    this.wake?.();
+                    this.notifyDrained();
+                }
+                else if (event.type === 'error' && event.fatal) {
+                    throw new Error(event.message);
+                }
+                else if (event.type === 'suspended') {
+                    this.fail(new Error(`ccl-sdk: session suspended; resumeWithDecision(${event.sessionId}) is required`), event.origin === 'background' ? 'interrupted' : 'suspended');
+                    break;
+                }
+            }
+            if (!this.closed)
+                this.fail(new Error('ccl-sdk: session transport ended'));
+        }
+        catch (error) {
+            this.fail(error);
+        }
+        finally {
+            await this.controls.close();
+        }
+    }
+    observe(event) {
+        try {
+            this.options.onLifecycle?.({ ...event, at: Date.now(), pid: this.pid, sessionId: this.sessionId,
+                pendingTurns: this.queue.length + (this.active ? 1 : 0) });
+        }
+        catch { /* host observer */ }
+    }
+    fail(reason, outcome = 'interrupted') {
+        if (this.closed)
+            return;
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        this.closed = true;
+        this.accepting = false;
+        const active = this.active;
+        this.active = undefined;
+        const queued = this.queue.splice(0);
+        if (active) {
+            this.observe({ type: 'turn_finished', turnId: active.turn.id, outcome, reason: error.message });
+            active.reject(error);
+        }
+        for (const entry of queued) {
+            this.observe({ type: 'turn_finished', turnId: entry.turn.id, outcome: 'cancelled', reason: error.message });
+            entry.reject(error);
+        }
+        this.observe({ type: 'session_closed', reason: error.message });
+        this.wake?.();
+        this.notifyDrained();
+        void this.controls.close().catch(() => { });
+    }
+    notifyDrained() {
+        if (this.active || this.queue.length)
+            return;
+        for (const resolve of this.drainWaiters.splice(0))
+            resolve();
+    }
+    async interrupt() {
+        if (this.active) {
+            if (!this.active.cancelRequested) {
+                this.active.cancelRequested = true;
+                this.observe({ type: 'turn_cancel_requested', turnId: this.active.turn.id });
+            }
+            await this.controls.interrupt();
+        }
+    }
+    async cancel(id) {
+        if (this.active?.turn.id === id)
+            return this.interrupt();
+        const index = this.queue.findIndex(entry => entry.turn.id === id);
+        if (index < 0)
+            return;
+        const entry = this.queue.splice(index, 1)[0];
+        this.observe({ type: 'turn_finished', turnId: id, outcome: 'cancelled', reason: 'Cancelled before dispatch' });
+        entry.reject(new Error('ccl-sdk: queued turn cancelled'));
+        this.notifyDrained();
+    }
+    /** Stop accepting inputs and drain accepted turns, keeping controls alive. */
+    async endInput() {
+        this.accepting = false;
+        if (!this.active && !this.queue.length)
+            return;
+        await new Promise(resolve => this.drainWaiters.push(resolve));
+    }
+    async close() {
+        this.fail(new Error('ccl-sdk: session closed'));
+        await this.controls.close();
+        await this.pumping;
+    }
+}
+export function createSession(options = {}) {
+    return new Session(options);
+}

package/dist/sdk/types.d.ts

@@ -142,6 +142,8 @@ export type QueryOptions = {
      * suggestions; it is neither a result nor an instruction for the host to retry.
      */
     includeErrorDiagnostics?: boolean;
+    /** Opt-in finite, nonterminal gateway status events. Defaults to false. */
+    includeRequestProgress?: 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
@@ -297,10 +299,63 @@ export type Usage = {
  * minimal set from the issue (P0-1) plus `permission_resolved` (audit trail)
  * and optional `raw` passthrough.
  */
-export type SDKEvent = {
+export type SDKUserMessage = {
+    type: 'user';
+    message: {
+        role: 'user';
+        content: string | Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+    };
+    uuid?: string;
+    parent_tool_use_id?: null;
+    session_id?: string;
+};
+export type SDKEvent = SDKEventPayload & {
+    turnId?: string;
+    origin?: 'user' | 'background';
+};
+/** Host observations, separate from model output and artifact verification.
+ * started means the input was written to the CLI, not that a model responded.
+ * Active interruptions can have external effects; they are not queued cancellations. */
+export type SessionLifecycleEvent = {
+    at: number;
+    pid?: number;
+    sessionId?: string;
+    pendingTurns: number;
+} & ({
+    type: 'turn_queued' | 'turn_started' | 'turn_cancel_requested';
+    turnId: string;
+} | {
+    type: 'turn_finished';
+    turnId: string;
+    outcome: 'succeeded' | 'failed' | 'cancelled' | 'interrupted' | 'suspended';
+    reason?: string;
+} | {
+    type: 'permission_waiting';
+    turnId?: string;
+    requestId: string;
+    toolUseId: string;
+    toolName: string;
+} | {
+    type: 'permission_resolved';
+    turnId?: string;
+    requestId: string;
+    toolUseId: string;
+    behavior: 'allow' | 'deny';
+} | {
+    type: 'session_closed';
+    reason: string;
+});
+type SDKEventPayload = {
     type: 'assistant_text';
     text: string;
     sessionId?: string;
+} | {
+    type: 'request_progress';
+    progress: import('./requestProgress.js').GatewayRequestProgress;
+    sessionId?: string;
 } | {
     type: 'error_diagnostic';
     diagnostic: import('./errorDiagnostics.js').RecoveryDiagnostic;
@@ -452,3 +507,4 @@ export type Transport = {
      * rewritten). Absent for in-memory test transports. */
     pid?: number;
 };
+export {};

package/docs/ccl-duo-agent.md

@@ -100,6 +100,8 @@ Duo 让一个 Agent 执行任务，另一个独立检查结果。双方各有上
 
 本地修复候选在模型查询失败终止后将对应 Duo 任务置为暂停，保留材料和审查记录。先检查错误、凭据或模型可用性，再使用 `/duo resume`；失败不会被标为审核完成。
 
+2026-10-15 本地候选修复了超时后“显示已恢复、任务仍停在暂停阶段”的问题。恢复时根据当前要求、材料和有效审核记录重新确定工作阶段，再允许双方继续；暂停期间改过要求时，旧 PASS 不能恢复为可接受状态。此修复尚未发布。
+
 Duo 退出和任务完成不是一回事。任务被接受后 Duo 回到待命，可直接输入下一项任务；即使旧材料后来变化，仍可接新任务或使用 `/duo exit`。清理失败会显示原因，但不能锁住输入。普通 `/exit` 退出 CCL 会话。
 
 ### 必要时由用户裁决

package/docs/cli-installation.md

@@ -0,0 +1,86 @@
+# CLI installation and upgrades
+
+For `1.4.5-rc.10`, use Node.js `>=22.19.0`. This matches the declared minimum of
+the pinned `undici 8.0.2` runtime dependency; the earlier Node 20 declaration no
+longer applies. macOS Node/Bun verification does not imply Windows verification.
+
+Starting with `1.4.5-rc.10`, CCL declares `ccl` and `margay` as names for the same
+`dist/cli.js`. Both names must report the package version and provide the same
+options. The `1.4.5-rc.9` package declares only
+`margay`. Installing that existing version will not add `ccl`.
+
+## Global and project installs
+
+For a terminal command available outside a project, install the desired released
+version globally:
+
+```sh
+npm install --global @margay/ccl-core@latest
+margay --version
+```
+
+After installing a release with both entries, also run `ccl --version`. Both
+outputs must match the installed package's version. Global installation does not
+replace a CLI embedded in Margay Desktop or already loaded by a running process.
+
+Without `--global`, npm installs a project dependency. Run that copy explicitly:
+
+```sh
+npm install @margay/ccl-core@latest
+./node_modules/.bin/margay --version
+```
+
+Releases with both entries also provide `./node_modules/.bin/ccl`. A successful
+project install does not upgrade commands elsewhere on the shell's PATH.
+
+## Migrating old custom launchers (macOS/Linux)
+
+Some earlier local deployments created shell scripts that pin a release path.
+These are separate from npm-managed links. Inspect resolution before and after
+upgrading:
+
+```sh
+type -a ccl margay
+npm prefix --global
+npm ls --global @margay/ccl-core --depth=0
+```
+
+There are two distinct cases:
+
+- **npm reports `EEXIST`:** an unmanaged launcher occupies the intended npm bin
+  path. Inspect the named file and confirm it belongs to the old CCL deployment.
+  Move that specific file to an unused backup path, then repeat the installation.
+  Preserve unrelated executables; a blanket `--force` is not a migration plan.
+- **Installation succeeds, but the command reports an old version:** an alias,
+  shell function or an earlier PATH directory is taking precedence. Inspect the
+  resolved entry. Back up the specific obsolete CCL wrapper, or update an explicit
+  alias/function to use the npm entry. Ensure the npm prefix's `bin` directory is
+  on PATH. Refresh the shell command cache (`rehash` in zsh, `hash -r` in bash),
+  then verify both commands again from outside the source checkout.
+
+Keep each backup until the new commands work. To roll back a custom wrapper,
+restore its saved bytes at the original path after inspecting what currently
+occupies that path. For an npm-managed installation, install the previous exact
+version. Future npm upgrades manage both links once the custom wrappers have
+been migrated.
+
+## Checking a release tarball
+
+From a built checkout, pack the release and test its actual npm installation:
+
+```sh
+npm pack --ignore-scripts --pack-destination /path/to/artifacts
+node tests/package-cli-install.mjs /path/to/artifacts/candidate.tgz /path/to/previous.tgz
+```
+
+The smoke test uses isolated install prefixes, HOME/configuration and cache. It
+checks fresh global and project installs, upgrade from the previous tarball,
+both commands through PATH, matching executable/version/help, an unmanaged-file
+collision, backup migration and PATH shadowing. Dependency lifecycle scripts are
+disabled; this verifies CLI installation and startup, not native dependency or
+model behavior. It currently runs on POSIX; Windows `.cmd`/PowerShell launchers
+require a Windows run. It cleans its temporary installations even on failure.
+
+Use the final tarball as the test input. A metadata edit after publishing rc.9
+does not change rc.9 on npm; allocate a new version, rebuild, pack and verify
+before publishing the corrected release.

package/docs/context-checkpoints-and-daemon.md

@@ -0,0 +1,91 @@
+# Completed-step checkpoints and background scheduling
+
+For a long task, `ContextCheckpoint` can save selected completed tool results with
+a summary and artifact references. Subsequent requests carry that summary and
+retrieval references. Full original outputs, including image blocks, remain in
+the session's transcript-adjacent `.checkpoints` directory with SHA-256 integrity
+checks. `list` locates saved records; `restore` makes the original evidence
+available again, including after transcript compaction or resume.
+
+At a completed phase, omit `tool_use_ids` to save all eligible completed results.
+For a subset, `list` returns available result IDs with their tool names and inputs.
+Use the `checkpoint_id` returned by `save` or `list` when restoring; invented
+protocol IDs are rejected.
+
+The model chooses completed work; the tool rejects missing results, unresolved
+permission interactions, errors, background launches, and duplicate archives.
+User messages, corrections and user-supplied images are never projected away.
+Checkpoint storage failures leave the incoming context intact. This path uses the
+existing full compaction and result-budget machinery; it does not enable the
+unimplemented provider cache-editing features. Checkpointing can change cache
+reuse and adds tool calls, so savings depend on the actual task and provider.
+
+`ccl daemon start --cwd /path/to/project` starts a detached local owner for the
+project's existing `.ccl/scheduled_tasks.json`. The launching CLI may exit; the
+owner remains. `ccl daemon run` is the foreground equivalent for an external
+service manager. This command does not install a login or reboot service.
+
+The owner uses the existing cron scheduler and project lock. It records an
+occurrence before acknowledging it, then records execution and local delivery
+separately under `.ccl/daemon/`. `status` shows these records. Completed output is
+saved in `results/`; tool/events evidence is retained in `events/`. There is no
+automatic email, chat or other external delivery.
+
+```sh
+ccl daemon status --cwd /path/to/project
+ccl daemon cancel OCCURRENCE_ID --cwd /path/to/project
+ccl daemon approve OCCURRENCE_ID allow --cwd /path/to/project
+ccl daemon approve OCCURRENCE_ID deny --cwd /path/to/project
+ccl daemon run-missed OCCURRENCE_ID --cwd /path/to/project
+ccl daemon deliver OCCURRENCE_ID --cwd /path/to/project
+ccl daemon stop --cwd /path/to/project
+```
+
+The CLI's existing permission rules apply. An unresolved permission suspends
+execution until an explicit `approve` decision. Missed one-shot tasks are retained
+as `missed` and need `run-missed`; recurring timing follows the shared scheduler.
+On restart, accepted but not started work can continue. Work interrupted after
+execution began is recorded as `interrupted` and never automatically replayed:
+inspect its events and external effects before scheduling new work. `deliver`
+retries saving an already successful result, without rerunning its tools.
+
+`cancel` stops an occurrence; delete the durable cron definition as well when
+future recurring occurrences should cease. A permission wait and an interrupted
+run remain visible across restarts. Stop does not erase schedules or evidence.
+
+When asking the assistant to schedule work, choose its execution scope:
+
+- `CronCreate {execution: "session", afterMs: 60000, prompt: "…"}` keeps the
+  reminder in the current process. A one-shot print command exits after its turn,
+  so this scope does not promise execution after exit.
+- `CronCreate {execution: "background", afterMs: 60000, prompt: "…"}` saves the
+  definition durably and starts or reuses the project's detached owner. Calendar
+  and anchored interval schedules use the same scope selection.
+- Older calls with only `durable: true` still save the definition without starting
+  an owner. Explicit `execution: "session"` cannot be combined with durable storage.
+
+The response separates `saved`, `status`, `owner.ready`, canonical `project`,
+`nextRunAt`, `permissions`, and `resultDirectory`. `background_ready` requires a
+live protocol response and ownership of the project scheduler lock. An interactive
+scheduler yields that lock after its pending definition writes finish; private
+session reminders continue in their own process.
+
+If the response is `saved_not_running`, retain its task ID and use
+`CronCreate {operation: "handoff", taskId: "…"}` to retry. This keeps the same
+schedule and identity. Do not create a duplicate. A different CLI path or configuration
+already running for the project is reported explicitly; inspect it and stop it
+before handing off with the new configuration. Startup does not inherit the
+creating terminal's permission bypass mode. Existing configured rules apply,
+and unresolved actions remain `waiting_permission` until explicitly approved.
+
+The owner uses the creating CLI path, model, configuration inputs and credential
+environment. Protocol, multiplexer and test-session variables are removed. Launch
+configuration is passed through a private pipe, without writing gateway credentials
+into task or owner records. Restarting after a reboot requires starting an owner
+again with valid configuration; no temporary credentials are promoted to permanent
+configuration.
+
+`CronList` includes background execution/delivery records and result locations,
+even after a completed one-shot definition has been removed. `ccl daemon status`
+provides the same records from a fresh CLI. Process liveness (`running`) and verified
+scheduler readiness (`owner.ready`) are separate fields.

package/docs/gateway-quickstart.md

@@ -190,8 +190,60 @@ by endpoint switching.
 Output/context limits do not mean the account is out of credit. See the
 [recovery guide](./error-recovery-usage.md) for consent and external-blocker UX.
 
+## Request Deadlines And Slow Waits
+
+The source candidate adds connection and response deadlines while preserving
+the existing total request setup budget. These values are milliseconds:
+
+| Variable | Default | Applies until |
+| --- | --- | --- |
+| `CCL_GATEWAY_REQUEST_TIMEOUT_MS` | `300000` | A response stream is established, including retry delays |
+| `CCL_GATEWAY_CONNECT_TIMEOUT_MS` | Total setup budget | A pooled/new connection can send the request |
+| `CCL_GATEWAY_RESPONSE_TIMEOUT_MS` | Total setup budget | Response headers arrive after sending |
+| `CCL_GATEWAY_SLOW_WAIT_MS` | `30000` | A single slow-status notice becomes eligible |
+
+Values must be whole numbers from 1 to 3600000. Invalid values fall back to the
+default and produce a one-time stderr notice. A phase deadline cannot extend
+the remaining total budget, and retries do not receive a new total budget.
+Defaults therefore do not shorten the existing five-minute setup allowance.
+
+For example, allow up to 30 seconds to connect and 180 seconds for headers:
+
+```sh
+CCL_GATEWAY_CONNECT_TIMEOUT_MS=30000 CCL_GATEWAY_RESPONSE_TIMEOUT_MS=180000 margay
+```
+
+After streaming starts, the separate model-progress idle watchdog applies;
+the setup deadline does not impose a maximum duration on healthy output.
+The TUI shows the current request phase and a slow-wait notice. Escape cancels
+through the existing task cancellation path. Status notices do not reset the
+model-progress watchdog or become assistant text.
+
+A local timeout reports `gateway_request_timeout` with the observed phase.
+It cannot establish whether the remote request completed. Check task state
+before repeating work that may have side effects. SDK hosts can opt into
+[structured request status](../sdk/README.md#gateway-request-status-source-candidate).
+
 ## Troubleshooting
 
+In the source candidate, headless runs with `CI=1` can authenticate using an
+admitted gateway configuration alone. A separate Anthropic API key is not
+required for that route. Missing or rejected gateway credentials still require
+a valid login or another supported credential source. This fixes a startup
+failure present in rc.9; it does not change the gateway's 401 handling.
+
+The source candidate also reports a failed in-process teammate request to its
+team leader with the visible failure reason. The teammate remains available for
+explicit new work after the failure; a timeout does not automatically retry the
+task or mark it complete. Check any uncertain side effects before resuming.
+
+In the source candidate, headless background completions belong to the input
+that launched them. They share that input's `--max-turns` ceiling and cannot
+restart it after an error or interrupt. Successful background work is collected
+before its final result. A new SDK input can start fresh work; late notifications
+from the previous input do not start model calls for it. Closing an SDK query
+also waits for background shell termination during the CLI's bounded shutdown.
+
 | Symptom | Action |
 | --- | --- |
 | Website offers no login entry | Confirm that login is enabled for that website/environment; a 200 page alone does not prove it is enabled. Cancel the CLI wait if disabled |

package/docs/releases/1.4.5-rc.10.md

@@ -0,0 +1,50 @@
+# 1.4.5-rc.10
+
+本版本包含双命令入口和 Mac Phase B 稳定性修复。包同时注册 `ccl` 和
+`margay`，两个命令指向同一份运行程序，功能、参数和版本相同。
+CLI 与 SDK 随同一个 `@margay/ccl-core` 包交付。
+
+## 相对 rc.9 的更新
+
+- 网关请求区分连接、等待响应和流式读取阶段，阶段期限共用请求总期限。
+  CLI/SDK 可选择接收等待进度；通知异常不阻塞请求，不混入模型上下文。
+- 无头执行的一次输入只返回一个终态。任务失败后，旧后台通知不会重新唤起模型、
+  执行工具或重复返回结果；取消及 SDK 关闭会清理所属后台任务。
+- 自动继续与压缩累计使用剩余任务预算，避免重置额度后不断运行。
+- 修复 CI 网关凭据识别、Duo 超时后的恢复，以及进程内/独立进程 Swarm 的失败通知。
+- 保留 rc.9 的输出预算、慢请求等待和有界断流恢复；已完成工具结果继续保留。
+- 将外部运行依赖 `undici` 固定为本候选验证过的 `8.0.2`，避免全新 npm 安装
+  自动选择不同版本。Node 声明要求调整为 `>=22.19.0`，与该依赖声明一致；
+  原先的 Node 20 支持声明不再适用。
+
+## 安装与升级
+
+全局安装后核对两个入口：
+
+```sh
+npm install --global @margay/ccl-core@1.4.5-rc.10
+ccl --version
+margay --version
+```
+
+两者应输出 `1.4.5-rc.10 (Margay)`。不带 `--global` 的安装只更新项目依赖，
+可通过 `./node_modules/.bin/ccl` 或 `./node_modules/.bin/margay` 使用。
+
+旧的自定义启动脚本、alias 或 PATH 排序可能继续选择旧版本。若安装报告
+`EEXIST` 或运行版本不一致，按[安装与升级说明](../cli-installation.md)检查并
+备份迁移对应入口。npm 全局安装不会替换 Margay Desktop 内嵌的运行包。
+
+## 验证与已知边界
+
+Phase B 候选已在 Mac 验证 Node/Bun 下 CLI、SDK 的成功、超时、取消和后续输入，
+以及 TUI、Duo、Swarm 和 Margay.app 私有副本的消费链路。CLI 构建 SHA256：
+`92a070720228fe35b80608e751fb59ea0116ac7c9e9115c009da98e1063a39df`。
+包的安装检查另外验证 POSIX 全新全局/项目安装、rc.9 升级、双入口、旧脚本冲突和 PATH 遮挡。
+
+- 本版不包含“轮次耗尽返回退出码 2，由上层自动续接”的新方案；到上限仍报告
+  `error_max_turns`。真实视频验证的首个 48 轮调用失败，另一次明确输入才完成交付。
+- DeepSeek thinking 400 的根因及针对性修复尚未收口；不能承诺本版消除该错误，
+  也不能仅凭 `blocked_external` 认定连接/超时问题已修复。
+- Windows 实机未验证；全仓 typecheck 的 11 条既有诊断未解决。
+- 获批 reactive compact 与 taskBudget 组合在当前公开入口不可达，仅作源码核对。
+  运营接口 401 及 shell 失败文案与 `is_error:false` 不一致的线索仍待定位。