@tea-agent/loop-agent 0.43.0-next.3 → 0.43.0-next.4

package/CHANGELOG.md

@@ -2,25 +2,26 @@
 
 ## [Unreleased]
 
+### 新增
+
+- Operator Chat 在具备 Aimax 凭据资格时，向对话进程注入 `$AIMAX_AUTH_TOKEN`（明文或 `sm4:v1:` 解密后的 ticket），供 skills 读取；文件缺失、无法解析或解密失败时不注入该变量。
+- Operator Chat 终端管理（DSH 风格）：模型获得 `terminal` 持久 PTY 工具（跨平台 shell 目录——Windows 提供 powershell/bash，macOS/Linux 提供 bash/zsh，pwsh 7 装了即用；cwd/环境变量/后台任务跨调用保留，完成标记协议 + 超时与截断保护，枚举与默认值按平台动态生成）；Console 右侧辅助栏新增「终端」面板（xterm.js 渲染，实时查看/接管模型的 shell，按平台动态展示可创建的 shell，支持发送输入、Ctrl+C、终止并关闭）；模型 shell 与用户面板共用同一会话注册表并开在工作区仓库根目录，命名区分来源。
+
 ### 改进
 
-- 前端 DAG 修正否定约束导致的小任务误升级；Plan 在分片前统一 compact 判定并保留完整执行组。支持冻结 coverage 并发上限（1–4，默认 4），限流后减少后续并发且不增加重试。自动恢复子进程与 DAG 共用长跑超时，避免继承通用 120 秒上限而中途终止。
-- 前端 DAG 保留完整需求并按作用域/执行组分批，工具提交改为先校验和耐久保存再回执；支持按组共享覆盖、逐端点/逐 finding 提交和缺项恢复。小任务走短流程，容量耗尽直接缩小剩余工作；模型窗口不再硬编码为 100K/16K。独立 AC、来源保真与 writer/verify 门禁保持有效。
-- 观测台阅读与口径修补：失败节点的产出页把「错误输出」提到正文之前，未登记文件关系时不再展示空文件卡；检查器 Tab 条放不下时两端渐隐提示并保证选中 Tab 可见，每页顶部说明卡可收起。异常 Task 的分类与建议跟进显示中文业务术语（未知 token 原样透传并可悬停看原始值），资源池「合计」改为口径明确的「已建 Task」并附悬停说明，数据更新文案改为「数据更新于 … · 仅提示」。DAG 详情面包屑使用可读运行标题（缺失回退运行 ID、窄屏截断），「记录保存位置」移入「诊断信息」折叠区，页面刷新按钮与标题同行靠右。
-- 观测台保留检查器 Tab 导航，日志分类收进下拉框，辅助操作改为带提示的图标；所有执行记录区域（检查器执行记录/产出、运行页最新输出）统一配备对话式「回到底部」悬浮按钮：内容可滚动且视口离开底部即出现，贴底或内容不足一屏时隐藏，点击回到底部；活跃运行同时恢复跟随并提示未读条数，终态运行同样可用。执行分次仅在相关页面固定显示，上翻暂停跟随，并记住分次阅读位置。补充日志搜索、错误过滤、图定位和完整脱敏文本下载。
-- 实际上下文改为中文材料目录优先、技术信息折叠；修复历史轮次混读当前上下文和旧请求覆盖新尝试的问题。保留仅看错误与原始协议事件，原始协议使用直接可达的图标开关，移除单项更多菜单和日志 HTML 导出；交接包明确固定来源并支持刷新。
-- 检查器隐藏无内容或明确不适用的入口：单次执行不显示尝试对比，Shell/静态节点不显示实际上下文，静态节点不显示执行记录；切换节点与新增尝试时自动更新，保留用户当前的比较选择。
-- 资源池筛选覆盖任务标题和全部任务区域，返回列表及历史分页保留阅读状态；重跑草稿和影响预览可恢复，结果不确定时原样重试已确认的请求，避免重复创建运行。
-- 执行记录默认跟随最新内容；上翻自动暂停并出现对话式「回到底部」按钮，点击回到底部；历史记录保留阅读位置，终态运行同样可用。
-- DAG 节点检查器仅对最新且仍运行的执行默认跟随；右下角显示阅读状态、新记录提示和“回到最新”，上翻即暂停。
+- 优化 Operator Chat 长会话的流式渲染：完成回合、消息行、工具卡和用户输入锚点建立稳定的 memo 边界，流式文本更新不再重复渲染整段历史或重装锚点测量监听；缓存会在历史消息或工具实际更新时正确失效；无新增折叠回合时不再提交空状态及重复写入本地存储，工具参数与结果格式化按真实输入变化缓存。
+- 对话页「过程折叠」对齐 DSH 细节：折叠后的内容仍保留在页面中，浏览器 Ctrl+F 可直接命中并自动展开；折叠行展开时不再多出底部空隙；箭头改为 16px、颜色更淡的固定图标（靠旋转而非换图标），并补齐系统「减少动态效果」偏好；汇总文案新增「N 个 subagent」，内置 Explore 子代理不再计入普通工具调用。
 
 ### 修复
 
