qlogicagent 2.20.1 → 2.20.3

package/dist/types/cli/task-distillation-coordinator.d.ts

@@ -1,14 +1,16 @@
 /**
  * Task distillation coordinator (R3 wiring) — 候选采集/空闲窗蒸馏/晋升通知。
  * 纯逻辑在 skills/memory/task-distillation.ts;本模块只做依赖装配与生命周期:
- *   · recordTurn: turn-handler 回合完成处调用(轻量,embedding 异步)
+ *   · captureTurn: 回合完成屏障内只持久化候选;embedding 留给可抢占后台
+ *   · enrichCandidate: 后台补充 embedding;被前台抢占也不影响已持久化候选
  *   · runPass:   idle 空闲窗(stdio-server onIdle 并联)与 memory.distill RPC 共用入口
  *   · 蒸馏产物: category=procedure 进长期记忆(tag distilled@v1+sig),召回自然带出;
  *     LLM 摘要(dream 同款小模型)失败时降级确定性模板 —— 蒸馏永不因模型不可用而丢样本。
- *   · 晋升(spec:唯一技能入口): accessCount ≥ 阈值且未被负反馈沉底 → system.activity 推荐。
+ *   · 晋升(spec:唯一技能入口):复用量只用于发现候选;Host 的来源证据与跨会话前台结果验证是硬门槛。
  */
 import { type PromotionMetrics, type CandidateStoreFile, type PromotionProposal, type ProcedureUsageStoreFile, type PromotionStoreFile } from "../skills/memory/task-distillation.js";
 import type { HostCapabilityClient } from "../transport/host-capability-client.js";
