@margay/ccl-core 1.5.1-alpha.2 → 1.5.1-alpha.4

package/dist/sdk/background.d.ts

@@ -1,5 +1,6 @@
 import type { BackgroundRun, BackgroundRunAction, BackgroundRunApproval, BackgroundRunEvents, BackgroundRunLookup, BackgroundRunSelector, BackgroundRunSpec, BackgroundRunSource } from './backgroundRunTypes.js';
 import type { OccurrenceCancelRequest, OccurrenceApprovalRequest, OccurrenceApprovalReceipt, OccurrenceLookup, OccurrenceEvents, ScheduledOccurrence } from './scheduledOccurrenceTypes.js';
+import type { ScheduledNotificationSelector, ScheduledNotificationRebind, ScheduledNotificationBindingLookup } from './scheduledNotificationTypes.js';
 export type BackgroundClientOptions = {
     cwd: string;
     cliPath: string;
@@ -19,6 +20,19 @@ export declare class BackgroundClientError extends Error {
 /** Durable runs do not retain JS callbacks or in-process SDK MCP servers. Use
  * persistent stdio/HTTP tools configured through launch instead. */
 export declare function createBackgroundClient(options: BackgroundClientOptions): {
+    getScheduledNotificationBinding: (selector: ScheduledNotificationSelector) => Promise<ScheduledNotificationBindingLookup>;
+    rebindScheduledNotifications: (request: ScheduledNotificationRebind) => Promise<{
+        selector: {
+            taskId: string;
+            taskCreatedAt: number;
+        } | {
+            occurrenceId: string;
+        };
+        sessionId: string;
+        revision: number;
+        generation: string;
+        updatedAt: number;
+    }>;
     getOccurrence: (request: {
         occurrenceId: string;
     }) => Promise<OccurrenceLookup>;

package/dist/sdk/background.js

@@ -18,7 +18,7 @@ export function createBackgroundClient(options) {
         // Serialization can throw (for example for a cyclic input); do it before
         // allocating a subprocess that would otherwise wait forever for stdin.
         const input = JSON.stringify(request);
-        const retryAdvice = command.includes('occurrence') ? 'Read the original occurrence and approvalDecisions. Retry approval only with the same actionId and payload.' : 'Query the original requestKey; do not submit a new key.';
+        const retryAdvice = command.includes('notification') ? 'Read the original notification binding. Retry a binding mutation only with the same actionId and payload.' : command.includes('occurrence') ? 'Read the original occurrence and approvalDecisions. Retry approval only with the same actionId and payload.' : 'Query the original requestKey; do not submit a new key.';
         return new Promise((resolve, reject) => {
             const child = spawn(options.execPath ?? process.execPath, [options.cliPath, 'daemon', command, '--cwd', options.cwd, '--request-stdin'], {
                 cwd: options.cwd, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'],
@@ -73,6 +73,8 @@ export function createBackgroundClient(options) {
         });
     }
     return {
+        getScheduledNotificationBinding: (selector) => invoke('get-scheduled-notification-binding', { selector }),
+        rebindScheduledNotifications: (request) => invoke('rebind-scheduled-notifications', request),
         getOccurrence: (request) => invoke('get-occurrence', request),
         listOccurrences: (request = {}) => invoke('list-occurrences', request),
         readOccurrenceEvents: (request) => invoke('occurrence-events', request),

package/dist/sdk/cancellation.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod/v4';
+/** Control-channel provenance, not the identity or intent of a person. */
+export declare const hostCancellationSchema: z.ZodObject<{
+    origin: z.ZodLiteral<"host">;
+    reason: z.ZodEnum<{
+        cancelled: "cancelled";
+        timeout: "timeout";
+        connection_closed: "connection_closed";
+        callback_error: "callback_error";
+        permission_denied: "permission_denied";
+    }>;
+}, z.core.$strict>;
+export type HostCancellation = z.infer<typeof hostCancellationSchema>;
+export declare function readHostCancellation(value: unknown): HostCancellation | undefined;
+export declare function hostCancellationMessage(cancellation: HostCancellation, execution?: 'not_started' | 'unknown'): string;

package/dist/sdk/cancellation.js

@@ -0,0 +1,18 @@
+import { z } from 'zod/v4';
+/** Control-channel provenance, not the identity or intent of a person. */
+export const hostCancellationSchema = z.object({
+    origin: z.literal('host'),
+    reason: z.enum(['cancelled', 'timeout', 'connection_closed', 'callback_error', 'permission_denied']),
+}).strict();
+export function readHostCancellation(value) {
+    const parsed = hostCancellationSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+export function hostCancellationMessage(cancellation, execution = 'unknown') {
+    return `Host control channel ended this turn (${JSON.stringify(cancellation)}). ` +
+        (cancellation.reason === 'permission_denied'
+            ? 'The host ended the turn after a permission denial; preserve the recorded decision without inferring who made it. '
+            : 'This lifecycle cancellation is not a user permission refusal or a user preference. ') +
+        (execution === 'not_started' ? 'This tool call was not executed. ' : 'A missing result does not establish whether an in-flight operation had effects. ') +
+        'Stop this turn. On a later authorized continuation, retain completed results and check existing execution evidence before repeating side effects. This cancellation grants no permission and does not revoke unrelated existing authorization.';
+}

package/dist/sdk/index.d.ts

@@ -9,6 +9,7 @@ export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSk
 export { query, queryHandleWithTransport } from './queryHandle.js';
 export { createSession, Session, type SessionOptions, type SessionControls, type Turn, type TurnResult, type InputMetadata } from './session.js';
 export type { InputProvenance } from './inputProvenance.js';
+export type { HostCancellation } from './cancellation.js';
 export { readQueryLifecycle, type QueryLifecycleRead } from './queryLifecycle.js';
 export type { QueryLifecycleRecord, QueryLifecycleObservation, QueryLifecycleWrite } from './queryLifecycleTypes.js';
 export { RuntimeResourcesSchema, RuntimeResourceSchema, type RuntimeResources, type RuntimeResource } from './runtimeResources.js';
@@ -20,6 +21,7 @@ export type { GatewayRequestPhase, GatewayRequestProgress } from './requestProgr
 export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, SessionLifecycleEvent, Transport, Usage, WireMessage, } from './types.js';
 export { getExecutionGuidance } from './executionGuidance.js';
 export { createBackgroundClient, BackgroundClientError, type BackgroundClientOptions } from './background.js';
+export type { ScheduledNotificationSelector, ScheduledNotificationRebind, ScheduledNotificationBinding, ScheduledNotificationBindingLookup, EffectiveScheduledNotificationRoute } from './scheduledNotificationTypes.js';
 export type { BackgroundRun, BackgroundRunSpec, BackgroundRunLookup, BackgroundRunSelector, BackgroundRunEvent, BackgroundRunEvents, BackgroundRunAction, BackgroundRunApproval, BackgroundPermission, BackgroundRunSource } from './backgroundRunTypes.js';
 export { runCommandProcess, type CommandProcessInput, type CommandProcessResult } from './commandProcess.js';
 export { createCommandAdapter, type CommandAdapter, type CommandAdapterSpec, type CommandDefinition, type CommandOperation, type CommandOutcome, type CommandExecution, type JsonValue } from './commandAdapter.js';

package/dist/sdk/query.d.ts

@@ -20,6 +20,7 @@ type PermissionDecisionWire = {
     message: string;
     interaction?: InteractionResponse;
     interrupt?: boolean;
+    cancellation?: import('./cancellation.js').HostCancellation;
     toolUseID: string;
 };
 type CallbackOutcome = {

package/dist/sdk/query.js

@@ -34,6 +34,7 @@ import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, sym
 import { createHash } from 'crypto';
 import { describeError, errorDetailsList, sanitizeErrorEnvelope, sanitizeErrorText, sanitizeRecoveryDiagnostic, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
 import { interactionResponseSchema } from './interactionResponseSchema.js';
+import { hostCancellationSchema } from './cancellation.js';
 import { tmpdir } from 'os';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -196,6 +197,7 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
     const deny = (message, failClosedReason) => ({
         kind: 'decision',
         decision: { behavior: 'deny', message, toolUseID: context.toolUseId,
+            cancellation: { origin: 'host', reason: timedOut ? 'timeout' : 'callback_error' },
             ...(toolName === 'AskUserQuestion' ? { interaction: { outcome: timedOut ? 'timed_out' : 'interaction_unavailable' } } : {}),
         },
         failClosedReason,
@@ -239,6 +241,10 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
             };
         }
         case 'deny': {
+            const cancellation = hostCancellationSchema.safeParse(raw.cancellation);
+            if (raw.cancellation !== undefined && !cancellation.success) {
+                return deny('Cancellation provenance was invalid; no user choice was inferred.', 'unrecognized_result');
+            }
             const interaction = interactionResponseSchema.safeParse(raw.interaction);
             if (raw.interaction !== undefined && !interaction.success) {
                 return deny('Interaction response was invalid; no user choice was inferred.', 'unrecognized_result');
@@ -250,6 +256,8 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
                     message: sanitizeErrorText(raw.message ?? 'Denied by host'),
                     ...(toolName === 'AskUserQuestion' && interaction.success ? { interaction: interaction.data } : {}),
                     ...(raw.interrupt !== undefined && { interrupt: raw.interrupt }),
+                    ...(cancellation.success ? { cancellation: cancellation.data } : raw.interrupt
+                        ? { cancellation: { origin: 'host', reason: 'permission_denied' } } : {}),
                     toolUseID: context.toolUseId,
                 },
             };
@@ -699,6 +707,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         toolUseId,
                         behavior: outcome.decision.behavior,
                         ...(outcome.decision.behavior === 'deny' && outcome.decision.interaction ? { interaction: outcome.decision.interaction } : {}),
+                        ...(outcome.decision.behavior === 'deny' && outcome.decision.cancellation ? { cancellation: outcome.decision.cancellation } : {}),
                         source: 'callback',
                         ...(outcome.failClosedReason && {
                             failClosedReason: outcome.failClosedReason,

package/dist/sdk/queryHandle.js

@@ -25,6 +25,7 @@
  */
 import { queryWithTransport, spawnForOptions } from './query.js';
 import { isAsyncInput } from './queryInput.js';
+import { hostCancellationSchema } from './cancellation.js';
 let requestCounter = 0;
 const nextRequestId = () => `ccl-sdk-req-${++requestCounter}-${Math.random().toString(36).slice(2, 10)}`;
 class QueryHandle {
@@ -81,14 +82,15 @@ class QueryHandle {
         // The init promise is settled internally; hosts that never ask for the
         // initialization result must not see an unhandled rejection.
         this.initPromise.catch(() => { });
-        void transport.exited.then(() => this.cancelPermission?.(), () => this.cancelPermission?.());
+        const retired = () => this.cancelPermission?.({ origin: 'host', reason: 'connection_closed' });
+        void transport.exited.then(retired, retired);
         const callback = options.canUseTool;
         void this.pump(prompt, callback ? {
             ...options,
             canUseTool: async (...args) => {
                 let cancel;
                 const cancelled = new Promise(resolve => {
-                    cancel = () => resolve({ behavior: 'deny', message: 'Permission wait cancelled by host', interrupt: true });
+                    cancel = cancellation => resolve({ behavior: 'deny', message: 'Permission wait cancelled by host', interrupt: true, cancellation });
                 });
                 this.cancelPermission = cancel;
                 try {
@@ -220,9 +222,12 @@ class QueryHandle {
         if (response.subtype === 'error') {
             entry.reject(new Error(String(response.error ?? 'control request failed')));
         }
-        else {
+        else if (response.subtype === 'success') {
             entry.resolve(response.response);
         }
+        else {
+            entry.reject(new Error('ccl-sdk: invalid control acknowledgement'));
+        }
     }
     trackInitialize(requestId) {
         this.pending.set(requestId, {
@@ -278,19 +283,34 @@ class QueryHandle {
             return Promise.reject(new Error(this.endReason));
         const requestId = nextRequestId();
         return new Promise((resolve, reject) => {
-            this.pending.set(requestId, { resolve, reject });
+            const timer = opts.timeoutMs ? setTimeout(() => {
+                const entry = this.pending.get(requestId);
+                this.pending.delete(requestId);
+                entry?.reject(new Error('ccl-sdk: interrupt acknowledgement timed out; stop outcome is unknown'));
+            }, opts.timeoutMs) : undefined;
+            this.pending.set(requestId, {
+                resolve: value => { if (timer)
+                    clearTimeout(timer); resolve(value); },
+                reject: error => { if (timer)
+                    clearTimeout(timer); reject(error); },
+            });
             this.transport
                 .write({ type: 'control_request', request_id: requestId, request })
                 .catch(error => {
                 if (this.pending.delete(requestId)) {
+                    if (timer)
+                        clearTimeout(timer);
                     reject(error instanceof Error ? error : new Error(String(error)));
                 }
             });
         });
     }
-    interrupt() {
-        this.cancelPermission?.();
-        return this.controlRequest({ subtype: 'interrupt' });
+    interrupt(cancellation = { origin: 'host', reason: 'cancelled' }) {
+        const parsed = hostCancellationSchema.safeParse(cancellation);
+        if (!parsed.success)
+            return Promise.reject(new Error('ccl-sdk: invalid cancellation provenance'));
+        this.cancelPermission?.(parsed.data);
+        return this.controlRequest({ subtype: 'interrupt', cancellation: parsed.data }, { timeoutMs: 10000 });
     }
     setPermissionMode(mode) {
         return this.controlRequest({ subtype: 'set_permission_mode', mode });
@@ -372,7 +392,7 @@ class QueryHandle {
         return (await this.initializationResult()).account;
     }
     async close() {
-        this.cancelPermission?.();
+        this.cancelPermission?.({ origin: 'host', reason: 'connection_closed' });
         this.markDead('ccl-sdk: query closed');
         await this.transport.close();
     }

package/dist/sdk/queryLifecycleTypes.d.ts

@@ -28,8 +28,8 @@ export declare const QueryLifecycleSchema: z.ZodObject<{
             actor: z.ZodEnum<{
                 unknown: "unknown";
                 agent: "agent";
-                human: "human";
                 host: "host";
+                human: "human";
             }>;
             source: z.ZodString;
             session_id: z.ZodOptional<z.ZodString>;
@@ -113,8 +113,8 @@ export declare const QueryLifecycleObservationSchema: z.ZodObject<{
                 actor: z.ZodEnum<{
                     unknown: "unknown";
                     agent: "agent";
-                    human: "human";
                     host: "host";
+                    human: "human";
                 }>;
                 source: z.ZodString;
                 session_id: z.ZodOptional<z.ZodString>;

package/dist/sdk/scheduledNotificationTypes.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod/v4';
+export declare const scheduledNotificationSelectorSchema: z.ZodUnion<readonly [z.ZodObject<{
+    taskId: z.ZodString;
+    taskCreatedAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    occurrenceId: z.ZodString;
+}, z.core.$strict>]>;
+export type ScheduledNotificationSelector = z.infer<typeof scheduledNotificationSelectorSchema>;
+export declare const scheduledNotificationLookupSchema: z.ZodObject<{
+    selector: z.ZodUnion<readonly [z.ZodObject<{
+        taskId: z.ZodString;
+        taskCreatedAt: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        occurrenceId: z.ZodString;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export declare const scheduledNotificationRebindSchema: z.ZodObject<{
+    selector: z.ZodUnion<readonly [z.ZodObject<{
+        taskId: z.ZodString;
+        taskCreatedAt: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        occurrenceId: z.ZodString;
+    }, z.core.$strict>]>;
+    targetSessionId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    actionId: z.ZodString;
+}, z.core.$strict>;
+export type ScheduledNotificationRebind = z.infer<typeof scheduledNotificationRebindSchema>;
+export declare const scheduledNotificationBindingSchema: z.ZodObject<{
+    selector: z.ZodUnion<readonly [z.ZodObject<{
+        taskId: z.ZodString;
+        taskCreatedAt: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        occurrenceId: z.ZodString;
+    }, z.core.$strict>]>;
+    sessionId: z.ZodString;
+    revision: z.ZodNumber;
+    generation: z.ZodString;
+    updatedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type ScheduledNotificationBinding = z.infer<typeof scheduledNotificationBindingSchema>;
+export type EffectiveScheduledNotificationRoute = {
+    sessionId: string | null;
+    source: 'occurrence' | 'task' | 'delegation' | 'unbound';
+    binding?: ScheduledNotificationBinding;
+};
+export type ScheduledNotificationBindingLookup = {
+    selector: ScheduledNotificationSelector;
+    revision: number;
+    binding: ScheduledNotificationBinding | null;
+    /** For occurrence selectors, includes inherited task routing. */
+    effective?: EffectiveScheduledNotificationRoute;
+};

package/dist/sdk/scheduledNotificationTypes.js

@@ -0,0 +1,18 @@
+import { z } from 'zod/v4';
+export const scheduledNotificationSelectorSchema = z.union([
+    z.strictObject({ taskId: z.string().min(1), taskCreatedAt: z.number().int().nonnegative() }),
+    z.strictObject({ occurrenceId: z.string().regex(/^[a-f0-9]{64}$/) }),
+]);
+export const scheduledNotificationLookupSchema = z.strictObject({ selector: scheduledNotificationSelectorSchema });
+export const scheduledNotificationRebindSchema = scheduledNotificationLookupSchema.extend({
+    targetSessionId: z.string().min(1).max(200),
+    expectedRevision: z.number().int().nonnegative(),
+    actionId: z.string().min(1).max(200),
+});
+export const scheduledNotificationBindingSchema = z.strictObject({
+    selector: scheduledNotificationSelectorSchema,
+    sessionId: z.string().min(1).max(200),
+    revision: z.number().int().positive(),
+    generation: z.string().uuid(),
+    updatedAt: z.number().int().nonnegative(),
+});

package/dist/sdk/types.d.ts

@@ -29,6 +29,8 @@ export type CanUseToolResult = {
     interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** Also interrupt the current turn instead of letting the agent continue. */
     interrupt?: boolean;
+    /** Host control-channel provenance; not a human refusal or a new authorization. */
+    cancellation?: import('./cancellation.js').HostCancellation;
 } | {
     /**
      * Suspend the session at this tool call (issue P0-2 pending): the tool
@@ -403,6 +405,7 @@ type SDKEventPayload = {
     behavior: 'allow' | 'deny';
     /** Why the SDK decided this way when the host callback did not decide. */
     failClosedReason?: string;
+    cancellation?: import('./cancellation.js').HostCancellation;
     interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** 'pending_decision' when resolved by resumeWithDecision, not the live callback. */
     source?: 'callback' | 'pending_decision';
@@ -479,7 +482,7 @@ export type InitializationResult = {
  * the stream is identical to the bare queryWithTransport generator.
  */
 export interface Query extends AsyncGenerator<SDKEvent, void, unknown> {
-    interrupt(): Promise<unknown>;
+    interrupt(cancellation?: import('./cancellation.js').HostCancellation): Promise<unknown>;
     setPermissionMode(mode: string): Promise<unknown>;
     setModel(model?: string): Promise<unknown>;
     setMaxThinkingTokens(n: number | null): Promise<unknown>;

package/docs/background-runs.md

@@ -93,6 +93,24 @@ await background.cancelRun({ runId, expectedRevision, actionId: 'cancel-1' })
 
 `ccl daemon submit|get|events|cancel-run|approve-run --request-stdin --cwd PROJECT` 从 stdin 接收 JSON。submit 可启动缺失的兼容 daemon；读取不会启动进程。旧活 owner 配置不匹配时明确拒绝，不暗中替换。daemon stop 停调度；取消某一 run 使用 cancel-run。
 
+### 安装升级与已有定时任务
+
+安装新包不会重启正在运行的 daemon。`ccl daemon status --cwd PROJECT`、`scheduledStatus` 和 `CronList` 的 background 结果包含：
+
+- `runningCliDigest`：通过活 owner 协议核实的启动时 CLI SHA-256；旧 owner 未保存该字段或没有核实到活 owner 时为 `null`。
+- `installedCliDigest`：执行这次查询的 CLI 文件 SHA-256；读取失败时为 `null`。嵌入 service 的调用者可显式传比较路径。
+- `cliCompatibility`：`match`、`mismatch` 或 `unknown`，另有 `cliCompatibilityReason` 解释不同或未知的原因。
+
+`owner.ready` 仍表示已获得调度租约，不等于版本一致或任务已完成。摘要一致只表示 CLI 字节一致，不证明启动配置一致。旧 owner 的 `configId` 不能反推其 CLI 摘要；升级覆盖同一路径后也不能从新文件推断旧进程版本。`CronCreate` 的后台 handoff 结果也带相同的摘要字段。
+
+产品启动或巡检可只读查询并提示用户。需要切换时，保留任务 ID、原启动配置及 occurrence 状态，由用户决定时机；明确执行 `ccl daemon stop --cwd PROJECT`，确认旧 owner 已退出、租约已释放，再从原宿主以相同配置对原 taskId 重试 `CronCreate operation:handoff`。采用 CLI start 时也要保留原宿主对应的配置；无条件裸 start 可能使用不同模型/设置，导致下一次 handoff 仍拒绝。不要删除重建排程，也不要循环重试不同配置或自动杀进程。stop 超时先查原 owner 状态，不能把超时当成已停止。
+
+已接受的 occurrence 独立于排程定义：删除定义只影响未来触发，旧 occurrence 仍可按原 ID 查询、按明确决定取消；取消不会撤销已经发生的外部效果。新 owner 保留 waiting_permission，running/resuming 的不确定执行按 interrupted 处理，不自动重放。错过时点仍按原 missed/coalesce 规则处理，不意味着所有错过任务都自动补跑。
+
+恢复审批必须同时存在原 session 的 confirmed pending 与精确匹配的 suspended 事件。`pendingPermission` 缺失时，新 owner 尝试恢复；失败会保留 `approvalRecoveryError`，不能编造 request/tool ID 批准。alpha.4 的原生 pending 没有新版 confirmed 挂起协议，因此不能承诺它能直接恢复，也不能补写 confirmed 绕过检查。由获授权的项目宿主先查询原 occurrence、核实已有外部效果，再按用户决定保留或使用 `cancel-occurrence`（snapshot.revision + 稳定 actionId）取消；不会自动取消或重新执行整项工作。
+
+未显式绑定时，通知仍按原 `delegation.sourceSessionId` 投递。新会话可以使用下面的独立换绑接口；没有 delegation 或已删定义的旧 occurrence 也能绑定。`reauthorize` 只更新未来触发的权限委托，不改变既有 occurrence 或显式通知绑定。
+
 | 目的 | SDK | CLI 子命令 | `BackgroundRun` 模型工具 action |
 | --- | --- | --- | --- |
 | 持久接受 | `submitRun` | `submit` | `submit` |
@@ -217,11 +235,37 @@ CLI 使用 `ccl daemon <子命令> --request-stdin --cwd PROJECT`，stdin 中为
 
 只读查询不启动 owner，也不消费通知；决定和取消需要兼容的运行 owner。旧 `daemon approve <id> allow` 无精确身份，返回迁移错误。模型工具用 `BackgroundRun` 的 `occurrence_id` 配合 `get/events/approve/cancel`；批准字段为 `expected_revision/request_id/tool_use_id/action_id/decision`，事件使用 `after_sequence`，不用 run 的 opaque `cursor`。模型收到宿主通知不等于用户授权，allow 仍遵循前台权限确认或明确适用策略。
 
+### 新会话接收原任务通知
+
+换绑只改变通知收件人，不启动 owner，不删除重建任务，也不改变计划、执行状态、worker session、权限或待批身份。CLI/SDK 是受信本机宿主接口，可指定目标 session；模型工具请求确认，并由宿主填入当前 session，模型不能指定其他会话。
+
+- 整项排程：在新会话用 `CronList` 读取原任务的 `notificationBinding.revision`，调用 `CronCreate`，输入 `operation: "rebind-notifications"`、原 `taskId`、`bindingRevision` 和稳定 `actionId`。首次 revision 为 0。此入口要求定义仍存在；一次性任务触发后定义可能已移除。
+- 单次发生：使用 `BackgroundRun action:"notification-binding", occurrence_id:原ID` 读取该 occurrence 的绑定 revision，再用 `action:"rebind-notifications"`、相同 `occurrence_id`、`binding_revision`、稳定 `action_id` 换绑。它适用于定义已删或没有 delegation 的旧记录。
+- SDK/CLI 整项选择器为 `{taskId, taskCreatedAt}`；它匹配已有记录和未来触发，防止同 ID 重建任务串收件人。定义已删时可从原 occurrence 的 task 快照取得身份。单次选择器为 `{occurrenceId}`。两种选择器不能混用。
+
+```js
+const selector = { occurrenceId: originalOccurrenceId }
+const binding = await background.getScheduledNotificationBinding(selector)
+const request = {
+  selector, targetSessionId: newSessionId,
+  expectedRevision: binding.revision, actionId: stableActionId,
+}
+const receipt = await background.rebindScheduledNotifications(request)
+```
+
+对应 CLI 为 `ccl daemon get-scheduled-notification-binding --request-stdin --cwd PROJECT`，stdin 内容 `{ "selector": { "occurrenceId": "原64位ID" } }`；写接口为 `rebind-scheduled-notifications`，另加 `targetSessionId`、`expectedRevision`、`actionId`。读取不创建绑定。确认回执不确定时重试原请求；同一 actionId 同一内容返回原回执，不再次换绑。复用 actionId 改内容报 `action_conflict`；新动作遇到 `stale_binding` 时先读现状，再由宿主决定是否发起新的修改。
+
+有效路由优先级是单次 occurrence 显式绑定、task 身份绑定、原 delegation。换绑整项任务不会覆盖单次显式选择。lookup 的 revision 只属于所选绑定，不能把 `effective.binding.revision` 当成另一选择器的 revision。`CronList.background` 和 `daemon status` 显示 task 的绑定 revision、收件 session，以及 occurrence 的有效 route；路由文件损坏时报告 `notificationRoutingError`，不会回退投递给原收件人，owner readiness 和 CLI 摘要仍可查询。修复路由存储前先保留原文件并核实目标，不用删文件来隐式恢复旧路由。
+
+显式换绑后只补发最新可通知状态，不回放过期审批历史。稳定通知 UUID 包含绑定代次和当前待批身份/终态；coalesce 或 delivery 更新不重复同一待办，新的 pending 或终态会通知。A→B→A 使用新代次，旧 A 回执不会吞掉新通知。只有实际持久 transcript 消息才算接收回执，入队、get/events 或缓存本身都不算。
+
+换绑对尚未被消费者 prepare 接受的通知生效：旧队列项在消费前复核路由和当前状态，不匹配则丢弃重取。已经接受或持久保存的旧通知无法撤回，因此不承诺两个会话在换绑瞬间零重叠。收到通知不授予审批权，批准仍须查询原 occurrence 并使用精确 pending 身份。旧格式无法恢复 pending 时，通知报告恢复错误，不生成虚构批准。
+
 ### 前端体验与故障恢复
 
-- TUI 与持续运行的 SDK/headless 主循环：原会话收到 `scheduled-task` 宿主事件，主助手解释具体待批工具、当前结果或失败。此事件不冒充新的用户指令。SDK 的自主通知结果不绑定到上一条用户输入的 turn UUID。
+- TUI 与持续运行的 SDK/headless 主循环：有效绑定会话收到 `scheduled-task` 宿主事件，主助手解释具体待批工具、当前结果或失败。此事件不冒充新的用户指令。SDK 的自主通知结果不绑定到上一条用户输入的 turn UUID。
 - 已退出的一次性 headless：不承诺向已关闭的输出流推送。消费者可通过上述 SDK/CLI 查询和处理结构化 pending；恢复原会话时补收未投递消息。Pepper 等 assistant 负责自己的外部消息渠道及送达回执。
-- 接收者离线、入队失败或入队后尚未写入 transcript：保留通知游标，补投稳定 UUID。只有原会话持久保存的通知消息才算宿主接收回执；get/events 和队列操作记录都不算。已保存不代表模型已解释或 IM 已送达。
+- 接收者离线、入队失败或入队后尚未写入 transcript：保留通知游标，补投稳定 UUID。只有接收会话持久保存的通知消息才算宿主接收回执；get/events 和队列操作记录都不算。已保存不代表模型已解释或 IM 已送达。
 - 同一待批调用跨周期只提示一次，查询及实际消费时显示最新合并次数。投递前、队列消费前重查状态，已经批准、拒绝、取消或结束的旧审批不再提问；历史事件仍可读。状态读取失败不会冒充“已解决”。
 - 等待批准时 owner 重启：保留经确认尚未执行的原调用，可在明确批准后恢复原 session。恢复严格核对工具与完整输入，不因同名工具就套用旧批准。
 - 决定和恢复 intent 已保存后崩溃：重启标记 `interrupted`，不自动再执行。先核查原收据、工具结果及适用的 Operation 恢复契约；宿主不保证任意外部系统 exactly-once。

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

@@ -0,0 +1,23 @@
+# 1.5.1-alpha.3
+
+本预发布版在 [1.5.1-alpha.2](1.5.1-alpha.2.md) 基础上增加宿主取消来源契约（#58）和视觉输出预算配置及有界恢复（#59）。使用明确版本或 `alpha` 标签安装；npm 发布状态以 registry 为准，`latest` 保持不变。
+
+## 宿主停止与权限拒绝
+
+SDK `handle.interrupt()`、权限回调超时/异常和会话退役会保留宿主取消来源，不再被误写成用户拒绝或用户偏好。普通工具 Deny 继续保留拒绝依据；取消不撤销其他授权，也不授予新权限。
+
+`interrupt()` 可接收 `HostCancellation`，权限回调 deny 可附带 `cancellation`；来源也会出现在 `permission_resolved` 和原生 transcript。旧客户端只返回 `deny('Conversation stopped')` 时仍按拒绝处理，需迁移到 interrupt 或显式 cancellation。AskUserQuestion 的非终止 unavailable/timeout 交互保持原行为，不制造用户答案。
+
+取消与结果返回竞态时保留已完成事实，迟到的 allow 不启动已取消的工具。成功停止 ACK 只确认控制请求被接受；拒绝、畸形 ACK、断连或10秒无 ACK 会明确失败，停止结果可能未知。取消不回滚已发生的外部效果，强杀或close也不保证最后消息持久化；恢复前仍需核对事实，不能盲目重放。
+
+## 视觉输出预算
+
+CLI 环境变量 `CCL_VISUAL_MAX_OUTPUT_TOKENS` 默认8192；可选 `CCL_VISUAL_RECOVERY_MAX_OUTPUT_TOKENS` 显式授权一次更高预算恢复，默认不启用。SDK通过已有 `options.env` 配置。值必须是正安全整数，恢复预算必须大于初始预算；非法配置在读图或模型请求前失败。Agent模型不能通过工具参数改预算或覆盖视觉模型。
+
+现有模型输出上限和共享上下文限制仍会约束请求。只有完整终态的输出限额失败、无拒绝/过滤、有效预算确实增加且恢复额度未用时，才会用原模型、协议、提示和已授权图片字节重试。预算被模型上限截平时不发无效重试。空响应与输出限额恢复共用一次内容重试，另允许此前一次能力上下文刷新；至多3次推理共用900秒期限。
+
+成功和失败均记录尝试历史、request ID、请求/有效预算、限制来源、重试关联、耗时及累计已知usage。缺少input/output用量时 `usageComplete=false`，不把未知成本当作零。最终未完成不会报视觉通过。成功结果提示也不再无条件暗示此前发生过失败和恢复。
+
+提高预算可能增加成本，不保证提升视觉准确性。原三图同提示的真实模型对照中，8192和16384都单次完成，未复现旧截断；本次真实运行未触发自动恢复，恢复边界由CLI/SDK接线及单元测试验证。模型仍有精确颜色判断误差，完整输出不能替代业务验收。
+
+使用方式及兼容边界见 [SDK API](../../sdk/API.md)。CLI与SDK保持同版本；已运行进程不会热更新，正常结束后新会话使用新版。未改默认模型、权限策略或业务数据，无需数据迁移。仍不承诺跨外部系统exactly-once、模型始终正确理解图像或任意终止都能回收已发生的副作用。

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

@@ -0,0 +1,27 @@
+# 1.5.1-alpha.4
+
+本预发布版在 [1.5.1-alpha.3](1.5.1-alpha.3.md) 基础上交付 #60 的 daemon 升级状态和独立通知换绑。安装指定版本或使用 `alpha` 标签；`latest` 保持不变。CLI 与 SDK 应使用同版本。
+
+## 升级状态与旧记录
+
+`daemon status`、`CronList.background` 和 `CronCreate` 的后台返回包含运行/安装 CLI 摘要及 `cliCompatibility: match | mismatch | unknown`。旧 owner 没有启动摘要时明确 unknown；不会把升级后同路径的新文件当成旧进程版本。`owner.ready` 与版本一致性分开。
+
+安装不会重启现有 daemon。需要切换时保留原任务身份和启动配置，明确 stop 并确认旧 owner 退出，再从原宿主对原 taskId handoff；不要删除重建排程。stop 导致活动 SDK aborted 时保存 interrupted，重启不自动重放；等待审批记录保留，错过周期按既有 missed/coalesce 契约处理。
+
+恢复审批仍要求原 session 的 confirmed pending 和精确请求身份。旧 alpha.4 原生 pending 没有该确认协议时，保留恢复错误，不伪造批准或自动重跑；可查询原 occurrence，并在明确授权下取消。删除定义不删除已接受记录，取消不撤销已发生的外部效果。
+
+## 新会话通知换绑
+
+SDK `getScheduledNotificationBinding` / `rebindScheduledNotifications` 与同名 kebab-case CLI 子命令支持原 `{taskId, taskCreatedAt}` 或 `{occurrenceId}` 选择器。换绑含 `targetSessionId`、`expectedRevision`（首次 0）、稳定 `actionId`；同动作重试返回原回执，冲突和损坏明确报错。
+
+模型工具使用 `CronCreate operation:rebind-notifications` 或 `BackgroundRun action:notification-binding/rebind-notifications`；经过权限确认，收件人固定为宿主当前会话。换绑不启动 owner，不改任务、计划、执行、权限或待批身份。单 occurrence 显式绑定优先于 task，最后才使用原 delegation。已删定义的 occurrence 仍可换绑。
+
+REPL 和持续 headless 会话使用共同通知实现。新绑定只投当前待办/结果，以持久 transcript 为回执；代次隔离支持 A→B→A，合并周期不重复同一待办。消费前复核会丢弃旧路由队列项，已经接受的旧通知无法撤回，不承诺换绑瞬间零重叠。通知不是审批，仍需查询原 occurrence 后针对精确 pending 决定。
+
+## 验证与兼容边界
+
+隔离测试覆盖真实旧 alpha.4 产物切换、现代 pending 原会话恢复、运行任务中止与 missed/coalesce，以及最终候选 CLI/SDK、真实 detached owner、两个持续会话、工具拒绝/允许换绑、真实 transcript 和原精确批准一次执行。确定性 provider 证明接线与生命周期，不证明真实模型自主规划质量；REPL 验证为实际 hook/队列消费，不是整屏视觉验收。
+
+独立路由是新增可选存储，未绑定任务沿用原路由。旧运行版本不会理解新绑定，启用此功能后不应混用旧前台消费者或直接降级并期待新路由仍生效。包回退不能撤销已经接受的通知或业务效果，回退前需核实接收方与待执行记录。
+
+完整升级顺序、CLI/SDK/工具字段、优先级及失败处理见 [后台任务契约](../background-runs.md) 与 [SDK API](../../sdk/API.md)。本版包含 alpha.3 的 #58/#59 修复，不宣称解决视觉模型准确性问题。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.5.1-alpha.2",
+  "version": "1.5.1-alpha.4",
   "description": "Core runtime extracted from Claude Code (ccl) for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
@@ -54,7 +54,9 @@
     "docs/releases/1.5.0-alpha.6.md",
     "docs/releases/1.5.1-alpha.md",
     "docs/releases/1.5.1-alpha.1.md",
-    "docs/releases/1.5.1-alpha.2.md"
+    "docs/releases/1.5.1-alpha.2.md",
+    "docs/releases/1.5.1-alpha.3.md",
+    "docs/releases/1.5.1-alpha.4.md"
   ],
   "engines": {
     "node": ">=22.19.0"

package/sdk/API.md

@@ -213,7 +213,7 @@ type CanUseToolFn = (
 
 type CanUseToolResult =
   | { behavior: 'allow'; updatedInput?: Record<string, unknown> }  // 放行;updatedInput=改写输入(modify)
-  | { behavior: 'deny'; message?: string; interrupt?: boolean }     // 拒绝;interrupt=true 同时中断本回合
+  | { behavior: 'deny'; message?: string; interrupt?: boolean; cancellation?: HostCancellation }
   | { behavior: 'pending' }                                          // 挂起走异步审批(§5)
 ```
 
@@ -222,6 +222,12 @@ type CanUseToolResult =
 - `allow` 未提供 `updatedInput`(或提供空对象)时按原始 input 执行。
 - 未配置 `canUseTool` 时 SDK 不启用权限转发(工具按 CLI 自身权限规则走);若此时 CLI 仍发来请求,按 deny 兜底。
 
+宿主停止与权限拒绝是不同事件。停止生成可直接 `await handle.interrupt()`；它取消未完成权限等待，默认来源为 `{origin:'host',reason:'cancelled'}`。也可传完整的 `HostCancellation`，reason 支持 `cancelled`、`timeout`、`connection_closed`、`callback_error`、`permission_denied`。`origin` 表示控制通道来源，不推断是谁点击了停止。原始 stream-json 请求为 `{type:'control_request',request_id,request:{subtype:'interrupt',cancellation}}`，省略 cancellation 同样表示宿主取消。
+
+需要在权限回调结束等待时，可返回 `{behavior:'deny',message:'Conversation stopped',cancellation:{origin:'host',reason:'cancelled'}}`。这结束当前轮，工具不执行；`permission_resolved.cancellation` 与原生 transcript 的 `toolUseResult.cancellation` 保留来源。回调超时/异常自动携带 timeout/callback_error。AskUserQuestion 的 timed_out/interaction_unavailable 继续按已有非终止交互失败处理，不制造用户答案。未带 cancellation 的普通 deny 仍是拒绝；deny+interrupt 记录 permission_denied 并保留原拒绝依据，不推断人工决定。旧客户端的 `deny('Conversation stopped')` 仍是拒绝，宿主应迁移到 interrupt 或显式 cancellation，CCL 不通过文字猜测来源。
+
+interrupt 的 Promise 只在匹配成功 ACK 后完成；拒绝、畸形 ACK、断连会 reject，10 秒没有 ACK 也会 reject，表示停止结果未知。还须观察当前轮的 result，不能把 ACK 当作工具已回滚。迟到的 allow 不会启动已取消的工具。已完成结果保留；在途操作缺少结果不能证明没有副作用，恢复时先核对事实，不能盲目重放。取消本身不撤销其他已存在授权，也不授予新权限。`end_session` 支持优雅退役并记录 connection_closed；直接强杀进程或 `close()` 是资源清理，不保证最后一条消息已持久化，需按未知结果恢复。
+
 ---
 
 ## 5. pending 挂起 / 跨进程恢复(审批闭环)
@@ -673,3 +679,63 @@ operation-replay guarantee, and does not introduce a new permission gate.
 Check the actual tool schema for `mode`; an older installation with the same
 candidate version string may not have it. An existence precheck followed by normal
 Write is not an equivalent no-replacement contract.
+
+## Visual specialist output budget (1.5.1-alpha.3)
+
+The synchronous `Agent` specialist `visual-ui-analysis` accepts its existing
+`prompt` and `image_paths`. The host controls its output allowance; the model
+cannot set it through Agent arguments or override the selected vision model.
+CLI processes read `CCL_VISUAL_MAX_OUTPUT_TOKENS` (default `8192`) and optional
+`CCL_VISUAL_RECOVERY_MAX_OUTPUT_TOKENS` (disabled by default). SDK hosts use the
+same variables through `options.env`:
+
+```ts
+const handle = query({
+  prompt: 'Inspect the supplied rendered slides with the visual specialist.',
+  options: {
+    env: {
+      CCL_VISUAL_MAX_OUTPUT_TOKENS: '16384',
+      CCL_VISUAL_RECOVERY_MAX_OUTPUT_TOKENS: '32768',
+    },
+    // Supply your normal cwd, credentials and permission callback as appropriate.
+  },
+})
+```
+
+Values must be decimal positive safe integers; the recovery value must exceed
+the initial value. Invalid configuration fails before image reads or model I/O.
+The existing provider/configured output limits and shared context budget still
+cap each request. Unknown limits remain unknown; a larger allowance is not a
+claim that the model supports it. Reasoning and visible text share the allowance.
+
+A terminal output-limit failure can use the higher allowance once, only when
+its effective budget increases. If a model caps both requests at 8192, no recovery
+request is sent. Recovery reuses the selected model, protocol, prompt and already
+authorized image bytes. It shares one content retry with normal-terminal empty
+response recovery. A capability-context refresh is separately allowed once before
+content recovery, so at most three inference attempts share one 900-second
+operation deadline. Cancellation, refusal, filtering, incomplete streams and an
+exhausted recovery do not trigger a further content retry.
+
+The returned visual facts retain every attempt's request ID, requested and
+effective budget, safe `requestBudget` limit snapshot, duration, and one-based
+`retryOfAttempt` / `retryOfRequestId` links. Both completed and failed inspections
+include `visualDiagnostics.usage`, `usageComplete`, and total `durationMs` (from
+post-image-load resolution to terminal outcome). `usageComplete` concerns reported
+input/output counts; optional cache breakdowns may be absent. Missing usage is
+not proof of zero cost: totals sum known values, and `usageComplete: false` marks
+the incomplete accounting. Successful SDK tool usage retains the same numeric
+totals for compatibility. A final failure remains an incomplete inspection,
+preserves earlier failures, and asks the Owner to stop same-condition retries.
+
+Increasing output allowance can increase cost and does not establish visual
+accuracy. Verify page observations separately; a complete response alone is not
+business acceptance. These variables require a build containing this feature;
+the previously published alpha.2 does not support them.
+
+
+## Scheduled notification bindings
+
+`createBackgroundClient()` 提供 `getScheduledNotificationBinding(selector)` 与 `rebindScheduledNotifications(request)`，用于新会话接收原定时任务通知。选择器为 `{ taskId, taskCreatedAt }` 或 `{ occurrenceId }`；请求包含 `selector`、`targetSessionId`、`expectedRevision`（初始 0）和稳定 `actionId`。返回绑定含 `sessionId/revision/generation/updatedAt`。读取 occurrence 绑定还返回 `effective` 路由；显式 occurrence 优先于 task，task 优先于原 delegation。
+
+换绑不启动 owner、不改变原任务或审批状态。超时重试原 actionId 和原请求；同 ID 改内容拒绝，revision 冲突须读取当前状态后决定新动作。模型工具固定绑定到自己的宿主 session，并请求权限确认。已被消费者接受的旧通知不会撤回；新代次只通知当前待办或结果，不重放过期历史。完整 CLI、工具字段、错误和恢复说明见 [新会话接收原任务通知](../docs/background-runs.md#新会话接收原任务通知)。