-- 前端 Plan 重试复用首次冻结的分片归属，避免重试提示词变长导致进度绑定不匹配或重复处理已完成需求；布局缺失、损坏或漂移时保留证据并阻断派发。风险路由仅忽略完整的范围排除声明，条件句和嵌套否定中的真实权限风险在生成期与运行期均保持升级。
-- 执行记录搜索直接高亮命中文字，标识当前跳转记录；未搜索或无匹配时禁用上下箭头，清空搜索恢复原文。
-
-- 恢复运行在导入节点缺少明确读取范围时阻断工作区漂移，避免复用受变更影响的旧结果；读取范围明确且不受影响时仍可按路径复用。
-- 前端验证将子目录执行的 Vitest 报告统一为仓库相对路径，并对齐实际目录别名，避免已通过测试被误判为未执行；被筛除或失败的目标仍阻断。
+- 修复对话页存在运行活动时，收起状态的右侧辅助栏展开按钮覆盖「运行活动 N」及数字徽标的问题；中大尺寸布局现在保留 8px 操作间距，窄屏布局不变。
+- 修复 Operator Chat 消息流的六处实际使用问题：
+  - **回复被吞**：断线/重连（含每 25 秒的 SSE 事件窗口轮转）后，保留事件里已经生成的正文会在事件流恢复时重新应用到对应回合，不再被静默丢弃；仅当该回合已有更新内容时才跳过，避免重复气泡。
+  - **用户输入消失或重复**：服务端确认后，提交回滚（排队抢占、被拒绝、连接失败）不再删掉已确认的消息；确认帧到达时按请求 ID 或持久消息 ID 原地合并乐观气泡与会话快照，retained replay 不再追加同一条用户消息。
+  - **回复重复**：上下文溢出自动压缩并重新生成后，被打断的旧回复会被取代，不再与重新生成的回复同时显示。
+  - **只有思考没有正文**：模型回复以工具调用或思考结尾时，正文会作为回答显示，不再被折叠进「过程」区。
+  - **空气泡误删**：只包含思考或工具内容、正文为空的回合不再被清理掉。
+  - **停止语义**：被停止中断的工具调用显示「已停止」，不再显示为「出错」并强制展开、计入「N 次出错」。
 
 ## [0.42.0] - 2026-09-07
 

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.43.0-next.3",
-  "gitSha": "58353199a043d50d24063322a173d81b4b8f1d2f",
-  "builtAt": "2026-09-08T04:08:10.997Z"
+  "version": "0.43.0-next.4",
+  "gitSha": "a40dde963afaa57ff95e0e49aa33e051b5580827",
+  "builtAt": "2026-09-08T23:28:40.065Z"
 }

package/dist/worker/console/chat/assistant-content.js

