@joekytc/dsh-swarm 0.1.0

package/lib/dispatcher/git-credentials.js

@@ -0,0 +1,78 @@
+// src/dispatcher/git-credentials.ts
+import { execFileSync } from 'node:child_process';
+/**
+ * R20 D(execute) git 凭据注入（M4）：使 D 会话的 git ls-remote/push 可用。
+ *
+ * 机制：D 会话的 bash 每次调用都是新 shell（无环境持久），故 env 变量不可跨调用。
+ * 采用 repo-local http extraheader（AUTHORIZATION: basic），写入 <repo>/.git/config——
+ * 持久跨 bash 调用、由插件进程（web app 侧，不受 D 会话沙箱限制）注入。
+ *
+ * 鉴权按托管方区分：
+ * - 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
+ * （store/osxkeychain 等）不再触发 "credential storage lock"，无需中和。
+ *
+ * PAT 来源（按优先级）：DSH 凭据服务 ctx.credentials（$DSH_HOME/.credentials.yaml 的
+ * KANBAN_GIT_PAT/GIT_PAT）→ 进程 env（KANBAN_GIT_PAT > GIT_PAT > GH_TOKEN > GITHUB_TOKEN）。
+ * 未配置 PAT 时不注入（回退用户已有 git 凭据/SSH）。
+ */
+/** D 会话可用 git PAT 的 env 变量名（按优先级）。 */
+export const GIT_PAT_ENV_NAMES = ['KANBAN_GIT_PAT', 'GIT_PAT', 'GH_TOKEN', 'GITHUB_TOKEN'];
+/** 从进程 env 解析非空 PAT；无则返回 null。 */
+export function resolveGitPat(env) {
+    for (const name of GIT_PAT_ENV_NAMES) {
+        const v = env[name];
+        if (v && v.trim())
+            return v.trim();
+    }
+    return null;
+}
+/** 经 DSH 凭据服务解析 PAT（$DSH_HOME/.credentials.yaml / env / .env，见 dsh-credentials-local 分层）；无则回退进程 env。 */
+export async function resolveGitPatFromCtx(ctx, env) {
+    const creds = ctx.get?.('credentials');
+    if (creds?.resolve) {
+        for (const name of GIT_PAT_ENV_NAMES) {
+            try {
+                const r = await creds.resolve(name);
+                if (r?.value && r.value.trim())
+                    return r.value.trim();
+            }
+            catch { /* 单个引用解析失败继续下一个 */ }
+        }
+    }
+    return resolveGitPat(env);
+}
+/** PAT → http extraheader 值：GitLab(glpat-*) 用 oauth2 前缀，其余 x-access-token。 */
+export function gitAuthHeader(pat) {
+    const prefix = pat.startsWith('glpat-') ? 'oauth2:' : 'x-access-token:';
+    return 'AUTHORIZATION: basic ' + Buffer.from(prefix + pat).toString('base64');
+}
+/**
+ * 注入 repo-local http extraheader。返回 { ok, detail }（失败不抛——注入失败仅告警，
+ * D 仍可执行；用户自带凭据/SSH 的仓库不受影响）。
+ */
+export function injectGitCredentials(repoDir, pat) {
+    const targets = [];
+    try {
+        const url = execFileSync('git', ['-C', repoDir, 'remote', 'get-url', 'origin'], { encoding: 'utf8' }).trim();
+        if (url.startsWith('http://') || url.startsWith('https://'))
+            targets.push(url);
+    }
+    catch {
+        // 非 git 仓库或无 origin：注入目标为空
+    }
+    if (targets.length === 0)
+        return { ok: false, detail: 'no http remote origin' };
+    try {
+        const header = gitAuthHeader(pat);
+        for (const target of targets) {
+            // git config <section>.<subsection>.<variable>：http.<url>.extraheader
+            execFileSync('git', ['-C', repoDir, 'config', '--local', `http.${target}.extraheader`, header]);
+        }
+        return { ok: true, detail: targets.join(',') };
+    }
+    catch (err) {
+        return { ok: false, detail: String(err) };
+    }
+}

package/lib/dispatcher/merge-gate.d.ts