+import type { ProcedureVerificationEvidence } from "../host-contract/index.js";
 /** [A4] addProcedure 落库回执分类(见 TaskDistillationDeps.addProcedure)。 */
 export type AddProcedureOutcome = "created" | "merged" | "rejected" | "retryable-failure";
 export interface TaskDistillationDeps {
@@ -16,25 +18,35 @@ export interface TaskDistillationDeps {
     hostCapabilityClient: () => HostCapabilityClient | undefined;
     /** 签名 embedding;null=不可用(候选照存但不参与聚类,宁严勿松)。
      * B3(X7):number[](非 Float32Array)——host 模式下 embedText 结果跨 x/host.request JSON wire。 */
-    embed: (text: string) => Promise<number[] | null>;
+    embed: (text: string, signal?: AbortSignal) => Promise<number[] | null>;
     /** [A4] 落库回执四分类(由 ingestExtracted 的结构化 items 归并):
      *   created  = 真实新落库 → 标 distilled + 发通知(只有它发);
      *   merged   = 近重复合并/已入提案管道 —— 合法成功,标 distilled 不通知;
      *   rejected = 安全闸拒/冲突 —— 终态,候选标 rejected 不再重试;
      *   retryable-failure = RPC 抛错/环境未就绪 —— 候选保持 pending 等下轮。 */
-    addProcedure: (text: string, tags: string[]) => Promise<AddProcedureOutcome>;
+    addProcedure: (text: string, tags: string[], evidence: {
+        candidateIds: string[];
+        idempotencyKey: string;
+    }) => Promise<AddProcedureOutcome>;
     /** 小模型摘要(dream 同款);null/失败 → 降级模板 */
-    llmExtract?: (prompt: string) => Promise<string | null>;
+    llmExtract?: (prompt: string, signal?: AbortSignal) => Promise<string | null>;
     /** 晋升扫描数据源:全部 distilled 条目 {id,text,accessCount,importance} */
     listDistilled: () => Promise<Array<{
         id: string;
         text: string;
         accessCount: number;
         importance: number;
+        verification: ProcedureVerificationEvidence;
     }>>;
-    /** V3 promote/demote:archive(技能接棒)/unarchive(降格回归)。B3(X7)异步化:16 面 proxy 方法。
-     * [A10] 后仅 demote 侧消费(promote 三步已收归 Host saga)。 */
-    setMemoryArchived: (id: string, archived: boolean) => Promise<boolean>;
+    /** Exact archived-aware recovery probe; unlike listDistilled this does not hide retired rows. */
+    readDistilledProcedure: (procedureId: string) => Promise<{
+        id: string;
+        text: string;
+        accessCount: number;
+        importance: number;
+        isArchived: boolean;
+        verification: ProcedureVerificationEvidence;
+    } | null>;
     /** [A10] 升格窄 Saga(Host 协调,memory proxy promoteDistilledProcedure):
      * create+verify → archive → proposal accepted,幂等/补偿/续跑在 Host;
      * 大脑传入推理产物(渲染并校验过的 SKILL.md 全文、确定性 skillName、标题/计数/auto)。 */
@@ -54,6 +66,17 @@ export interface TaskDistillationDeps {
             proposalAccepted: boolean;
         };
     }>;
+    demoteProcedure: (input: {
+        procedureId: string;
+    }) => Promise<{
+        outcome: "completed" | "already-completed";
+        skillName: string;
+        steps: {
+            skillDeleted: boolean;
+            memoryUnarchived: boolean;
+            proposalReverted: boolean;
+        };
+    }>;
     /** [X7] procedure-usage.json 读:store-owner 归 gateway,经 x/host proxy(自动档跨-session 数据源)。 */
     readProcedureUsage: () => Promise<ProcedureUsageStoreFile>;
     /** [X7] task-distill-candidates.json 读/写:store-owner 归 gateway;大脑侧裁剪(capCandidateStore)后经 proxy 写。 */
@@ -78,17 +101,22 @@ export interface DistillPassResult {
     promotionsNotified: number;
     pendingCandidates: number;
 }
+export declare function resolveCandidateEmbedding(embed: (text: string, signal?: AbortSignal) => Promise<number[] | null>, text: string, timeoutMs?: number, signal?: AbortSignal): Promise<number[] | null>;
 export declare class TaskDistillationCoordinator {
     private readonly deps;
     private readonly turnIndexBySession;
+    private candidateMutationTail;
     constructor(deps: TaskDistillationDeps);
     private requireCapability;
-    /** 回合完成时采集候选。异步(embedding 网络调用),错误吞掉不碰回合主链。 */
-    recordTurn(input: RecordTurnInput): Promise<void>;
+    private withCandidateMutation;
+    /** 回合完成屏障内的轻量持久化。Host 写成功后进程回收也不会丢候选。 */
+    captureTurn(input: RecordTurnInput): Promise<string | null>;
+    /** Cancellable embedding enhancement for a candidate already owned by Host. */
+    enrichCandidate(candidateId: string, promptHead: string, signal?: AbortSignal): Promise<void>;
     /** 空闲窗/手动共用的蒸馏 pass。 */
-    runPass(reason: "idle" | "manual"): Promise<DistillPassResult>;
+    runPass(reason: "idle" | "manual", signal?: AbortSignal): Promise<DistillPassResult>;
     private renderProcedure;
-    /** 晋升扫描(spec:技能的唯一产生入口):复用达标且未被负反馈沉底 → 写持久提议。
+    /** 晋升扫描(spec:技能的唯一产生入口):候选先过发现阈值,再以 Host 能力验证作为硬门槛。
      * V3.1:提议是持久待办(promotion-proposals.json),UI 双入口消费;activity 仅作日志。 */
     private scanPromotions;
     listProposals(): Promise<PromotionProposal[]>;
@@ -104,12 +132,12 @@ export declare class TaskDistillationCoordinator {
      * 该窗口失败即双向死角(重跑撞 already exists,demote 缺 skillName 找不到目标)。 */
     promote(procedureId: string, opts?: {
         auto?: boolean;
-    }): Promise<{
+    }, signal?: AbortSignal): Promise<{
         ok: boolean;
         skillName?: string;
         error?: string;
     }>;
-    /** 降格(可撤销是信任基础):删技能+unarchive 回 procedure;proposal 置 dismissed(用户明确否定,不再纠缠)。 */
+    /** 降格的跨存储事务、补偿与崩溃续跑全部由 Host saga 持有。 */
     demote(procedureId: string): Promise<{
         ok: boolean;
         error?: string;

package/dist/types/cli/tool-bootstrap-core-registration.d.ts

@@ -36,13 +36,25 @@ export declare function registerLocalCoreTools(context: LocalCoreToolRegistratio
 export declare function validateExecCommand(command: string, workdir: string, groupMode?: boolean): string | null;
 /** office/pdf 文档扩展名 → mime;非文档返回 undefined。导出仅为单测。 */
 export declare function documentMimeForExtension(ext: string): string | undefined;
+interface GrepBackendOptions {
+    fileGlob?: string;
+    caseInsensitive?: boolean;
+    contextLines?: number;
+    headLimit?: number;
+    offset?: number;
+    includePath?: (candidate: string) => boolean;
+}
 export interface RipgrepGrepOutcome {
     matches: Array<{
         path: string;
         line: number;
         text: string;
+        contextBefore?: string[];
+        contextAfter?: string[];
     }>;
     truncated: boolean;
+    totalMatches?: number;
+    totalMatchesKnown: boolean;
     /** Model-facing incompleteness note (search tool appends it to content). */
     note?: string;
 }
@@ -56,7 +68,5 @@ export interface RipgrepGrepOutcome {
 export declare function resolveRipgrepOutcome(err: (Error & {
     killed?: boolean;
     code?: number | string | null;
-}) | null, stdout: string, options: {
-    headLimit?: number;
-    offset?: number;
-}): RipgrepGrepOutcome | null;
+}) | null, stdout: string, options: Pick<GrepBackendOptions, "headLimit" | "offset" | "contextLines" | "includePath">): RipgrepGrepOutcome | null;
+export {};

package/dist/types/cli/tool-bootstrap.d.ts

@@ -53,7 +53,7 @@ export interface BootstrapConfig {
     log?: AgentLogger;
     /** Called during foreground shell execution with incremental progress. */
     onExecProgress?(progress: ExecProgress): void;
-    /** host 多档 LLM 解析(web_answer/web_research 用);未提供则不注册这些工具(零孤立)。 */
+    /** Optional Host model resolver for locally compiled model-backed tools such as media understanding. */
     resolveClientForPurpose?(purpose: ModelPurpose): {
         transport: LLMTransport;
         apiKey: string;
@@ -61,6 +61,7 @@ export interface BootstrapConfig {
     } | null;
     getTaskScopeKey?(): string | undefined;
     getCurrentTurnId?(): string | undefined;
+    isGroupSecurityMode?(): boolean;
     sendNotification?(method: string, params: Record<string, unknown>): void;
     loadTunableOverrides?(): Promise<Record<string, unknown>>;
 }

package/dist/types/cli/turn-core.d.ts

@@ -18,12 +18,16 @@ export interface TurnCoreRequest {
     refreshTools?: () => ToolDefinition[];
     /** Mid-turn guidance drain (运行中引导) — forwarded to the tool loop. */
     drainPendingGuidance?: () => string[];
+    /** Session-scoped background result drain — forwarded to the tool loop. */
+    drainPendingTaskNotifications?: () => string[];
     /** Sanitize tool-result media the main model can't consume — forwarded to the tool loop. */
     sanitizeToolResultMedia?: (message: Record<string, unknown>) => Promise<void>;
     /** Persist each model-visible tool-stream message to the transcript — forwarded to the tool loop. */
     persistTurnMessage?: (message: ChatMessage) => void;
     systemPrompt: string;
     config: TurnConfig;
+    /** Epoch/identity guard supplied by the session lifecycle owner. */
+    isTurnCurrent?: () => boolean;
 }
 export interface TurnCoreAgent {
     run(request: TurnCoreRequest, signal?: AbortSignal): AsyncIterable<TurnEvent>;

package/dist/types/cli/turn-lifecycle.d.ts

@@ -9,6 +9,7 @@ export interface TurnLifecycleHost {
     sessionState: SessionState | null;
     memoryPrefetchState: MemoryPrefetchState;
     enableIdleDream(): void;
+    log?(message: string): void;
 }
 export interface PreparedTurnLifecycle {
     abortController: AbortController;

package/dist/types/contracts/hooks.d.ts

@@ -83,6 +83,8 @@ export interface HookContextMap {
     };
     "turn.completed": HookTurnContext & {
         outcomeId?: string;
+        prompt?: string;
+        response?: string;
     };
     "turn.failed": HookTurnContext & {
         code?: string;
@@ -118,9 +120,8 @@ export interface HookContextMap {
             category?: string | null;
             source?: string;
             label?: string;
+            metadata?: Record<string, unknown>;
         }>;
-        preferredCategories?: string[];
-        deprioritizedCategories?: string[];
     };
     "memory.after_recall": HookTurnContext & {
         blockCount?: number;

package/dist/types/contracts/turn-event.d.ts

@@ -110,6 +110,13 @@ export type TurnEvent = {
         name: string;
         reason: string;
     }>;
+    argumentCorrections?: {
+        roleAlias: number;
+        promptAlias: number;
+        backgroundAlias: number;
+        agentValue: number;
+        backgroundValue: number;
+    };
 } | {
     type: "lifecycle";
     turnId: string;

package/dist/types/host-contract/index.d.ts

@@ -17,6 +17,7 @@ export { MODEL_PURPOSES, type ModelPurpose } from "@xiaozhiclaw/module-sdk/model
 export type { HostSessionCollectionDelta, HostSessionCollectionScope, HostSessionCollectionSnapshot, HostSessionLifecycle, HostSessionProviderDiagnostic, HostSessionSummary, HostSessionTitleSource, NativeTranscript, NativeTranscriptMessage, } from "../host-session-collection-contract.js";
 export { isHostSessionCollectionDelta, isHostSessionCollectionSnapshot, isNativeTranscript, } from "../host-session-collection-contract.js";
 export * from "./provider-profile.js";
+export * from "./memory-category.js";
 /** agent 逻辑身份(小智自身也是一个 agentId="qlogicagent")。自身 vs 第三方仅由此值决定(F2)。 */
 export type AgentId = string;
 /** 确定性派生的项目主键(freeze §11.4#2,抄 VSCode getWorkspaceId)。绝不随机、绝不裸路径。 */
@@ -512,29 +513,24 @@ export interface MemoryRecord {
     createdAt?: string;
     updatedAt?: string;
 }
-/** [S1 补定] 记忆匹配条件(delete 用)。 */
+/** Exact durable-memory match used by the Host storage contract. */
 export interface MemoryMatch {
     ids?: string[];
     query?: string;
 }
 /**
- * MemoryProfileService —— 记忆 + profile 数据(spec §14)。
- * 小智可为默认写入/解释者,但非唯一 owner;任意 peer 经 host 读写(P2:写入必带 byAgent)。
- * 是 memory MCP 能力模块(freeze §3.7)的 store-owner;三张脸(MCP 面/UI-API 面/brain proxy 面 X7)
- * 都是 thin adapter,唯一写者恒为本服务(脸数≠拷贝数,M-1)。
+ * Minimal durable-store contract implemented only by Runtime.
  *
- * A 域库面(memories.db + 附件 + 晋升/蒸馏 JSON + 用户级 INDEX.md 派生渲染)与 C 域项目 memdir
- * (`<cwd>/.qlogicagent/memory/`)都由 Gateway 独占在线存取。C 域仍是项目文件而非用户 Host store,
- * 但 agent 只能经 projectMemory X7 语义代理访问,与 VSCode ext host 经 main IFileService proxy 同构。
+ * `memories.db` is the single L2 authority. Project/file memory is a separate L1
+ * surface and never acts as a fallback for this service.
  */
 export interface MemoryProfileService {
     atlas(query: MemoryQuery): MemoryRecord[];
     read(source: string, target: string): MemoryRecord | undefined;
-    /** 显式记录写入者(M-3) */
+    /** Every signed store write records the responsible Agent. */
     write(record: MemoryRecord, byAgent: AgentId): void;
     delete(match: MemoryMatch): void;
     consolidate(candidates: MemoryRecord[], source: string): void;
-    promote(proposal: unknown): void;
 }
 /** [S1 补定] 首启进度状态。 */
 export interface OnboardingState {
@@ -589,6 +585,15 @@ export interface RunState {
     status: string;
     events?: RunEvent[];
     checkpoint?: unknown;
+    /**
+     * Rollback history ids, oldest first — ids only, never the snapshots.
+     *
+     * The store already retains the last 20 named checkpoints, but `RunState` used to carry just the
+     * head, so every read surface could only ever report one. A run reopened from history then showed a
+     * single-entry timeline and could only roll back to the newest point, silently losing the rest.
+     * Snapshots stay out: status/list readers want the timeline, not 20 full Product states.
+     */
+    checkpointIds?: string[];
     openedAt: string;
     updatedAt: string;
 }
@@ -601,6 +606,18 @@ export interface RunState {
 export interface RunStateStore {
     /** Optional caller-selected domain id keeps Solo/Product/Goal public ids identical to host run ids. */
     openRun(kind: "solo" | "product" | "goal", owner: SessionContext, runId?: RunId): RunId;
+    /**
+     * Atomic open + first checkpoint: the run becomes addressable ONLY once it already carries a snapshot.
+     *
+     * `openRun` followed by a separate `checkpoint` is two round trips, and a failure between them leaves
+     * an enveloped run with `checkpoint === undefined`. Readers that project a whole project's run list
+     * cannot tolerate that shape, so one such remnant permanently breaks the entire list for that project.
+     * Writers that always have their first snapshot in hand MUST use this instead of open+checkpoint.
+     *
+     * Idempotent in the same way as `openRun` (same kind + projectId + owner session re-uses the run);
+     * on re-use the snapshot is applied as a normal checkpoint.
+     */
+    openRunWithCheckpoint(kind: "solo" | "product" | "goal", owner: SessionContext, snapshot: unknown, runId?: RunId, checkpointId?: string): RunId;
     recordEvent(runId: RunId, ev: RunEvent): void;
     /** product/solo 检查点 */
     checkpoint(runId: RunId, snapshot: unknown, checkpointId?: string): void;
@@ -789,12 +806,42 @@ export declare const DELEGATE_WIRE_METHODS: {
 export interface HostNotificationSink {
     notify(eventName: string, payload: unknown): void;
 }
+/** Durable hand-off from a completed foreground turn to the background semantic
+ * extractor. The Host owns this operational queue; the Agent owns extraction. */
+export interface HostMemoryExtractionTurnInput {
+    sessionId: string;
+    turnId: string;
+    priorUserMessage?: string;
+    userMessage: string;
+    assistantMessage: string;
+}
+export interface HostPendingMemoryExtractionTurn extends HostMemoryExtractionTurnInput {
+    id: string;
+    attempts: number;
+    lastError: string;
+    leaseOwner: string;
+    leasedUntil: number;
+    createdAt: number;
+    updatedAt: number;
+}
 /**
  * [X7] qlogicagent 大脑经 x/host.request 可调用的 memory proxy 精确方法面。
  * gateway 白名单与 qla HostMemoryProvider 都必须直接消费此常量，禁止两仓手抄后漂移。
  */
-export declare const HOST_MEMORY_PROXY_METHODS: readonly ["search", "addText", "embedText", "ingestExtracted", "proposeExtracted", "consumePendingProposals", "feedback", "findRelatedEvents", "synthesizeTimeline", "getActivitySummary", "getAllProfiles", "setProfile", "getAtlas", "setMemoryArchived", "triggerDecay", "resolveConflicts", "readProcedureUsage", "writeProcedureUsage", "readDistillCandidates", "writeDistillCandidates", "readPromotionProposals", "writePromotionProposals", "listActiveMemoriesByTag", "promoteDistilledProcedure", "recordInjectedAccess"];
+export declare const HOST_MEMORY_PROXY_METHODS: readonly ["search", "addText", "embedText", "ingestExtracted", "proposeExtracted", "consumePendingProposals", "feedback", "findRelatedEvents", "synthesizeTimeline", "getActivitySummary", "getAllProfiles", "setProfile", "getAtlas", "setMemoryArchived", "triggerDecay", "resolveConflicts", "readProcedureUsage", "writeProcedureUsage", "readDistillCandidates", "writeDistillCandidates", "readPromotionProposals", "writePromotionProposals", "listActiveMemoriesByTag", "readDistilledProcedure", "promoteDistilledProcedure", "demoteDistilledProcedure", "recordInjectedAccess", "recordRecallOutcome", "enqueueExtractionTurn", "claimPendingExtractionTurns", "completeExtractionTurn", "releaseExtractionTurn", "recordExtractionTurnFailure"];
 export type HostMemoryProxyMethod = (typeof HOST_MEMORY_PROXY_METHODS)[number];
+/** Host-computed proof that a distilled procedure is a repeatable capability.
+ * Source executions prove how it was learned; helped use rows prove that the
+ * distilled procedure itself subsequently worked in foreground turns. */
+export interface ProcedureVerificationEvidence {
+    sourceSuccessCount: number;
+    sourceDistinctSessions: number;
+    sourceDistinctPrompts: number;
+    successfulUseCount: number;
+    successfulUseSessions: number;
+    harmfulUseCount: number;
+    passed: boolean;
+}
 /** Project-scoped Markdown memory face. Gateway resolves cwd/project from the supervised caller. */
 export declare const HOST_PROJECT_MEMORY_PROXY_METHODS: readonly ["initialize", "getIndex", "addToIndex", "replaceInIndex", "removeFromIndex", "createFile", "writeFile", "readFile", "deleteFile", "listFiles", "searchLocal"];
 export type HostProjectMemoryProxyMethod = (typeof HOST_PROJECT_MEMORY_PROXY_METHODS)[number];
@@ -882,6 +929,37 @@ export type HostProjectRequestParams = {
         primaryWorkflowId?: string;
     };
 };
+export type HostSubagentType = "general" | "explore" | "plan" | "code" | "research" | "verify";
+export interface HostDelegationTelemetrySummary {
+    schemaVersion: 1;
+    launched: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    backgroundCount: number;
+    automaticDeliveryCount: number;
+    byAgentType: Partial<Record<HostSubagentType, number>>;
+    decisionCounts: {
+        adopted: number;
+        partiallyAdopted: number;
+        rejected: number;
+        unreported: number;
+    };
+    argumentCorrections: {
+        roleAlias: number;
+        promptAlias: number;
+        backgroundAlias: number;
+        agentValue: number;
+        backgroundValue: number;
+    };
+    durationMs: {
+        total: number;
+        max: number;
+    };
+    tokenUsage: {
+        total: number;
+    };
+}
 export interface HostTurnTelemetryInput {
     model?: string;
     provider?: string;
@@ -902,6 +980,7 @@ export interface HostTurnTelemetryInput {
         changedPathsPreview?: string[];
         hasTurnFileChanges?: boolean;
     };
+    delegationSummary?: HostDelegationTelemetrySummary;
 }
 /** Minimal, non-message-text evidence returned to the agent-side pure distiller. */
 export interface HostDistillableFeedbackEvent {
@@ -1210,6 +1289,12 @@ export type HostMemoryRequestParams = {
     service: "memory";
     method: HostMemoryProxyMethod;
     params: unknown[];
+    /**
+     * Optional supervised-session selector for background mutations. The Host
+     * validates that this session belongs to the calling supervised Agent before
+     * using it as evidence provenance; it is never trusted as storage authority.
+     */
+    sessionId?: string;
 };
 export type HostProjectMemoryRequestParams = {
     service: "projectMemory";
@@ -1360,7 +1445,7 @@ export type HostFeedbackRequestParams = {
     };
 };
 /** Agent-originated semantic run-state operations. Owner/project/cwd are resolved by Gateway scope. */
-export declare const HOST_RUN_STATE_PROXY_METHODS: readonly ["open", "recordEvent", "checkpoint", "get", "list", "delete", "getCheckpoint", "listCheckpoints", "restoreCheckpoint"];
+export declare const HOST_RUN_STATE_PROXY_METHODS: readonly ["open", "openWithCheckpoint", "recordEvent", "checkpoint", "get", "list", "delete", "getCheckpoint", "listCheckpoints", "restoreCheckpoint"];
 export type HostRunStateProxyMethod = typeof HOST_RUN_STATE_PROXY_METHODS[number];
 export type HostRunStateRequestParams = {
     service: "runState";
@@ -1371,6 +1456,19 @@ export type HostRunStateRequestParams = {
         projectId: ProjectId;
         sessionId: CanonicalSessionId;
     };
+}
+/** Atomic open + first checkpoint — see RunStateStore.openRunWithCheckpoint for why open+checkpoint is unsafe. */
+ | {
+    service: "runState";
+    method: "openWithCheckpoint";
+    params: {
+        runId: RunId;
+        kind: "solo" | "product" | "goal";
+        projectId: ProjectId;
+        snapshot: unknown;
+        checkpointId?: string;
+        sessionId: CanonicalSessionId;
+    };
 } | {
     service: "runState";
     method: "recordEvent";
@@ -1694,3 +1792,4 @@ export declare function supportsHostRequestService(capability: unknown, service:
  * protocol→host-contract 模块环,check-architecture-boundaries top-level-cycles 抓出)。
  */
 export { segmentForFts, segmentTextForFts } from "./fts-segment.js";
+export { HUB_SKILL_CATEGORIES, HUB_SKILL_CATEGORY_LABELS, isHubSkillCategory, type HubSkillCategory, } from "./skill-category.js";

package/dist/types/host-contract/memory-category.d.ts

@@ -0,0 +1,8 @@
+/** Host-owned taxonomy shared by every long-term-memory producer and consumer. */
+export declare const LONG_TERM_MEMORY_CATEGORIES: readonly ["fact", "preference", "insight", "lesson", "decision", "plan", "event", "pattern", "context", "procedure", "general"];
+export type LongTermMemoryCategory = (typeof LONG_TERM_MEMORY_CATEGORIES)[number];
+/** Logical relation between an atomic claim slot and its structured value. */
+export declare const MEMORY_CLAIM_RELATIONS: readonly ["equals", "includes", "excludes"];
+export type MemoryClaimRelation = (typeof MEMORY_CLAIM_RELATIONS)[number];
+export declare function normalizeLongTermMemoryCategory(value: unknown, fallback?: LongTermMemoryCategory): LongTermMemoryCategory;
+export declare function normalizeMemoryClaimRelation(value: unknown, fallback?: MemoryClaimRelation): MemoryClaimRelation;

package/dist/types/host-contract/skill-category.d.ts

@@ -0,0 +1,5 @@
+/** Host-owned taxonomy shared by skill promotion, persistence, and UI. */
+export declare const HUB_SKILL_CATEGORIES: readonly ["efficiency", "dev", "cloud", "data", "industrial", "marketing", "ecommerce", "procurement", "hr", "accounting", "finance", "legal", "lifestyle"];
+export type HubSkillCategory = (typeof HUB_SKILL_CATEGORIES)[number];
+export declare const HUB_SKILL_CATEGORY_LABELS: Readonly<Record<HubSkillCategory, string>>;
+export declare function isHubSkillCategory(value: unknown): value is HubSkillCategory;

package/dist/types/host-session-collection-contract.d.ts

@@ -23,6 +23,7 @@ export interface HostSessionSummary {
     title?: string;
     titleSource?: HostSessionTitleSource;
     lastActiveAt: string;
+    pinnedAt?: string;
     lifecycle: HostSessionLifecycle;
     /** Host-authorized mutation surface. Renderer commands are a projection of this list. */
     availableCommands: HostSessionCommand[];

package/dist/types/orchestration/agent-instance.d.ts

@@ -172,6 +172,21 @@ export declare class ProductOrchestrator {
     private consultLeaderAfterFailure;
     private applyDagMutationsToSession;
     private finishProduct;
+    /**
+     * Durable persistence failed → the run is over. Declaring that is not enough: the in-flight work has
+     * to actually stop.
+     *
+     * This used to only set phase and stop the checkpoint timer, so with 3 parallel tasks the run went
+     * "failed" for the client while the other 2 kept executing for up to their full timeout — still
+     * writing worktrees and still issuing EXPLICIT checkpoints (`stop()` only cancels the periodic
+     * timer, it does not block direct writes). The persisted state then drifted into phase=failed with
+     * tasks=completed, `finishProduct` never ran, and the session stayed in the map forever.
+     *
+     * `session.cancelled` is the existing single flag that closes all of that: it makes in-flight tasks
+     * treat their outcome as non-failure, aborts the retry loops, and short-circuits the post-task
+     * checkpoint + scheduleNext. Kept synchronous (14 call sites, several inside sync paths) — the
+     * per-task `finally` already tears down each task worktree, so no async cleanup is needed here.
+     */
     private failRunStatePersistence;
     private publishNotification;
     private emitDagTopology;

package/dist/types/orchestration/dag-scheduler.d.ts

@@ -92,6 +92,16 @@ export declare class DagScheduler {
         changedFiles?: string[];
         acceptanceUnverified?: boolean;
     }): void;
+    /**
+     * Mark failed. Terminal states are immutable: a node that already completed, was skipped, or
+     * already failed is left untouched.
+     *
+     * Without this guard markFailed was the one lifecycle transition with no precondition (markRunning /
+     * markCompleted / markSkipped all have one), so teardown and replay — which both call it on whatever
+     * task an instance last held — could rewrite a real success as a failure, erase its output, and then
+     * propagateSkips() would block the downstream that success had unlocked. Keeping the FIRST error also
+     * stops a late generic rejection ("gateway torn down") from burying the actual diagnosis.
+     */
     markFailed(id: string, error: string): void;
     markPaused(id: string): void;
     resumePaused(id: string): void;
@@ -126,6 +136,14 @@ export declare class DagScheduler {
      */
     resetForReplay(id: string): string[];
     /** Merge patch into node.params. Node must be pending. */
+    /**
+     * Merge patch into node.params. Allowed while the node is pending OR failed.
+     *
+     * "failed" is included because that is exactly when the leader refines a task: the node is not
+     * executing, and retryNode resets it to pending anyway, so the patch lands on the DAG that gets
+     * checkpointed. Holding such patches outside the node instead (a per-call scratch map) meant a
+     * refinement made in one consultation was gone by the next, and the retry re-ran the failing text.
+     */
     updateNodeParams(id: string, patch: Record<string, unknown>): void;
     /** Add an explicit edge. Validates no cycle. Validates ports exist on source. */
     addEdge(edge: Edge): void;

package/dist/types/orchestration/delegate-approval-policy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unattended orchestration runs are explicitly launched by the user and already inherit the
+ * Host-projected permission scope. Approve only the current operation; never widen the persisted
+ * permission policy. If the provider cannot offer a one-shot approval, fail closed.
+ */
+export declare function selectUnattendedApprovalOptionId(options: Array<Record<string, unknown>>): string;
+/** Planning-only delegates must never execute tools; answer explicitly so the provider cannot hang. */
+export declare function selectPlanningRejectionOptionId(options: Array<Record<string, unknown>>): string;

package/dist/types/orchestration/goal-acceptance.d.ts

@@ -1,4 +1,4 @@
-import type { AcceptanceChecklist, AcceptanceEvidence, AcceptanceStatus } from "./goal-run-types.js";
+import type { AcceptanceChecklist, AcceptanceCriterion, AcceptanceEvidence, AcceptanceStatus } from "./goal-run-types.js";
 /** Return a NEW checklist with one criterion's status flipped. Never mutates the input.
  *  Monotonicity contract: a criterion that already `passed` may only revert to `failed` via a
  *  deterministic verify REGRESSION (allowRegression=true). Any other downgrade of a passed criterion
@@ -14,7 +14,4 @@ export declare function unreachableCoversRemaining(checklist: AcceptanceChecklis
     reason: string;
 }[]): boolean;
 /** Derive a new immutable checklist version on goal-edit. Dropped criteria -> superseded. */
-export declare function newChecklistVersion(prev: AcceptanceChecklist, nextCriteria: {
-    id: string;
-    criterion: string;
-}[]): AcceptanceChecklist;
+export declare function newChecklistVersion(prev: AcceptanceChecklist, nextCriteria: Pick<AcceptanceCriterion, "id" | "criterion" | "verify" | "evidenceSource">[]): AcceptanceChecklist;

package/dist/types/orchestration/goal-loop-coordinator.d.ts

@@ -43,16 +43,17 @@ export declare class GoalLoopCoordinator {
     private readonly deps;
     private seq;
     private opChain;
-    private activeAbort;
+    private activePhase;
     private readonly persistenceContext;
     constructor(deps: GoalLoopCoordinatorDeps);
     private serialize;
     private notify;
     private append;
     private persist;
-    /** Launch a goal-run (instant, Codex-style). Returns the goalRunId. */
+    /** Durably reserve a goal-run without entering the leader lane. Returns the goalRunId immediately. */
     start(goal: string, agentPool: string[]): Promise<string>;
     private startImpl;
+    private ensureChecklistInitializedImpl;
     /** Load the run; seed `seq` so a fresh instance (post-crash) keeps appending monotonically. */
     private load;
     enqueueMessage(goalRunId: string, text: string): Promise<void>;
@@ -87,6 +88,7 @@ export declare class GoalLoopCoordinator {
     /** Drive phases until the run ends or is paused. Not serialized: it only calls the serialized
      *  runOnePhase in a loop, so a concurrent pause/stop is observed at the next boundary. */
     runToCompletion(goalRunId: string): Promise<PersistedGoalRunState>;
+    private publishRoundMessage;
     /** Pause: abort the in-flight phase IMMEDIATELY (before serialize) so it drains fast and the mutex
      *  frees quickly, then persist the paused state. If the in-flight phase is the one being aborted, it
      *  drains via its abort handler and persists `paused` itself (runOnePhaseImpl's catch); pauseImpl then

package/dist/types/orchestration/goal-mode-adapters.d.ts

@@ -5,6 +5,18 @@ import type { ProductOrchestrator } from "./agent-instance.js";
 import type { HostRunStateAuthority } from "./run-state-host-authority.js";
 import type { LeaderPort, PhaseRunnerPort } from "./goal-loop-coordinator.js";
 import { type AcceptanceCriterion, type AcceptanceDelta, type PhaseSpec } from "./goal-run-types.js";
+export type GoalVerifyCommandValidation = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Persisted Goal verifiers are unattended acceptance contracts, not general-purpose shell scripts.
+ * Reject known stdin, interactive, host-specific and nondeterministic constructs before persistence;
+ * runVerifyDeltas repeats the check for old snapshots and defense in depth.
+ */
+export declare function validateGoalVerifyCommand(command: string): GoalVerifyCommandValidation;
 /**
  * #2 verify 输出的头尾截断:测试/构建命令的失败摘要通常在输出**末尾**(框架的 summary 行),裸
  * slice(0,N) 保头丢尾会把真正的失败原因截掉,判官只能看到无关的开头。超限时保留头尾各半,并在
@@ -110,6 +122,10 @@ export declare function parsePhaseSpec(reply: string, availableAgentIds: string[
  */
 export declare function validateAssessDeltas(rawDeltas: AcceptanceDelta[], changedFiles: string[], log?: {
     warn(msg: string): void;
+}, context?: {
+    criteria?: AcceptanceCriterion[];
+    outputTexts?: string[];
+    assignmentReceiptLines?: string[];
 }): AcceptanceDelta[];
 /**
  * #1②: the judge-prompt view of this phase's project changed files. The PROMPT is windowed to stay

package/dist/types/orchestration/goal-run-types.d.ts

@@ -20,6 +20,9 @@ export interface AcceptanceCriterion {
     id: string;
     criterion: string;
     status: AcceptanceStatus;
+    /** Output-only criteria (reply/copy/summary/etc.) are accepted from the Product task result text,
+     *  never by inventing a shell verifier or citing an unrelated file. */
+    evidenceSource?: "output" | "host.product.assignment";
     evidence?: AcceptanceEvidence[];
     reason?: string;
     verify?: string;
@@ -71,7 +74,7 @@ export interface GoalQueuedMessage {
 export interface GoalRunEvent {
     seq: number;
     ts: string;
-    type: "goal_started" | "phase_planned" | "phase_started" | "task_settled" | "phase_assessed" | "progress_compacted" | "goal_edited" | "message_queued" | "paused" | "resumed" | "stopped" | "phase_boundary" | "ended";
+    type: "goal_started" | "checklist_initialized" | "phase_planned" | "phase_started" | "task_settled" | "phase_assessed" | "progress_compacted" | "goal_edited" | "message_queued" | "paused" | "resumed" | "stopped" | "phase_boundary" | "round_message" | "ended";
     payload: Record<string, unknown>;
 }
 /** Derived Goal checkpoint stored by Gateway RunState, rebuildable by replaying events. */
@@ -83,6 +86,8 @@ export interface PersistedGoalRunState {
     currentGoal: string;
     goalUpdatedAt?: string;
     checklistVersion: number;
+    /** False only between the durable start acknowledgement and the detached leader initialization. */
+    checklistInitialized?: boolean;
     status: GoalRunStatus;
     pauseState: GoalPauseState;
     phaseIndex: number;