@co0ontty/wand 4.83.1 → 4.84.0

package/dist/team-dispatch.js

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import { AI_TEAM_DEFAULT_MAX_STEPS, AI_TEAM_MAX_MEMBERS, AI_TEAM_MIN_MEMBERS, isSystemSiliconEmployee, memberAgents, } from "./ai-team-types.js";
+import { DECISION_MAX_OPTIONS } from "./decision-types.js";
+import { defaultMilestoneIdForWrite, scopedMilestoneId } from "./milestone-scope.js";
+import { provisionalTaskTitleFromDescription } from "./task-title.js";
+/** 团队页「直接开工」自动建卡的标记，与手写卡区分。 */
+export const TEAM_DISPATCH_LABEL = "team_direct";
+/** 临时派工的候选集：一次决策调用最多评估这么多员工（= 每题最多选项数）。 */
+export const DISPATCH_CANDIDATES_PER_CALL = DECISION_MAX_OPTIONS;
+/** 建议名单默认上限：够完成一件事，又不至于把团队开成大会。 */
+export const DISPATCH_MAX_MEMBERS_DEFAULT = 3;
+/** 一次规划最多发多少次判断（每批 8 人）：保证响应时间与决策 worker 队列不被目录规模拖垮。 */
+export const DISPATCH_MAX_CALLS = 8;
+/** 入选门槛：低于这个概率视为“不参与”。概率只是参考，不是正确率。 */
+export const DISPATCH_MIN_PROBABILITY_DEFAULT = 0.5;
+/** 开工说明与状态的上限，与团队直接开工同口径。 */
+export const DISPATCH_NOTE_MAX = 4000;
+const DISPATCH_INSTRUCTION_MAX = 500;
+const DISPATCH_DUTY_MAX = 120;
+function collapse(value, max) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, Math.max(1, max - 1))}…` : flat;
+}
+/**
+ * 可派工的员工目录。
+ * 系统运维（Wand 自己的生成式 AI 执行者）不是干活的人，永远不进候选集；
+ * 归档员工不参与派工，但历史会话仍可打开。
+ */
+export function listTeamDispatchCandidates(storage) {
+    return storage.listSiliconEmployees()
+        .filter((employee) => !employee.archivedAt && !isSystemSiliconEmployee(employee))
+        .map((employee) => candidateOf(employee));
+}
+function candidateOf(employee) {
+    return {
+        employeeId: employee.id,
+        name: employee.name,
+        duty: collapse(employee.duty ?? "", DISPATCH_DUTY_MAX),
+        tags: employee.tags ?? [],
+        avatar: employee.avatar ?? "",
+    };
+}
+function chunksOf(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size)
+        chunks.push(items.slice(index, index + size));
+    return chunks;
+}
+/**
+ * 用本地决策模型给任务挑参与员工：**只产出建议名单**，不自动开工。
+ * 每批最多 8 名候选、一名一题（是非判断），批次之间顺序调用（决策服务本身是单 worker）。
+ */
+export async function planTeamDispatch(request) {
+    const note = collapse(request.note ?? "", DISPATCH_NOTE_MAX);
+    if (!note)
+        throw new Error("请先写清这次要做什么（开工说明不能为空）。");
+    const maxMembers = clampInteger(request.maxMembers, DISPATCH_MAX_MEMBERS_DEFAULT, AI_TEAM_MIN_MEMBERS, AI_TEAM_MAX_MEMBERS);
+    const threshold = clampProbability(request.threshold, DISPATCH_MIN_PROBABILITY_DEFAULT);
+    const candidates = listTeamDispatchCandidates(request.storage);
+    const considered = candidates.length;
+    if (considered === 0) {
+        return emptyPlan({ considered, omitted: 0, threshold, maxMembers, note: "员工目录里还没有可派工的员工：先在「AI 团队 → 硅基员工」里建一个。" });
+    }
+    const batches = chunksOf(candidates, DISPATCH_CANDIDATES_PER_CALL);
+    const covered = batches.slice(0, DISPATCH_MAX_CALLS);
+    const omitted = Math.max(0, candidates.length - covered.length * DISPATCH_CANDIDATES_PER_CALL);
+    const scored = [];
+    let calls = 0;
+    let model = null;
+    let inputTokens = 0;
+    for (const [batchIndex, batch] of covered.entries()) {
+        const questions = {};
+        for (const [index, candidate] of batch.entries())
+            questions[`c${batchIndex}_${index}`] = {
+                type: "noul",
+                instructions: dispatchQuestion(candidate, note),
+            };
+        const result = await request.evaluate({ state: dispatchState(note), questions }, "team-dispatch", request.signal);
+        calls += 1;
+        model = model ?? result.model;
+        inputTokens += result.usage?.input_tokens ?? 0;
+        for (const [index, candidate] of batch.entries()) {
+            const answer = result.answers?.[`c${batchIndex}_${index}`];
+            const probability = typeof answer?.noul === "number" && Number.isFinite(answer.noul) ? answer.noul : 0;
+            if (probability < threshold)
+                continue;
+            scored.push({ ...candidate, probability, isLeader: false });
+        }
+    }
+    scored.sort((a, b) => b.probability - a.probability || a.name.localeCompare(b.name, "zh-Hans-CN"));
+    const members = scored.slice(0, maxMembers);
+    const bench = scored.slice(maxMembers);
+    if (members[0])
+        members[0] = { ...members[0], isLeader: true };
+    return {
+        members,
+        bench,
+        considered,
+        omitted,
+        threshold,
+        maxMembers,
+        note: planNote({ members, bench, considered, omitted, threshold, calls }),
+        decision: { calls, model, inputTokens },
+        experimental: true,
+    };
+}
+function dispatchQuestion(candidate, note) {
+    const tags = candidate.tags.length ? `；标签：${candidate.tags.join("、")}` : "";
+    const role = candidate.duty ? `；职责：${candidate.duty}` : "";
+    return collapse(`任务：${note}\n判断员工「${candidate.name}」是否应该参与这个任务${role}${tags}。只按能力与职责匹配判断，不要因为他已经做过别的事就默认参与。`, DISPATCH_INSTRUCTION_MAX);
+}
+function dispatchState(note) {
+    return collapse(`从员工目录里为一个任务挑选参与者。任务描述：${note}`, 16_000);
+}
+function planNote(input) {
+    if (input.members.length === 0) {
+        return `在已评估的候选里没有员工的参与概率超过 ${Math.round(input.threshold * 100)}%；可以放低门槛、补全员工职责/标签，或直接指定员工。`;
+    }
+    if (input.members.length < AI_TEAM_MIN_MEMBERS) {
+        return `只有 1 名员工的参与概率超过 ${Math.round(input.threshold * 100)}%，而团队开工至少需要 ${AI_TEAM_MIN_MEMBERS} 人：放低门槛，或从备选里再点一名。`;
+    }
+    const parts = [`从 ${input.considered} 名候选里建议 ${input.members.length} 人（${input.calls} 次本地判断）。`];
+    if (input.omitted > 0)
+        parts.push(`另有 ${input.omitted} 人未评估（一次规划最多评估 ${DISPATCH_MAX_CALLS * DISPATCH_CANDIDATES_PER_CALL} 人），可直接指定。`);
+    if (input.bench.length > 0)
+        parts.push(`另有 ${input.bench.length} 人达到门槛但超出人数上限，可作为备选。`);
+    parts.push("概率只是参考，不是正确率；确认后才会开工。");
+    return parts.join("");
+}
+function emptyPlan(input) {
+    return {
+        members: [],
+        bench: [],
+        considered: input.considered,
+        omitted: input.omitted,
+        threshold: input.threshold,
+        maxMembers: input.maxMembers,
+        note: input.note,
+        decision: { calls: 0, model: null, inputTokens: 0 },
+        experimental: true,
+    };
+}
+function clampInteger(value, fallback, min, max) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(parsed)));
+}
+function clampProbability(value, fallback) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(0.95, Math.max(0.05, parsed));
+}
+/**
+ * 确认开工：用建议名单建一个临时团队并起 run。
+ * 名单由调用方回传（服务端重新校验员工身份），所以“建议”和“开工”之间不需要服务端存计划。
+ */
+export async function startTeamDispatch(request) {
+    const note = collapse(request.note ?? "", DISPATCH_NOTE_MAX);
+    if (!note)
+        throw new Error("请先写清这次要做什么（开工说明不能为空）。");
+    if (request.members.length < AI_TEAM_MIN_MEMBERS)
+        throw new Error(`团队开工至少需要 ${AI_TEAM_MIN_MEMBERS} 名员工（含负责人）。`);
+    if (request.members.length > AI_TEAM_MAX_MEMBERS)
+        throw new Error(`临时派工最多 ${AI_TEAM_MAX_MEMBERS} 名员工。`);
+    const workspace = request.storage.getWorkspace(request.workspaceId);
+    if (!workspace)
+        throw new Error("请选择工作项目。");
+    if (workspace.kind === "global")
+        throw new Error("临时派工不能在全局暂存工作区运行，请先选择或创建一个项目。");
+    if (!workspace.cwd?.trim())
+        throw new Error("这个项目还没有工作目录，请先选择一个项目。");
+    const seen = new Set();
+    const requestedLeader = request.members.findIndex((member) => member.isLeader);
+    if (request.members.filter((member) => member.isLeader).length > 1)
+        throw new Error("只能指定一名负责人。");
+    const leaderAt = requestedLeader >= 0 ? requestedLeader : 0;
+    const members = [];
+    for (const [index, requested] of request.members.entries()) {
+        const employeeId = requested.employeeId?.trim();
+        if (!employeeId || seen.has(employeeId))
+            throw new Error("名单里有重复或缺失的员工。");
+        seen.add(employeeId);
+        const employee = request.storage.getSiliconEmployee(employeeId);
+        if (!employee)
+            throw new Error("名单里的员工不存在，请重新生成建议。");
+        if (employee.archivedAt)
+            throw new Error(`员工「${employee.name}」已归档，不能参与派工。`);
+        if (isSystemSiliconEmployee(employee))
+            throw new Error("系统运维员工不参与任务派工。");
+        const agents = memberAgents({ agents: employee.agents });
+        if (agents.length === 0)
+            throw new Error(`员工「${employee.name}」没有可用的执行候选，请先在员工设置里补上。`);
+        members.push({
+            id: `m_${randomUUID().replace(/-/g, "").slice(0, 8)}`,
+            employeeId: employee.id,
+            name: employee.name,
+            duty: collapse(employee.duty ?? "", DISPATCH_DUTY_MAX),
+            agents,
+            agent: agents[0],
+            role: "any",
+            isLeader: index === leaderAt,
+            avatar: employee.avatar ?? "",
+        });
+    }
+    if (request.members.length < AI_TEAM_MIN_MEMBERS) {
+        throw new Error(`团队开工至少需要 ${AI_TEAM_MIN_MEMBERS} 名员工（含负责人）。`);
+    }
+    const title = provisionalTaskTitleFromDescription(note) || "临时派工";
+    const now = new Date().toISOString();
+    const team = {
+        id: `t_dispatch_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+        name: collapse(request.name?.trim() || `临时派工 · ${title}`, 120),
+        description: note,
+        instructions: [
+            "本团队由本地决策模型按任务描述临时组建，只在这一次任务里协作。",
+            "分工与职责以成员说明为准；开工说明是本轮的唯一目标。",
+            `成员：${members.map((member) => `${member.name}（${member.duty || "未填写职责"}）`).join("；")}`,
+        ].join("\n"),
+        members,
+        requirePlanApproval: false,
+        maxSteps: AI_TEAM_DEFAULT_MAX_STEPS,
+        createdAt: now,
+        updatedAt: now,
+    };
+    request.storage.saveAiTeam(team);
+    const leader = members.find((member) => member.isLeader) ?? members[0];
+    const milestoneId = defaultMilestoneIdForWrite(request.storage);
+    const task = request.storage.createWandTask({
+        workspaceId: workspace.id,
+        title,
+        description: note,
+        status: "doing",
+        labels: [TEAM_DISPATCH_LABEL],
+        milestoneId: scopedMilestoneId(request.storage, milestoneId, workspace.id) ?? milestoneId,
+        agent: leader.agents[0] ?? null,
+        executionSubject: { type: "team", id: team.id },
+    });
+    try {
+        const run = await request.runner.start({ teamId: team.id, taskId: task.id, note });
+        return { teamId: team.id, taskId: task.id, run };
+    }
+    catch (error) {
+        try {
+            request.storage.deleteWandTask(task.id);
+        }
+        catch {
+            // 回滚失败不回滚错误本身：原始错误更重要。
+        }
+        try {
+            request.storage.deleteAiTeam(team.id);
+        }
+        catch {
+            // 同上：临时团队即使残留也不会被误用（run 没起来）。
+        }
+        throw error;
+    }
+}
+/** 决策服务可用性：不可用时明确报错，绝不编造名单。 */
+export function assertDispatchDecisionReady(decisions) {
+    const status = decisions.status();
+    if (!status.enabled)
+        throw new Error("本地决策未启用（localDecision.enabled=false），无法用决策模型选人。");
+    if (!status.supported)
+        throw new Error("本地决策在当前平台不可用（首期只支持 macOS arm64），无法用决策模型选人。");
+    if (!status.configured)
+        throw new Error("本地决策运行环境未配置（pythonPath / modelPath），无法用决策模型选人。");
+}

