@margay/ccl-core 1.4.6-beta.0 → 1.5.0-alpha.0

package/dist/sdk/index.d.ts

@@ -13,4 +13,4 @@ export { defaultStoreDir, fileSessionStore } from './store.js';
 export { spawnCliTransport } from './transport.js';
 export type { RecoveryDiagnostic } from './errorDiagnostics.js';
 export type { GatewayRequestPhase, GatewayRequestProgress } from './requestProgress.js';
-export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, Transport, Usage, WireMessage, } from './types.js';
+export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, SessionLifecycleEvent, Transport, Usage, WireMessage, } from './types.js';

package/dist/sdk/query.js

@@ -35,7 +35,7 @@ import { fileURLToPath } from 'url';
 import { SdkMcpRegistry } from './mcpServer.js';
 import { fileSessionStore } from './store.js';
 import { spawnCliTransport } from './transport.js';
-import { isAsyncInput, readWithInput } from './queryInput.js';
+import { isAsyncInput, normalizeUserInput, readWithInput } from './queryInput.js';
 const DEFAULT_CAN_USE_TOOL_TIMEOUT_MS = 300_000;
 /** Builds the CLI argv for a query. Exported for unit tests. */
 export function buildCliArgs(options) {
@@ -253,6 +253,7 @@ export async function* queryWithTransport(prompt, options, transport) {
     const hooks = options.hooks ?? {};
     const ownRequestIds = new Set();
     const toolNamesById = new Map();
+    const toolOrigins = new Map();
     let lastSessionId = options.sessionId ?? options.resume;
     let turn = 0;
     let sawResult = false;
@@ -321,11 +322,11 @@ export async function* queryWithTransport(prompt, options, transport) {
             const userContent = options.promptContentBlocks && options.promptContentBlocks.length > 0
                 ? options.promptContentBlocks
                 : [{ type: 'text', text: prompt }];
-            await transport.write({
+            await transport.write(normalizeUserInput({
                 type: 'user',
                 message: { role: 'user', content: userContent },
                 parent_tool_use_id: null,
-            });
+            }));
             // slice sdk-observability-hooks-usage (G5): the host's prompt was submitted to the agent.
             await runHook(hooks.onUserPromptSubmit &&
                 (() => hooks.onUserPromptSubmit({ prompt, sessionId: lastSessionId })));
@@ -341,6 +342,10 @@ export async function* queryWithTransport(prompt, options, transport) {
             })
             : transport.read();
         for await (const rawMessage of messages) {
+            let attribution = rawMessage.input_uuid === null
+                ? { origin: 'background' } : typeof rawMessage.input_uuid === 'string'
+                ? { origin: 'user', turnId: rawMessage.input_uuid }
+                : streamingInput && inputState.turnId ? { turnId: inputState.turnId } : {};
             // Keep ordinary raw passthrough unchanged. Diagnostic payloads are an
             // untrusted error boundary even when a host asks for raw wire events.
             if (rawMessage.type === 'system' && rawMessage.subtype === 'request_progress' && !options.includeRequestProgress)
@@ -364,18 +369,18 @@ export async function* queryWithTransport(prompt, options, transport) {
                 }
             }
             if (options.includeRaw)
-                yield { type: 'raw', message };
+                yield { ...attribution, type: 'raw', message };
             switch (message.type) {
                 case 'system': {
                     if (message.subtype === 'request_progress' && progress)
-                        yield {
+                        yield { ...attribution,
                             type: 'request_progress', progress,
                             sessionId: typeof message.session_id === 'string' ? message.session_id : undefined,
                         };
                     if (message.subtype === 'error_diagnostic') {
                         const diagnostic = sanitizeRecoveryDiagnostic(message.diagnostic);
                         if (diagnostic)
-                            yield {
+                            yield { ...attribution,
                                 type: 'error_diagnostic', diagnostic,
                                 sessionId: typeof message.session_id === 'string' ? message.session_id : undefined,
                             };
@@ -386,19 +391,19 @@ export async function* queryWithTransport(prompt, options, transport) {
                     const sessionId = message.session_id;
                     for (const block of contentBlocks(message.message)) {
                         if (block.type === 'text' && typeof block.text === 'string') {
-                            yield { type: 'assistant_text', text: block.text, sessionId };
+                            yield { ...attribution, type: 'assistant_text', text: block.text, sessionId };
                         }
                         else if (block.type === 'tool_use') {
                             const toolUseId = String(block.id ?? '');
                             const toolName = String(block.name ?? '');
                             toolNamesById.set(toolUseId, toolName);
-                            yield {
+                            toolOrigins.set(toolUseId, attribution);
+                            yield { ...attribution,
                                 type: 'tool_use',
                                 toolName,
                                 input: (block.input ?? {}),
                                 toolUseId,
-                                sessionId,
-                            };
+                                sessionId, };
                         }
                     }
                     turn += 1;
@@ -420,7 +425,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     : Array.isArray(block.content) ? block.content.map(part => part?.type === 'text' && typeof part.text === 'string' ? { ...part, text: sanitizeErrorText(part.text) } : part)
                                         : describeError(block.content)
                                 : block.content;
-                            yield {
+                            yield { ...attribution,
                                 type: 'tool_result',
                                 toolUseId,
                                 content: resultContent,
@@ -435,6 +440,8 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     isError,
                                     sessionId,
                                 })));
+                            toolOrigins.delete(toolUseId);
+                            toolNamesById.delete(toolUseId);
                         }
                     }
                     break;
@@ -473,8 +480,9 @@ export async function* queryWithTransport(prompt, options, transport) {
                     const toolName = String(request.tool_name ?? '');
                     const input = (request.input ?? {});
                     const toolUseId = String(request.tool_use_id ?? '');
+                    attribution = toolOrigins.get(toolUseId) ?? attribution;
                     const agentId = typeof request.agent_id === 'string' ? request.agent_id : undefined;
-                    yield {
+                    yield { ...attribution,
                         type: 'permission_request',
                         requestId,
                         toolName,
@@ -509,7 +517,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         await store.deletePendingApproval(pendingApproval.sessionId);
                         pendingDecision = undefined;
                         pendingApproval = null;
-                        yield {
+                        yield { ...attribution,
                             type: 'permission_resolved',
                             requestId,
                             toolUseId,
@@ -546,13 +554,13 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     },
                                 },
                             });
-                            yield {
+                            yield { ...attribution,
                                 type: 'error',
                                 message: 'pending approval requested before any session_id was observed',
                                 fatal: false,
                                 code: 'pending_without_session',
                             };
-                            yield {
+                            yield { ...attribution,
                                 type: 'permission_resolved',
                                 requestId,
                                 toolUseId,
@@ -574,7 +582,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         // the model must not see a denial. Terminating here leaves the
                         // transcript ending at the unresolved tool_use, which the
                         // resume path drops and re-drives.
-                        yield {
+                        yield { ...attribution,
                             type: 'suspended',
                             sessionId,
                             requestId,
@@ -599,7 +607,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                             response: outcome.decision,
                         },
                     });
-                    yield {
+                    yield { ...attribution,
                         type: 'permission_resolved',
                         requestId,
                         toolUseId,
@@ -618,7 +626,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     if (ownRequestIds.has(requestId)) {
                         ownRequestIds.delete(requestId);
                         if (response.subtype === 'error') {
-                            yield {
+                            yield { ...attribution,
                                 type: 'error',
                                 message: `initialize failed: ${String(response.error)}`,
                                 fatal: false,
@@ -644,9 +652,9 @@ export async function* queryWithTransport(prompt, options, transport) {
                             // Metering must not break the conversation stream.
                         }
                     }
-                    yield {
+                    yield { ...attribution,
                         type: 'result',
-                        ...(streamingInput ? { turnId: inputState.turnId } : {}),
+                        ...(streamingInput ? { turnId: inputState.resultTurnId } : {}),
                         subtype: String(message.subtype ?? 'unknown'),
                         usage,
                         totalCostUsd,
@@ -666,6 +674,12 @@ export async function* queryWithTransport(prompt, options, transport) {
                         structuredOutput: message
                             .structured_output,
                     };
+                    for (const [id, origin] of toolOrigins) {
+                        if (origin.turnId === attribution.turnId && origin.origin === attribution.origin) {
+                            toolOrigins.delete(id);
+                            toolNamesById.delete(id);
+                        }
+                    }
                     sessionEnded = !streamingInput;
                     if (!streamingInput)
                         await runHook(hooks.onSessionEnd &&
@@ -682,7 +696,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     // (token-level delta). Only arrives when includePartialMessages passed the flag.
                     const streamEvent = message.event;
                     if (streamEvent && typeof streamEvent.type === 'string') {
-                        yield {
+                        yield { ...attribution,
                             type: 'stream_event',
                             event: streamEvent,
                             sessionId: message.session_id,

package/dist/sdk/queryInput.d.ts

@@ -5,6 +5,7 @@ export declare function normalizeUserInput(value: unknown): SDKUserMessage;
 export type InputState = {
     finished: boolean;
     turnId?: string;
+    resultTurnId?: string;
 };
 /**
  * One input is in flight at a time. Keep reading controls while the producer

package/dist/sdk/queryInput.js

@@ -53,10 +53,22 @@ export async function* readWithInput(input, transport, state, submitted) {
                 pendingWire = undefined;
                 if (next.value.done)
                     return;
+                const message = next.value.value;
+                const resultId = Object.prototype.hasOwnProperty.call(message, 'input_uuid')
+                    ? typeof message.input_uuid === 'string' ? message.input_uuid : undefined
+                    : state.turnId; // Compatibility with CLIs predating explicit attribution.
+                const completesInput = message.type === 'result' && state.turnId !== undefined && resultId === state.turnId;
+                if (message.type === 'result')
+                    state.resultTurnId = resultId;
                 yield next.value.value;
                 if (next.value.value.type === 'result') {
-                    state.turnId = undefined;
-                    pendingInput = pull();
+                    if (completesInput)
+                        state.turnId = undefined;
+                    // Scheduled work can finish while the host is already waiting for
+                    // the next user input. Replacing that pull loses its eventual value
+                    // and strands a Session turn behind another source.next().
+                    if (!state.turnId)
+                        pendingInput ??= pull();
                 }
             }
         }

package/dist/sdk/session.d.ts

@@ -1,4 +1,4 @@
-import type { Query, QueryOptions, SDKEvent, SDKUserMessage, Transport } from './types.js';
+import type { Query, QueryOptions, SDKEvent, SDKUserMessage, SessionLifecycleEvent, Transport } from './types.js';
 export type TurnResult = Extract<SDKEvent, {
     type: 'result';
 }>;
@@ -8,6 +8,9 @@ export type SessionOptions = QueryOptions & {
     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;
@@ -29,6 +32,7 @@ export declare class Session {
     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;
@@ -37,6 +41,7 @@ export declare class Session {
     private enqueue;
     private inputs;
     private consume;
+    private observe;
     private fail;
     private notifyDrained;
     interrupt(): Promise<void>;

package/dist/sdk/session.js

@@ -16,6 +16,7 @@ export class Session {
     closed = false;
     drainWaiters = [];
     pumping;
+    sessionId;
     constructor(options = {}, transport) {
         this.limit = options.maxPendingTurns ?? 32;
         if (!Number.isSafeInteger(this.limit) || this.limit < 1) {
@@ -24,9 +25,23 @@ export class Session {
         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, owned);
+        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();
     }
@@ -63,6 +78,7 @@ export class Session {
             this.queue.unshift(entry);
         else
             this.queue.push(entry);
+        this.observe({ type: 'turn_queued', turnId: id });
         this.wake?.();
         return turn;
     }
@@ -87,17 +103,31 @@ export class Session {
     async consume() {
         try {
             for await (const event of this.handle) {
-                const correlated = { ...event, turnId: event.turnId ?? this.active?.turn.id };
+                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 === 'result' && this.active) {
+                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');
-                    this.active.resolve(event);
+                    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();
                 }
@@ -105,7 +135,8 @@ export class Session {
                     throw new Error(event.message);
                 }
                 else if (event.type === 'suspended') {
-                    throw new Error(`ccl-sdk: session suspended; resumeWithDecision(${event.sessionId}) is required`);
+                    this.fail(new Error(`ccl-sdk: session suspended; resumeWithDecision(${event.sessionId}) is required`), event.origin === 'background' ? 'interrupted' : 'suspended');
+                    break;
                 }
             }
             if (!this.closed)
@@ -118,14 +149,31 @@ export class Session {
             await this.controls.close();
         }
     }
-    fail(reason) {
+    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;
-        this.active?.reject(error);
+        const active = this.active;
         this.active = undefined;
-        for (const entry of this.queue.splice(0))
+        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(() => { });
@@ -137,8 +185,13 @@ export class Session {
             resolve();
     }
     async interrupt() {
-        if (this.active)
+        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)
@@ -146,7 +199,9 @@ export class Session {
         const index = this.queue.findIndex(entry => entry.turn.id === id);
         if (index < 0)
             return;
-        this.queue.splice(index, 1)[0].reject(new Error('ccl-sdk: queued turn cancelled'));
+        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. */

package/dist/sdk/types.d.ts

@@ -314,7 +314,40 @@ export type SDKUserMessage = {
 };
 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;

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

@@ -52,3 +52,40 @@ 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/releases/1.5.0-alpha.0.md

@@ -0,0 +1,44 @@
+# 1.5.0-alpha.0
+
+本版基于 `1.4.6-beta.0`，交付 AI 指令综合升级。原方案 F1–F14 的修复、真实端到端验证和六原则复核已完成，原协议 Lisa 在 R10 总复核通过。此版为 alpha 预览，不将办公生成的失败样本或既有类型诊断宣称为通过。
+
+## 主要变化
+
+- 主助手、子助手的能力说明与实际工具解析共用来源。bare 无 Agent 时可直接工作；零工具角色不再被描述成全工具。内置技能和常规提示不强制调用不存在的工具。
+- 技能目录按完整条目分页，保留中文用途与近邻排除；宿主维护真实加载状态，文件里的标签不再被视为授权凭据。
+- 执行型子助手保留项目约束；审查允许必要的隔离测试产物。配置使用真实路径 owner；Git 写操作按依赖顺序执行；旧 auto/smart 不再用短词覆盖上下文分类。
+- 定时任务支持一次性、固定间隔和带时区的日历计划，包含未来起点与显式时间容差。新建精确任务默认不主动提前或错峰。
+- 明确后台任务接通 daemon 的启动、调度锁和真实就绪检查；保存、执行、权限等待和投递状态分别呈现。关闭创建终端后，结果可从新入口取回。
+- SDK 增加生命周期事件，修复用户输入与自主后台结果并发时的挂起和归属。包内 `examples/assistant/` 提供连续会话、进度、权限恢复和 Office 独立验证的参考宿主。
+- 统一记忆选择 JSON 合同，避免整理 worker 重复检索。视觉输出预算受实际模型能力约束，预算耗尽或截断明确失败；主动取消不再误报缺少正常答案。
+- Office 渲染只清理自己登记且未被修改的过期页面，避免短版文档混入旧尾页。
+
+## 安装
+
+```sh
+npm install --global @margay/ccl-core@1.5.0-alpha.0
+ccl --version
+margay --version
+```
+
+两个入口均应输出 `1.5.0-alpha.0 (Margay)`。Node 要求仍为 `>=22.19.0`。预览标签为 `alpha`；`latest`、`next`、`stable`、`rc` 保持原值。
+
+此包同时提供 CLI 与 SDK，不会更新 Margay Desktop 内置依赖，也不会自动重启已有进程或安装系统开机服务。若 PATH 前面存在旧包装脚本，用 `type -a ccl margay` 与 `"$(npm prefix -g)/bin/ccl" --version` 核对实际入口。
+
+Office 参考流程的制作/渲染依赖及宿主与助手分工见包内 `examples/assistant/README.md` 和 `office/workflow.md`；发布包不自动安装 LibreOffice 或 Python 制作依赖。
+
+## 调度兼容与回退
+
+旧 cron 定义保持原有读取语义，不在读取时静默迁移。首次向已有旧格式文件写入版本 1 计划前，保存原字节到 `.ccl/scheduled_tasks.json.pre-v1.backup`。
+
+旧版本不能完整理解新建的 once/interval 计划。回退前先停止本项目的新调度 owner，导出新任务与执行结果，再恢复旧格式备份；没有旧文件时保留导出并移开新格式文件。之后才安装旧版本。不要同时运行新旧调度 owner；回退程序不会撤销已经执行的业务写入。详见 [调度与 daemon 说明](../context-checkpoints-and-daemon.md)。
+
+## 验证与结果
+
+实现过程通过分片回归、原版反例、公开 CLI/SDK 合同、真实 WezTerm 模型行为、安装包验证及 R1–R10 协议 Lisa 审核。真实后台测试确认创建终端退出后读取库存，未提前访问，新入口取回正确结果。公开参考宿主验证十轮同 PID、排队/steer/取消、断线不重放、权限 pending 后恢复以及错误制品拒绝。
+
+180 次短答和 30 个 Office 长任务的固定版本比较均保留失败及修复成本。Office 最终 29/30 合格，8/30 零修复，后者全部来自常驻会话的后续复用；候选 CLI/SDK 中位耗时增加，不能声称全面提速。这些性能包在比较开始时冻结，早于后续修复，不是本 alpha 最终包的性能成绩。
+
+已知边界：全仓类型检查仍有与基线相同的 11 条诊断；有头十图测试包含记录在案的人工介入；Windows 实机未在本次验证。按需 schema 子树的实验没有改变产品默认配置。AI 生成内容仍需事实和全页审阅，文件存在或模型自报不是交付通过。
+
+仓库内 [完整报告](../ai-instructions-upgrade-final-review-2026-10-20.md)、[网页信息图](../ai-upgrade-explained-2026-10-20.html) 保留修复、证据和审核关系。原始运行证据保留于执行机 `.rll/records/ai-upgrade/`；本版打包、安装与发布回执保留于 `.rll/records/release-1.5.0-alpha.0/`，本地原始证据不随 npm 包分发。

package/examples/assistant/README.md

@@ -0,0 +1,23 @@
+# Terminal assistant reference host
+
+This runnable host consumes the public `@margay/ccl-core/sdk`. It is included in the npm package; it does not modify the separate Margay GUI.
+
+From an installed package (Node 22.19+), run:
+
+```sh
+node node_modules/@margay/ccl-core/examples/assistant/terminal.mjs --cwd /path/to/project
+```
+
+From this checkout, build first (`npm run build`), then run `node examples/assistant/terminal.mjs --cwd /path/to/project`. Normal CLI account/configuration discovery applies. `--model MODEL` selects a model; `--extra-args '["--tools","Read,Write"]'` forwards explicit CLI options. Keep credentials in the existing account configuration, not command arguments.
+
+Type a task. `/status` shows turn IDs and separate execution, verification and artifact states. `/steer TEXT` interrupts the active turn and queues the correction before follow-ups. `/cancel` requests active interruption; `/cancel TURN_ID` also removes a queued turn before dispatch. Completed effects are not rolled back.
+
+Permission requests show the exact tool and input. `/allow TOOL_ID` or `/deny TOOL_ID` resolves a live request. `/defer TOOL_ID` persists it and suspends execution. Exit with `/exit`, restart with `--resume`, then explicitly allow or deny the saved request. Resume never approves automatically. Existing configured allow/deny rules remain in effect.
+
+`/artifact RELATIVE_PATH` reads a project file, records its size and SHA-256, and reports availability. A model result, a readable file, or a model-written `validation.json` does not establish content correctness. Independent verification is recorded separately.
+
+State defaults to `PROJECT/.ccl/assistant-client/`; `--state-dir DIR` selects another directory. `state.json` stores session identity, recent turn outcomes and artifact records; `events.jsonl` retains the full journal. CLI transcripts and SDK approval state use their existing stores. These files can contain task content: share them only as appropriate for that project. One client holds the state directory lock; another cannot overwrite it. After a crash, restart with `--resume`. Pending queued work is cancelled and work that may already have executed is marked interrupted; inputs are never replayed automatically. Inspect recorded effects before retrying. A stale lock expires after ten seconds.
+
+Queue and dispatch notifications are local SDK observations and make no model request. “已发送” means written to the CLI, not a model response. The actual text stream, tools and request progress are displayed as received. Background events carry `origin: 'background'` and are not assigned to the waiting user turn.
+
+For the Office workflow, `/office ["inputs","artifacts"]` sends the packaged workflow location and the supplied directories to the current session. It reads the provided CSV/brief/meeting material and creates editable files using the documented toolchain. `/verify-office ["inputs","artifacts"]` runs the packaged independent Python checker from the host after execution ends. It reports numeric/structural differences and keeps semantic review separate. The checker requires Python 3; generation and full-page rendering dependencies are documented in [the workflow](office/workflow.md). This is an explicit reference-client command; it does not claim registration as a global CLI slash command.