@co0ontty/wand 4.97.0 → 4.98.0

package/dist/migration-backup-retention.js

@@ -0,0 +1,91 @@
+import { readdirSync, lstatSync, unlinkSync } from "node:fs";
+import path from "node:path";
+/**
+ * 迁移前 SQLite 快照（`wand.db.pre-v<N>-<时间戳>-<随机>.bak`）的有界保留。
+ *
+ * 每次 schema 升级都会 `VACUUM INTO` 一份完整副本，而快照体积等于整库大小，
+ * 没有上限时旧备份会无限累积。这里只做「有界保留」，不做数据清理：
+ *
+ * - 迁移**失败**时绝不调用（调用方保证只在迁移成功且健康检查通过后调用）；
+ * - 默认保留最近 `keep` 份，外加调用方明确要求保留的那一份（刚成功这次迁移的回滚点）；
+ * - 只认迁移备份的命名，不碰 `wand.db`、`backups/` 里的人工恢复点或配置快照；
+ * - 删除失败不影响迁移结果。
+ */
+/** 迁移前快照的命名：`<db>.pre-v12-2026-10-18T09-58-41-937Z-ca8636.bak`。 */
+const MIGRATION_BACKUP_PATTERN = /\.pre-v\d+-\d{4}-\d{2}-\d{2}T[\d-]+Z-[0-9a-f]{6}\.bak$/;
+/** 人工标记的迁移前快照，例如 `pre-organization-baseline-repair-<时间戳>.bak`。 */
+const MANUAL_BACKUP_PATTERN = /\.pre-(?!v\d+-)[A-Za-z0-9-]+-\d{4}-\d{2}-\d{2}T[\d-]+Z\.bak$/;
+export const DEFAULT_MIGRATION_BACKUP_KEEP = 2;
+/**
+ * 保留最近若干份迁移快照。`keepPath` 是本次刚生成、必须保留的回滚点。
+ *
+ * `keep` 统计的是「自动迁移快照」，人工命名的快照不计入额度，单独保留最近一份，
+ * 避免把开发者手工留的基线修复点一起清掉。
+ */
+export function pruneMigrationBackups(dbPath, options = {}) {
+    const result = { deleted: [], freedBytes: 0, kept: [] };
+    const keepCount = Math.max(1, options.keep ?? DEFAULT_MIGRATION_BACKUP_KEEP);
+    const directory = path.dirname(dbPath);
+    const base = path.basename(dbPath);
+    let entries;
+    try {
+        entries = readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    const automatic = [];
+    const manual = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith(`${base}.pre-`))
+            continue;
+        const filePath = path.join(directory, entry.name);
+        let stat;
+        try {
+            stat = lstatSync(filePath);
+            // 符号链接一律不碰：备份文件必须是普通文件。
+            if (!stat.isFile() || stat.isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const record = { name: entry.name, filePath, mtimeMs: stat.mtimeMs, size: stat.size };
+        if (MIGRATION_BACKUP_PATTERN.test(entry.name))
+            automatic.push(record);
+        else if (MANUAL_BACKUP_PATTERN.test(entry.name))
+            manual.push(record);
+    }
+    const keepName = options.keepPath ? path.basename(options.keepPath) : null;
+    const newestFirst = (a, b) => b.mtimeMs - a.mtimeMs;
+    automatic.sort(newestFirst);
+    manual.sort(newestFirst);
+    const keep = new Set();
+    if (keepName)
+        keep.add(keepName);
+    for (const record of automatic.slice(0, keepCount))
+        keep.add(record.name);
+    // 人工快照只留最近一份，其余按同一规则回收。
+    if (manual.length > 0)
+        keep.add(manual[0].name);
+    for (const record of [...automatic, ...manual]) {
+        if (keep.has(record.name)) {
+            result.kept.push(record.name);
+            continue;
+        }
+        if (options.dryRun) {
+            result.deleted.push(record.name);
+            result.freedBytes += record.size;
+            continue;
+        }
+        try {
+            unlinkSync(record.filePath);
+            result.deleted.push(record.name);
+            result.freedBytes += record.size;
+        }
+        catch {
+            // 删不掉（权限/占用）就留着，下次扫描再试。
+        }
+    }
+    return result;
+}

package/dist/pi-tmux-host.d.ts

@@ -40,5 +40,33 @@ export declare class PiTmuxHost implements StructuredExecHost {
     listRuns(): Promise<StructuredRunState[]>;
     kill(job: NativeJob): Promise<void>;
     forgetRun(runId: string): void;
+    /**
+     * 回收 pi-native 下已经没用的执行产物。每次 Pi 原生回合都会在 slot 里
+     * `mkdtemp` 一个新 turn 目录（events.jsonl / stderr.log / state.json 等），
+     * 而 forgetRun 只写 ack 标记、从不删目录，所以会按回合数无限堆积。
+     *
+     * 只回收三类确定无主的东西：
+     * - slot 已 ack 且 runId 不再属于任何存活会话：整个 slot 无主；
+     * - slot 无主的，整槽删除；
+     * - slot 仍有主的，只删非 current.json 引用、已 ack 且进程已退出、超保留期的 turn。
+     *
+     * 保留 current.json 指向的 turn：`listRuns` / `adoptRun` 仍靠它的 events.jsonl
+     * 重放恢复；未 ack 的 slot 可能是尚未收尾的回合，一律不动。
+     */
+    collectGarbage(options: {
+        /** 仍在数据库里的会话 id；不在其中的 slot 视为无主。 */
+        liveSessionIds: ReadonlySet<string>;
+        retentionMs: number;
+        now?: number;
+    }): PiNativeGcReport;
+    private readJob;
+    /** 无主 slot 是否已整体静默：所有 turn 都不再是运行中，且最新写入超过保留期。 */
+    private slotIsIdle;
+}
+/** pi-native 回收结果：删了几个 slot / 几个旧 turn / 释放多少字节。 */
+export interface PiNativeGcReport {
+    removedSlots: number;
+    removedTurns: number;
+    freedBytes: number;
 }
 export {};

package/dist/pi-tmux-host.js

@@ -382,4 +382,193 @@ export class PiTmuxHost {
         writeFileSync(job.ack, "consumed\n", { mode: 0o600 });
         this.observed.delete(runId);
     }
+    /**
+     * 回收 pi-native 下已经没用的执行产物。每次 Pi 原生回合都会在 slot 里
+     * `mkdtemp` 一个新 turn 目录（events.jsonl / stderr.log / state.json 等），
+     * 而 forgetRun 只写 ack 标记、从不删目录，所以会按回合数无限堆积。
+     *
+     * 只回收三类确定无主的东西：
+     * - slot 已 ack 且 runId 不再属于任何存活会话：整个 slot 无主；
+     * - slot 无主的，整槽删除；
+     * - slot 仍有主的，只删非 current.json 引用、已 ack 且进程已退出、超保留期的 turn。
+     *
+     * 保留 current.json 指向的 turn：`listRuns` / `adoptRun` 仍靠它的 events.jsonl
+     * 重放恢复；未 ack 的 slot 可能是尚未收尾的回合，一律不动。
+     */
+    collectGarbage(options) {
+        const report = { removedSlots: 0, removedTurns: 0, freedBytes: 0 };
+        const now = options.now ?? Date.now();
+        let entries;
+        try {
+            entries = readdirSync(this.root, { withFileTypes: true });
+        }
+        catch {
+            return report;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const slot = path.join(this.root, entry.name);
+            const job = this.readJob(slot);
+            if (!job)
+                continue;
+            const acked = existsSync(job.ack);
+            const sessionId = job.runId.replace(/^structured:/, "");
+            const orphan = !options.liveSessionIds.has(sessionId);
+            if (orphan) {
+                // 无主 slot 也得等 ack 完成：未 ack 说明回合可能还在收尾。
+                if (!acked)
+                    continue;
+                if (!this.slotIsIdle(slot, job, now, options.retentionMs))
+                    continue;
+                report.freedBytes += directoryBytes(slot);
+                if (removeTree(slot))
+                    report.removedSlots += 1;
+                else
+                    report.freedBytes -= directoryBytes(slot);
+                continue;
+            }
+            // 有主 slot：只删不被 current.json 引用的旧 turn。
+            const current = path.dirname(job.events);
+            let turns;
+            try {
+                turns = readdirSync(slot, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const turn of turns) {
+                if (!turn.isDirectory() || !turn.name.startsWith("turn-"))
+                    continue;
+                const directory = path.join(slot, turn.name);
+                if (directory === current)
+                    continue;
+                if (!existsSync(path.join(directory, "ack")))
+                    continue;
+                const state = readJson(path.join(directory, "state.json"));
+                // 进程还活着的回合不能被当成垃圾。state 写 running 但 PID 已消失的
+                // （异常退出/被强杀）按已退出处理，否则这种回合会永久堆积。
+                if (!state || stateAlive(state))
+                    continue;
+                let latest;
+                try {
+                    latest = directoryLatestMtime(directory);
+                }
+                catch {
+                    continue;
+                }
+                if (now - latest < options.retentionMs)
+                    continue;
+                const bytes = directoryBytes(directory);
+                if (!removeTree(directory))
+                    continue;
+                report.removedTurns += 1;
+                report.freedBytes += bytes;
+            }
+        }
+        return report;
+    }
+    readJob(slot) {
+        try {
+            return JSON.parse(readFileSync(path.join(slot, "current.json"), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 无主 slot 是否已整体静默：所有 turn 都不再是运行中，且最新写入超过保留期。 */
+    slotIsIdle(slot, job, now, retentionMs) {
+        const current = path.dirname(job.events);
+        const state = readJson(job.state);
+        if (state && stateAlive(state))
+            return false;
+        let latest;
+        try {
+            latest = directoryLatestMtime(slot);
+        }
+        catch {
+            return false;
+        }
+        if (now - latest < retentionMs)
+            return false;
+        // 非 current 的 turn 里如果还有活进程，整槽不能删。
+        let turns;
+        try {
+            turns = readdirSync(slot, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const turn of turns) {
+            if (!turn.isDirectory() || !turn.name.startsWith("turn-"))
+                continue;
+            const directory = path.join(slot, turn.name);
+            if (directory === current)
+                continue;
+            const other = readJson(path.join(directory, "state.json"));
+            if (other && stateAlive(other))
+                return false;
+        }
+        return true;
+    }
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** 回合是否仍活着：state 声称未退出且 PID 真实存在。 */
+function stateAlive(state) {
+    return state.status !== "exited" && pidAlive(state.pid);
+}
+function pidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the PID exists but belongs to another user; treat as alive.
+        return error.code === "EPERM";
+    }
+}
+function directoryLatestMtime(directory) {
+    let latest = lstatSync(directory).mtimeMs;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        const stat = lstatSync(child);
+        if (stat.isDirectory())
+            latest = Math.max(latest, directoryLatestMtime(child));
+        // 只看 mtime：ctime 无法回拨，且文件被任何元数据操作碰一下就会刷新，
+        // 用它做保留期会把「早已结束的回合」永远当成刚活动过。
+        else
+            latest = Math.max(latest, stat.mtimeMs);
+    }
+    return latest;
+}
+function directoryBytes(directory) {
+    let total = 0;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        const stat = lstatSync(child);
+        if (stat.isDirectory())
+            total += directoryBytes(child);
+        else
+            total += stat.size;
+    }
+    return total;
+}
+/** 只删目录，不跟随符号链接。 */
+function removeTree(directory) {
+    try {
+        rmSync(directory, { recursive: true, force: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
 }

package/dist/server-employee-routes.d.ts

@@ -5,6 +5,7 @@ import type { QuickCommitAiOptions } from "./ai-text-runner.js";
 import type { WandStorage } from "./storage.js";
 import type { WandTaskAgent } from "./task-types.js";
 import type { WandConfig } from "./types.js";
+export declare function parseSystemSessionLimit(value: unknown, existing?: SiliconEmployee | null): number | null;
 /** Recruitment uses HR’s own ordered candidates and persona, never the ops chain. */
 export declare function employeeDraftAiOptions(storage: WandStorage, config?: WandConfig, free?: Pick<OpenRouterFreeModelsService, "resolveForCall">): QuickCommitAiOptions;
 export interface EmployeeDraftRequest {

package/dist/server-employee-routes.js

@@ -15,6 +15,17 @@ import { SESSION_PROVIDERS } from "./session-provider.js";
 import { DEFAULT_WAND_TASK_AGENT_KIND } from "./task-types.js";
 import { EMPLOYEE_KNOWLEDGE_MAX_ENTRIES } from "./employee-knowledge-types.js";
 import { badRequest } from "./http-error.js";
+import { systemAiSessions } from "./system-ai-session-recorder.js";
+export function parseSystemSessionLimit(value, existing) {
+    if (value === undefined)
+        return existing?.systemSessionLimit ?? null;
+    if (value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 10_000) {
+        throw badRequest("系统调用历史保留上限必须是 0 到 10000 的整数，或 null（不限）。");
+    }
+    return value;
+}
 /** Recruitment uses HR’s own ordered candidates and persona, never the ops chain. */
 export function employeeDraftAiOptions(storage, config, free) {
     if (!config)
@@ -90,7 +101,7 @@ export function parseSystemEmployeeAgents(value, existing) {
     if (body.systemKey !== undefined && body.systemKey !== existing.systemKey) {
         throw badRequest("该员工是内置的，身份不可修改。");
     }
-    return isFixedAvatarEmployee(existing) && body.agents === undefined ? existing.agents : parseEmployeeAgents(body.agents);
+    return body.agents === undefined ? existing.agents : parseEmployeeAgents(body.agents);
 }
 /** Partial edits preserve omitted fields and the raw saved prompt, not a generated read projection. */
 export function parseFixedAvatarEmployeeInput(value, existing, now) {
@@ -103,7 +114,7 @@ export function parseFixedAvatarEmployeeInput(value, existing, now) {
         throw badRequest("员工职责不能超过 2000 个字符。");
     if (prompt.length > 20_000)
         throw badRequest("员工设定 Prompt 不能超过 20000 个字符。");
-    return { ...existing, name, duty, prompt, agents, updatedAt: now };
+    return { ...existing, name, duty, prompt, agents, systemSessionLimit: parseSystemSessionLimit(body.systemSessionLimit, existing), updatedAt: now };
 }
 /** One validation owner for every employee candidate list, including legacy single agents. */
 function parseEmployeeAgents(value) {
@@ -148,6 +159,7 @@ export function parseSiliconEmployeeInput(value, existing, now) {
         avatar,
         agents,
         tags,
+        systemSessionLimit: parseSystemSessionLimit(body.systemSessionLimit, existing),
         archivedAt: existing?.archivedAt,
         createdAt: existing ? existing.createdAt : now,
         updatedAt: now,
@@ -337,9 +349,10 @@ export function registerSiliconEmployeeRoutes(app, deps) {
             const employee = isFixedAvatarEmployee(definition)
                 ? parseFixedAvatarEmployeeInput(input, definition, now)
                 : isBuiltinSiliconEmployee(existing)
-                    ? { ...existing, agents: parseSystemEmployeeAgents(input, existing), updatedAt: now }
-                    : parseSiliconEmployeeInput(input, existing, now);
+                    ? { ...existing, agents: parseSystemEmployeeAgents(input, existing), systemSessionLimit: parseSystemSessionLimit(input.systemSessionLimit, existing), updatedAt: now }
+                    : parseSiliconEmployeeInput({ ...definition, ...input }, definition, now);
             storage.saveSiliconEmployee(employee);
+            systemAiSessions(storage).enforceRetention(employee.id);
             notifyEmployee(employee.id);
             res.json(storage.getSiliconEmployee(employee.id));
         }

package/dist/server-local-model-routes.js

@@ -1,10 +1,9 @@
 import { DecisionError } from "./decision-types.js";
-import { SpeechError } from "./speech-service.js";
 /** Behind generic /api authentication; inference-only capabilities cannot install dependencies. */
 export function registerLocalModelRoutes(app, deps) {
     app.use("/api/local-models", deps.requireSessions, (_req, res, next) => { res.set("Cache-Control", "no-store"); next(); });
     const kind = (req, res, next) => {
-        if (req.params.kind !== "laya" && req.params.kind !== "speech") {
+        if (req.params.kind !== "laya") {
             res.status(404).json({ error: "未知本地模型。" });
             return;
         }
@@ -51,20 +50,8 @@ export function registerLocalModelRoutes(app, deps) {
             next(error);
         }
     });
-    app.patch("/api/local-models/speech/settings", deps.requireAdmin, async (req, res, next) => {
-        try {
-            if (!req.body || Array.isArray(req.body) || Object.keys(req.body).length !== 1 || typeof req.body.enabled !== "boolean") {
-                throw new DecisionError("INVALID_REQUEST", "仅允许修改语音启用状态。");
-            }
-            await deps.models.setSpeechEnabled(req.body.enabled);
-            res.status(202).json(await deps.models.status());
-        }
-        catch (error) {
-            next(error);
-        }
-    });
     const errors = (error, _req, res, _next) => {
-        if (error instanceof DecisionError || error instanceof SpeechError) {
+        if (error instanceof DecisionError) {
             res.status(error.status).json({ error: error.message, code: error.code });
             return;
         }

package/dist/server-session-input-routes.js

@@ -68,11 +68,11 @@ export function registerSessionInputRoutes(app, ctx) {
             return;
         }
         try {
-            const snapshot = structured.reorderQueuedMessages(req.params.id, rawOrder.map((v) => Number(v)));
+            const snapshot = structured.reorderQueuedMessages(req.params.id, rawOrder.map((v) => Number(v)), req.body?.expectedQueue);
             res.json(sessionResponseDTO(snapshot, req));
         }
         catch (error) {
-            sendRouteError(res, surfaceDomainError(error, /^(排序长度与当前队列不一致，请刷新后重试。|排序参数无效。)$/) ?? error, "无法调整排队顺序。");
+            sendRouteError(res, surfaceDomainError(error, /^(排序长度与当前队列不一致，请刷新后重试。|排序参数无效。|排队消息已变化，请刷新后重试。)$/) ?? error, "无法调整排队顺序。");
         }
     });
     app.patch("/api/structured-sessions/:id/queued/:index", (req, res) => {
@@ -126,7 +126,7 @@ export function registerSessionInputRoutes(app, ctx) {
     }));
     app.delete("/api/structured-sessions/:id/queued", (req, res) => {
         try {
-            const snapshot = structured.clearQueuedMessages(req.params.id);
+            const snapshot = structured.clearQueuedMessages(req.params.id, req.body?.expectedQueue);
             res.json(sessionResponseDTO(snapshot, req));
         }
         catch (error) {

package/dist/server-session-lifecycle-routes.js

@@ -4,6 +4,12 @@ import { defaultRoleForCli } from "./default-employee.js";
 import { fallbackProviderModel, resolveExplicitOrFallbackModel, sessionEmployeeFields } from "./session-model.js";
 import { resolveSessionCwd } from "./session-cwd.js";
 import { asyncRoute } from "./express-async.js";
+import { principalHasScope } from "./auth.js";
+import { inferProviderFromCommand, providerCliCommand } from "./session-provider.js";
+import { recordRecentPath } from "./recent-paths.js";
+import { toSessionDetailDTO } from "./session-transport.js";
+import { compactToolMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
+import { enrichStructuredMessages } from "./structured-client-protocol.js";
 import { installedPiExtensions } from "./pi-extension-resources.js";
 import { discoverPiResources, resolvePiResourceSelection } from "./pi-resource-catalog.js";
 import { effectivePiSessionSettings, patchPiSessionSettings } from "./pi-session-settings.js";
@@ -18,9 +24,86 @@ import { getInputDebugMeta, startResumedPtySession, restoreArchivedSession } fro
 /** Session creation, metadata/provider/model settings, resume, archive and deletion routes. */
 export function registerSessionLifecycleRoutes(app, ctx) {
     const { processes, structured, storage, defaultMode, config, sessions, onSessionCreated, decisions, wantsCompactTools, sessionResponseDTO, piSettingsResponse, requirePiSession, } = ctx;
-    app.post("/api/structured-sessions", asyncRoute(async (req, res) => {
+    app.post("/api/sessions", asyncRoute(async (req, res) => {
         const body = req.body;
         try {
+            if (body.kind !== "structured" && body.kind !== "pty")
+                throw badRequest("kind 必须是 structured 或 pty。");
+            if (body.prompt !== undefined && typeof body.prompt !== "string")
+                throw badRequest("prompt 必须是字符串。");
+            if (body.initialInput !== undefined && typeof body.initialInput !== "string")
+                throw badRequest("initialInput 必须是字符串。");
+            const prompt = body.prompt?.trim();
+            if (body.kind === "pty") {
+                if (prompt !== undefined)
+                    throw badRequest("PTY 会话不接受结构化 prompt，请使用 initialInput。");
+                if ((body.engine !== undefined && body.engine !== "cli") || body.runner !== undefined
+                    || body.employeeId !== undefined || body.teamId !== undefined
+                    || (body.subject !== undefined && body.subject?.type !== "cli")) {
+                    throw badRequest("PTY 不支持 SDK engine、runner 或员工/团队身份。");
+                }
+                if (body.provider !== undefined && !isSessionProvider(body.provider))
+                    throw badRequest("请选择有效的执行工具。");
+                const interactiveShell = body.shell === true;
+                if (interactiveShell && (body.command !== undefined || body.provider !== undefined)) {
+                    throw badRequest("shell:true 不能同时指定 command 或 provider。");
+                }
+                if (!req.principal || !principalHasScope(req.principal, "admin")) {
+                    if (!interactiveShell) {
+                        const rawCommand = typeof body.command === "string" ? body.command.trim() : "";
+                        const provider = isSessionProvider(body.provider) ? body.provider : inferProviderFromCommand(rawCommand);
+                        const isProviderCli = !!provider && (!rawCommand || rawCommand === provider || rawCommand === providerCliCommand(provider));
+                        if (!isProviderCli) {
+                            res.status(403).json({ error: "当前连接只能启动已配置的 CLI 工具，不能执行自定义命令。", code: "forbidden" });
+                            return;
+                        }
+                    }
+                }
+                if (!interactiveShell && !body.command?.trim())
+                    throw badRequest("请输入要执行的命令。");
+                if (body.mode !== undefined && !isExecutionMode(body.mode))
+                    throw badRequest(`无效执行模式: ${String(body.mode)}`);
+                const initialInput = body.initialInput?.trim();
+                const origin = parseSessionCreationOrigin(body);
+                const rawModel = typeof body.model === "string" ? body.model.trim() : "";
+                const rawCommand = body.command?.trim() ?? "";
+                const provider = interactiveShell
+                    ? undefined
+                    : (isSessionProvider(body.provider) ? body.provider : inferProviderFromCommand(rawCommand) ?? "claude");
+                const command = provider === "qoder" && rawCommand === "qoder" ? "qodercli" : rawCommand;
+                const effectiveModel = provider ? rawModel || fallbackProviderModel(config, provider) : undefined;
+                const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
+                const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
+                const sessionCwd = resolveSessionCwd(body.cwd, config.defaultCwd);
+                const workspaceId = resolveWorkspaceIdForNewSession(storage, sessionCwd, body.workspaceId);
+                const role = !interactiveShell && !body.systemPrompt?.trim() && origin.sessionSource === "interactive"
+                    && (isSessionProvider(body.provider) || inferProviderFromCommand(command))
+                    ? defaultRoleForCli(storage, provider) : null;
+                const snapshot = await (interactiveShell
+                    ? processes.startShell(sessionCwd, body.mode ?? "default", {
+                        worktreeEnabled: body.worktreeEnabled === true, cols: reqCols, rows: reqRows, workspaceId,
+                        workspaceTaskId: body.workspaceTaskId, ...origin,
+                    })
+                    : processes.start(command, sessionCwd, body.mode ?? config.defaultMode, initialInput || undefined, {
+                        worktreeEnabled: body.worktreeEnabled === true, provider, model: effectiveModel, cols: reqCols, rows: reqRows,
+                        thinkingEffort: body.thinkingEffort ?? config.defaultThinkingEffort,
+                        systemPrompt: body.systemPrompt?.trim() || role?.prompt, ...sessionEmployeeFields(role),
+                        workspaceId, workspaceTaskId: body.workspaceTaskId, ...origin,
+                    }));
+                recordRecentPath(storage, snapshot.cwd);
+                const messages = enrichStructuredMessages(snapshot.messages ?? [], snapshot.id);
+                const windowed = windowMessagesForTransport(wantsCompactTools(req) ? compactToolMessagesForTransport(messages) : messages, config.cardDefaults ?? {});
+                res.status(201).json(toSessionDetailDTO(snapshot, {
+                    messages: windowed.messages, messageOffset: windowed.messageOffset, messageTotal: windowed.messageTotal,
+                }));
+                return;
+            }
+            if (body.shell !== undefined || body.command !== undefined || body.initialInput !== undefined
+                || body.kind !== "structured") {
+                throw badRequest("结构化会话不接受 PTY 参数。");
+            }
+            if (body.engine !== undefined && body.engine !== "cli" && body.engine !== "sdk")
+                throw badRequest("请选择有效的执行引擎。");
             if (body.teamId !== undefined || body.subject?.type === "team") {
                 throw badRequest("AI 团队请通过团队开工入口创建群聊。");
             }
@@ -30,7 +113,7 @@ export function registerSessionLifecycleRoutes(app, ctx) {
             if (employeeId === null || (body.employeeId !== undefined && !employeeId)) {
                 throw badRequest("employeeId 必须是员工 ID。");
             }
-            if (employeeId && (body.kind === "pty" || body.runner === "pty")) {
+            if (employeeId && body.runner === "pty") {
                 throw badRequest("硅基员工只支持结构化会话。");
             }
             const employee = employeeId ? storage.getSiliconEmployee(employeeId) : null;
@@ -103,30 +186,23 @@ export function registerSessionLifecycleRoutes(app, ctx) {
                 ...origin,
             });
             onSessionCreated?.(snapshot.cwd);
-            const prompt = body.prompt?.trim();
             if (prompt) {
-                if (body.respondImmediately === true) {
-                    // 只创建、不等首轮：整轮可能是几分钟，调用方（新建任务对话框、worktree 合并）
-                    // 等在 HTTP 上会把用户锁在「正在创建…」且关闭按钮被禁用。与
-                    // /api/sessions/:id/input 的 respondImmediately、/api/wand-tasks/:id/dispatch
-                    // 一致：先回会话快照，首轮进度继续走结构化事件。
-                    structured.sendMessage(snapshot.id, prompt).catch((error) => {
+                try {
+                    Promise.resolve(structured.sendMessage(snapshot.id, prompt)).catch((error) => {
                         console.error("[wand] Accepted structured prompt later failed", {
                             sessionId: snapshot.id,
                             error: getInputDebugMeta(error),
                         });
                     });
-                    const accepted = structured.get(snapshot.id);
-                    if (!accepted)
-                        throw badRequest("未找到该结构化会话。");
-                    res.status(201).json(sessionResponseDTO(accepted, req));
-                    return;
                 }
-                const finished = await structured.sendMessage(snapshot.id, prompt);
-                res.status(201).json(sessionResponseDTO(finished, req));
-                return;
+                catch (error) {
+                    console.error("[wand] Accepted structured prompt later failed", {
+                        sessionId: snapshot.id,
+                        error: getInputDebugMeta(error),
+                    });
+                }
             }
-            res.status(201).json(sessionResponseDTO(snapshot, req));
+            res.status(201).json(sessionResponseDTO(structured.get(snapshot.id) ?? snapshot, req));
         }
         catch (error) {
             sendRouteError(res, surfaceDomainError(error, /Wand Agent|harness|core/i) ?? error, "无法启动结构化会话。");

package/dist/server-task-routes.js

@@ -1,5 +1,7 @@
 import { taskDispatchReceipt } from "./task-dispatch-receipt.js";
-import { dispatchAgentForTask, resolveTaskDispatchTarget } from "./agent-dispatch.js";
+import { registerTaskCommentRoutes, submitTaskComment } from "./task-comment-dispatch.js";
+import { randomUUID } from "node:crypto";
+import { AgentDispatchPreflightError, dispatchAgentForTask, resolveTaskDispatchTarget } from "./agent-dispatch.js";
 import { memberAgents } from "./ai-team-types.js";
 import { defaultRoleForCli } from "./default-employee.js";
 import { asyncRoute } from "./express-async.js";
@@ -200,13 +202,7 @@ export function registerTaskRoutes(app, deps) {
         res.json(model.tasks.filter(task => workspaceId === undefined || task.workspaceId === workspaceId)
             .map(task => taskDto(deps, task, model)));
     });
-    app.get("/api/wand-tasks/:id/comments", (req, res) => {
-        if (!storage.getWandTask(req.params.id)) {
-            res.status(404).json({ error: "未找到该任务。" });
-            return;
-        }
-        res.set("Cache-Control", "no-store").json({ comments: storage.listWandTaskComments(req.params.id) });
-    });
+    registerTaskCommentRoutes(app, deps);
     app.get("/api/wand-task-agent-defaults", (_req, res) => {
         res.json(readTaskBoardLastAgent(storage));
     });
@@ -644,7 +640,6 @@ export function registerTaskRoutes(app, deps) {
                 throw badRequest("所选工具不支持该运行模式，请重新选择。");
             if (employee && body.agent !== undefined && !override)
                 throw badRequest("请选择有效的本次工具配置。");
-            const executionEmployee = employee && override ? { ...employee, agents: [override] } : employee;
             const agent = override ?? selected?.agent ?? (body.agent === undefined
                 ? cliDefault ?? task.agent ?? fallbackAgent ?? parseWandTaskAgent(JSON.stringify(body))
                 : parseTaskAgent(body.agent, task.agent?.mode, task.agent?.kind));
@@ -666,9 +661,19 @@ export function registerTaskRoutes(app, deps) {
                     assertTaskWorkspaceMove(storage, task.id, workspaceId);
                 task = storage.updateWandTask(task.id, { workspaceId }) ?? task;
             }
-            const { session, cwd, workspaceId } = await dispatchAgentForTask({ storage, config, structured: structured ?? null, processes: processes ?? null }, { task, agent, prompt, automationId: `wand-task:${task.id}`,
-                systemPrompt: employee?.prompt, employee: executionEmployee ?? undefined,
-                employeeCandidateIndex: override ? 0 : selected?.index });
+            // Compatibility creation/drag clients also enter the same durable comment path for employees.
+            // No implicit description fallback: a first dispatch needs an explicit round instruction too.
+            if (employee) {
+                const result = await submitTaskComment(deps, task.id, { requestId: text(body.requestId) || randomUUID(), body: requestedPrompt, employeeId: employee.id }, override ?? undefined);
+                const session = result.comment.dispatch?.sessionId ? sessions?.getSlim(result.comment.dispatch.sessionId)
+                    ?? storage.getSessionSlim(result.comment.dispatch.sessionId) : null;
+                if (session)
+                    storage.updateWandTask(task.id, { agent, executionSubject: { type: "employee", id: employee.id, ...(override ? { agentOverride: override } : {}) }, status: task.status === "todo" ? "doing" : task.status });
+                res.status(202).json({ ok: true, taskId: task.id, subject: { type: "employee", id: employee.id }, comment: result.comment,
+                    session: session ? { ...taskSessionSummary(session), employeeCandidateIndex: session.employeeCandidateIndex } : null });
+                return;
+            }
+            const { session, cwd, workspaceId } = await dispatchAgentForTask({ storage, config, structured: structured ?? null, processes: processes ?? null }, { task, agent, prompt, automationId: `wand-task:${task.id}` });
             task = storage.getWandTask(task.id);
             const usedSubject = subject?.type === "employee" ? { type: "employee", id: subject.id, ...(override ? { agentOverride: override } : {}) } : subject ?? { type: "cli", id: agent.provider };
             storage.updateWandTask(task.id, {
@@ -709,7 +714,7 @@ export function registerTaskRoutes(app, deps) {
             });
         }
         catch (error) {
-            sendRouteError(res, surfaceDomainError(error, /^(任务所属项目已被删除，请重新指定。|任务容器不存在，请恢复任务后再派发。|绑定员工只支持结构化会话。|员工执行候选与启动快照不一致。|当前服务未启用结构化会话，无法派发 Agent。|当前服务未启用终端会话，无法派发 Agent。|LAYA 仅支持有界决策，不能执行聊天或任务；该候选尚未接受输入。)$/) ?? error, "无法派发 Agent。");
+            sendRouteError(res, error instanceof AgentDispatchPreflightError ? badRequest(error.message) : surfaceDomainError(error, /^(任务所属项目已被删除，请重新指定。|任务容器不存在，请恢复任务后再派发。|绑定员工只支持结构化会话。|员工执行候选与启动快照不一致。|当前服务未启用结构化会话，无法派发 Agent。|当前服务未启用终端会话，无法派发 Agent。|LAYA 仅支持有界决策，不能执行聊天或任务；该候选尚未接受输入。)$/) ?? error, "无法派发 Agent。");
         }
     }));
     app.get("/api/wand-tasks/:id", asyncRoute(async (req, res) => {