@@ -0,0 +1,28 @@
+import type { KanbanService } from '../domain/kanban-service.js';
+import type { BoardState, Task } from '../domain/types.js';
+/** 合入输入：repoDir=目标仓库绝对路径；targetBranch=规格卡声明分支；featureBranch=D 交接 metadata.branch。 */
+export interface MergeInput {
+    repoDir: string;
+    targetBranch: string;
+    featureBranch: string;
+}
+export declare const MERGE_DONE_PREFIX = "[merge-done]";
+export declare const MERGE_SKIP_PREFIX = "[merge-skip]";
+export declare const MERGE_FAILED_PREFIX = "[merge-failed]";
+export interface GitRun {
+    (args: string[], cwd: string): string;
+}
+/** 真实 git 执行器：execFileSync 同步执行，非零退出抛错（与 git-credentials.ts 同模式）。 */
+export declare function realGitRun(args: string[], cwd: string): string;
+/** 从 D(execute) 终态卡解析合入输入。任一要素缺失（repo 不存在 / TARGET_BRANCH 标记 / branch metadata）→ null（软跳过）。 */
+export declare function resolveMergeInput(dTask: Task, state: BoardState, fallbackRepo: string): MergeInput | null;
+/** 幂等判定：已存在 [merge-done] 评论，或 feature 分支已是 target 祖先（git merge-base --is-ancestor exit 0）。 */
+export declare function isAlreadyMerged(state: BoardState, dTaskId: string, repoDir: string, targetBranch: string, featureBranch: string, git: GitRun): boolean;
+/**
+ * 执行合入（DT 通过后由 system 调用）：checkout target → merge --no-ff feature → push。
+ * 返回 'merged' | 'failed' | 'skipped'。失败不抛：记录 [merge-failed] 评论，链仍可收尾
+ * （坏代码未被合入 = 方向安全；人工可事后修复）。
+ */
+export declare function runMergeGate(kanban: KanbanService, state: BoardState, dTask: Task, input: MergeInput, git?: GitRun): Promise<'merged' | 'failed' | 'skipped'>;
+/** 链完成钩子入口（dispatcher setOnChainCompleted 调用）：DT 通过后合入。解析失败软跳过。 */
+export declare function mergeDAfterReview(kanban: KanbanService, chainId: string, fallbackRepo: string): Promise<'merged' | 'failed' | 'skipped'>;

package/lib/dispatcher/merge-gate.js

