@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/dispatcher/git-credentials.js

@@ -1,7 +1,7 @@
 // src/dispatcher/git-credentials.ts
 import { execFileSync } from 'node:child_process';
 /**
- * R20 D(execute) git 凭据注入（M4）：使 D 会话的 git ls-remote/push 可用。
+ * D(execute) git 凭据注入：使 D 会话的 git ls-remote/push 可用。
  *
  * 机制：D 会话的 bash 每次调用都是新 shell（无环境持久），故 env 变量不可跨调用。
  * 采用 repo-local http extraheader（AUTHORIZATION: basic），写入 <repo>/.git/config——
@@ -10,7 +10,7 @@ import { execFileSync } from 'node:child_process';
  * 鉴权按托管方区分：
  * - GitLab PAT（glpat- 前缀）→ basic base64("oauth2:<PAT>")（GitLab 规范，实测 ls-remote 通过）；
  * - 其余（GitHub 等）→ basic base64("x-access-token:<PAT>")。
- * D 会话为 danger-full-access（用户决策 Q4），HOME 可写，故 git 的 credential.helper
+ * D 会话为 danger-full-access（用户决策），HOME 可写，故 git 的 credential.helper
  * （store/osxkeychain 等）不再触发 "credential storage lock"，无需中和。
  *
  * PAT 来源（按优先级）：DSH 凭据服务 ctx.credentials（$DSH_HOME/.credentials.yaml 的

package/lib/dispatcher/model-candidates.d.ts

@@ -2,7 +2,7 @@ import type { KanbanConfig } from '../config.js';
 import type { Role } from '../domain/types.js';
 import type { AgentModelOptions } from './dispatcher.js';
 /**
- * 模型候选链（交付质量链 Task 12）：角色创建时主模型 → fallbacks 依次静默切换。
+ * 模型候选链：角色创建时主模型 → fallbacks 依次静默切换。
  * primary = config.roles.models[role]；未配置回退 defaultModel。
  * reasoningEffort 未指定一律 'high'。
  *

package/lib/dispatcher/model-candidates.js

@@ -1,5 +1,5 @@
 /**
- * 模型候选链（交付质量链 Task 12）：角色创建时主模型 → fallbacks 依次静默切换。
+ * 模型候选链：角色创建时主模型 → fallbacks 依次静默切换。
  * primary = config.roles.models[role]；未配置回退 defaultModel。
  * reasoningEffort 未指定一律 'high'。
  *

package/lib/dispatcher/session-events.d.ts

@@ -1,9 +1,11 @@
 /**
- * 会话事件条目统一读取助手（修复轮 6，举一反三）：
- * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
- * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 会话事件条目统一读取助手：
+ * 0.1.2（DSH-0.1.2-A4-03）起 Session.events getter 已移除——宿主新读取面是
+ * `session.seq`（日志长度）+ `session.snapshotEvents(fromSeq?, toSeqExclusive?)`。
+ * 事件条目形态（落盘与快照一致）为 { type, seq, time, data: { ... } }（append 时
+ * name/arguments 位于 e.data 下而非顶层）。
  * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
- * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ * 等所有消费点使用（先 snapshotEvents()、无则回退 events、再 []），避免逐个踩 `e.name 取不到` 的坑。
  */
 /** 取事件类型（如 'tool/call'）。 */
 export declare function eventType(e: {
@@ -13,16 +15,10 @@ export declare function eventType(e: {
     };
 }): string | undefined;
 /** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
-export declare function toolName(e: {
-    name?: unknown;
-    data?: {
-        name?: unknown;
-    };
-}): string | undefined;
+export declare function toolName(e: unknown): string | undefined;
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
-export declare function toolArgs(e: {
-    arguments?: unknown;
-    data?: {
-        arguments?: unknown;
-    };
-}): Record<string, unknown>;
+export declare function toolArgs(e: unknown): Record<string, unknown>;
+/** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
+ *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+export declare function replayModel(e: unknown): string | null;

package/lib/dispatcher/session-events.js

@@ -1,10 +1,12 @@
 // src/dispatcher/session-events.ts
 /**
- * 会话事件条目统一读取助手（修复轮 6，举一反三）：
- * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
- * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 会话事件条目统一读取助手：
+ * 0.1.2（DSH-0.1.2-A4-03）起 Session.events getter 已移除——宿主新读取面是
+ * `session.seq`（日志长度）+ `session.snapshotEvents(fromSeq?, toSeqExclusive?)`。
+ * 事件条目形态（落盘与快照一致）为 { type, seq, time, data: { ... } }（append 时
+ * name/arguments 位于 e.data 下而非顶层）。
  * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
- * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ * 等所有消费点使用（先 snapshotEvents()、无则回退 events、再 []），避免逐个踩 `e.name 取不到` 的坑。
  */
 /** 取事件类型（如 'tool/call'）。 */
 export function eventType(e) {
@@ -13,12 +15,14 @@ export function eventType(e) {
 }
 /** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
 export function toolName(e) {
-    const n = e?.name ?? e?.data?.name;
+    const rec = e;
+    const n = rec?.name ?? rec?.data?.name;
     return typeof n === 'string' ? n : undefined;
 }
 /** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
 export function toolArgs(e) {
-    const a = e?.arguments ?? e?.data?.arguments;
+    const rec = e;
+    const a = rec?.arguments ?? rec?.data?.arguments;
     if (a && typeof a === 'object')
         return a;
     if (typeof a === 'string') {
@@ -31,3 +35,11 @@ export function toolArgs(e) {
     }
     return {};
 }
+/** 取 assistant 消息的网关缓存回放标记（replayState.response.responseModel，如 'from-cache'）。
+ *  非 assistant/message 或无标记返回 null。2026-09-04：远程网关回复缓存整包回放时由 SSE
+ *  id/model 字段透传（dsh 纯透传），插件侧据此识别缓存劫持零产出。 */
+export function replayModel(e) {
+    const rec = e;
+    const m = rec?.data?.message?.source?.replayState?.response?.responseModel;
+    return typeof m === 'string' ? m : null;
+}

package/lib/dispatcher/target-repo.d.ts

@@ -1,6 +1,6 @@
 import type { BoardState, Task } from '../domain/types.js';
 /**
- * R20 D(execute) 目标仓库路径解析（B2/B3 共用）：
+ * D(execute) 目标仓库路径解析：
  * 1. 任务 body 的 TARGET_REPO=<path> 标记（V 生成 D 任务体时写入，见 v-orchestrator D 阶段指令）；
  * 2. 规格卡 file-prefetch 附件 ref（需求澄清清单 manifest 的仓库路径）；
  * 3. 回退默认目录（kanban 存储 / 会话工作区）。
@@ -10,6 +10,6 @@ import type { BoardState, Task } from '../domain/types.js';
  * 存在性校验同时兜底沙箱根：workspace-write 以会话 cwd 为写边界，指向不存在的
  * 目录会导致所有写被拒，故不存在时回退而非保留。
  */
-/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（B 前置授权）。 */
+/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（前置授权）。 */
 export declare function isPathInside(child: string, parent: string): boolean;
 export declare function resolveTargetRepoDir(task: Task, state: BoardState, fallback: string, allowFallback?: boolean): string;

package/lib/dispatcher/target-repo.js

@@ -2,7 +2,7 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 /**
- * R20 D(execute) 目标仓库路径解析（B2/B3 共用）：
+ * D(execute) 目标仓库路径解析：
  * 1. 任务 body 的 TARGET_REPO=<path> 标记（V 生成 D 任务体时写入，见 v-orchestrator D 阶段指令）；
  * 2. 规格卡 file-prefetch 附件 ref（需求澄清清单 manifest 的仓库路径）；
  * 3. 回退默认目录（kanban 存储 / 会话工作区）。
@@ -12,7 +12,7 @@ import { resolve } from 'node:path';
  * 存在性校验同时兜底沙箱根：workspace-write 以会话 cwd 为写边界，指向不存在的
  * 目录会导致所有写被拒，故不存在时回退而非保留。
  */
-/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（B 前置授权）。 */
+/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（前置授权）。 */
 export function isPathInside(child, parent) {
     const c = resolve(child);
     const p = resolve(parent);
@@ -37,6 +37,6 @@ export function resolveTargetRepoDir(task, state, fallback, allowFallback = true
             return abs;
     }
     // allowFallback=false（合入门控用）：不降级到回退目录——合入必须落在显式声明的目标仓库，
-    // 禁止 merge 到 kanban 存储/会话工作区等回退目录（M1，方向安全）。
+    // 禁止 merge 到 kanban 存储/会话工作区等回退目录（方向安全）。
     return allowFallback ? resolve(fallback) : '';
 }

package/lib/dispatcher/v-orchestrator.d.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { KanbanService } from '../domain/kanban-service.js';
-import type { KanbanConfig } from '../config.js';
+import type { ConfigProvider } from '../services/config-provider.js';
 import type { Role, TaskMode } from '../domain/types.js';
 import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
 import type { AgentModelOptions } from './dispatcher.js';
@@ -18,10 +18,19 @@ export declare const R20_PHASE_EXPECT: Record<VPhase, {
     assignee: Role;
     mode: TaskMode;
 } | null>;
-/** M5：每阶段建卡的 body 生成指令（角色定位确定性模板，消除 V 自由发挥导致的角色漂移）。
+/** 每阶段建卡的 body 生成指令（角色定位确定性模板，消除 V 自由发挥导致的角色漂移）。
  *  P=计划者（绝不执行）、D=唯一执行者（TARGET_REPO 必须取自规格卡 file-prefetch 附件 ref，禁止回退/猜测）、
  *  W=KB 同步（绝不执行代码）。V 把对应模板写入 kanban_create 的 body。 */
 export declare const PHASE_INSTRUCTIONS: Partial<Record<VPhase, string>>;
+/** W 角色知识库双模式：按 kbMode 构建各阶段建卡 body 指令（phase 键控——W2/W3 同为
+ *  assignee='w'+mode='kb'，assignee+mode 签名无法区分两相文案；系统状态本就按 phase 键控）。
+ *  remote → PHASE_INSTRUCTIONS 原文（护栏测试零改动前提）；local → 覆盖 w2/w3/d/dt 四相
+ *  （skill 工具加载 llm-wiki + 本地库 fs 读写，禁 wiki_write/wiki_read），p/pt/summary 原样回落。
+ *  ctx.taskId 给出则插值确切页路径，缺省用占位符（建卡时 taskId 尚不存在，消费点传 undefined）。 */
+export declare function buildPhaseInstruction(phase: VPhase, ctx: {
+    chainId: string;
+    taskId?: string;
+}, kbMode: 'remote' | 'local'): string;
 interface AgentLike {
     followup(msg: {
         content: {
@@ -33,18 +42,19 @@ interface AgentLike {
         };
     }): void;
     whenIdle(): Promise<void>;
-    session: {
-        events: Array<{
-            name?: string;
-            arguments?: unknown;
-        }>;
-    };
+    /** 宿主形态容忍：dsh 0.1.2-rc.1 下 Session.events 已移除（DSH-0.1.2-A4-03）→
+     *  经 seq/snapshotEvents 读取；events 声明仅为兼容旧宿主/测试。 */
+    session?: {
+        seq?: number;
+        snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): Array<Record<string, unknown>>;
+        events?: Array<Record<string, unknown>>;
+    } | undefined;
 }
 export declare class VOrchestrator {
     private readonly ctx;
     private readonly kanban;
     private readonly agents;
-    private readonly config;
+    private readonly configProvider;
     private readonly orchestrations;
     private readonly wiki;
     private readonly defaultModel;
@@ -55,9 +65,32 @@ export declare class VOrchestrator {
         resume(o: unknown): Promise<{
             agent: AgentLike;
         }>;
-    }, config: KanbanConfig, orchestrations: Map<string, ChainOrchestration>, wiki: WikiVaultClient, defaultModel?: AgentModelOptions);
+    }, configProvider: ConfigProvider, orchestrations: Map<string, ChainOrchestration>, wiki: WikiVaultClient, defaultModel?: AgentModelOptions);
     private currentPhase;