@@ -115,9 +115,30 @@ export function splitFinalAssistantBlocks(blocks, options = {}) {
     if (lastProcessIndex === -1) {
         return { answerBlocks: displayable, processBlocks: [] };
     }
+    const trailing = displayable.slice(lastProcessIndex + 1);
+    if (trailing.length > 0) {
+        return {
+            answerBlocks: trailing,
+            processBlocks: displayable.slice(0, lastProcessIndex + 1),
+        };
+    }
+    // The stage ends on a non-text block (a tool call after the prose, or a final
+    // thinking block). Returning an empty answer here hid the whole reply inside
+    // the collapsed process subtree; keep the last prose block as the visible
+    // answer instead (2026-09-08).
+    let lastTextIndex = -1;
+    for (let i = displayable.length - 1; i >= 0; i--) {
+        if (isFinalAnswerBlock(displayable[i])) {
+            lastTextIndex = i;
+            break;
+        }
+    }
+    if (lastTextIndex === -1) {
+        return { answerBlocks: [], processBlocks: displayable };
+    }
     return {
-        answerBlocks: displayable.slice(lastProcessIndex + 1),
-        processBlocks: displayable.slice(0, lastProcessIndex + 1),
+        answerBlocks: [displayable[lastTextIndex]],
+        processBlocks: displayable.filter((_block, index) => index !== lastTextIndex),
     };
 }
 export function joinAssistantText(blocks) {

package/dist/worker/console/chat/explore-tools.js

@@ -71,6 +71,10 @@ export const SECRET_SCRUB_PATTERNS = [
         name: "private-key-block",
         re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |)PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |)PRIVATE KEY-----/g,
     },