@@ -0,0 +1,74 @@
+// src/dispatcher/merge-gate.ts
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveTargetRepoDir } from './target-repo.js';
+export const MERGE_DONE_PREFIX = '[merge-done]';
+export const MERGE_SKIP_PREFIX = '[merge-skip]';
+export const MERGE_FAILED_PREFIX = '[merge-failed]';
+/** 真实 git 执行器：execFileSync 同步执行，非零退出抛错（与 git-credentials.ts 同模式）。 */
+export function realGitRun(args, cwd) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }).trim();
+}
+/** 从 D(execute) 终态卡解析合入输入。任一要素缺失（repo 不存在 / TARGET_BRANCH 标记 / branch metadata）→ null（软跳过）。 */
+export function resolveMergeInput(dTask, state, fallbackRepo) {
+    // allowFallback=false：合入仓库必须是显式声明的 TARGET_REPO/规格卡 ref，绝不回退到 kanban 存储等目录。
+    const repoDir = resolveTargetRepoDir(dTask, state, fallbackRepo, false);
+    if (!repoDir || !existsSync(resolve(repoDir)))
+        return null;
+    const targetBranch = dTask.body?.match(/TARGET_BRANCH\s*=\s*(\S+)/)?.[1];
+    const featureBranch = String(state.handoffs.get(dTask.id)?.metadata?.['branch'] ?? '').trim();
+    if (!targetBranch || !featureBranch)
+        return null;
+    return { repoDir, targetBranch, featureBranch };
+}
+/** 幂等判定：已存在 [merge-done] 评论，或 feature 分支已是 target 祖先（git merge-base --is-ancestor exit 0）。 */
+export function isAlreadyMerged(state, dTaskId, repoDir, targetBranch, featureBranch, git) {
+    // 仅认 system 写入的 [merge-done] 标记：角色可伪造评论体，author 过滤防幂等门被冒名绕过。
+    const doneComment = state.events.some((e) => e.taskId === dTaskId && e.kind === 'task/commented' && e.author === 'system' &&
+        String(e.payload['body'] ?? '').startsWith(MERGE_DONE_PREFIX));
+    if (doneComment)
+        return true;
+    try {
+        git(['merge-base', '--is-ancestor', featureBranch, targetBranch], repoDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 执行合入（DT 通过后由 system 调用）：checkout target → merge --no-ff feature → push。
+ * 返回 'merged' | 'failed' | 'skipped'。失败不抛：记录 [merge-failed] 评论，链仍可收尾
+ * （坏代码未被合入 = 方向安全；人工可事后修复）。
+ */
+export async function runMergeGate(kanban, state, dTask, input, git = realGitRun) {
+    const { repoDir, targetBranch, featureBranch } = input;
+    if (isAlreadyMerged(state, dTask.id, repoDir, targetBranch, featureBranch, git))
+        return 'skipped';
+    try {
+        git(['checkout', targetBranch], repoDir);
+        git(['merge', '--no-ff', featureBranch, '-m', `[AI-GEN] merge ${featureBranch} into ${targetBranch} after DT pass`], repoDir);
+        git(['push'], repoDir);
+        const hash = git(['rev-parse', 'HEAD'], repoDir);
+        await kanban.comment(dTask.id, `${MERGE_DONE_PREFIX} merged ${featureBranch} → ${targetBranch} hash=${hash}`, 'system');
+        return 'merged';
+    }
+    catch (err) {
+        await kanban.comment(dTask.id, `${MERGE_FAILED_PREFIX} merge ${featureBranch} → ${targetBranch} failed: ${String(err)}`, 'system');
+        return 'failed';
+    }
+}
+/** 链完成钩子入口（dispatcher setOnChainCompleted 调用）：DT 通过后合入。解析失败软跳过。 */
+export async function mergeDAfterReview(kanban, chainId, fallbackRepo) {
+    const state = await kanban.snapshot();
+    const dTask = [...state.tasks.values()].find((t) => t.chainId === chainId && t.assignee === 'd' && t.mode === 'execute' && t.status === 'done');
+    if (!dTask)
+        return 'skipped';
+    const input = resolveMergeInput(dTask, state, fallbackRepo);
+    if (!input) {
+        await kanban.comment(dTask.id, `${MERGE_SKIP_PREFIX} 无法解析合入输入（缺 branch metadata / TARGET_BRANCH 标记 / repo 不存在），跳过自动合入`, 'system');
+        return 'skipped';
+    }
+    return runMergeGate(kanban, state, dTask, input);
+}

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

@@ -0,0 +1,13 @@
+import type { KanbanConfig } from '../config.js';
+import type { Role } from '../domain/types.js';
+import type { AgentModelOptions } from './dispatcher.js';
+/**
+ * 模型候选链（交付质量链 Task 12）：角色创建时主模型 → fallbacks 依次静默切换。
+ * primary = config.roles.models[role]；未配置回退 defaultModel。
+ * reasoningEffort 未指定一律 'high'。
+ *
+ * @returns 有序候选链（不含不可用者；可能为空 = 无任何配置）
+ */
+export declare function buildModelCandidates(config: KanbanConfig, role: Role, defaultModel?: AgentModelOptions): AgentModelOptions[];
+/** 判定 create/resume 错误是否属于 model/provider 不可用（可静默切换下一候选）。 */
+export declare function isModelUnavailableError(err: unknown): boolean;

package/lib/dispatcher/model-candidates.js

@@ -0,0 +1,31 @@
+/**
+ * 模型候选链（交付质量链 Task 12）：角色创建时主模型 → fallbacks 依次静默切换。
+ * primary = config.roles.models[role]；未配置回退 defaultModel。
+ * reasoningEffort 未指定一律 'high'。
+ *
+ * @returns 有序候选链（不含不可用者；可能为空 = 无任何配置）
+ */
+export function buildModelCandidates(config, role, defaultModel) {
+    const m = config.roles?.models?.[role];
+    const chain = [];
+    if (m?.provider && m?.model) {
+        chain.push({ provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high' });
+        for (const f of m.fallbacks ?? []) {
+            if (f?.provider && f?.model)
+                chain.push({ provider: f.provider, model: f.model, reasoningEffort: f.reasoningEffort ?? 'high' });
+        }
+    }
+    else if (defaultModel?.provider && defaultModel?.model) {
+        chain.push({ provider: defaultModel.provider, model: defaultModel.model, reasoningEffort: defaultModel.reasoningEffort ?? 'high' });
+    }
+    return chain;
+}
+/** 判定 create/resume 错误是否属于 model/provider 不可用（可静默切换下一候选）。 */
+export function isModelUnavailableError(err) {
+    const msg = String(err instanceof Error ? err.message : err).toLowerCase();
+    if (msg.includes('adapter'))
+        return true; // no adapter registered for provider …
+    if (msg.includes('provider') && (msg.includes('unavailable') || msg.includes('not') || msg.includes('fail')))
+        return true;
+    return msg.includes('model') && (msg.includes('unavailable') || msg.includes('not found') || msg.includes('no adapter'));
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 会话事件条目统一读取助手（修复轮 6，举一反三）：
+ * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
+ * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
+ * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ */
+/** 取事件类型（如 'tool/call'）。 */
+export declare function eventType(e: {
+    type?: unknown;
+    data?: {
+        type?: unknown;
+    };
+}): string | undefined;
+/** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
+export declare function toolName(e: {
+    name?: unknown;
+    data?: {
+        name?: unknown;
+    };
+}): string | undefined;
+/** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
+export declare function toolArgs(e: {
+    arguments?: unknown;
+    data?: {
+        arguments?: unknown;
+    };
+}): Record<string, unknown>;

package/lib/dispatcher/session-events.js

@@ -0,0 +1,33 @@
+// src/dispatcher/session-events.ts
+/**
+ * 会话事件条目统一读取助手（修复轮 6，举一反三）：
+ * dsh-session 的 session.events 条目落盘形态为 { type, seq, time, data: { ... } }（append 时
+ * data 嵌套在 data 键下），name/arguments 等字段位于 e.data 下而非顶层。
+ * 本助手兼容两种形态（顶层展开 / data 嵌套），供 v-orchestrator / agent-runner / chain-auditor
+ * 等所有读取 agent.session.events 的消费点使用，避免逐个踩 `e.name 取不到` 的坑。
+ */
+/** 取事件类型（如 'tool/call'）。 */
+export function eventType(e) {
+    const t = e?.type ?? e?.data?.type;
+    return typeof t === 'string' ? t : undefined;
+}
+/** 取工具调用名（如 'kanban_complete' / 'bash' / 'kanban_create'）。 */
+export function toolName(e) {
+    const n = e?.name ?? e?.data?.name;
+    return typeof n === 'string' ? n : undefined;
+}
+/** 取工具调用参数对象（兼容 JSON 字符串 / 对象两种落盘形态）。 */
+export function toolArgs(e) {
+    const a = e?.arguments ?? e?.data?.arguments;
+    if (a && typeof a === 'object')
+        return a;
+    if (typeof a === 'string') {
+        try {
+            return JSON.parse(a);
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}

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

@@ -0,0 +1,15 @@
+import type { BoardState, Task } from '../domain/types.js';
+/**
+ * R20 D(execute) 目标仓库路径解析（B2/B3 共用）：
+ * 1. 任务 body 的 TARGET_REPO=<path> 标记（V 生成 D 任务体时写入，见 v-orchestrator D 阶段指令）；
+ * 2. 规格卡 file-prefetch 附件 ref（需求澄清清单 manifest 的仓库路径）；
+ * 3. 回退默认目录（kanban 存储 / 会话工作区）。
+ *
+ * 解析为绝对路径并校验存在性；候选不存在时继续降级，全部失败回退默认目录——
+ * 保证给 agents.create 的 meta.cwd 恒为绝对路径（会话校验要求 isAbsolute）。
+ * 存在性校验同时兜底沙箱根：workspace-write 以会话 cwd 为写边界，指向不存在的
+ * 目录会导致所有写被拒，故不存在时回退而非保留。
+ */
+/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（B 前置授权）。 */
+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

@@ -0,0 +1,42 @@
+// src/dispatcher/target-repo.ts
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * R20 D(execute) 目标仓库路径解析（B2/B3 共用）：
+ * 1. 任务 body 的 TARGET_REPO=<path> 标记（V 生成 D 任务体时写入，见 v-orchestrator D 阶段指令）；
+ * 2. 规格卡 file-prefetch 附件 ref（需求澄清清单 manifest 的仓库路径）；
+ * 3. 回退默认目录（kanban 存储 / 会话工作区）。
+ *
+ * 解析为绝对路径并校验存在性；候选不存在时继续降级，全部失败回退默认目录——
+ * 保证给 agents.create 的 meta.cwd 恒为绝对路径（会话校验要求 isAbsolute）。
+ * 存在性校验同时兜底沙箱根：workspace-write 以会话 cwd 为写边界，指向不存在的
+ * 目录会导致所有写被拒，故不存在时回退而非保留。
+ */
+/** 判断 child 是否位于 parent 目录内（含等于）。用于 D 目标仓库是否在会话工作空间内的判定（B 前置授权）。 */
+export function isPathInside(child, parent) {
+    const c = resolve(child);
+    const p = resolve(parent);
+    if (c === p)
+        return true;
+    return c.startsWith(p.endsWith('/') ? p : p + '/');
+}
+export function resolveTargetRepoDir(task, state, fallback, allowFallback = true) {
+    const candidates = [];
+    const body = task.body ?? '';
+    const m = body.match(/TARGET_REPO\s*=\s*(\S+)/);
+    if (m)
+        candidates.push(m[1]);
+    const chain = state.chains.get(task.chainId);
+    const card = chain?.specCardId ? state.specCards.get(chain.specCardId) : undefined;
+    const prefetch = card?.attachments.find((a) => a.kind === 'file-prefetch');
+    if (prefetch?.ref)
+        candidates.push(prefetch.ref);
+    for (const c of candidates) {
+        const abs = resolve(c);
+        if (existsSync(abs))
+            return abs;
+    }
+    // allowFallback=false（合入门控用）：不降级到回退目录——合入必须落在显式声明的目标仓库，
+    // 禁止 merge 到 kanban 存储/会话工作区等回退目录（M1，方向安全）。
+    return allowFallback ? resolve(fallback) : '';
+}

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

@@ -0,0 +1,74 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanService } from '../domain/kanban-service.js';
+import type { KanbanConfig } from '../config.js';
+import type { Role, TaskMode } from '../domain/types.js';
+import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import type { AgentModelOptions } from './dispatcher.js';
+export type VPhase = 'p' | 'pt' | 'w2' | 'd' | 'dt' | 'w3' | 'summary';
+export interface ChainOrchestration {
+    chainId: string;
+    phase: VPhase;
+    sessionId: string | null;
+    waitingOn: string | null;
+    stallCount?: number;
+}
+export declare const R20_PHASE_ORDER: VPhase[];
+/** 每 phase 的期望建卡（pt 由 P 交付 pt_decision.needed=true 触发；dt 固定）。 */
+export declare const R20_PHASE_EXPECT: Record<VPhase, {
+    assignee: Role;
+    mode: TaskMode;
+} | null>;
+/** M5：每阶段建卡的 body 生成指令（角色定位确定性模板，消除 V 自由发挥导致的角色漂移）。
+ *  P=计划者（绝不执行）、D=唯一执行者（TARGET_REPO 必须取自规格卡 file-prefetch 附件 ref，禁止回退/猜测）、
+ *  W=KB 同步（绝不执行代码）。V 把对应模板写入 kanban_create 的 body。 */
+export declare const PHASE_INSTRUCTIONS: Partial<Record<VPhase, string>>;
+interface AgentLike {
+    followup(msg: {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        source: {
+            kind: string;
+        };
+    }): void;
+    whenIdle(): Promise<void>;
+    session: {
+        events: Array<{
+            name?: string;
+            arguments?: unknown;
+        }>;
+    };
+}
+export declare class VOrchestrator {
+    private readonly ctx;
+    private readonly kanban;
+    private readonly agents;
+    private readonly config;
+    private readonly orchestrations;
+    private readonly wiki;
+    private readonly defaultModel;
+    constructor(ctx: Context, kanban: KanbanService, agents: {
+        create(o: unknown): Promise<{
+            agent: AgentLike;
+        }>;
+        resume(o: unknown): Promise<{
+            agent: AgentLike;
+        }>;
+    }, config: KanbanConfig, orchestrations: Map<string, ChainOrchestration>, wiki: WikiVaultClient, defaultModel?: AgentModelOptions);
+    private currentPhase;
+    wakeV(chainId: string): Promise<void>;
+    /** 阻塞复核幂等判定：任务最近一次 task/blocked 之后已存在 [blocked-review] 开头的评论。
+     *  注：at 为 Date.now() 毫秒精度，block 与评论可能同毫秒（测试/快路径实测碰撞）→ 用 seq 比较（确定性）。 */
+    private hasBlockReview;
+    /** 评审卡 completed 处理（交付质量链）：读 handoff 的 review_evidence verdict 分流。
+     *  pass → recordReview(passed) + 推进；fail → recordReview(failed) + createReworkTask + 新建复审卡；
+     *  reviewAttempt ≥ maxReworksPerRole → review/gave-up + [review-final] 证据链（链保持）。
+     *  严禁对已完成的上游 P/D 调 blockTask（done 不可变；返工走新 rework 卡）。 */
+    private handleReviewCompletion;
+    private advance;
+    private getVAgent;
+    /** M2(Q5)+归组：链的 workspaceDir（发起 /plan: 的主 agent 工作空间）；缺失返回 null（调用方询问/报错，不落 kanban 存储）。 */
+    private chainWorkspace;
+}
+export {};