c0de-agent 1.9.0 → 1.10.0

package/dist/server/agent-manager.d.ts

@@ -14,9 +14,24 @@ type ActiveRun = {
 };
 /** Agent run 跟踪器 + 控制操作。 */
 type AgentManager = {
+    /**
+     * 同步原子占位（P0-4 POST /api/chat 并发守卫）：sessionId 无条目时立即占位并返回
+     * true；已有条目（占位或活跃 run）时返回 false。has+set 一气呵成、全程无 await，
+     * 杜绝 check-then-act 竞态——此前守卫用 get 检查、真正注册在 SSE 回调内，中间隔
+     * 多个 await，双发 POST 均通过守卫后后注册覆盖前者（runs.set），且先结束者在
+     * finally unregister 时误删仍在跑的 run，abort/steer/pause 全部失效。
+     * 占位由 register 填充、unregister 释放，二者均幂等。
+     */
+    tryAcquire(sessionId: string): boolean;
+    /** 注册活跃 run；若该 sessionId 已被 tryAcquire 占位则填充该占位。 */
     register(run: ActiveRun): void;
+    /** 取活跃 run；占位期间（register 前）返回 undefined，视为无活跃 run。 */
     get(sessionId: string): ActiveRun | undefined;
+    /** 该 sessionId 是否处于占位状态（tryAcquire 后、register 前）。 */
+    isStarting(sessionId: string): boolean;
+    /** 释放条目（占位或活跃 run）；幂等。 */
     unregister(sessionId: string): void;
+    /** 活跃 run 数（不含占位）。 */
     size(): number;
     abort(sessionId: string): boolean;
     pause(sessionId: string): boolean;

package/dist/server/agent-manager.js

@@ -1,59 +1,83 @@
 // src/server/agent-manager.ts
 import { abortAgent, injectSteering, pauseAgent, resumeAgent } from '../core/index.js';
+/** 取 slot 内的活跃 run；占位（'starting'）或不存在返回 undefined。 */
+function slotRun(slot) {
+    return slot?.kind === 'run' ? slot.run : undefined;
+}
 function createAgentManager() {
     const runs = new Map();
     return {
+        tryAcquire(sessionId) {
+            if (runs.has(sessionId))
+                return false;
+            runs.set(sessionId, { kind: 'starting' });
+            return true;
+        },
         register(run) {
-            runs.set(run.sessionId, run);
+            runs.set(run.sessionId, { kind: 'run', run });
         },
         get(sessionId) {
-            return runs.get(sessionId);
+            return slotRun(runs.get(sessionId));
+        },
+        isStarting(sessionId) {
+            return runs.get(sessionId)?.kind === 'starting';
         },
         unregister(sessionId) {
             runs.delete(sessionId);
         },
         size() {
-            return runs.size;
+            let n = 0;
+            for (const slot of runs.values()) {
+                if (slot.kind === 'run')
+                    n += 1;
+            }
+            return n;
         },
         abort(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             abortAgent(run.state);
             return true;
         },
         pause(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             pauseAgent(run.state);
             return true;
         },
         resume(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             resumeAgent(run.state);
             return true;
         },
         steer(sessionId, message) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             injectSteering(run.state, message);
             return true;
         },
         children(parentSessionId) {
-            return Array.from(runs.values()).filter((r) => r.parentSessionId === parentSessionId);
+            return Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r?.parentSessionId === parentSessionId);
         },
         backgroundJobs() {
-            return Array.from(runs.values()).filter((r) => r.jobId !== undefined);
+            return Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r?.jobId !== undefined);
         },
         dispose() {
             // dev 热重载重建前调用：中止所有活跃 run（loop 在 turn/流边界检测 signal
             // → unwind → 调用方 finally 持久化 + unregister），然后清空 Map。
-            for (const run of runs.values()) {
-                abortAgent(run.state);
+            for (const slot of runs.values()) {
+                const run = slotRun(slot);
+                if (run)
+                    abortAgent(run.state);
             }
             runs.clear();
         },

package/dist/server/app.js

@@ -32,7 +32,8 @@ function createApp(ctx) {
     // spec §24.2：仅允许本地/可信 origin 跨域读，拒绝外部网页。
     app.use('*', createCORSMiddleware({ allowedOrigins: ctx.config.security.allowedOrigins }));
     // spec §24.2：Bearer token 认证（配置了 token 时生效；/api/health 探活放行）。
-    app.use('/api/*', createAuthMiddleware(ctx.config.security.authEnabled ? ctx.config.security.token : undefined));
+    // token 来源：用户配置 security.token，或启动时自动生成（ctx.authToken）。
+    app.use('/api/*', createAuthMiddleware(ctx.authToken));
     // 路由
     app.route('/api/health', createHealthRoute());
     app.route('/api/agents', createAgentRoute(ctx));

package/dist/server/context.js

@@ -35,6 +35,8 @@ function createServerContext(opts) {
         agentManager: createAgentManager(),
         permissionStore: createPermissionStore(),
         permissionMode: config.permission.defaultMode,
+        // 测试工厂不解析/生成 token（不触碰用户全局数据目录）。
+        authToken: undefined,
         agentRegistry,
         // 工作流注册表：惰性初始化，只含内置（测试工厂；生产路径走 buildServerContext）。
         get workflowRegistry() {

package/dist/server/middleware/cors.d.ts

@@ -1,10 +1,19 @@
 import type { MiddlewareHandler } from 'hono';
 /**
  * 判断 origin 是否为本地/可信来源（spec §24.2「CORS 限制本地 origin」）。
- * 允许：本机回环任意端口、file://（PWA 安装后）、浏览器扩展、'null'
- * （file 协议/隐私沙箱发出的 Origin 头）。
+ *
+ * 仅允许本机回环任意端口 + 显式配置的 allowedOrigins。
+ * 显式不放行 'null'（sandboxed iframe）、file:// 与浏览器扩展前缀——
+ * 任意网页/扩展均可伪造这些来源，等价于完全关闭 CORS 防护。
+ * 认证未启用时（authEnabled=false 的显式选择），本函数仍是唯一的跨域读取防线。
  */
 export declare function isLocalOrigin(origin: string): boolean;
+/**
+ * Origin 是否被允许（本地回环 + 配置的额外 origin）。
+ * 供 CORS 中间件与 WebSocket 升级路径共用——浏览器对 WS 不实施 CORS，
+ * 但会携带 Origin 头，必须在服务端显式校验。
+ */
+export declare function isAllowedOrigin(origin: string, allowedOrigins?: string[]): boolean;
 export type CORSOptions = {
     /** 额外允许的 origin（如远程访问场景配置的域名）。 */
     allowedOrigins?: string[];

package/dist/server/middleware/cors.js

@@ -2,23 +2,26 @@
 const LOCAL_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 /**
  * 判断 origin 是否为本地/可信来源（spec §24.2「CORS 限制本地 origin」）。
- * 允许：本机回环任意端口、file://（PWA 安装后）、浏览器扩展、'null'
- * （file 协议/隐私沙箱发出的 Origin 头）。
+ *
+ * 仅允许本机回环任意端口 + 显式配置的 allowedOrigins。
+ * 显式不放行 'null'（sandboxed iframe）、file:// 与浏览器扩展前缀——
+ * 任意网页/扩展均可伪造这些来源，等价于完全关闭 CORS 防护。
+ * 认证未启用时（authEnabled=false 的显式选择），本函数仍是唯一的跨域读取防线。
  */
 export function isLocalOrigin(origin) {
     if (!origin)
         return false;
-    if (LOCAL_ORIGIN.test(origin))
-        return true;
-    if (origin === 'null')
-        return true;
-    if (origin.startsWith('file://'))
-        return true;
-    if (origin.startsWith('chrome-extension://'))
-        return true;
-    if (origin.startsWith('moz-extension://'))
+    return LOCAL_ORIGIN.test(origin);
+}
+/**
+ * Origin 是否被允许（本地回环 + 配置的额外 origin）。
+ * 供 CORS 中间件与 WebSocket 升级路径共用——浏览器对 WS 不实施 CORS，
+ * 但会携带 Origin 头，必须在服务端显式校验。
+ */
+export function isAllowedOrigin(origin, allowedOrigins) {
+    if (isLocalOrigin(origin))
         return true;
-    return false;
+    return allowedOrigins?.includes(origin) ?? false;
 }
 /**
  * CORS 中间件：仅对本地/可信 origin 回显 Access-Control-Allow-Origin，

package/dist/server/routes/chat.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { createAgent, runAgent } from '../../core/agent.js';
@@ -9,8 +9,8 @@ import { buildWorkflowNotice, containsWorkflow } from '../../core/workflow.js';
 import { getProject } from '../../project/project.js';
 import { getLLMSegments, getSession, updateSessionLastRun } from '../../session/session.js';
 import { upsertFileSnapshot } from '../../session/snapshot.js';
+import { resolveEnabledToolNames } from '../../tools/index.js';
 import { autoAllowChecker } from '../../tools/permission.js';
-import { listTools } from '../../tools/registry.js';
 import { apiError } from '../middleware/error.js';
 import { createInteractivePermissionChecker } from '../permission/interactive.js';
 import { safeResolve } from '../util/safe-path.js';
@@ -160,6 +160,7 @@ function createChatRoute(ctx) {
             }
         }
         // @文件上下文：读取文件内容写入快照，后续 getSessionContext→injectSnapshots 自动注入。
+        // 快照记录文件 mtime——注入前比对磁盘，过期自动刷新（P1-5）。
         // 路径越界或读取失败静默跳过，不阻塞主对话流。
         const files = body.files;
         if (files?.length) {
@@ -168,8 +169,13 @@ function createChatRoute(ctx) {
                 if (!resolved)
                     continue;
                 try {
+                    // 先 stat 再 readFile（与 session/context.ts 刷新路径一致）：若先读后
+                    // stat，文件恰在两次调用间被写会存「旧内容 + 新 mtime」，注入前的
+                    // mtime 相等判定使旧内容被永久钉住；先 stat 后读最坏存「新内容 +
+                    // 旧 mtime」，下次注入仍会触发刷新，可自愈。
+                    const st = await stat(resolved);
                     const content = await readFile(resolved, 'utf-8');
-                    await upsertFileSnapshot(ctx.db, sessionId, p, content);
+                    await upsertFileSnapshot(ctx.db, sessionId, p, content, st.mtimeMs);
                 }
                 catch {
                     // 文件读取失败静默跳过
@@ -178,175 +184,230 @@ function createChatRoute(ctx) {
         }
         const provider = body.provider ?? ctx.config.defaultProvider;
         const model = body.model ?? ctx.config.defaultModel;
-        // 前端 ToolToggle 全选时不传 tools（undefined），语义为「启用全部注册工具」。
-        // 显式传 [] 才是禁用全部。config.tools.enabled 仅 CLI 模式使用，此处不回退它，
-        // 避免配置里 enabled:[] 把 Web 全选误降级为无工具（LLM 无法 function call）。
-        const tools = body.tools ??
-            listTools(ctx.toolRegistry, { config: {}, cwd }).map((t) => t.name);
-        // primary agent 解析（spec: agent-frontend-switching §4.3）
-        const agentName = body.agent ?? 'default';
-        const agentDef = ctx.agentRegistry.get(agentName);
-        if (!agentDef || agentDef.mode === 'subagent') {
-            return apiError(c, 400, 'INVALID_AGENT', `Unknown or non-primary agent: ${agentName}`);
+        // 并发守卫（P0-4）：同步原子占位 tryAcquire（Map has+set 一气呵成、无 await）。
+        // 旧实现先 get 检查、真正 register 在 SSE 回调内，两者之间隔多个 await
+        // （getLLMSegments、createAgent 等）：双发 POST 在窗口内均通过守卫，后注册
+        // 覆盖前者（agentManager runs.set），且 A 结束时 unregister 把仍在跑的 B
+        // 删掉，abort/steer/pause 对 B 全部失效。占位失败说明该会话已被占用
+        // （活跃 run 或另一请求的占位），立即 409。
+        if (!ctx.agentManager.tryAcquire(sessionId)) {
+            return apiError(c, 409, 'RUN_ACTIVE', '该会话已有进行中的对话');
         }
-        // agent def 覆盖：tools（plan 限只读）、model（可选）
-        const resolvedTools = agentDef.tools ?? tools;
-        const resolvedModel = agentDef.model ?? model;
-        // 分段预检：切换 provider/model/tools 将开新段（前缀失效→缓存 miss），
-        // 需用户显式确认（confirmSegmentBreak）。首轮无活跃段时跳过。
-        const existingRun = ctx.agentManager.get(sessionId);
-        const segs = existingRun ? existingRun.state.segments : await getLLMSegments(ctx.db, sessionId);
-        const active = segs[segs.length - 1];
-        if (active) {
-            const reqTools = new Set(resolvedTools);
-            const segTools = new Set(active.tools.map((t) => t.name));
-            const toolsDiffer = reqTools.size !== segTools.size || [...reqTools].some((t) => !segTools.has(t));
-            const modelDiffer = active.provider !== provider || active.model !== resolvedModel;
-            // 旧段 agentName undefined 视为 'default'
-            const agentDiffer = (active.agentName ?? 'default') !== agentName;
-            const confirmed = body.confirmSegmentBreak === true;
-            if ((modelDiffer || toolsDiffer || agentDiffer) && !confirmed) {
-                return apiError(c, 409, 'SEGMENT_BREAK_REQUIRED', '切换模型/工具将开始新的上下文段（缓存失效），需用户确认', {
-                    activeSegment: {
-                        provider: active.provider,
-                        model: active.model,
-                        tools: active.tools.map((t) => t.name),
-                    },
-                });
-            }
-        }
-        return streamSSE(c, async (stream) => {
-            // 权限检查器：ask 权限通过 SSE 通知前端，阻塞等待确认
-            const permissionChecker = createInteractivePermissionChecker(ctx.permissionStore, {
-                getMode: () => ctx.permissionMode,
-                onPermissionRequired: async (req) => {
-                    await stream.writeSSE({
-                        event: 'permission_required',
-                        data: JSON.stringify({ _tag: 'permission_required', ...req }),
-                    });
-                },
-            });
-            // cwd 已在斜杠拦截前解析，此处直接复用
-            // 构建 agent 依赖（注入测试用 chatStream）
-            const deps = {
-                db: ctx.db,
-                llmRegistry: ctx.llmRegistry,
-                toolRegistry: ctx.toolRegistry,
-                urlRegistry: ctx.urlRegistry,
-                hookRunner: ctx.hookRunner,
-                permission: permissionChecker,
-                config: ctx.config,
-                agentRegistry: ctx.agentRegistry,
-                cwd,
-                ...(ctx.chatStream ? { chatStream: ctx.chatStream } : {}),
-            };
-            const agentConfig = {
-                provider,
-                model: resolvedModel,
-                tools: resolvedTools,
-                plugins: ctx.config.plugins.enabled,
-                agentName,
-                ...(agentDef.systemPrompt ? { agentRolePrompt: agentDef.systemPrompt } : {}),
-            };
-            const state = await createAgent(session, agentConfig, deps);
-            // 持久化 run 状态：status='running' 写入 DB。服务重启后此字段仍为 'running'
-            // 而进程无活跃 run → 检测为 interrupted。finally 中标记 'completed'。
-            const runStartedAt = Date.now();
-            await updateSessionLastRun(ctx.db, sessionId, {
-                status: 'running',
-                ...(agentName !== 'default' ? { agentName } : {}),
-                provider,
-                model: resolvedModel,
-                startedAt: runStartedAt,
-            });
-            ctx.agentManager.register({ sessionId, state, deps });
-            // workflowz 关键词检测：用户消息包含独立关键词时注入工作流通知（steering），
-            // 引导模型用 task 工具批量 fan-out 做确定性多子 agent 分解。
-            if (containsWorkflow(message)) {
-                const wfList = ctx.workflowRegistry
-                    ? ctx.workflowRegistry.list().map((w) => ({
-                        name: w.meta.name,
-                        description: w.meta.description,
-                    }))
-                    : [];
-                injectSteering(state, buildWorkflowNotice(wfList));
+        // 占位持有期（tryAcquire → SSE 回调 register）内的任何提前返回或抛错都必须
+        // 释放占位，否则该会话被永久 409 锁死。handedOff 标记所有权已移交 SSE 回调
+        // （其 finally 负责幂等释放），移交前的全部路径在 finally 统一兜底释放。
+        let handedOff = false;
+        try {
+            // 工具解析（P1-1）：config.tools.enabled 非空时作为默认集；空 = 全部注册工具。
+            // disabled 已在 registry 层过滤（createDefaultRegistry），此处兜底。
+            const tools = resolveEnabledToolNames(ctx.toolRegistry, ctx.config, body.tools);
+            // primary agent 解析（spec: agent-frontend-switching §4.3）
+            const agentName = body.agent ?? 'default';
+            const agentDef = ctx.agentRegistry.get(agentName);
+            if (!agentDef || agentDef.mode === 'subagent') {
+                return apiError(c, 400, 'INVALID_AGENT', `Unknown or non-primary agent: ${agentName}`);
             }
-            // 客户端断开时中止 agent
-            stream.onAbort(() => {
-                ctx.agentManager.abort(sessionId);
-            });
-            // 跟踪 done 事件是否已发送：agentLoop 正常完成时 yield done；
-            // 但 error/abort/max_turns 等路径不 yield done，需在 finally 补发。
-            // 否则前端 isStreaming 永远不会变 false，按钮卡在「终止」态。
-            let doneSent = false;
-            try {
-                for await (const event of runAgent(state, userContent, deps)) {
-                    if (event._tag === 'done')
-                        doneSent = true;
-                    await stream.writeSSE({
-                        event: event._tag,
-                        data: JSON.stringify(event),
+            // agent def 覆盖：tools（plan 限只读）、model（可选）
+            const resolvedTools = agentDef.tools ?? tools;
+            const resolvedModel = agentDef.model ?? model;
+            // 分段预检：切换 provider/model/tools 将开新段（前缀失效→缓存 miss），
+            // 需用户显式确认（confirmSegmentBreak）。首轮无活跃段时跳过。
+            // 守卫 409 短路后 agentManager.get 恒为 undefined，原 existingRun 三元
+            // 恒走 else 分支（死代码，已删除）。
+            const segs = await getLLMSegments(ctx.db, sessionId);
+            const active = segs[segs.length - 1];
+            if (active) {
+                const reqTools = new Set(resolvedTools);
+                const segTools = new Set(active.tools.map((t) => t.name));
+                const toolsDiffer = reqTools.size !== segTools.size || [...reqTools].some((t) => !segTools.has(t));
+                const modelDiffer = active.provider !== provider || active.model !== resolvedModel;
+                // 旧段 agentName undefined 视为 'default'
+                const agentDiffer = (active.agentName ?? 'default') !== agentName;
+                const confirmed = body.confirmSegmentBreak === true;
+                if ((modelDiffer || toolsDiffer || agentDiffer) && !confirmed) {
+                    return apiError(c, 409, 'SEGMENT_BREAK_REQUIRED', '切换模型/工具将开始新的上下文段（缓存失效），需用户确认', {
+                        activeSegment: {
+                            provider: active.provider,
+                            model: active.model,
+                            tools: active.tools.map((t) => t.name),
+                        },
                     });
                 }
             }
-            catch (err) {
-                const message = err instanceof Error
-                    ? err.message
-                    : typeof err === 'object' && err !== null && 'message' in err
-                        ? String(err.message)
-                        : String(err);
-                await stream.writeSSE({
-                    event: 'error',
-                    data: JSON.stringify({
-                        _tag: 'error',
-                        error: {
-                            _tag: 'unexpected',
-                            message,
+            const response = streamSSE(c, async (stream) => {
+                // P0-4：回调从首行起全部纳入 try/finally——createAgent、updateSessionLastRun
+                // 等启动阶段失败同样必须释放占位并补发 error/done（hono 的 stream 包装器
+                // 只 console.error 不善后），不得泄漏占位或让前端卡在 streaming 态。
+                let doneSent = false;
+                let runStartedAt;
+                try {
+                    // 权限检查器：ask 权限通过 SSE 通知前端，阻塞等待确认
+                    const permissionChecker = createInteractivePermissionChecker(ctx.permissionStore, {
+                        getMode: () => ctx.permissionMode,
+                        onPermissionRequired: async (req) => {
+                            await stream.writeSSE({
+                                event: 'permission_required',
+                                data: JSON.stringify({ _tag: 'permission_required', ...req }),
+                            });
                         },
-                    }),
-                });
-            }
-            finally {
-                // 先从 agentManager 注销：必须最先执行，确保客户端断开使 writeSSE reject
-                // 时 agent 状态（state/deps/AbortController）不会泄漏到 Map（unregister 仅做
-                // Map.delete、不依赖 state，放最前安全）。
-                ctx.agentManager.unregister(sessionId);
-                // agentLoop 的 error/abort/max_turns 路径不 yield done，在此补发。
-                // 正常完成路径已在循环中 yield done，doneSent=true 时跳过避免重复。
-                // 客户端已断开时 writeSSE 会 reject，吞掉以保证后续 updateSessionLastRun 执行。
-                if (!doneSent) {
+                    });
+                    // cwd 已在斜杠拦截前解析，此处直接复用
+                    // 构建 agent 依赖（注入测试用 chatStream）
+                    const deps = {
+                        db: ctx.db,
+                        llmRegistry: ctx.llmRegistry,
+                        toolRegistry: ctx.toolRegistry,
+                        urlRegistry: ctx.urlRegistry,
+                        hookRunner: ctx.hookRunner,
+                        permission: permissionChecker,
+                        config: ctx.config,
+                        agentRegistry: ctx.agentRegistry,
+                        cwd,
+                        ...(ctx.chatStream ? { chatStream: ctx.chatStream } : {}),
+                    };
+                    const agentConfig = {
+                        provider,
+                        model: resolvedModel,
+                        tools: resolvedTools,
+                        plugins: ctx.config.plugins.enabled,
+                        agentName,
+                        ...(agentDef.systemPrompt ? { agentRolePrompt: agentDef.systemPrompt } : {}),
+                    };
+                    const state = await createAgent(session, agentConfig, deps);
+                    // 持久化 run 状态：status='running' 写入 DB。服务重启后此字段仍为 'running'
+                    // 而进程无活跃 run → 检测为 interrupted。finally 中标记 'completed'。
+                    runStartedAt = Date.now();
+                    await updateSessionLastRun(ctx.db, sessionId, {
+                        status: 'running',
+                        ...(agentName !== 'default' ? { agentName } : {}),
+                        provider,
+                        model: resolvedModel,
+                        startedAt: runStartedAt,
+                    });
+                    // 填充 tryAcquire 留下的占位（原 register 语义：按 sessionId 覆盖写入）
+                    ctx.agentManager.register({ sessionId, state, deps });
+                    // workflowz 关键词检测：用户消息包含独立关键词时注入工作流通知（steering），
+                    // 引导模型用 task 工具批量 fan-out 做确定性多子 agent 分解。
+                    if (containsWorkflow(message)) {
+                        const wfList = ctx.workflowRegistry
+                            ? ctx.workflowRegistry.list().map((w) => ({
+                                name: w.meta.name,
+                                description: w.meta.description,
+                            }))
+                            : [];
+                        injectSteering(state, buildWorkflowNotice(wfList));
+                    }
+                    // 客户端断开时中止 agent
+                    stream.onAbort(() => {
+                        ctx.agentManager.abort(sessionId);
+                    });
+                    // 跟踪 done 事件是否已发送：agentLoop 正常完成时 yield done；
+                    // 但 error/abort/max_turns 等路径不 yield done，需在 finally 补发。
+                    // 否则前端 isStreaming 永远不会变 false，按钮卡在「终止」态。
+                    try {
+                        for await (const event of runAgent(state, userContent, deps)) {
+                            if (event._tag === 'done')
+                                doneSent = true;
+                            await stream.writeSSE({
+                                event: event._tag,
+                                data: JSON.stringify(event),
+                            });
+                        }
+                    }
+                    catch (err) {
+                        const message = err instanceof Error
+                            ? err.message
+                            : typeof err === 'object' && err !== null && 'message' in err
+                                ? String(err.message)
+                                : String(err);
+                        await stream.writeSSE({
+                            event: 'error',
+                            data: JSON.stringify({
+                                _tag: 'error',
+                                error: {
+                                    _tag: 'unexpected',
+                                    message,
+                                },
+                            }),
+                        });
+                    }
+                }
+                catch (err) {
+                    // 启动阶段（createAgent/updateSessionLastRun 等）失败：补发 error 事件。
+                    // 客户端已断开时 writeSSE 会 reject，吞掉以保证 finally 善后执行。
                     await stream
-                        .writeSSE({ event: 'done', data: JSON.stringify({ _tag: 'done' }) })
+                        .writeSSE({
+                        event: 'error',
+                        data: JSON.stringify({
+                            _tag: 'error',
+                            error: {
+                                _tag: 'unexpected',
+                                message: err instanceof Error ? err.message : String(err),
+                            },
+                        }),
+                    })
                         .catch(() => { });
                 }
-                // 无论正常完成、错误还是 abort，只要服务还活着就标记 completed。
-                // 只有服务崩溃/重启才会留下 status='running' → 下次加载检测为 interrupted。
-                await updateSessionLastRun(ctx.db, sessionId, {
-                    status: 'completed',
-                    ...(agentName !== 'default' ? { agentName } : {}),
-                    provider,
-                    model: resolvedModel,
-                    startedAt: runStartedAt,
-                }).catch(() => { });
-            }
-        });
+                finally {
+                    // 先从 agentManager 释放（占位与活跃 run 均幂等）：必须最先执行，确保
+                    // 客户端断开使 writeSSE reject 时 agent 状态（state/deps/AbortController）
+                    // 不会泄漏到 Map（unregister 仅做 Map.delete、不依赖 state，放最前安全）。
+                    ctx.agentManager.unregister(sessionId);
+                    // agentLoop 的 error/abort/max_turns 路径不 yield done，在此补发。
+                    // 正常完成路径已在循环中 yield done，doneSent=true 时跳过避免重复。
+                    // 客户端已断开时 writeSSE 会 reject，吞掉以保证后续 updateSessionLastRun 执行。
+                    if (!doneSent) {
+                        await stream
+                            .writeSSE({ event: 'done', data: JSON.stringify({ _tag: 'done' }) })
+                            .catch(() => { });
+                    }
+                    // 无论正常完成、错误还是 abort，只要服务还活着就标记 completed。
+                    // 只有服务崩溃/重启才会留下 status='running' → 下次加载检测为 interrupted。
+                    // runStartedAt 未定义说明 run 从未真正启动（createAgent 即失败），DB 中
+                    // 无 'running' 标记需要清理，跳过写入。
+                    if (runStartedAt !== undefined) {
+                        await updateSessionLastRun(ctx.db, sessionId, {
+                            status: 'completed',
+                            ...(agentName !== 'default' ? { agentName } : {}),
+                            provider,
+                            model: resolvedModel,
+                            startedAt: runStartedAt,
+                        }).catch(() => { });
+                    }
+                }
+            });
+            // streamSSE 已同步启动回调（回调的 register/finally 从此接管占位填充与
+            // 释放），所有权移交：本层 finally 不再兜底释放。
+            handedOff = true;
+            return response;
+        }
+        finally {
+            if (!handedOff)
+                ctx.agentManager.unregister(sessionId);
+        }
     });
     // 控制端点
+    // P0-4：占位中的会话（tryAcquire 后、register 前）run 尚无 state 可供
+    // abort/pause/resume/steer 操作——返回明确 409 而非静默 false 或崩溃。
+    const runStarting = (c, sessionId) => ctx.agentManager.isStarting(sessionId)
+        ? apiError(c, 409, 'RUN_STARTING', '该会话的对话正在启动，请稍后重试')
+        : undefined;
     app.post('/abort', async (c) => {
         const { sessionId } = await c.req.json();
-        return c.json({ aborted: ctx.agentManager.abort(sessionId) });
+        return runStarting(c, sessionId) ?? c.json({ aborted: ctx.agentManager.abort(sessionId) });
     });
     app.post('/pause', async (c) => {
         const { sessionId } = await c.req.json();
-        return c.json({ paused: ctx.agentManager.pause(sessionId) });
+        return runStarting(c, sessionId) ?? c.json({ paused: ctx.agentManager.pause(sessionId) });
     });
     app.post('/resume', async (c) => {
         const { sessionId } = await c.req.json();
-        return c.json({ resumed: ctx.agentManager.resume(sessionId) });
+        return runStarting(c, sessionId) ?? c.json({ resumed: ctx.agentManager.resume(sessionId) });
     });
     app.post('/steer', async (c) => {
         const body = await c.req.json();
-        return c.json({ steered: ctx.agentManager.steer(body.sessionId, body.message) });
+        return (runStarting(c, body.sessionId) ??
+            c.json({ steered: ctx.agentManager.steer(body.sessionId, body.message) }));
     });
     return app;
 }