@co0ontty/wand 4.76.0 → 4.77.0-beta.g6c4df97

package/dist/ai-team-runner.js

@@ -0,0 +1,1370 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { dispatchAgentForTask, resolveTaskDispatchTarget, sendToAgentSession, stopAgentSession, } from "./agent-dispatch.js";
+import { AI_TEAM_REPORT_DIR, aiTeamChatHistoryPath, aiTeamHandoffPath, aiTeamReportPath, buildLeaderFollowupPrompt, buildLeaderFormatRetryPrompt, buildAiTeamObjective, buildLeaderKickoffPrompt, buildMemberPrompt, leaderOf, parseLeaderDecision, renderChatHistoryFile, renderHandoffFile, } from "./ai-team-prompts.js";
+import { AI_TEAM_STARTUP_WINDOW_MS, classifyCandidateFailure, classifyStartupFailure, isDegradableWorkFailure, isModelUnknownBeforeDispatch, } from "./ai-team-availability.js";
+import { AI_TEAM_ACTIVE_RUN_STATUSES, AI_TEAM_DETAIL_CHAT_TURNS, agentKey, memberAgents, } from "./ai-team-types.js";
+import { getErrorMessage } from "./error-utils.js";
+import { activityState } from "./missions.js";
+const REPORT_MAX_BYTES = 64 * 1024;
+/** 报告文件最后一次写入后要稳定这么久才读取，避免读到写了一半的文件。 */
+const REPORT_SETTLE_MS = 1500;
+const OUTPUT_DEBOUNCE_MS = 1000;
+const SWEEP_INTERVAL_MS = 5000;
+const MAX_FORMAT_RETRIES = 2;
+/** 同一个候选累计这么多次 startup-timeout 就按五元组拉黑（§3.4 黑名单 agents 层）。 */
+const STARTUP_TIMEOUT_STRIKES = 2;
+/** 群聊会话的 automationId 前缀；后面接运行 id。 */
+export const AI_TEAM_CHAT_PREFIX = "ai-team-chat:";
+/** 等批准时，群里回复这些词就是批准，其余内容都当修改意见。 */
+const APPROVE_REPLY = /^(批准|同意|可以|开始|开干|好的?|ok|okay|yes|lgtm|approve)[。.!！]*$/i;
+const STOP_REPLY = /^(停止|停下|stop)[。.!！]*$/i;
+/** 用户可见的冲突错误（路由转 409）。 */
+export class AiTeamConflictError extends Error {
+}
+export function createAiTeamSessionOps(deps) {
+    return {
+        async open(input) {
+            const { session } = await dispatchAgentForTask(deps, input);
+            return session.id;
+        },
+        send: (sessionId, text) => sendToAgentSession(deps, sessionId, text),
+        stop: (sessionId) => stopAgentSession(deps, sessionId),
+        snapshot: (sessionId) => deps.sessions.getLatest(sessionId),
+        ownerOf: (sessionId) => deps.sessions.ownerOf(sessionId),
+    };
+}
+export function createAiTeamChatOps(deps) {
+    const structured = deps.structured;
+    if (!structured)
+        return undefined;
+    return {
+        open({ task, run, title }) {
+            const target = resolveTaskDispatchTarget(deps, task);
+            const leader = leaderOf(run.team);
+            const session = structured.createRelaySession({
+                cwd: run.cwd,
+                mode: leader.agent.mode,
+                provider: leader.agent.provider,
+                worktreeEnabled: false,
+                sessionSource: "interactive",
+                automationId: `${AI_TEAM_CHAT_PREFIX}${run.id}`,
+                workspaceId: target.workspaceId,
+                workspaceTaskId: target.workspaceTaskId,
+                title,
+            });
+            deps.storage.bindWandTaskSession(task.id, session.id);
+            return session.id;
+        },
+        post: (sessionId, turns) => {
+            structured.appendRelayTurns(sessionId, turns);
+        },
+    };
+}
+export function createAiTeamRunner(deps) {
+    const runner = new AiTeamRunner({
+        storage: deps.storage,
+        resolveCwd: (task) => resolveTaskDispatchTarget(deps, task).cwd,
+        ops: createAiTeamSessionOps(deps),
+        chat: createAiTeamChatOps(deps),
+        notify: deps.notify,
+        models: deps.models,
+    });
+    deps.structured?.registerRelay(AI_TEAM_CHAT_PREFIX, (sessionId, text) => runner.chatInput(sessionId, text));
+    return runner;
+}
+/**
+ * 群聊里的发言人。上传的头像是 data URL，每条消息都带一份太重，改用按 id 取的像素猫。
+ * `provider` 传该步**实际使用候选**的 provider（§3.6/B15）；Leader 或没有步骤的场景回退首选。
+ */
+function chatAuthor(member, sessionId, provider) {
+    return {
+        id: member.id,
+        name: member.name,
+        avatar: member.avatar && !member.avatar.startsWith("data:") ? member.avatar : undefined,
+        leader: member.isLeader || undefined,
+        provider: provider ?? memberAgents(member)[0]?.provider ?? member.agent.provider,
+        sessionId: sessionId ?? undefined,
+    };
+}
+const chatText = (text) => [{ type: "text", text }];
+/** CLI 的错误常是「一行摘要 + 一大段 JSON」，有用的信息在头尾；中间截掉以免撑爆报告。 */
+function summarizeError(error) {
+    const text = (error ?? "").trim();
+    if (text.length <= 400)
+        return text;
+    return `${text.slice(0, 160)} … ${text.slice(-240)}`;
+}
+const HOME_PATH_PLACEHOLDER = "~";
+const CONFIG_PATH_PLACEHOLDER = "<配置目录>";
+const SECRET_VALUE_PLACEHOLDER = "<已隐藏>";
+/**
+ * 凭据参数名。强名字（token / secret / api_key / connection_code …）`=` 与 `:` 两种写法都收；
+ * 弱名字（code / key）只收 `code=` / `key=` 形式——否则 provider 错误 JSON 里的
+ * `code: 'ENOENT'`、`status_code: 503` 也会被误吞，而连接码本身就是 64 位 hex，逃不掉。
+ */
+const SECRET_PARAM_PATTERN = new RegExp("\\b((?:(?:access[_-]?token|refresh[_-]?token|id[_-]?token|auth[_-]?token|api[_-]?key|apikey"
+    + "|secret[_-]?key|client[_-]?secret|private[_-]?key|connection[_-]?code|password|passwd|secret|token)"
+    + "\\s*[=:]|(?:code|key)\\s*=)\\s*)(?:\"[^\"]*\"|'[^']*'|[^\\s&;,}\"]+)", "gi");
+/** 已知签发前缀（sk- / ghp_ / xoxb- / AIza…）后面跟的长串一定是凭据。 */
+const KNOWN_SECRET_PATTERN = /\b(?:sk|pk|ghp|gho|ghu|ghs|ghr|xox[abprs]?|AIza|ya29)[-_][A-Za-z0-9]{10,}/g;
+/** HTTP Authorization 头的值形态：`Bearer <凭据>` 整段收掉。 */
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+/** 高熵长串兜底：≥32 字符的连续 body（provider 文案里的路径、模型名都不到这个长度）。 */
+const LONG_TOKEN_PATTERN = /\b[A-Za-z0-9][A-Za-z0-9+/=_-]{30,}\b/g;
+/**
+ * 落库 / 进群聊前的脱敏（§4.5「全链路不写连接码 / token / home 路径」）。
+ * 纯函数、无 IO：目录由调用方传进来，同一个输入永远得到同一个输出，重复清洗结果不变。
+ * 顺序很关键：先把配置目录（在家目录下）整段换掉，再换家目录，否则 `~/.wand` 会漏半截。
+ * 方向是宁多勿漏：认不准的超长串一律隐藏，代价只是文案少一段可调试信息。
+ */
+export function redactAiTeamErrorText(text, dirs = {}) {
+    if (!text)
+        return text;
+    let out = text;
+    const configDir = dirs.configDir?.trim();
+    if (configDir && configDir.length > 1)
+        out = out.split(configDir).join(CONFIG_PATH_PLACEHOLDER);
+    const homeDir = dirs.homeDir?.trim();
+    if (homeDir && homeDir.length > 1 && homeDir !== path.sep) {
+        out = out.split(homeDir).join(HOME_PATH_PLACEHOLDER);
+    }
+    // 报错里提到的可能是别的用户 / 别的机器（本机 homedir 比对不上），通用家目录前缀一并收掉。
+    out = out.replace(/(^|[\s"'(=,])(?:\/(?:Users|home)\/|C:\\+Users\\+)[^/"'(),\s]*/g, `$1${HOME_PATH_PLACEHOLDER}`);
+    out = out.replace(SECRET_PARAM_PATTERN, `$1${SECRET_VALUE_PLACEHOLDER}`);
+    out = out.replace(BEARER_PATTERN, SECRET_VALUE_PLACEHOLDER);
+    out = out.replace(KNOWN_SECRET_PATTERN, SECRET_VALUE_PLACEHOLDER);
+    out = out.replace(LONG_TOKEN_PATTERN, (match) => (/\d/.test(match) && /[A-Za-z]/.test(match)) || /[_-]/.test(match) ? SECRET_VALUE_PLACEHOLDER : match);
+    return out;
+}
+function isSessionGone(snapshot) {
+    return snapshot.status === "exited" || snapshot.status === "failed" || snapshot.status === "stopped";
+}
+function turnText(turn) {
+    return turn.content
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text.trim())
+        .filter(Boolean)
+        .join("\n\n");
+}
+/** 找到提示词（含 reportPath）那一轮之后的 assistant 文本；没有回复返回 null。 */
+function assistantReplyAfterPrompt(snapshot, reportPath) {
+    const messages = snapshot.messages ?? [];
+    let promptIndex = -1;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const turn = messages[index];
+        if (turn.role === "user" && turnText(turn).includes(reportPath)) {
+            promptIndex = index;
+            break;
+        }
+    }
+    if (promptIndex < 0)
+        return null;
+    const replies = messages.slice(promptIndex + 1).filter((turn) => turn.role === "assistant");
+    if (replies.length === 0)
+        return null;
+    return replies.map(turnText).filter(Boolean).join("\n\n");
+}
+function readReport(file) {
+    const buffer = readFileSync(file);
+    if (buffer.length <= REPORT_MAX_BYTES)
+        return buffer.toString("utf8");
+    return `${buffer.subarray(0, REPORT_MAX_BYTES).toString("utf8")}\n\n（已截断）`;
+}
+/** 把 .wand-team/ 加进仓库的 info/exclude，避免报告文件出现在未跟踪列表里。 */
+function excludeReportDir(cwd) {
+    try {
+        const gitDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!gitDir)
+            return;
+        const excludeFile = path.join(path.resolve(cwd, gitDir), "info", "exclude");
+        const line = `/${AI_TEAM_REPORT_DIR}/`;
+        const current = existsSync(excludeFile) ? readFileSync(excludeFile, "utf8") : "";
+        if (current.split(/\r?\n/).some((entry) => entry.trim() === line))
+            return;
+        appendFileSync(excludeFile, `${current && !current.endsWith("\n") ? "\n" : ""}${line}\n`);
+    }
+    catch {
+        // 不在 git 仓库里或没有写权限：跳过，不影响运行。
+    }
+}
+/**
+ * AI 团队调度器。状态全部在数据库里，会话事件驱动推进；同一运行的所有操作串行执行。
+ * 成员会话是普通 Wand 会话，服务端只负责传话：Leader 决定派谁做什么，成员交报告。
+ */
+export class AiTeamRunner {
+    storage;
+    ops;
+    chat;
+    resolveCwd;
+    notifyListener;
+    modelsOf;
+    now;
+    chains = new Map();
+    outputTimers = new Map();
+    recheckTimers = new Map();
+    /** 已经确定「不降级、按既有路径记 failed」的步骤，防止 finishStep 再判一次形成回环。 */
+    noDegrade = new Set();
+    sweepTimer = null;
+    /** 脱敏参照目录只算一次：os.homedir() 读 env，configDir 随 storage 定，运行期不变。 */
+    redactionDirsValue = null;
+    constructor(options) {
+        this.storage = options.storage;
+        this.ops = options.ops;
+        this.chat = options.chat;
+        this.resolveCwd = options.resolveCwd;
+        this.notifyListener = options.notify;
+        this.modelsOf = options.models;
+        this.now = options.now ?? Date.now;
+    }
+    /** 本 runner 的遮蔽参照目录（§4.5）。 */
+    get redactionDirs() {
+        if (!this.redactionDirsValue) {
+            let homeDir = "";
+            try {
+                homeDir = os.homedir();
+            }
+            catch {
+                homeDir = ""; // 拿不到家目录时仍按通用 /Users、/home 前缀与凭据规则清洗
+            }
+            this.redactionDirsValue = { homeDir, configDir: this.storage.directory() };
+        }
+        return this.redactionDirsValue;
+    }
+    /** 只脱敏、不改长度语义（用于本来就不截断的文案）。 */
+    redact(text) {
+        return redactAiTeamErrorText(text, this.redactionDirs);
+    }
+    /** 先脱敏再头尾截断：截断会把中间的敏感串切出来，顺序不能反。 */
+    cleanError(text) {
+        return summarizeError(this.redact(text ?? ""));
+    }
+    // ── 公开操作 ──
+    async start(input) {
+        const team = this.storage.getAiTeam(input.teamId);
+        if (!team)
+            throw new Error("团队不存在。");
+        const task = this.storage.getWandTask(input.taskId);
+        if (!task)
+            throw new Error("任务不存在。");
+        const active = this.storage.listAiTeamRuns({ taskId: task.id, statuses: AI_TEAM_ACTIVE_RUN_STATUSES });
+        if (active.length > 0)
+            throw new AiTeamConflictError("这张任务已经有进行中的团队运行。");
+        const cwd = this.resolveCwd(task);
+        const objective = buildAiTeamObjective(task, input.note);
+        const createdAt = this.iso();
+        const run = {
+            id: `run_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+            teamId: team.id,
+            team,
+            taskId: task.id,
+            objective,
+            cwd,
+            status: "running",
+            statusDetail: "",
+            stepsUsed: 0,
+            stepLimit: team.maxSteps,
+            formatRetries: 0,
+            planApproved: !team.requirePlanApproval,
+            chatSessionId: input.chatSessionId ?? null,
+            pendingNotes: [],
+            createdAt,
+            updatedAt: createdAt,
+        };
+        // 群聊只回显用户刚输入的那句。任务标题已经在会话名里，不要再伪装成用户又说了一次。
+        const shown = input.chatSessionId ? "" : (input.note?.trim() || objective);
+        // 续跑（用户在同一个群聊里接着说话）要在写进新 notice 之前把历史落下，否则会把
+        // 「团队这次接手」这种新行也当成历史写进去。
+        const chatHistory = input.chatSessionId ? this.writeChatHistory(run) : null;
+        this.openChat(run, task, shown, chatHistory);
+        this.storage.saveAiTeamRun(run);
+        if (task.status === "todo")
+            this.storage.updateWandTask(task.id, { status: "doing" });
+        excludeReportDir(cwd);
+        await this.enqueue(run.id, async () => {
+            const step = this.createLeaderStep(run, "制定计划");
+            await this.dispatchStep(run, step, (reportPath, fresh) => (buildLeaderKickoffPrompt(run, reportPath, fresh, chatHistory)));
+        });
+        return this.detail(run.id);
+    }
+    approve(runId, options = {}) {
+        return this.act(runId, async (run) => {
+            this.requireStatus(run, "awaiting_approval", "当前没有待批准的计划。");
+            if (options.echo !== false)
+                this.postUser(run, "批准");
+            run.planApproved = true;
+            this.setStatus(run, "running", "");
+            await this.advance(run);
+        });
+    }
+    reject(runId, feedback, options = {}) {
+        return this.act(runId, async (run) => {
+            this.requireStatus(run, "awaiting_approval", "当前没有待批准的计划。");
+            const text = feedback.trim();
+            if (!text)
+                throw new Error("请写下驳回意见。");
+            if (options.echo !== false)
+                this.postUser(run, text);
+            for (const step of this.storage.listAiTeamSteps(run.id)) {
+                if (step.status === "queued")
+                    this.saveStep({ ...step, status: "skipped", endedAt: this.iso() });
+            }
+            this.setStatus(run, "running", "");
+            await this.startLeaderRound(run, `用户没有批准这个计划，意见：${text}\n请重新安排。`);
+        });
+    }
+    reply(runId, text, options = {}) {
+        return this.act(runId, async (run) => {
+            this.requireStatus(run, "waiting_user", "团队当前没有在等你回复。");
+            const note = text.trim();
+            if (!note)
+                throw new Error("回复不能为空。");
+            if (options.echo !== false)
+                this.postUser(run, note);
+            run.formatRetries = 0;
+            this.refreshTeam(run);
+            this.setStatus(run, "running", "");
+            await this.startLeaderRound(run, note);
+        });
+    }
+    continueRun(runId, extraSteps) {
+        return this.act(runId, async (run) => {
+            this.requireStatus(run, "waiting_user", "团队当前没有在等你。");
+            const extra = Math.min(50, Math.max(5, Math.round(extraSteps) || 10));
+            this.refreshTeam(run);
+            run.stepLimit = Math.max(run.stepLimit, run.stepsUsed) + extra;
+            this.postNotice(run, `步数上限加到 ${run.stepLimit}，继续执行`);
+            this.setStatus(run, "running", "");
+            await this.advance(run);
+        });
+    }
+    completeStep(runId, stepId, report) {
+        return this.act(runId, async (run) => {
+            const step = this.storage.listAiTeamSteps(run.id).find((item) => item.id === stepId);
+            if (!step || step.status !== "running" || step.kind !== "work") {
+                throw new AiTeamConflictError("只能手动完成正在进行的成员步骤。");
+            }
+            await this.finishStep(run, step, { kind: "done", text: report.trim() || "用户手动标记完成", fromFile: false });
+        });
+    }
+    stop(runId) {
+        return this.act(runId, async (run) => {
+            if (!AI_TEAM_ACTIVE_RUN_STATUSES.includes(run.status))
+                throw new AiTeamConflictError("这次运行已经结束。");
+            const endedAt = this.iso();
+            for (const step of this.storage.listAiTeamSteps(run.id)) {
+                if (step.status !== "running" && step.status !== "queued")
+                    continue;
+                if (step.status === "running" && step.sessionId) {
+                    try {
+                        this.ops.stop(step.sessionId);
+                    }
+                    catch (error) {
+                        console.error(`[AiTeam] stop session ${step.sessionId} failed:`, getErrorMessage(error));
+                    }
+                }
+                this.saveStep({ ...step, status: "skipped", endedAt });
+            }
+            this.postNotice(run, "团队已停止。在群里发消息可以让团队接着处理。");
+            this.setStatus(run, "stopped", "已由用户停止");
+        });
+    }
+    /**
+     * 用户在群聊里说的话。等回复时转给负责人；等批准时「批准」类短语直接批准，其余当修改意见；
+     * 成员干活时先记下，负责人下一轮一起看到；运行已结束则接着开一轮新的。
+     */
+    async chatInput(sessionId, text) {
+        const run = this.storage.getLatestAiTeamRunByChat(sessionId);
+        if (!run)
+            throw new Error("找不到这个群聊对应的团队运行。");
+        const note = text.trim();
+        if (STOP_REPLY.test(note) && AI_TEAM_ACTIVE_RUN_STATUSES.includes(run.status)) {
+            await this.stop(run.id);
+            return;
+        }
+        switch (run.status) {
+            case "awaiting_approval":
+                if (APPROVE_REPLY.test(note))
+                    await this.approve(run.id, { echo: false });
+                else
+                    await this.reject(run.id, note, { echo: false });
+                return;
+            case "waiting_user":
+                await this.reply(run.id, note, { echo: false });
+                return;
+            case "running":
+                await this.act(run.id, async (current) => {
+                    if (current.status !== "running")
+                        throw new AiTeamConflictError("团队状态刚变了，请再发一次。");
+                    current.pendingNotes = [...current.pendingNotes, note];
+                    this.postNotice(current, "已记下，负责人安排下一步时会看到。回复「停止」可以叫停团队。");
+                    this.saveRun(current);
+                });
+                return;
+            default: {
+                const team = this.storage.getAiTeam(run.teamId);
+                if (!team)
+                    throw new Error("团队已被删除，没法接着处理。");
+                await this.start({ teamId: team.id, taskId: run.taskId, note, chatSessionId: sessionId });
+            }
+        }
+    }
+    detail(runId) {
+        const run = this.storage.getAiTeamRun(runId);
+        if (!run)
+            throw new Error("团队运行不存在。");
+        const steps = this.storage.listAiTeamSteps(run.id);
+        const memberStates = {};
+        for (const step of steps) {
+            if (step.status !== "running" || !step.sessionId)
+                continue;
+            const snapshot = this.ops.snapshot(step.sessionId);
+            if (snapshot)
+                memberStates[step.sessionId] = activityState(snapshot);
+        }
+        // 群聊回合只给最近这一段（§4.4）；没有群聊会话的旧运行给空数组，前端不用判 null。
+        const messages = run.chatSessionId ? this.ops.snapshot(run.chatSessionId)?.messages ?? [] : [];
+        return {
+            run,
+            steps,
+            memberStates,
+            chatTurns: messages.slice(-AI_TEAM_DETAIL_CHAT_TURNS),
+        };
+    }
+    listForTask(taskId) {
+        return this.storage.listAiTeamRuns({ taskId });
+    }
+    /** 团队页的运行记录；teamId 为空时列出所有团队（侧边栏计数用）。 */
+    listRuns(filter) {
+        const runs = this.storage.listAiTeamRuns({
+            teamId: filter.teamId,
+            statuses: filter.activeOnly ? AI_TEAM_ACTIVE_RUN_STATUSES : undefined,
+            limit: filter.limit,
+        });
+        return runs.map((run) => {
+            const task = this.storage.getWandTask(run.taskId);
+            return { ...run, taskTitle: task?.title ?? "（任务已删除）", taskIdentifier: task?.identifier ?? "" };
+        });
+    }
+    // ── 事件驱动 ──
+    /** 与 missions.ingest 并列调用。绝大多数事件与团队无关，必须廉价返回。 */
+    ingest(event) {
+        if (!event.sessionId || event.sessionId === "__system__")
+            return;
+        if (event.type !== "status" && event.type !== "ended" && event.type !== "task" && event.type !== "output")
+            return;
+        const step = this.storage.getRunningAiTeamStepBySession(event.sessionId);
+        if (!step)
+            return;
+        if (event.type === "output") {
+            if (this.outputTimers.has(event.sessionId))
+                return;
+            const timer = setTimeout(() => {
+                this.outputTimers.delete(event.sessionId);
+                void this.enqueue(step.runId, () => this.evaluate(step.runId));
+            }, OUTPUT_DEBOUNCE_MS);
+            timer.unref?.();
+            this.outputTimers.set(event.sessionId, timer);
+            return;
+        }
+        void this.enqueue(step.runId, () => this.evaluate(step.runId));
+    }
+    /** 服务启动时调用：把重启前未结束的运行接回来，并开始兜底巡检。 */
+    reconcile() {
+        for (const run of this.storage.listAiTeamRuns({ statuses: ["running"] })) {
+            void this.enqueue(run.id, async () => {
+                const current = this.storage.getAiTeamRun(run.id);
+                if (!current || current.status !== "running")
+                    return;
+                const running = this.storage.listAiTeamSteps(current.id).filter((step) => step.status === "running");
+                for (const step of running) {
+                    if (step.sessionId && this.ops.snapshot(step.sessionId))
+                        continue;
+                    await this.finishStep(current, step, { kind: "failed", text: "服务重启后会话丢失" }, false);
+                }
+                await this.evaluate(current.id);
+                const latest = this.storage.getAiTeamRun(current.id);
+                if (latest?.status === "running")
+                    await this.advance(latest);
+            });
+        }
+        this.startSweep();
+    }
+    /** 兜底巡检：PTY 成员写完报告后可能不再产生事件。 */
+    startSweep() {
+        if (this.sweepTimer)
+            return;
+        this.sweepTimer = setInterval(() => {
+            for (const run of this.storage.listAiTeamRuns({ statuses: ["running"] })) {
+                void this.enqueue(run.id, () => this.evaluate(run.id));
+            }
+        }, SWEEP_INTERVAL_MS);
+        this.sweepTimer.unref?.();
+    }
+    dispose() {
+        if (this.sweepTimer)
+            clearInterval(this.sweepTimer);
+        this.sweepTimer = null;
+        for (const timer of this.outputTimers.values())
+            clearTimeout(timer);
+        for (const timer of this.recheckTimers.values())
+            clearTimeout(timer);
+        this.outputTimers.clear();
+        this.recheckTimers.clear();
+        this.noDegrade.clear();
+    }
+    /** 等当前排队的所有操作跑完（测试用）。 */
+    async idle() {
+        while (this.chains.size > 0) {
+            await Promise.all([...this.chains.values()]);
+        }
+    }
+    // ── 内部：串行化 ──
+    enqueue(runId, task) {
+        const previous = this.chains.get(runId) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(task);
+        const tracked = next.catch((error) => {
+            if (!(error instanceof AiTeamConflictError)) {
+                console.error(`[AiTeam] run ${runId}:`, getErrorMessage(error));
+            }
+        });
+        this.chains.set(runId, tracked);
+        void tracked.then(() => {
+            if (this.chains.get(runId) === tracked)
+                this.chains.delete(runId);
+        });
+        return next;
+    }
+    async act(runId, action) {
+        await this.enqueue(runId, async () => {
+            const run = this.storage.getAiTeamRun(runId);
+            if (!run)
+                throw new Error("团队运行不存在。");
+            await action(run);
+        });
+        return this.detail(runId);
+    }
+    requireStatus(run, status, message) {
+        if (run.status !== status)
+            throw new AiTeamConflictError(message);
+    }
+    // ── 内部：推进 ──
+    async evaluate(runId) {
+        const run = this.storage.getAiTeamRun(runId);
+        if (!run || run.status !== "running")
+            return;
+        const running = this.storage.listAiTeamSteps(run.id).filter((item) => item.status === "running");
+        let finished = false;
+        for (const step of running) {
+            const outcome = this.stepOutcome(run, step);
+            if (outcome.kind === "pending") {
+                if (outcome.recheckInMs !== undefined)
+                    this.scheduleRecheck(run.id, outcome.recheckInMs);
+                continue;
+            }
+            // 并行成员可能同时交差：先全部记下，最后统一推进一次。
+            await this.finishStep(run, step, outcome, false);
+            finished = true;
+            if (run.status !== "running")
+                return;
+        }
+        if (finished)
+            await this.advance(run);
+    }
+    scheduleRecheck(runId, delayMs) {
+        if (this.recheckTimers.has(runId))
+            return;
+        const timer = setTimeout(() => {
+            this.recheckTimers.delete(runId);
+            void this.enqueue(runId, () => this.evaluate(runId));
+        }, delayMs);
+        timer.unref?.();
+        this.recheckTimers.set(runId, timer);
+    }
+    stepOutcome(run, step) {
+        if (!step.sessionId)
+            return { kind: "pending" };
+        const snapshot = this.ops.snapshot(step.sessionId);
+        if (!snapshot)
+            return { kind: "failed", text: "会话不存在" };
+        const state = activityState(snapshot);
+        const gone = isSessionGone(snapshot);
+        const busy = !gone && (state === "needs_permission"
+            || state === "needs_input"
+            || snapshot.structuredState?.inFlight === true
+            || (snapshot.queuedMessages?.length ?? 0) > 0
+            || snapshot.ptyBusy === true);
+        const reportFile = path.join(run.cwd, step.reportPath);
+        if (existsSync(reportFile)) {
+            const age = this.now() - statSync(reportFile).mtimeMs;
+            if (!gone && age < REPORT_SETTLE_MS)
+                return { kind: "pending", recheckInMs: REPORT_SETTLE_MS - age + 100 };
+            // 结构化会话还在说话时先等它结束：文件可能还会被改写。
+            if (!busy || this.ops.ownerOf(step.sessionId) === "pty") {
+                return { kind: "done", text: readReport(reportFile), fromFile: true };
+            }
+            return { kind: "pending" };
+        }
+        if (busy)
+            return { kind: "pending" };
+        const reply = snapshot.messages?.length ? assistantReplyAfterPrompt(snapshot, step.reportPath) : null;
+        if (gone) {
+            // 出错退出时最后一条回复往往就是错误本身（如 API 503），不能当成报告或决定。
+            if (reply && snapshot.status !== "failed")
+                return { kind: "done", text: reply, fromFile: false };
+            return {
+                kind: "failed",
+                text: this.cleanError(snapshot.structuredState?.lastError) || "会话已结束，未交付报告",
+                sessionError: snapshot.status === "failed",
+            };
+        }
+        if (this.ops.ownerOf(step.sessionId) === "structured" && reply !== null) {
+            return { kind: "done", text: reply, fromFile: false };
+        }
+        return { kind: "pending" };
+    }
+    /** proceed=false 时只记结果不推进，由调用方在记完一批之后统一 advance。 */
+    async finishStep(run, step, outcome, proceed = true) {
+        const endedAt = this.iso();
+        // §3.4 触发点 2（异步主通道）：必须在 stepsUsed 递增之前判，否则首个失败候选白扣一步预算。
+        if (step.kind === "work" && outcome.kind === "failed" && outcome.sessionError
+            && !this.noDegrade.has(step.id)) {
+            const failure = this.asyncStartupFailure(run, step, outcome.text);
+            if (failure) {
+                await this.degradeWorkStep(run, step, failure, proceed);
+                return;
+            }
+        }
+        run.stepsUsed += 1;
+        if (step.kind === "work") {
+            const report = outcome.text.trim() || (outcome.kind === "done" ? "（成员没有写报告）" : "失败");
+            this.saveStep({ ...step, status: outcome.kind === "done" ? "done" : "failed", report, endedAt });
+            const member = this.member(run.team, step.memberId);
+            if (member) {
+                this.postTurn(run, {
+                    role: "assistant",
+                    author: chatAuthor(member, step.sessionId, this.actualAgent(member, step)?.provider),
+                    content: chatText(`${outcome.kind === "done" ? "✅ 完成" : "❌ 没完成"}「${step.title}」\n\n${report}`),
+                });
+            }
+            this.saveRun(run);
+            if (proceed)
+                await this.advance(run);
+            return;
+        }
+        // 负责人的模型报错时停下来等用户（换模型或稍后回复即可接着来），不当成格式错误空转重试。
+        const leader = leaderOf(run.team);
+        if (outcome.kind === "failed" && outcome.sessionError) {
+            this.saveStep({ ...step, status: "failed", report: outcome.text, endedAt });
+            this.postTurn(run, {
+                role: "assistant", notice: true, author: chatAuthor(leader, step.sessionId),
+                content: chatText(`负责人的模型出错：${outcome.text}\n可以去团队页换个模型，然后在群里回复一句让团队继续。`),
+            });
+            this.setStatus(run, "waiting_user", `负责人出错：${outcome.text}`);
+            return;
+        }
+        // 会话丢失和回复格式错误走同一条有限重试：会话没了就新开一个并补上团队背景。
+        const parsed = outcome.kind === "failed"
+            ? { ok: false, error: `负责人会话没有交付决定（${outcome.text}）。` }
+            : parseLeaderDecision(outcome.text, run.team);
+        if (!parsed.ok) {
+            this.saveStep({ ...step, status: "failed", report: parsed.error, endedAt });
+            if (run.formatRetries >= MAX_FORMAT_RETRIES) {
+                this.postNotice(run, `负责人连续几次回复都没按约定格式，团队先停下。在群里回复一句让他重新安排。`, step.sessionId);
+                this.setStatus(run, "waiting_user", outcome.kind === "failed" ? parsed.error : "Leader 回复格式多次不正确");
+                return;
+            }
+            run.formatRetries += 1;
+            this.postNotice(run, `负责人的回复没能读懂，让他重答（${run.formatRetries}/${MAX_FORMAT_RETRIES}）`, step.sessionId);
+            this.saveRun(run);
+            const retry = this.createLeaderStep(run, "重新回复");
+            await this.dispatchStep(run, retry, (reportPath, fresh) => (buildLeaderFormatRetryPrompt(run, parsed.error, reportPath, fresh, this.chatHistoryFor(run))));
+            return;
+        }
+        run.formatRetries = 0;
+        const decision = parsed.decision;
+        this.saveStep({ ...step, status: "done", report: decision.message, endedAt });
+        this.postLeaderDecision(run, step, decision);
+        if (decision.action === "ask") {
+            this.setStatus(run, "waiting_user", decision.message);
+            return;
+        }
+        if (decision.action === "finish") {
+            this.setStatus(run, "done", decision.message);
+            return;
+        }
+        let seq = this.nextSeq(run.id);
+        const ids = decision.steps.map(() => randomUUID());
+        for (const [index, assigned] of decision.steps.entries()) {
+            this.saveStep({
+                id: ids[index],
+                runId: run.id,
+                seq,
+                kind: "work",
+                memberId: assigned.memberId,
+                title: assigned.title,
+                instructions: assigned.instructions,
+                sessionId: null,
+                status: "queued",
+                report: "",
+                reportPath: aiTeamReportPath(run.id, seq, "work", assigned.memberId),
+                dependsOn: assigned.after.map((position) => ids[position]),
+                startedAt: null,
+                endedAt: null,
+            });
+            seq += 1;
+        }
+        if (!run.planApproved) {
+            this.setStatus(run, "awaiting_approval", decision.message);
+            return;
+        }
+        this.saveRun(run);
+        await this.advance(run);
+    }
+    /**
+     * 派出所有已就绪的成员步骤：依赖都已完成、且该成员手上没有活。不同成员并行，同一成员串行。
+     * 有成员失败、队列清空或依赖再也满足不了时，等在跑的都结束后交回 Leader。
+     */
+    async advance(run) {
+        if (run.status !== "running")
+            return;
+        const steps = this.storage.listAiTeamSteps(run.id);
+        const running = steps.filter((step) => step.status === "running");
+        if (running.some((step) => step.kind === "leader"))
+            return;
+        const lastLeaderSeq = Math.max(0, ...steps.filter((step) => step.kind === "leader" && step.status !== "queued").map((step) => step.seq));
+        const failedSinceLeader = steps.some((step) => step.kind === "work" && step.seq > lastLeaderSeq && step.status === "failed");
+        const queued = steps.filter((step) => step.status === "queued");
+        if (queued.some((step) => step.kind === "leader")) {
+            // 重启时可能留下一个还没发出的 Leader 步骤：直接重开一轮。
+            if (running.length === 0)
+                await this.startLeaderRound(run);
+            return;
+        }
+        if (!failedSinceLeader) {
+            const byId = new Map(steps.map((step) => [step.id, step]));
+            const busyMembers = new Set(running.map((step) => step.memberId));
+            let inFlight = running.length;
+            for (const next of queued) {
+                if (busyMembers.has(next.memberId))
+                    continue;
+                if (!next.dependsOn.every((id) => byId.get(id)?.status === "done"))
+                    continue;
+                if (run.stepsUsed + inFlight >= run.stepLimit)
+                    break;
+                const member = this.member(run.team, next.memberId);
+                busyMembers.add(next.memberId);
+                inFlight += 1;
+                if (!member) {
+                    await this.finishStep(run, next, { kind: "failed", text: "成员不存在" }, false);
+                    continue;
+                }
+                await this.dispatchStep(run, next, (_reportPath, fresh) => (buildMemberPrompt(run, next, member, fresh, this.memberUpstream(run, next), this.chatHistoryFor(run))), false);
+            }
+        }
+        // 还有人在干活就等；否则（队列清空、有人失败、依赖落空或步数用完）交回 Leader，
+        // 步数用完时 startLeaderRound 会停下来等用户。
+        if (this.storage.listAiTeamSteps(run.id).some((step) => step.status === "running"))
+            return;
+        await this.startLeaderRound(run);
+    }
+    /** 开一轮 Leader：把上一轮 Leader 之后结束的成员报告交给他。 */
+    async startLeaderRound(run, userNote) {
+        if (!this.hasBudget(run))
+            return;
+        // 成员干活时用户在群里说的话，这一轮一起交给负责人。
+        if (run.pendingNotes.length > 0) {
+            userNote = [...run.pendingNotes, userNote ?? ""].filter(Boolean).join("\n\n");
+            run.pendingNotes = [];
+            this.saveRun(run);
+        }
+        const steps = this.storage.listAiTeamSteps(run.id);
+        // Leader 重新安排时，之前排队的步骤作废。
+        const endedAt = this.iso();
+        for (const step of steps) {
+            if (step.status === "queued")
+                this.saveStep({ ...step, status: "skipped", endedAt });
+        }
+        const lastLeaderSeq = Math.max(0, ...steps.filter((step) => step.kind === "leader" && step.status === "done").map((step) => step.seq));
+        const finished = steps
+            .filter((step) => step.kind === "work" && step.seq > lastLeaderSeq && (step.status === "done" || step.status === "failed"))
+            .map((step) => ({ step, memberName: this.member(run.team, step.memberId)?.name ?? step.memberId }));
+        const step = this.createLeaderStep(run, userNote ? "回应用户" : "安排下一步");
+        const handoffPath = this.writeHandoff(run, step.seq, "leader", finished.map(({ step: item, memberName }) => this.handoffEntry(run, item, memberName)));
+        await this.dispatchStep(run, step, (reportPath, fresh) => (buildLeaderFollowupPrompt(run, finished, reportPath, userNote, fresh, handoffPath, this.chatHistoryFor(run))));
+    }
+    /** 一条交接条目：元信息 + 报告全文（全文只进交接文件，不进提示词）。 */
+    handoffEntry(run, step, memberName) {
+        return {
+            seq: step.seq,
+            title: step.title,
+            memberName: memberName ?? this.member(run.team, step.memberId)?.name ?? step.memberId,
+            status: step.status,
+            reportPath: step.reportPath,
+            report: step.report,
+        };
+    }
+    /**
+     * 成员步骤的上游交接：把依赖步骤的报告写成一个交接文件，提示词只给路径。
+     * 没有依赖、或写文件失败时返回 null（提示词仍逐行列出上游报告文件）。
+     */
+    memberUpstream(run, step) {
+        if (step.dependsOn.length === 0)
+            return null;
+        const byId = new Map(this.storage.listAiTeamSteps(run.id).map((item) => [item.id, item]));
+        const deps = step.dependsOn
+            .map((id) => byId.get(id))
+            .filter((item) => Boolean(item));
+        if (deps.length === 0)
+            return null;
+        const entries = deps.map((item) => this.handoffEntry(run, item));
+        const handoffPath = this.writeHandoff(run, step.seq, "work", entries);
+        if (!handoffPath)
+            return null;
+        return {
+            handoffPath,
+            steps: entries.map(({ seq, title, memberName, status, reportPath }) => ({ seq, title, memberName, status, reportPath })),
+        };
+    }
+    /**
+     * 同一个群聊里接着开新运行时的续跑交接（§4.4 同一套文件交接）：把之前几轮的步骤摘要
+     * 与群聊原文写进 `.wand-team/<runId>/chat-history.md`，提示词只给路径。
+     * 不是续跑（没有群聊会话、之前没有运行、群聊也还是空的）返回 null，提示词就不带这一段。
+     */
+    writeChatHistory(run) {
+        const chatSessionId = run.chatSessionId;
+        if (!chatSessionId)
+            return null;
+        // 库按 created_at DESC 返回，换回时间正序，读的人看到的是「先做了什么、后做了什么」。
+        const previous = this.storage.listAiTeamRuns({ taskId: run.taskId })
+            .filter((item) => item.id !== run.id && item.chatSessionId === chatSessionId)
+            .reverse();
+        const turns = this.ops.snapshot(chatSessionId)?.messages ?? [];
+        if (previous.length === 0 && turns.length === 0)
+            return null;
+        const runs = previous.map((item) => ({
+            status: item.status,
+            steps: this.storage.listAiTeamSteps(item.id).map((step) => ({
+                seq: step.seq,
+                memberName: this.member(run.team, step.memberId)?.name ?? step.memberId,
+                title: step.title,
+                status: step.status,
+            })),
+        }));
+        const relative = aiTeamChatHistoryPath(run.id);
+        try {
+            const file = path.join(run.cwd, relative);
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, renderChatHistoryFile({ runs, turns, generatedAt: this.iso() }), "utf8");
+            return relative;
+        }
+        catch (error) {
+            console.error(`[AiTeam] write chat history ${relative} failed:`, getErrorMessage(error));
+            return null;
+        }
+    }
+    /**
+     * 这次运行要接着的群聊上下文文件；文件不在（不是续跑、或写失败）就给 null。
+     * 续跑标记就落在文件本身，所以服务重启后同一路径依旧成立，不用额外存一列。
+     */
+    chatHistoryFor(run) {
+        const relative = aiTeamChatHistoryPath(run.id);
+        return existsSync(path.join(run.cwd, relative)) ? relative : null;
+    }
+    /** 交接文件写到报告目录；失败只记日志，不阻断派发。 */
+    writeHandoff(run, seq, kind, entries) {
+        if (entries.length === 0)
+            return null;
+        const relative = aiTeamHandoffPath(run.id, seq, kind);
+        try {
+            const file = path.join(run.cwd, relative);
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, renderHandoffFile(entries, this.iso()), "utf8");
+            return relative;
+        }
+        catch (error) {
+            console.error(`[AiTeam] write handoff ${relative} failed:`, getErrorMessage(error));
+            return null;
+        }
+    }
+    hasBudget(run) {
+        if (run.stepsUsed < run.stepLimit)
+            return true;
+        this.postNotice(run, `已用完 ${run.stepLimit} 步的上限，团队先停下。回复一句让团队继续，或在任务面板里加步数。`);
+        this.setStatus(run, "waiting_user", "已达到步数上限");
+        return false;
+    }
+    createLeaderStep(run, title) {
+        const seq = this.nextSeq(run.id);
+        const leader = leaderOf(run.team);
+        const step = {
+            id: randomUUID(),
+            runId: run.id,
+            seq,
+            kind: "leader",
+            memberId: leader.id,
+            title,
+            instructions: "",
+            sessionId: null,
+            status: "queued",
+            report: "",
+            reportPath: aiTeamReportPath(run.id, seq, "leader", leader.id),
+            dependsOn: [],
+            startedAt: null,
+            endedAt: null,
+        };
+        this.saveStep(step);
+        return step;
+    }
+    /**
+     * 派出一个步骤：先把步骤标成 running 再发送；同一成员的活会话复用（上下文延续）。
+     * 提示词分两段：`system`（角色与规则）只在新建会话时交给系统提示通道，`message` 是本轮用户消息。
+     */
+    async dispatchStep(run, step, buildPrompt, proceed = true) {
+        const member = this.member(run.team, step.memberId);
+        const candidates = member ? memberAgents(member) : [];
+        const info = this.infoOf(step);
+        const agent = candidates[info.usedCandidate];
+        // §3.4 触发点 1 的事前分支：当前候选已被拉黑、候选列表被改到没有这一档，或快照就绪且模型
+        // 明确不在清单里。三者都走 degradeWorkStep 留痕，不在这里静默换候选。
+        if (member && step.kind === "work") {
+            const blocked = agent
+                ? this.blockedCandidate(run.id, agent)
+                : { kind: "runtime-failure", reason: `候选列表已变更，没有候选 ${info.usedCandidate + 1}` };
+            const unknown = blocked === null && agent.kind === "structured"
+                && isModelUnknownBeforeDispatch(agent, this.modelsOf?.(agent.provider))
+                ? { kind: "model-unknown", reason: `模型 ${agent.model} 不在 ${agent.provider} 已发现的模型清单里` }
+                : null;
+            const pre = blocked ?? unknown;
+            if (pre) {
+                await this.degradeWorkStep(run, step, pre, proceed);
+                return;
+            }
+        }
+        const reusable = member ? this.liveSessionFor(run, member, step.id, agent) : null;
+        const prompt = buildPrompt(step.reportPath, reusable === null);
+        const startedAt = this.iso();
+        let running = { ...step, instructions: step.kind === "leader" ? prompt.message : step.instructions, status: "running", startedAt, sessionId: reusable };
+        this.saveStep(running);
+        this.notify(run);
+        if (member && step.kind === "work") {
+            this.postNotice(run, `${member.name} 开始「${step.title}」`, reusable, member, agent?.provider);
+        }
+        try {
+            if (!member)
+                throw new Error("成员不存在");
+            if (!agent)
+                throw new Error("成员没有配置可用的 CLI 候选");
+            if (reusable) {
+                await this.ops.send(reusable, prompt.message);
+            }
+            else {
+                const task = this.storage.getWandTask(run.taskId);
+                if (!task)
+                    throw new Error("任务卡已被删除");
+                const sessionId = await this.ops.open({
+                    task,
+                    agent,
+                    prompt: prompt.message,
+                    automationId: `ai-team:${run.id}`,
+                    systemPrompt: prompt.system,
+                });
+                running = { ...running, sessionId };
+                this.saveStep(running);
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            const kind = classifyCandidateFailure(message);
+            if (agent && kind === "host-disabled") {
+                // 进程级信号（agent-dispatch 的「当前服务未启用 … 会话」）：本次运行该 kind 的候选全部不再
+                // 尝试，也不能当成「不可降级」直接吞掉——记进黑名单后交给既有失败出口。
+                this.disableHostKind(run.id, agent.kind);
+            }
+            else if (agent && step.kind === "work" && kind === "spawn-missing"
+                && !existsSync(path.join(run.cwd, step.reportPath)) && !this.noDegrade.has(step.id)) {
+                // §3.4 触发点 1：会话根本没起来，ENOENT 对 structured / pty 同样可靠（修正 B4 排除的是
+                // PTY 的异步分类）。传 `running` 而不是入参 `step`：复用会话时 sessionId 只在 running 上。
+                // 候选边界与黑名单由 degradeWorkStep 自己判，耗尽时它走 failed 出口。
+                await this.degradeWorkStep(run, running, { kind, reason: message }, proceed);
+                return;
+            }
+            await this.finishStep(run, running, { kind: "failed", text: `派发失败：${this.redact(message)}` }, proceed);
+        }
+    }
+    /**
+     * 换候选 = 开新步（§3.4 五步），与 Leader 的格式重试同构。全程在调用方的 enqueue 链里；
+     * 只直接派出 A′，**不整轮 advance**（N1：advance 的 queued/byId/busyMembers 是进循环时的快照，
+     * 整轮调整会在同一栈里对同一步二次派发）。`proceed` 原样透传给 A′ 的 dispatchStep。
+     */
+    async degradeWorkStep(run, step, failure, proceed) {
+        const info = this.infoOf(step);
+        const member = this.member(run.team, step.memberId);
+        const candidates = member ? memberAgents(member) : [];
+        const agent = candidates[info.usedCandidate];
+        // 三条流（群聊 notice / 旧步 report / dispatch_info_json.skipped[].reason）共用这一个出口，
+        // 先脱敏再截断：CLI 原文常带 /Users/<user>/… 与 token=…，落库前必须收掉（§4.5）。
+        const reason = this.cleanError(failure.reason) || failure.kind;
+        const skipped = [
+            ...info.skipped,
+            ...(agent ? [{ candidate: info.usedCandidate, agent, reason, errorKind: failure.kind }] : []),
+        ];
+        const next = info.usedCandidate + 1;
+        const tail = candidates.slice(next);
+        // 级联深度天然以候选上限（4）为界：每降一级 usedCandidate +1。耗尽时退回既有 failed 出口，
+        // 交回 Leader 决定 ask/finish，不另设 waiting_user 捷径、不循环。
+        if (!member || !agent || tail.length === 0 || tail.every((item) => this.blockedCandidate(run.id, item))) {
+            const detail = skipped.map((item) => `候选 ${item.candidate + 1}（${item.reason}）`).join("、");
+            this.noDegrade.add(step.id);
+            try {
+                await this.finishStep(run, step, {
+                    kind: "failed",
+                    sessionError: true,
+                    text: `${member?.name ?? "该成员"}的所有候选均不可用：${detail || reason}`,
+                }, proceed);
+            }
+            finally {
+                this.noDegrade.delete(step.id);
+            }
+            return;
+        }
+        // ① 安全阀：判错也不能让两个 CLI 同时写同一个工作目录。
+        if (step.sessionId) {
+            const previous = this.ops.snapshot(step.sessionId);
+            if (previous && !isSessionGone(previous)) {
+                try {
+                    this.ops.stop(step.sessionId);
+                }
+                catch (error) {
+                    // stop 抛错不做兜底会让旧步卡在 running，这里只记日志继续记账。
+                    console.error(`[AiTeam] stop degraded session ${step.sessionId} failed:`, getErrorMessage(error));
+                }
+            }
+        }
+        // ② 旧步只留痕：skipped 不占 stepsUsed（走 finishStep 会记 failed 并扣预算）。
+        //    跳过链随这一步一起落 dispatch_info_json，重启后恢复链不会从候选 1 重来。
+        this.saveStep({
+            ...step,
+            status: "skipped",
+            report: `候选 ${info.usedCandidate + 1} 不可用：${reason}`,
+            endedAt: this.iso(),
+            dispatchInfo: { ...info, skipped },
+        });
+        // ③ 新步：同成员、同标题、同指令，继承 dependsOn；新 seq → reportPath 天然不同，
+        //    不会撞上上一候选留在原地的半截报告文件。
+        const seq = this.nextSeq(run.id);
+        const replacement = {
+            id: randomUUID(),
+            runId: run.id,
+            seq,
+            kind: "work",
+            memberId: step.memberId,
+            title: step.title,
+            instructions: step.instructions,
+            sessionId: null,
+            status: "queued",
+            report: "",
+            reportPath: aiTeamReportPath(run.id, seq, "work", step.memberId),
+            dependsOn: step.dependsOn,
+            startedAt: null,
+            endedAt: null,
+            dispatchInfo: { usedCandidate: next, skipped },
+        };
+        this.saveStep(replacement);
+        // 群聊降级行（§5.3/B15）：一次降级一行，署名用切过去的新候选；事前 model-unknown 跳过
+        // 同样走 degradeWorkStep，所以这里也覆盖它。reason 已经过脱敏 + 头尾截断（§4.5）。
+        this.postNotice(run, `⚠️ ${member.name} 的首选配置不可用（${reason}），已切换到候选 ${next + 1}`, null, member, candidates[next]?.provider);
+        // ④ 依赖重指向（R1）：排队步骤等的仍是「这件事做完」，只是换了承载候选的步骤。
+        //    running / done 的历史步骤不改写。
+        for (const queued of this.storage.listAiTeamSteps(run.id)) {
+            if (queued.status !== "queued" || !queued.dependsOn.includes(step.id))
+                continue;
+            this.saveStep({
+                ...queued,
+                dependsOn: queued.dependsOn.map((id) => (id === step.id ? replacement.id : id)),
+            });
+        }
+        // ⑤ 黑名单记账（立即写 run_state_json），然后只直接派 A′。
+        this.accountCandidateFailure(run.id, agent, failure.kind);
+        await this.dispatchStep(run, replacement, (reportPath, fresh) => {
+            const target = this.member(run.team, replacement.memberId) ?? member;
+            return buildMemberPrompt(run, replacement, target, fresh, this.memberUpstream(run, replacement), this.chatHistoryFor(run));
+        }, proceed);
+    }
+    /**
+     * 会话「起来又倒下」的启动期归因（§3.4 触发点 2）。判定核在 ai-team-availability，
+     * 这里只负责喂时钟、快照与报告产出；不满足降级条件返回 null，按既有路径记 failed。
+     */
+    asyncStartupFailure(run, step, outcomeText) {
+        const member = this.member(run.team, step.memberId);
+        if (!member)
+            return null;
+        const info = this.infoOf(step);
+        const candidates = memberAgents(member);
+        const agent = candidates[info.usedCandidate];
+        if (!agent)
+            return null;
+        const snapshot = step.sessionId ? this.ops.snapshot(step.sessionId) : null;
+        // 启动时刻未知时按窗口外处理：宁可交回 Leader，不猜它是启动失败。
+        const startedAt = step.startedAt ? Date.parse(step.startedAt) : Number.NaN;
+        const elapsedMs = Number.isFinite(startedAt) ? Math.max(0, this.now() - startedAt) : AI_TEAM_STARTUP_WINDOW_MS;
+        const errorMessage = snapshot?.structuredState?.lastError ?? outcomeText;
+        const kind = classifyStartupFailure({
+            status: snapshot?.status ?? "failed",
+            hasAssistantReply: Boolean(snapshot?.messages?.some((turn) => turn.role === "assistant")),
+            elapsedMs,
+            errorMessage,
+        });
+        if (!isDegradableWorkFailure({
+            stepKind: step.kind,
+            agentKind: agent.kind,
+            sessionError: true,
+            hasReportOutput: existsSync(path.join(run.cwd, step.reportPath)),
+            failure: kind,
+            usedCandidate: info.usedCandidate,
+            candidateCount: candidates.length,
+            nextCandidateBlocked: this.blockedCandidate(run.id, candidates[info.usedCandidate + 1]) !== null,
+        }))
+            return null;
+        return { kind, reason: errorMessage };
+    }
+    /** run 级黑名单里这一层是谁封的、为什么封（§3.4 修正 B12 两层键值 + host-disabled 进程级）。 */
+    blockedCandidate(runId, agent) {
+        if (!agent)
+            return null;
+        const state = this.stateOf(runId);
+        if (state.hostDisabled.includes(agent.kind)) {
+            return {
+                kind: "host-disabled",
+                reason: `本服务未启用${agent.kind === "pty" ? "终端" : "结构化"}会话，候选 ${agent.provider} 不再尝试`,
+            };
+        }
+        if (state.providers.includes(agent.provider)) {
+            return { kind: "spawn-missing", reason: `${agent.provider} CLI 不可用` };
+        }
+        const blocked = state.agents.find((item) => item.key === agentKey(agent));
+        if (blocked)
+            return { kind: blocked.kind, reason: `${agent.provider}/${agent.model} 已被标记不可用` };
+        return null;
+    }
+    /** 黑名单从库里读（§3.4）：run 不存在或列里是脏值时退化成空黑名单。 */
+    stateOf(runId) {
+        return this.storage.getAiTeamRunState(runId);
+    }
+    /** 每次黑名单变更立即落库，重启后已拉黑的候选与 strikes 计数都还在。 */
+    saveState(runId, state) {
+        this.storage.setAiTeamRunState(runId, state);
+    }
+    /** host-disabled 是进程级信号：本次运行该 kind 的候选全部不再尝试。 */
+    disableHostKind(runId, kind) {
+        const state = this.stateOf(runId);
+        if (state.hostDisabled.includes(kind))
+            return;
+        this.saveState(runId, { ...state, hostDisabled: [...state.hostDisabled, kind] });
+    }
+    /**
+     * 失败候选的黑名单记账（§3.4）：spawn-missing 封 provider、model-unknown 直接封五元组、
+     * startup-timeout 累计到 STARTUP_TIMEOUT_STRIKES 才封。runtime-failure 这类不计入，
+     * 一次写完一次落库。
+     */
+    accountCandidateFailure(runId, agent, kind) {
+        const state = this.stateOf(runId);
+        const key = agentKey(agent);
+        if (kind === "spawn-missing") {
+            if (state.providers.includes(agent.provider))
+                return;
+            this.saveState(runId, { ...state, providers: [...state.providers, agent.provider] });
+            return;
+        }
+        if (kind === "model-unknown") {
+            if (state.agents.some((item) => item.key === key))
+                return;
+            this.saveState(runId, { ...state, agents: [...state.agents, { key, kind }] });
+            return;
+        }
+        if (kind !== "startup-timeout")
+            return;
+        const strikes = Math.min(999, (state.strikes[key] ?? 0) + 1);
+        const agents = strikes >= STARTUP_TIMEOUT_STRIKES && !state.agents.some((item) => item.key === key)
+            ? [...state.agents, { key, kind: "startup-timeout" }]
+            : state.agents;
+        this.saveState(runId, { ...state, strikes: { ...state.strikes, [key]: strikes }, agents });
+    }
+    /**
+     * 本步实际用的候选与累计跳过的候选（`dispatch_info_json`）；没有记录 = 首选、没跳过过任何候选。
+     * 读的是步骤行自己，重启后同一条恢复链继续从库里接着走。
+     */
+    infoOf(step) {
+        return step.dispatchInfo ?? { usedCandidate: 0, skipped: [] };
+    }
+    /** 该步实际使用的候选（§3.6 署名口径）：候选一律经 memberAgents 读，越界回退首选。 */
+    actualAgent(member, step) {
+        const candidates = memberAgents(member);
+        return candidates[this.infoOf(step).usedCandidate] ?? candidates[0] ?? null;
+    }
+    /**
+     * 运行停下来等用户时，用户可能刚在团队页换了成员的 CLI / 模型（比如额度用尽换一个）。
+     * 接着跑之前换成最新配置；成员被删了或没有负责人时保留原快照。
+     */
+    refreshTeam(run) {
+        const latest = this.storage.getAiTeam(run.teamId);
+        if (!latest || !latest.members.some((member) => member.isLeader))
+            return;
+        const used = new Set(this.storage.listAiTeamSteps(run.id).map((step) => step.memberId));
+        if ([...used].some((id) => !latest.members.some((member) => member.id === id)))
+            return;
+        run.team = latest;
+    }
+    /**
+     * 同一成员复用还活着的会话。比对基准是该成员**最近一步实际使用的候选**（§3.6），
+     * 降级之后不会因为「和首选不一致」而每步都另开会话；候选换了五元组就不复用。
+     */
+    liveSessionFor(run, member, excludeStepId, agent) {
+        const steps = this.storage.listAiTeamSteps(run.id);
+        for (let index = steps.length - 1; index >= 0; index -= 1) {
+            const step = steps[index];
+            if (step.id === excludeStepId || step.memberId !== member.id || !step.sessionId)
+                continue;
+            const snapshot = this.ops.snapshot(step.sessionId);
+            if (!snapshot || isSessionGone(snapshot))
+                return null;
+            const candidates = memberAgents(member);
+            const previous = candidates[this.infoOf(step).usedCandidate] ?? candidates[0];
+            if (!previous || (agent && agentKey(previous) !== agentKey(agent)))
+                return null;
+            if (snapshot.provider && snapshot.provider !== previous.provider)
+                return null;
+            const model = previous.model === "default" ? "" : previous.model;
+            if (model && snapshot.selectedModel && snapshot.selectedModel !== model)
+                return null;
+            return step.sessionId;
+        }
+        return null;
+    }
+    // ── 群聊 ──
+    openChat(run, task, objective, chatHistory) {
+        if (!this.chat)
+            return;
+        try {
+            if (!run.chatSessionId) {
+                run.chatSessionId = this.chat.open({ task, run, title: `${run.team.name} · ${task.title}` });
+            }
+        }
+        catch (error) {
+            console.error(`[AiTeam] open chat for ${run.id} failed:`, getErrorMessage(error));
+            return;
+        }
+        const roster = run.team.members.map((member) => member.isLeader ? `${member.name}（负责人）` : member.name).join("、");
+        if (objective)
+            this.postUser(run, objective);
+        // 续跑时不说「接手」：用户看得出这是同一轮工作往下走，并把交给团队的历史文件摊开给他核。
+        this.postNotice(run, chatHistory
+            ? `接着这个群聊里上一轮的进度继续；交给负责人和成员的记录见 ${chatHistory}`
+            : `团队「${run.team.name}」接手了这个任务：${roster}`);
+    }
+    postTurn(run, turn) {
+        if (!this.chat || !run.chatSessionId)
+            return;
+        try {
+            this.chat.post(run.chatSessionId, [turn]);
+        }
+        catch (error) {
+            console.error(`[AiTeam] post to chat ${run.chatSessionId} failed:`, getErrorMessage(error));
+        }
+    }
+    postUser(run, text) {
+        this.postTurn(run, { role: "user", content: chatText(text) });
+    }
+    postNotice(run, text, sessionId, member, provider) {
+        this.postTurn(run, {
+            role: "assistant", notice: true, content: chatText(text),
+            author: member ? chatAuthor(member, sessionId, provider) : undefined,
+        });
+    }
+    /** 负责人的决定：说明 + 派工清单；等批准 / 等回复时告诉用户在群里怎么接话。 */
+    postLeaderDecision(run, step, decision) {
+        const lines = [decision.message.trim()];
+        if (decision.action === "assign") {
+            const assigned = decision.steps.map((item, index) => {
+                const name = this.member(run.team, item.memberId)?.name ?? item.memberId;
+                const after = item.after.length > 0 ? `（等第 ${item.after.map((at) => at + 1).join("、")} 项完成后）` : "";
+                return `${index + 1}. **@${name}** ${item.title}${after}`;
+            });
+            lines.push(assigned.join("\n"));
+        }
+        this.postTurn(run, {
+            role: "assistant",
+            author: chatAuthor(leaderOf(run.team), step.sessionId),
+            content: chatText(lines.filter(Boolean).join("\n\n")),
+        });
+        if (decision.action === "assign" && !run.planApproved) {
+            this.postNotice(run, "等你批准计划：回复「批准」开始执行，或者直接写修改意见。");
+        }
+        else if (decision.action === "ask") {
+            this.postNotice(run, "负责人在等你回复，直接在群里回答即可。");
+        }
+        else if (decision.action === "finish") {
+            this.postNotice(run, "团队已完成。还有要改的，直接在群里说，团队会接着处理。");
+        }
+        this.postVerifyOverlapNotices(run, decision);
+    }
+    /**
+     * 职责交叉只提示、不拦截（§3.3 修正 B13）：同一个成员既实现过又验收时，在群里提一句，
+     * 由用户决定是否让负责人调整。服务端不做任何职责硬校验，步骤照常派发。
+     */
+    postVerifyOverlapNotices(run, decision) {
+        if (decision.action !== "assign")
+            return;
+        // 此刻本步还没落库，listAiTeamSteps 里只有历史步骤，正好用来判「已经做过实现」。
+        const history = this.storage.listAiTeamSteps(run.id);
+        const notified = new Set();
+        for (const assigned of decision.steps) {
+            if (notified.has(assigned.memberId))
+                continue;
+            const member = this.member(run.team, assigned.memberId);
+            if (!member || member.role !== "verify")
+                continue;
+            const didWork = history.some((step) => step.kind === "work" && step.memberId === member.id && step.status === "done");
+            if (!didWork)
+                continue;
+            notified.add(member.id);
+            this.postNotice(run, `「${member.name}」既做过实现又被安排验收，介意的话在群里说一句让负责人调整。`);
+        }
+    }
+    member(team, memberId) {
+        return team.members.find((member) => member.id === memberId) ?? null;
+    }
+    nextSeq(runId) {
+        const steps = this.storage.listAiTeamSteps(runId);
+        return (steps[steps.length - 1]?.seq ?? 0) + 1;
+    }
+    setStatus(run, status, detail) {
+        run.status = status;
+        run.statusDetail = detail;
+        this.saveRun(run);
+    }
+    saveRun(run) {
+        run.updatedAt = this.iso();
+        this.storage.saveAiTeamRun(run);
+        this.notify(run);
+    }
+    saveStep(step) {
+        this.storage.saveAiTeamStep(step);
+    }
+    notify(run) {
+        try {
+            this.notifyListener?.(run);
+        }
+        catch {
+            // 通知失败不影响已写入的状态；客户端会在下次打开时重新拉取。
+        }
+    }
+    iso() {
+        return new Date(this.now()).toISOString();
+    }
+}