+    {
+        name: "aimax-auth-token",
+        re: /\bAIMAX_AUTH_TOKEN=["']?[^\s"']+/g,
+    },
 ];
 /** Throw a typed explore error (kept as a value object so callers can read .code). */
 export class ExploreDeniedError extends Error {
@@ -89,6 +93,10 @@ export class ExploreDeniedError extends Error {
  */
 export function scrubSecrets(input) {
     let out = input;
+    const liveToken = process.env.AIMAX_AUTH_TOKEN;
+    if (liveToken && liveToken.length >= 8 && out.includes(liveToken)) {
+        out = out.split(liveToken).join("[REDACTED:aimax-auth-token]");
+    }
     const redactions = [];
     for (const { name, re } of SECRET_SCRUB_PATTERNS) {
         re.lastIndex = 0;
@@ -98,6 +106,11 @@ export function scrubSecrets(input) {
             redactions.push({ name, count: matches.length });
         }
     }
+    if (liveToken && liveToken.length >= 8 && input.includes(liveToken)) {
+        const existing = redactions.find((entry) => entry.name === "aimax-auth-token");
+        if (!existing)
+            redactions.push({ name: "aimax-auth-token", count: 1 });
+    }
     return { scrubbed: out, redactions };
 }
 /** True if a repo-relative path matches a sensitive-file denylist pattern. */

package/dist/worker/console/chat/pi-runtime.js

@@ -43,6 +43,7 @@ import { resolveDefaultChatModel, resolveLowChatModel, } from "./model-resolver.
 import { filterActiveInterviewTools } from "../interview/tools.js";
 import { RUNTIME_CONTEXT_TEXT_MAX, redactRuntimeText, } from "./runtime-context.js";
 import { buildTodoContinuationContext, } from "./todos.js";
+import { buildPersistentTerminalTools } from "./terminal-tools.js";
 import { buildGoalContinuationContext, } from "./goals.js";
 import { injectWizardLocalHeaders, } from "./sdd-data-alignment.js";
 /**
@@ -1054,6 +1055,9 @@ export class ConsolePiRuntime {
             },
         });
     }
+    async syncAimaxAuthToken() {
+        await this.options.sddDataAlignment?.auth?.getToken();
+    }
     /** Absolute path for repo-scoped resource preferences (may be undefined in unit tests). */
     get resourcePreferencesPath() {
         return this.options.resourcePreferencesPath;
@@ -1341,6 +1345,7 @@ export class ConsolePiRuntime {
      * `initializing: true`; dependent routes wait on the same promise.
      */
     async createSession(init) {
+        await this.syncAimaxAuthToken();
         const sessionId = `operator-chat-${randomBytes(12).toString("hex")}`;
         this.disposedSessions.delete(sessionId);
         const sessionManager = await this.bindings.createSessionManager({
@@ -1438,6 +1443,7 @@ export class ConsolePiRuntime {
     async materializeSession(sessionId, init) {
         if (this.disposedSessions.has(sessionId))
             return;
+        await this.syncAimaxAuthToken();
         const agentDir = await safeGetAgentDir(this.bindings);
         // Capture before services parse models.json. A concurrent edit can therefore
         // cause at most one harmless extra refresh, never a missed next-turn refresh.
@@ -1547,6 +1553,16 @@ export class ConsolePiRuntime {
         const goalTools = this.options.goalRegistry
             ? await buildGoalTools({ sessionId, registry: this.options.goalRegistry })
             : [];
+        const terminalTools = this.options.terminalRegistry
+            ? await buildPersistentTerminalTools({
+                ownerSessionId: sessionId,
+                registry: this.options.terminalRegistry,
+                defaultCwd: this.options.cwd,
+            }).catch((error) => {
+                process.stderr.write(`[console] chat terminal-tools build failed: ${error instanceof Error ? error.message : String(error)}\n`);
+                return [];
+            })
+            : [];
         const agentTool = await buildAgentCustomTool({
             parentSessionId: sessionId,
             orchestrator: this.exploreOrchestrator,
@@ -1571,6 +1587,7 @@ export class ConsolePiRuntime {
             ...(questionTool ? [questionTool] : []),
             ...(todoTool ? [todoTool] : []),
             ...goalTools,
+            ...terminalTools,
             ...(agentTool ? [agentTool] : []),
         ];
     }
@@ -2347,6 +2364,7 @@ export class ConsolePiRuntime {
      * than silently creating a fresh empty session and losing prior context.
      */
     async reopenSession(init) {
+        await this.syncAimaxAuthToken();
         const sessionId = init.sessionId;
         // Wait for in-flight create materialization rather than racing reopen.
         const initState = this.sessionInit.get(sessionId);

package/dist/worker/console/chat/routes.js

@@ -44,6 +44,8 @@ import { buildGoalCompactionInstructions, buildGoalContinuationContext, } from "
 import { classifyGoalRoundAdmission, } from "./goal-round-driver.js";
 import { isTerminalOperationState } from "../../../infrastructure/console/operation-store.js";
 import { SddDataAlignmentError, } from "./sdd-data-alignment.js";
+import { TerminalSessionRegistry } from "./terminal-sessions.js";
+import { handleTerminalRequest } from "./terminal-routes.js";
 function projectBrowserChatSession(record) {
     const { telemetrySessionId, ...projected } = record;
     void telemetrySessionId;
@@ -4146,6 +4148,15 @@ export async function handleChatMessages(res, deps, sessionId, url) {
 export async function handleChatRequest(req, res, deps, pathname, workspaceScope) {
     if (!deps)
         return false;
+    // Terminal management API (model + Console UI shared PTY registry).
+    if (await handleTerminalRequest(req, res, {
+        terminals: deps.terminals ?? new TerminalSessionRegistry(),
+        gateMutation: (r) => gateMutation(r, deps),
+        // Terminals open in the workspace repo root, not the Console process cwd.
+        defaultCwd: deps.appData.repoRoot,
+    }, pathname)) {
+        return true;
+    }
     if (!pathname.startsWith("/api/operator/v1/chat/") &&
         !pathname.startsWith("/api/operator/v1/pi/"))
         return false;

package/dist/worker/console/chat/sdd-data-alignment.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createDecipheriv, randomBytes } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -10,8 +10,49 @@ export const SDD_SKILL_NAMES = [
 /** Backward-compatible name for callers that need a stable representative value. */
 export const SDD_DEFAULT_SKILL_NAME = "SDD-implementation-test-review";
 export const SDD_TELEMETRY_URL = "https://wizard-ai.paic.com.cn/code_pilot/api/skill-usage-log";
-export const SDD_TELEMETRY_SIGN = "52aad0c09e6b46818a11ee702d6fe0ba";
+/** SM4 key hex; also the SDD telemetry `ws-sign` value. */
+export const DEFAULT_AI_MA_PUB_SALT_KEY = "52aad0c09e6b46818a11ee702d6fe0ba";
+export const SDD_TELEMETRY_SIGN = DEFAULT_AI_MA_PUB_SALT_KEY;
+export const AIMAX_AUTH_TOKEN_ENV = "AIMAX_AUTH_TOKEN";
 export const WIZARD_LOCAL_DEFAULT_USER_AGENT = "Builder/OpenCode ai-sdk/provider-utils/4.0.21 runtime/bun/1.3.11";
+const SM4_V1_PREFIX = "sm4:v1:";
+/** Decode a plaintext ticket or `sm4:v1:` ciphertext. Unknown prefixes and crypto errors fail closed. */
+export function decodeAimaxAuthToken(raw, keyHex = DEFAULT_AI_MA_PUB_SALT_KEY) {
+    const candidate = raw.trim();
+    if (!candidate)
+        return undefined;
+    if (!candidate.startsWith("sm4:"))
+        return candidate;
+    if (!candidate.startsWith(SM4_V1_PREFIX))
+        return undefined;
+    const hex = candidate.slice(SM4_V1_PREFIX.length);
+    if (!hex || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex))
+        return undefined;
+    const key = Buffer.from(keyHex.trim(), "hex");
+    if (key.length !== 16)
+        return undefined;
+    try {
+        const encrypted = Buffer.from(hex, "hex");
+        if (encrypted.length === 0 || encrypted.length % 16 !== 0)
+            return undefined;
+        const decipher = createDecipheriv("sm4-ecb", key, null);
+        decipher.setAutoPadding(true);
+        const plain = Buffer.concat([decipher.update(encrypted), decipher.final()])
+            .toString("utf8")
+            .trim();
+        return plain || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Set or delete `AIMAX_AUTH_TOKEN`. Empty string is treated as absent. */
+export function syncAimaxAuthTokenEnv(env, token) {
+    if (token)
+        env[AIMAX_AUTH_TOKEN_ENV] = token;
+    else
+        delete env[AIMAX_AUTH_TOKEN_ENV];
+}
 function sameAuthFileVersion(left, right) {
     if (!left.exists || !right.exists)
         return left.exists === right.exists;
@@ -21,9 +62,22 @@ function sameAuthFileVersion(left, right) {
 /** Reads ~/.aima-go/auth.json with metadata-based parse caching and fail-closed semantics. */
 export class AimaxAuthReader {
     authFile;
+    env;
     cached;
-    constructor(authFile = path.join(os.homedir(), ".aima-go", "auth.json")) {
+    constructor(authFile = path.join(os.homedir(), ".aima-go", "auth.json"), env = process.env) {
         this.authFile = authFile;
+        this.env = env;
+    }
+    resolveKeyHex() {
+        const injected = typeof this.env.AI_MA_PUB_SALT_KEY === "string" ? this.env.AI_MA_PUB_SALT_KEY.trim() : "";
+        if (injected)
+            return injected;
+        const host = process.env.AI_MA_PUB_SALT_KEY?.trim();
+        return host || DEFAULT_AI_MA_PUB_SALT_KEY;
+    }
+    finish(token) {
+        syncAimaxAuthTokenEnv(this.env, token);
+        return token;
     }
     async getToken() {
         let version;
@@ -34,22 +88,24 @@ export class AimaxAuthReader {
         }
         catch {
             this.cached = { version: { exists: false } };
-            return undefined;
+            return this.finish(undefined);
+        }
+        if (this.cached && sameAuthFileVersion(this.cached.version, version)) {
+            return this.finish(this.cached.token);
         }
-        if (this.cached && sameAuthFileVersion(this.cached.version, version))
-            return this.cached.token;
         let token;
         try {
             const parsed = JSON.parse(await readFile(this.authFile, "utf8"));
             const candidate = parsed["aimax-auth-token"];
-            if (typeof candidate === "string" && candidate.trim())
-                token = candidate;
+            if (typeof candidate === "string" && candidate.trim()) {
+                token = decodeAimaxAuthToken(candidate, this.resolveKeyHex());
+            }
         }
         catch {
             // Malformed or unreadable files are intentionally ineligible.
         }
         this.cached = { version, ...(token ? { token } : {}) };
-        return token;
+        return this.finish(token);
     }
     async isEligible() {
         return Boolean(await this.getToken());

package/dist/worker/console/chat/terminal-routes.js

@@ -0,0 +1,216 @@
+/**
+ * Operator Chat — terminal management HTTP API (Console UI side).
+ *
+ * Endpoints (all under /api/operator/v1/chat):
+ *   GET  /terminals                          list terminal sessions (all owners)
+ *   POST /terminals                          spawn { shell, name?, cwd?, ownerSessionId? }
+ *   GET  /terminals/:id                      session info + buffered output
+ *   POST /terminals/:id/input                { data }  write to the PTY
+ *   POST /terminals/:id/resize               { cols, rows }
+ *   POST /terminals/:id/interrupt            send Ctrl+C
+ *   POST /terminals/:id/kill                 stop and await full exit
+ *   GET  /terminals/:id/stream               SSE: buffered replay + live chunks
+ *
+ * Mutating routes require the Console boot token (same gate as other chat
+ * mutations). The stream is read-only and uses the same origin checks as the
+ * chat event stream.
+ */
+import { TerminalSessionError, availableShellKinds, } from "./terminal-sessions.js";
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(payload);
+}
+function mapTerminalError(res, error) {
+    if (error instanceof TerminalSessionError) {
+        const status = error.code === "TERMINAL_NOT_FOUND"
+            ? 404
+            : error.code === "TERMINAL_EXITED" || error.code === "TERMINAL_SEND_ACTIVE"
+                ? 409
+                : 500;
+        sendJson(res, status, {
+            ok: false,
+            error: { code: error.code, message: error.message },
+        });
+        return;
+    }
+    sendJson(res, 500, {
+        ok: false,
+        error: {
+            code: "TERMINAL_INTERNAL",
+            message: error instanceof Error ? error.message : String(error),
+        },
+    });
+}
+async function readJsonBody(req, maxBytes = 512 * 1024) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes)
+            throw new Error("request body too large");
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw.trim())
+        return {};
+    return JSON.parse(raw);
+}
+/** Route dispatcher; returns true when the request was handled. */
+export async function handleTerminalRequest(req, res, deps, pathname) {
+    if (!pathname.startsWith("/api/operator/v1/chat/terminals"))
+        return false;
+    const method = (req.method ?? "GET").toUpperCase();
+    const rest = pathname.slice("/api/operator/v1/chat/terminals".length);
+    const parts = rest.split("/").filter(Boolean);
+    try {
+        // GET /terminals — list (+ available shell kinds for this platform)
+        if (method === "GET" && parts.length === 0) {
+            sendJson(res, 200, {
+                ok: true,
+                data: {
+                    terminals: deps.terminals.list(),
+                    availableShells: availableShellKinds().kinds,
+                },
+            });
+            return true;
+        }
+        // POST /terminals — spawn
+        if (method === "POST" && parts.length === 0) {
+            const gate = deps.gateMutation(req);
+            if (!gate.ok) {
+                sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+                return true;
+            }
+            const body = await readJsonBody(req);
+            const kinds = availableShellKinds().kinds;
+            const shell = kinds.includes(body.shell)
+                ? body.shell
+                : undefined;
+            if (!shell) {
+                sendJson(res, 400, {
+                    ok: false,
+                    error: {
+                        code: "INVALID_INPUT",
+                        message: `shell must be one of: ${kinds.join(", ")} (available on this platform)`,
+                    },
+                });
+                return true;
+            }
+            const info = deps.terminals.spawn({
+                ownerSessionId: typeof body.ownerSessionId === "string" && body.ownerSessionId
+                    ? body.ownerSessionId
+                    : "console-ui",
+                name: typeof body.name === "string" && body.name ? body.name : `${shell}-ui`,
+                shell: shell,
+                cwd: typeof body.cwd === "string" && body.cwd
+                    ? body.cwd
+                    : (deps.defaultCwd ?? undefined),
+                cols: typeof body.cols === "number" ? body.cols : undefined,
+                rows: typeof body.rows === "number" ? body.rows : undefined,
+            });
+            sendJson(res, 201, { ok: true, data: info });
+            return true;
+        }
+        const sessionId = parts[0];
+        if (!sessionId)
+            return false;
+        const sub = parts[1] ?? "";
+        // GET /terminals/:id — info + buffered output
+        if (method === "GET" && parts.length === 1) {
+            const info = deps.terminals.get(sessionId);
+            const output = deps.terminals.readAll(sessionId);
+            sendJson(res, 200, { ok: true, data: { ...info, output } });
+            return true;
+        }
+        // GET /terminals/:id/stream — SSE
+        if (method === "GET" && sub === "stream") {
+            // Validate existence first (404 before opening the stream).
+            const info = deps.terminals.get(sessionId);
+            void info;
+            res.writeHead(200, {
+                "content-type": "text/event-stream; charset=utf-8",
+                "cache-control": "no-cache, no-store",
+                connection: "keep-alive",
+                "x-accel-buffering": "no",
+            });
+            const writeFrame = (event, data) => {
+                if (res.writableEnded)
+                    return;
+                res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            };
+            const buffered = deps.terminals.readAll(sessionId);
+            writeFrame("snapshot", {
+                truncated: buffered.truncated,
+                totalOutputChars: buffered.totalOutputChars,
+                text: buffered.text,
+                info: deps.terminals.get(sessionId),
+            });
+            const unsubscribe = deps.terminals.subscribe(sessionId, (chunk) => {
+                writeFrame("data", { chunk });
+            });
+            const heartbeat = setInterval(() => {
+                if (!res.writableEnded)
+                    res.write(": heartbeat\n\n");
+            }, 15_000);
+            res.once("close", () => {
+                clearInterval(heartbeat);
+                unsubscribe();
+            });
+            return true;
+        }
+        // Everything else mutates → gate first.
+        const gate = deps.gateMutation(req);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        if (method === "POST" && sub === "input" && parts.length === 2) {
+            const body = await readJsonBody(req);
+            if (typeof body.data !== "string") {
+                sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "data (string) is required" } });
+                return true;
+            }
+            deps.terminals.send(sessionId, body.data);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "resize" && parts.length === 2) {
+            const body = await readJsonBody(req);
+            const cols = Number(body.cols);
+            const rows = Number(body.rows);
+            if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 2 || rows < 2 || cols > 500 || rows > 200) {
+                sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "cols and rows (integers 2..500/200) are required" } });
+                return true;
+            }
+            deps.terminals.resize(sessionId, cols, rows);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "interrupt" && parts.length === 2) {
+            deps.terminals.interrupt(sessionId);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        if (method === "POST" && sub === "kill" && parts.length === 2) {
+            await deps.terminals.kill(sessionId);
+            sendJson(res, 200, { ok: true });
+            return true;
+        }
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `unknown terminal route: ${method} ${pathname}` } });
+        return true;
+    }
+    catch (error) {
+        if (!res.headersSent)
+            mapTerminalError(res, error);
+        else
+            res.end();
+        return true;
+    }
+}