package/dist/tool-preview.js

@@ -1,3 +1,4 @@
+import { contentHasStructuredImage, isStructuredImagePart } from "./structured-content.js";
 export const TOOL_PREVIEW_LIMIT = 180;
 /** A small, literal excerpt for a collapsed card, never generated by a model. */
 export function compactPreviewText(value) {
@@ -112,8 +113,13 @@ export function toolResultPreview(result) {
     const raw = typeof result.content === "string" ? result.content : result.content
         .filter(part => part.type === "text" && typeof part.text === "string")
         .slice(0, 3).map(part => part.text).join("\n");
-    if (!raw.trim())
+    if (!raw.trim()) {
+        if (Array.isArray(result.content) && contentHasStructuredImage(result.content)) {
+            const count = result.content.filter(isStructuredImagePart).length;
+            return compactPreviewText(count > 1 ? `返回 ${count} 张图片` : "返回 1 张图片");
+        }
         return "";
+    }
     let text = raw;
     let exit = "";
     if (raw.length <= 65_536 && /^\s*[{[]/.test(raw)) {

package/dist/tui/commands.js

@@ -942,6 +942,48 @@ function homeForUser(userName, fallback) {
     }
     return fallback;
 }
+function shellFromConfig(configPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        const shell = typeof parsed.shell === "string" ? parsed.shell.trim() : "";
+        return shell || null;
+    }
+    catch {
+        return null;
+    }
+}
+function shellForUser(userName, fallback) {
+    if (userName && userName !== "root") {
+        if (process.platform === "darwin") {
+            const resolved = spawnSync("dscl", [".", "-read", `/Users/${userName}`, "UserShell"], {
+                encoding: "utf8",
+                timeout: 3000,
+            });
+            const match = (resolved.stdout || "").match(/UserShell:\s*(.+)/);
+            if (resolved.status === 0 && match?.[1])
+                return match[1].trim();
+        }
+        if (process.platform === "linux") {
+            const resolved = spawnSync("getent", ["passwd", userName], { encoding: "utf8", timeout: 3000 });
+            const shell = (resolved.stdout || "").split(":")[6];
+            if (resolved.status === 0 && shell)
+                return shell.trim();
+        }
+    }
+    try {
+        const current = os.userInfo().shell?.trim();
+        if (current)
+            return current;
+    }
+    catch {
+        // userInfo() can throw in stripped-down service environments.
+    }
+    return process.env.SHELL?.trim() || fallback;
+}
+function serviceShellFor(ctx, runUser) {
+    return shellFromConfig(ctx.configPath)
+        ?? shellForUser(runUser, process.platform === "darwin" ? "/bin/zsh" : "/bin/bash");
+}
 function statUid(targetPath) {
     return readFileStat(targetPath).uid;
 }
@@ -960,6 +1002,7 @@ function installSystemdService(ctx, scope) {
     const runUser = scope === "system" ? ownerUserNameForPath(ctx.configPath) : currentUserName();
     const fallbackHome = process.env.HOME || os.homedir();
     const runHome = scope === "system" ? homeForUser(runUser, fallbackHome) : fallbackHome;
+    const runShell = serviceShellFor(ctx, runUser);
     // 关键：把调用 `wand service:install` 时的真实 PATH 写进 unit。
     // 否则 systemd 默认 PATH 极简（system scope 之前写死 `nodeBin:/usr/local/...`，
     // user scope 干脆没写），spawn 出的 claude/codex 子进程会撞 "command not found"
@@ -977,6 +1020,7 @@ function installSystemdService(ctx, scope) {
         `ExecStart=${nodeBin} ${wandBin} web -c ${ctx.configPath}`,
         `Environment=WAND_NO_TUI=1`,
         `Environment=PATH=${servicePath}`,
+        `Environment=SHELL=${runShell}`,
         "Restart=always",
         "RestartSec=3",
         "StandardOutput=journal",
@@ -1019,6 +1063,7 @@ function installSystemdService(ctx, scope) {
         "Type=simple",
         `ExecStart=${nodeBin} ${wandBin} terminald -c ${ctx.configPath}`,
         `Environment=PATH=${servicePath}`,
+        `Environment=SHELL=${runShell}`,
         "Restart=always",
         "RestartSec=3",
         "StandardOutput=journal",
@@ -1060,6 +1105,7 @@ function installSystemdService(ctx, scope) {
         `scope: ${scope}`,
         `unit: ${unitPath}`,
         `terminal unit: ${terminalUnitPath}`,
+        `shell: ${runShell}`,
         ...daemonNotes,
         "daemons:",
         describeDaemonEndpoints(ctx.configPath),
@@ -1122,6 +1168,7 @@ function installLaunchdService(ctx, scope) {
     const runUser = scope === "system" ? ownerUserNameForPath(ctx.configPath) : currentUserName();
     const fallbackHome = process.env.HOME || os.homedir();
     const runHome = scope === "system" ? homeForUser(runUser, fallbackHome) : fallbackHome;
+    const runShell = serviceShellFor(ctx, runUser);
     // 与 systemd 同理：launchd 默认 PATH 极简，spawn 出的 claude 会找不到。
     const servicePath = buildServicePath(nodeBinDir, runHome);
     // launchd 默认把 stdout/stderr 丢进 /dev/null：线上出问题时连“daemon 活着但端点没了”
@@ -1151,6 +1198,7 @@ ${userNameField}  <key>WorkingDirectory</key><string>${runHome}</string>
   <dict>
     <key>WAND_NO_TUI</key><string>1</string>
     <key>PATH</key><string>${servicePath}</string>
+    <key>SHELL</key><string>${runShell}</string>
     <key>HOME</key><string>${runHome}</string>
   </dict>
   <key>RunAtLoad</key><true/>
@@ -1175,6 +1223,7 @@ ${userNameField}  <key>WorkingDirectory</key><string>${runHome}</string>
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key><string>${servicePath}</string>
+    <key>SHELL</key><string>${runShell}</string>
     <key>HOME</key><string>${runHome}</string>
   </dict>
   <key>RunAtLoad</key><true/>
@@ -1232,7 +1281,7 @@ ${logFields("terminald.log", "terminald-error.log")}  <key>KeepAlive</key><true/
         message: `已注册 launchd ${scope === "user" ? "用户代理" : "系统守护"}: ${plistPath}` +
             (daemonNotes.length > 0 ? `（已清理 ${daemonNotes.length} 个僵尸 daemon）` : "") +
             (staleDaemonNote(ctx.configPath) ?? ""),
-        detail: [terminalDetail, started.detail, ...daemonNotes, "daemons:", describeDaemonEndpoints(ctx.configPath)]
+        detail: [`shell: ${runShell}`, terminalDetail, started.detail, ...daemonNotes, "daemons:", describeDaemonEndpoints(ctx.configPath)]
             .filter(Boolean)
             .join("\n"),
     };

package/dist/tui/ipc-protocol.d.ts

@@ -31,7 +31,7 @@ export interface IpcSnapshotData {
 }
 export interface IpcRequest {
     id: string;
-    cmd: "snapshot" | "ping" | "shutdown";
+    cmd: "snapshot" | "ping" | "shutdown" | "core-status" | "core-drain";
 }
 export interface IpcResponseOk<T = unknown> {
     id: string;

package/dist/tui/ipc-server.d.ts

@@ -4,12 +4,16 @@
  * Windows 不支持（socketPath 返回空字符串），调用方应跳过 startIpcServer。
  */
 import { IpcSnapshotData } from "./ipc-protocol.js";
+import type { CoreStatus } from "../core-status-cli.js";
 export interface IpcServerDeps {
     socketPath: string;
     /** 由 TUI 上层组装。同步函数，避免在 socket callback 里做异步阻塞。 */
     snapshotProvider: () => IpcSnapshotData;
     /** attach 客户端发起 shutdown 时调用；返回 promise，resolve 后服务端退出。 */
     onShutdown?: () => void | Promise<void>;
+    coreStatusProvider?: () => CoreStatus;
+    /** Connection-scoped admission barrier; disconnect cancels the pending restart. */
+    beginCoreDrain?: () => () => void;
 }
 export interface IpcServerHandle {
     close(): Promise<void>;

package/dist/tui/ipc-server.js

@@ -19,7 +19,16 @@ export function startIpcServer(deps) {
         }
         catch { /* noop */ }
     }
+    const connections = new Map();
     const server = net.createServer((conn) => {
+        connections.set(conn, null);
+        conn.on("close", () => {
+            const release = connections.get(conn);
+            connections.delete(conn);
+            // Server shutdown must not resume queues just before manager disposal.
+            if (!closed)
+                release?.();
+        });
         let buf = "";
         const decoder = new StringDecoder("utf8");
         conn.on("data", (chunk) => {
@@ -58,6 +67,18 @@ export function startIpcServer(deps) {
                     conn.write(JSON.stringify(resp) + "\n");
                     return;
                 }
+                case "core-status":
+                case "core-drain": {
+                    if (!deps.coreStatusProvider || (req.cmd === "core-drain" && !deps.beginCoreDrain)) {
+                        throw new Error(`unknown cmd: ${req.cmd}`);
+                    }
+                    if (req.cmd === "core-drain" && !connections.get(conn)) {
+                        connections.set(conn, deps.beginCoreDrain());
+                    }
+                    const resp = { id: req.id, ok: true, data: deps.coreStatusProvider() };
+                    conn.write(JSON.stringify(resp) + "\n");
+                    return;
+                }
                 case "shutdown": {
                     const ack = { id: req.id, ok: true, data: { accepted: true } };
                     conn.write(JSON.stringify(ack) + "\n");
@@ -103,6 +124,8 @@ export function startIpcServer(deps) {
         close: async () => {
             closed = true;
             stopSocketKeepalive();
+            for (const conn of connections.keys())
+                conn.destroy();
             await new Promise((resolve) => {
                 server.close(() => resolve());
                 // 兜底：1s 内强制 resolve

package/dist/turn-heartbeat.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 回合静默期心跳：一条回合真的还在跑（structured `inFlight` / PTY `ptyBusy`），但服务端
+ * 连续这么久没产生任何事件时，用**现有的 status 事件类型**重发一次权威快照（带上最新的
+ * turn 锚点），给客户端「仍在运行、只是这一句很长」的证据。
+ *
+ * 这里不新增协议、不新增事件类型，也不做无界轮询：
+ *   - timer 是会话级的，只在回合在飞期间存在；
+ *   - `observe()` 在回合开始和每次观测到活动时重新计时（对齐 process-manager 里
+ *     `refreshPtyTurn()` 的既有做法）；
+ *   - `cancel()` 在回合结束 / 会话停止、删除时立即撤销；
+ *   - `dispose()` 在服务关闭时清干净，不允许任何 timer 跨进程存活；
+ *   - 触发一次后由 `notify` 的返回值决定是否续下一个窗口——回合不再在飞就自然停。
+ */
+/**
+ * 静默阈值 30s：大致是用户开始怀疑「是不是卡死了」的时间尺度，同时保证一轮最多触发
+ * 两次心跳就把「还在跑」传达出去。注意这与 `ws-broadcast` 的 HEARTBEAT_INTERVAL_MS
+ * 不是一回事——那个只探测 socket 连接活性，不携带会话事实。
+ */
+export declare const TURN_QUIET_HEARTBEAT_MS = 30000;
+export declare class TurnQuietHeartbeat {
+    /** 重发快照；返回 true 表示这一轮仍在飞，需要继续下一个静默窗口。 */
+    private readonly notify;
+    private readonly delayMs;
+    private readonly timers;
+    private disposed;
+    constructor(
+    /** 重发快照；返回 true 表示这一轮仍在飞，需要继续下一个静默窗口。 */
+    notify: (sessionId: string) => boolean, delayMs?: number);
+    /** 观测到活动（回合开始 / 输出 chunk / 状态变化）：把静默窗口往后推。 */
+    observe(sessionId: string): void;
+    /** 回合收敛或会话被移除：立即撤销这个会话的静默窗口。 */
+    cancel(sessionId: string): void;
+    /** 服务关闭：一次性丢掉所有在飞的窗口，之后不再接受新的 observe。 */
+    dispose(): void;
+}

package/dist/turn-heartbeat.js

@@ -0,0 +1,64 @@
+/**
+ * 回合静默期心跳：一条回合真的还在跑（structured `inFlight` / PTY `ptyBusy`），但服务端
+ * 连续这么久没产生任何事件时，用**现有的 status 事件类型**重发一次权威快照（带上最新的
+ * turn 锚点），给客户端「仍在运行、只是这一句很长」的证据。
+ *
+ * 这里不新增协议、不新增事件类型，也不做无界轮询：
+ *   - timer 是会话级的，只在回合在飞期间存在；
+ *   - `observe()` 在回合开始和每次观测到活动时重新计时（对齐 process-manager 里
+ *     `refreshPtyTurn()` 的既有做法）；
+ *   - `cancel()` 在回合结束 / 会话停止、删除时立即撤销；
+ *   - `dispose()` 在服务关闭时清干净，不允许任何 timer 跨进程存活；
+ *   - 触发一次后由 `notify` 的返回值决定是否续下一个窗口——回合不再在飞就自然停。
+ */
+/**
+ * 静默阈值 30s：大致是用户开始怀疑「是不是卡死了」的时间尺度，同时保证一轮最多触发
+ * 两次心跳就把「还在跑」传达出去。注意这与 `ws-broadcast` 的 HEARTBEAT_INTERVAL_MS
+ * 不是一回事——那个只探测 socket 连接活性，不携带会话事实。
+ */
+export const TURN_QUIET_HEARTBEAT_MS = 30_000;
+export class TurnQuietHeartbeat {
+    notify;
+    delayMs;
+    timers = new Map();
+    disposed = false;
+    constructor(
+    /** 重发快照；返回 true 表示这一轮仍在飞，需要继续下一个静默窗口。 */
+    notify, delayMs = TURN_QUIET_HEARTBEAT_MS) {
+        this.notify = notify;
+        this.delayMs = delayMs;
+    }
+    /** 观测到活动（回合开始 / 输出 chunk / 状态变化）：把静默窗口往后推。 */
+    observe(sessionId) {
+        if (this.disposed)
+            return;
+        const existing = this.timers.get(sessionId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.timers.delete(sessionId);
+            if (this.disposed)
+                return;
+            if (this.notify(sessionId))
+                this.observe(sessionId);
+        }, this.delayMs);
+        // 心跳不能让空闲进程 / 测试用例挂在 event loop 上。
+        timer.unref?.();
+        this.timers.set(sessionId, timer);
+    }
+    /** 回合收敛或会话被移除：立即撤销这个会话的静默窗口。 */
+    cancel(sessionId) {
+        const existing = this.timers.get(sessionId);
+        if (!existing)
+            return;
+        clearTimeout(existing);
+        this.timers.delete(sessionId);
+    }
+    /** 服务关闭：一次性丢掉所有在飞的窗口，之后不再接受新的 observe。 */
+    dispose() {
+        this.disposed = true;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+}