+    /** stall 自动再唤醒上限（同一阶段连续零产出 → 自动重试 ≤3 次，间隔递增）后放弃并显形。 */
+    private static readonly STALL_REWAKE_LIMIT;
+    /** stall 再唤醒基础延迟（按 stallCount 倍增：5s/10s/15s），给瞬时故障/采样波动恢复窗口。 */
+    private static readonly STALL_REWAKE_DELAY_MS;
+    private rewakeTimers;
+    /** 同链 wakeV 并发防护：在途时后续唤醒合并为 pending，完成后补跑一次（事件不丢）。 */
+    private waking;
+    private pendingWake;
+    /** orchestration 变更回调（dispatcher 注入 saveOrchs）——stall re-wake 路径绕过
+     *  EventWaker，其 stallCount/phase 变化需自行落盘，防重启丢重试进度。 */
+    onOrchChange?: () => void;
     wakeV(chainId: string): Promise<void>;
+    /** stall 自动再唤醒（≤3 次）。同链 pending 幂等；建卡成功（stallCount=0）后到期的
+     *  re-wake 自动作废（回调内按 stallCount 判空跳过）。 */
+    private scheduleRewake;
+    /** 清理待触发的 re-wake 定时器（插件 dispose 时调用）。 */
+    dispose(): void;
+    /** 链级看门狗（Dispatcher，防线①）探针：编排 entry；无 entry 返回 null。 */
+    orchestrationOf(chainId: string): ChainOrchestration | null;
+    /** 链级看门狗探针：该链是否有在途唤醒 / 待补跑唤醒 / 待触发再唤醒——任一为真视为「有人在管」。 */
+    isWakeInFlight(chainId: string): boolean;
+    /** 链级看门狗重唤醒入口（Dispatcher 防线①）：复用 wakeV（同链并发合并/补跑幂等内建）。 */
+    wake(chainId: string): Promise<void>;
+    private wakeVInner;
     /** 阻塞复核幂等判定：任务最近一次 task/blocked 之后已存在 [blocked-review] 开头的评论。
      *  注：at 为 Date.now() 毫秒精度，block 与评论可能同毫秒（测试/快路径实测碰撞）→ 用 seq 比较（确定性）。 */
     private hasBlockReview;
@@ -68,7 +101,7 @@ export declare class VOrchestrator {
     private handleReviewCompletion;
     private advance;
     private getVAgent;
-    /** M2(Q5)+归组：链的 workspaceDir（发起 /plan: 的主 agent 工作空间）；缺失返回 null（调用方询问/报错，不落 kanban 存储）。 */
+    /** 归组：链的 workspaceDir（发起 /plan: 的主 agent 工作空间）；缺失返回 null（调用方询问/报错，不落 kanban 存储）。 */
     private chainWorkspace;
 }
 export {};