@jingyi0605/codingns 0.1.1 → 0.1.3

package/dist/server/modules/terminal/terminal-service.js

@@ -2,14 +2,18 @@ import { EventEmitter } from "node:events";
 import path from "node:path";
 import { AppError } from "../../shared/errors/app-error.js";
 import { createId } from "../../shared/utils/id.js";
+import { isTerminalDebugEnabled, logTerminalDebug, terminalDebugNowMs } from "../../shared/utils/terminal-debug-log.js";
 import { nowIso } from "../../shared/utils/time.js";
 import { resolveWorkspaceCwd } from "./terminal-paths.js";
-import { getDefaultShell, resolveRequestedShell } from "./terminal-shell.js";
+import { getDefaultShell, resolveRequestedShell, resolveWindowsPersistentRuntimeType } from "./terminal-shell.js";
 import { captureTmuxPaneContent } from "./runtime/adapters/tmux-runtime-adapter.js";
+import { isConptyRuntimeType } from "./runtime/conpty-runtime-shared.js";
 import { TerminalLogFileStore } from "./runtime/terminal-log-file-store.js";
 import { TerminalLogSpooler } from "./runtime/terminal-log-spooler.js";
 import { TerminalOutputBuffer } from "./runtime/terminal-output-buffer.js";
 import { TerminalRuntimeManager } from "./runtime/terminal-runtime-manager.js";
+const TERMINAL_ACTIVITY_FLUSH_INTERVAL_MS = 2_000;
+const TERMINAL_OUTPUT_FLUSH_INTERVAL_MS = 8;
 export class TerminalService extends EventEmitter {
     db;
     terminalInstanceRepository;
@@ -17,14 +21,17 @@ export class TerminalService extends EventEmitter {
     workspaceService;
     outputBuffer = new TerminalOutputBuffer();
     runtimeManager = new TerminalRuntimeManager();
-    lastPersistedActivity = new Map();
     terminalSubscriptionCounts = new Map();
     pendingCloseReasons = new Map();
     pendingDeletedTerminalIds = new Set();
+    pendingActivityByTerminalId = new Map();
+    pendingInputTraceByTerminalId = new Map();
+    pendingOutputByTerminalId = new Map();
     terminalLogSpooler;
     terminalLogFileRepository;
     terminalLogSegmentRepository;
     terminalLogFileStore;
+    activityFlushTimer = null;
     isDisposing = false;
     constructor(db, terminalInstanceRepository, terminalRuntimeSessionRepository, workspaceService, _idleTimeoutSeconds, options = {}) {
         super();
@@ -55,12 +62,12 @@ export class TerminalService extends EventEmitter {
         });
         this.recoverRuntimeStates();
     }
-    createTerminal(input) {
+    async createTerminal(input) {
         const workspace = this.workspaceService.getWorkspaceOrThrow(input.workspaceId);
         const now = nowIso();
         const shell = resolveRequestedShell(sanitizeShell(input.shell) ?? getDefaultShell());
         const cwd = resolveWorkspaceCwd(workspace.path, input.cwd);
-        const runtimeType = resolveRequestedRuntimeType(input.runtimeType);
+        const runtimeType = resolveRequestedRuntimeType(input.runtimeType, shell);
         const runtimeSessionId = createId();
         const attachTarget = buildAttachTarget(runtimeType, runtimeSessionId);
         const terminal = {
@@ -104,9 +111,12 @@ export class TerminalService extends EventEmitter {
         persist();
         try {
             const env = buildTerminalEnv(input.env);
-            const createdInspection = this.runtimeManager.createPersistentSession(terminal, runtimeSession, env);
-            const attachmentProcessId = this.runtimeManager.ensureAttached(terminal, runtimeSession, env);
+            const createdInspection = await this.runtimeManager.createPersistentSession(terminal, runtimeSession, env);
+            runtimeSession.agentPid = createdInspection.agentPid ?? runtimeSession.agentPid;
+            const attachmentProcessId = await this.runtimeManager.ensureAttached(terminal, runtimeSession, env);
             const processId = createdInspection.shellPid ?? attachmentProcessId;
+            terminal.processId = processId;
+            runtimeSession.shellPid = processId;
             const runningTerminal = {
                 ...terminal,
                 status: "running",
@@ -123,6 +133,7 @@ export class TerminalService extends EventEmitter {
             });
             this.terminalRuntimeSessionRepository.updateState({
                 id: runtimeSession.id,
+                agentPid: createdInspection.agentPid ?? runtimeSession.agentPid,
                 shellPid: processId,
                 state: "running",
                 lastCheckedAt: nowIso(),
@@ -145,23 +156,32 @@ export class TerminalService extends EventEmitter {
             });
             this.terminalRuntimeSessionRepository.updateState({
                 id: runtimeSession.id,
+                agentPid: runtimeSession.agentPid,
                 shellPid: null,
                 state: "error",
                 lastCheckedAt: failedAt,
                 lastErrorDetail: error instanceof Error ? error.message : "PTY 启动失败",
                 updatedAt: failedAt
             });
+            if (runtimeSession.agentPid) {
+                try {
+                    process.kill(runtimeSession.agentPid);
+                }
+                catch {
+                    // agent 已退出时忽略。
+                }
+            }
             const failedTerminal = this.getTerminalOrThrow(terminal.id);
             this.emit("status", failedTerminal);
             throw error;
         }
     }
-    listTerminals(workspaceId) {
+    async listTerminals(workspaceId) {
         this.workspaceService.getWorkspaceOrThrow(workspaceId);
         const terminals = this.terminalInstanceRepository.listByWorkspace(workspaceId);
         let hasLifecycleChange = false;
         for (const terminal of terminals) {
-            if (this.reconcileTerminalRuntime(terminal)) {
+            if (await this.reconcileTerminalRuntime(terminal)) {
                 hasLifecycleChange = true;
             }
         }
@@ -169,6 +189,10 @@ export class TerminalService extends EventEmitter {
             ? this.terminalInstanceRepository.listByWorkspace(workspaceId)
             : terminals;
     }
+    listTerminalSnapshotItems(workspaceId) {
+        this.workspaceService.getWorkspaceOrThrow(workspaceId);
+        return this.terminalInstanceRepository.listByWorkspace(workspaceId);
+    }
     getTerminalOrThrow(terminalId) {
         const terminal = this.terminalInstanceRepository.findById(terminalId);
         if (!terminal) {
@@ -191,7 +215,7 @@ export class TerminalService extends EventEmitter {
         }
         return session;
     }
-    closeTerminal(terminalId, reason = "user_closed") {
+    async closeTerminal(terminalId, reason = "user_closed") {
         const terminal = this.getTerminalOrThrow(terminalId);
         const session = this.getRuntimeSessionOrThrow(terminal.runtimeSessionId);
         this.pendingCloseReasons.set(terminalId, reason);
@@ -200,7 +224,7 @@ export class TerminalService extends EventEmitter {
             return { success: true };
         }
         this.flushTerminalLogs(terminalId);
-        const willEmitExit = this.runtimeManager.terminateSession(terminal, session);
+        const willEmitExit = await this.runtimeManager.terminateSession(terminal, session);
         if (!willEmitExit) {
             this.finalizeTerminalClosure(terminal, session, {
                 requestedClose: true,
@@ -212,11 +236,12 @@ export class TerminalService extends EventEmitter {
         }
         return { success: true };
     }
-    deleteTerminal(terminalId) {
+    async deleteTerminal(terminalId) {
         const terminal = this.getTerminalOrThrow(terminalId);
         const session = this.getRuntimeSessionOrThrow(terminal.runtimeSessionId);
         this.pendingCloseReasons.delete(terminalId);
-        this.lastPersistedActivity.delete(terminalId);
+        this.pendingActivityByTerminalId.delete(terminalId);
+        this.clearActivityFlushTimerIfIdle();
         this.flushTerminalLogs(terminalId);
         this.pendingDeletedTerminalIds.add(terminalId);
         const deleteRecords = this.db.transaction(() => {
@@ -232,7 +257,7 @@ export class TerminalService extends EventEmitter {
         }
         let willEmitExit = false;
         try {
-            willEmitExit = this.runtimeManager.terminateSession(terminal, session);
+            willEmitExit = await this.runtimeManager.terminateSession(terminal, session);
         }
         catch (error) {
             this.pendingDeletedTerminalIds.delete(terminalId);
@@ -250,7 +275,7 @@ export class TerminalService extends EventEmitter {
         }
         return { success: true };
     }
-    writeInput(terminalId, content) {
+    async writeInput(terminalId, content, debugContext = {}) {
         if (!content) {
             throw new AppError({
                 statusCode: 400,
@@ -259,12 +284,31 @@ export class TerminalService extends EventEmitter {
                 field: "content"
             });
         }
-        const terminal = this.ensureTerminalInteractive(terminalId);
+        const serviceWriteStartedAtMs = terminalDebugNowMs();
+        const terminal = await this.ensureTerminalInteractive(terminalId);
         this.runtimeManager.write(terminal.id, content);
+        const serviceWriteFinishedAtMs = terminalDebugNowMs();
+        this.recordPendingInputTrace(terminalId, content, {
+            ...debugContext,
+            serviceWriteStartedAtMs,
+            serviceWriteFinishedAtMs
+        });
+        logTerminalDebug("terminal.input.write_completed", {
+            terminalId,
+            traceId: debugContext.clientTraceId ?? null,
+            charCount: content.length,
+            ensureAndWriteMs: serviceWriteFinishedAtMs - serviceWriteStartedAtMs,
+            wsToWriteMs: debugContext.wsReceivedAtMs === null || debugContext.wsReceivedAtMs === undefined
+                ? null
+                : serviceWriteFinishedAtMs - debugContext.wsReceivedAtMs,
+            clientToWriteMs: debugContext.clientSentAtMs === null || debugContext.clientSentAtMs === undefined
+                ? null
+                : serviceWriteFinishedAtMs - debugContext.clientSentAtMs
+        });
         this.touchLastActiveAt(terminalId);
         return { accepted: true };
     }
-    resizeTerminal(terminalId, cols, rows) {
+    async resizeTerminal(terminalId, cols, rows) {
         if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 20 || rows < 5) {
             throw new AppError({
                 statusCode: 400,
@@ -273,12 +317,12 @@ export class TerminalService extends EventEmitter {
                 field: "cols"
             });
         }
-        const terminal = this.ensureTerminalInteractive(terminalId);
+        const terminal = await this.ensureTerminalInteractive(terminalId);
         this.runtimeManager.resize(terminal.id, cols, rows);
         this.touchLastActiveAt(terminalId);
         return { accepted: true };
     }
-    subscribeTerminal(terminalId, lastCursor, callbacks) {
+    async subscribeTerminal(terminalId, lastCursor, callbacks) {
         const outputListener = (event) => {
             if (event.terminalId !== terminalId) {
                 return;
@@ -304,7 +348,7 @@ export class TerminalService extends EventEmitter {
         this.on("exit", exitListener);
         this.retainTerminalSubscription(terminalId);
         try {
-            const current = this.ensureTerminalAttachedForSubscription(terminalId);
+            const current = await this.ensureTerminalAttachedForSubscription(terminalId);
             const backfill = this.outputBuffer.readSince(terminalId, lastCursor);
             void callbacks.onStatus(current);
             void callbacks.onBackfill(backfill);
@@ -332,17 +376,20 @@ export class TerminalService extends EventEmitter {
     }
     async dispose() {
         this.isDisposing = true;
+        this.flushPendingTerminalOutput();
+        this.flushPendingActivity();
         this.terminalLogSpooler?.flushAll();
         this.runtimeManager.closeAllAttachments();
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    readTerminalHistory(terminalId, beforeSeq, limit) {
+    async readTerminalHistory(terminalId, beforeSeq, limit) {
         const terminal = this.getTerminalOrThrow(terminalId);
+        this.flushTerminalLogs(terminalId);
         const runtimeSession = terminal.runtimeSessionId
             ? this.terminalRuntimeSessionRepository.findById(terminal.runtimeSessionId)
             : null;
         if (beforeSeq === 1 && runtimeSession?.runtimeType === "tmux") {
-            const capturedContent = normalizeTerminalHistoryContent(captureTmuxPaneContent(runtimeSession.sessionKey));
+            const capturedContent = normalizeTerminalHistoryContent(await captureTmuxPaneContent(runtimeSession.sessionKey));
             const capturedLineCount = countTerminalHistoryLines(capturedContent);
             return {
                 terminalId,
@@ -427,16 +474,16 @@ export class TerminalService extends EventEmitter {
         if (this.isDisposing) {
             return;
         }
-        const chunks = this.outputBuffer.append(terminalId, content);
-        if (chunks.length === 0) {
+        const batch = this.getOrCreatePendingOutputBatch(terminalId);
+        batch.contents.push(content);
+        if (batch.timer !== null) {
             return;
         }
-        this.terminalLogSpooler?.appendChunks(terminalId, chunks);
-        this.touchLastActiveAt(terminalId);
-        this.emit("output", {
-            terminalId,
-            chunks
-        });
+        batch.timer = setTimeout(() => {
+            batch.timer = null;
+            this.flushPendingTerminalOutput(terminalId);
+        }, TERMINAL_OUTPUT_FLUSH_INTERVAL_MS);
+        batch.timer.unref?.();
     }
     handleRuntimeExit(event) {
         if (this.isDisposing) {
@@ -444,7 +491,9 @@ export class TerminalService extends EventEmitter {
         }
         if (this.pendingDeletedTerminalIds.delete(event.terminalId)) {
             this.pendingCloseReasons.delete(event.terminalId);
-            this.lastPersistedActivity.delete(event.terminalId);
+            this.pendingActivityByTerminalId.delete(event.terminalId);
+            this.clearActivityFlushTimerIfIdle();
+            this.pendingInputTraceByTerminalId.delete(event.terminalId);
             this.clearTerminalLogs(event.terminalId);
             return;
         }
@@ -461,17 +510,16 @@ export class TerminalService extends EventEmitter {
         if (this.isDisposing) {
             return;
         }
-        const now = Date.now();
-        const previous = this.lastPersistedActivity.get(terminalId) ?? 0;
-        if (now - previous >= 500) {
-            this.lastPersistedActivity.set(terminalId, now);
-            this.terminalInstanceRepository.touchLastActiveAt(terminalId, nowIso(new Date(now)));
-        }
+        this.pendingActivityByTerminalId.set(terminalId, nowIso());
+        this.scheduleActivityFlush();
     }
-    ensureTerminalInteractive(terminalId) {
+    async ensureTerminalInteractive(terminalId) {
         const terminal = this.getTerminalOrThrow(terminalId);
+        if (terminal.status === "running" && this.runtimeManager.isAttached(terminal.id)) {
+            return terminal;
+        }
         const session = this.getRuntimeSessionOrThrow(terminal.runtimeSessionId);
-        const nextTerminal = this.ensureTerminalRunning(terminal, session, true);
+        const nextTerminal = await this.ensureTerminalRunning(terminal, session, true);
         if (nextTerminal.status !== "running") {
             throw new AppError({
                 statusCode: 409,
@@ -481,16 +529,16 @@ export class TerminalService extends EventEmitter {
         }
         return nextTerminal;
     }
-    ensureTerminalAttachedForSubscription(terminalId) {
+    async ensureTerminalAttachedForSubscription(terminalId) {
         const terminal = this.getTerminalOrThrow(terminalId);
         const session = this.getRuntimeSessionOrThrow(terminal.runtimeSessionId);
         return this.ensureTerminalRunning(terminal, session, true);
     }
-    ensureTerminalRunning(terminal, session, ensureAttached) {
+    async ensureTerminalRunning(terminal, session, ensureAttached) {
         if (terminal.status === "closed" || terminal.status === "error") {
             return terminal;
         }
-        const inspection = this.runtimeManager.inspectPersistentSession(terminal, session);
+        const inspection = await this.runtimeManager.inspectPersistentSession(terminal, session);
         if (!inspection.alive) {
             if (shouldMarkRuntimeLost(terminal, inspection.detail)) {
                 return this.markTerminalLost(terminal, session, inspection.detail);
@@ -498,12 +546,18 @@ export class TerminalService extends EventEmitter {
             return this.markTerminalError(terminal, session, inspection.detail ?? buildMissingProcessStatusDetail(terminal));
         }
         if (ensureAttached) {
-            const attachmentProcessId = this.runtimeManager.ensureAttached(terminal, session, buildTerminalEnv());
+            if (session.runtimeType === "embedded-pty") {
+                if (!this.runtimeManager.isAttached(terminal.id)) {
+                    return this.markTerminalError(terminal, session, inspection.detail ?? "EMBEDDED_RUNTIME_NOT_ATTACHED");
+                }
+                return this.markTerminalRunning(terminal, session, inspection.shellPid ?? this.runtimeManager.getProcessId(terminal.id), inspection.detail);
+            }
+            const attachmentProcessId = this.runtimeManager.ensureLegacyAttached(terminal, session, buildTerminalEnv());
             return this.markTerminalRunning(terminal, session, inspection.shellPid ?? attachmentProcessId, inspection.detail);
         }
         return this.markTerminalRunning(terminal, session, inspection.shellPid, inspection.detail);
     }
-    reconcileTerminalRuntime(terminal) {
+    async reconcileTerminalRuntime(terminal) {
         if (terminal.status === "closed" || terminal.status === "error") {
             return false;
         }
@@ -513,7 +567,7 @@ export class TerminalService extends EventEmitter {
             statusDetail: terminal.statusDetail
         });
         const session = this.getRuntimeSessionOrThrow(terminal.runtimeSessionId);
-        const nextTerminal = this.ensureTerminalRunning(terminal, session, false);
+        const nextTerminal = await this.ensureTerminalRunning(terminal, session, false);
         const after = JSON.stringify({
             status: nextTerminal.status,
             processId: nextTerminal.processId,
@@ -544,6 +598,7 @@ export class TerminalService extends EventEmitter {
         });
         this.terminalRuntimeSessionRepository.updateState({
             id: session.id,
+            agentPid: session.agentPid,
             shellPid: processId,
             state: "running",
             lastCheckedAt: updatedAt,
@@ -558,6 +613,7 @@ export class TerminalService extends EventEmitter {
         const updatedAt = nowIso();
         this.terminalRuntimeSessionRepository.updateState({
             id: session.id,
+            agentPid: session.agentPid,
             shellPid: terminal.processId,
             state: "lost",
             lastCheckedAt: updatedAt,
@@ -578,6 +634,9 @@ export class TerminalService extends EventEmitter {
         return updated;
     }
     markTerminalError(terminal, session, detail) {
+        this.pendingActivityByTerminalId.delete(terminal.id);
+        this.clearActivityFlushTimerIfIdle();
+        this.pendingInputTraceByTerminalId.delete(terminal.id);
         const closedAt = nowIso();
         this.terminalInstanceRepository.updateLifecycle({
             id: terminal.id,
@@ -590,6 +649,7 @@ export class TerminalService extends EventEmitter {
         });
         this.terminalRuntimeSessionRepository.updateState({
             id: session.id,
+            agentPid: session.agentPid,
             shellPid: terminal.processId,
             state: "error",
             lastCheckedAt: closedAt,
@@ -603,10 +663,13 @@ export class TerminalService extends EventEmitter {
     finalizeTerminalClosure(terminal, session, event) {
         const closeReason = this.pendingCloseReasons.get(terminal.id) ?? "user_closed";
         this.pendingCloseReasons.delete(terminal.id);
+        this.pendingActivityByTerminalId.delete(terminal.id);
+        this.clearActivityFlushTimerIfIdle();
+        this.pendingInputTraceByTerminalId.delete(terminal.id);
         const finishedAt = nowIso();
         const status = event.requestedClose || event.exitCode === 0 ? "closed" : "error";
         const statusDetail = status === "error"
-            ? event.sessionDetail ?? `终端异常退出，exitCode=${event.exitCode ?? "unknown"}`
+            ? normalizeTerminalErrorDetail(event.sessionDetail, event.exitCode)
             : resolveClosedStatusDetail(closeReason, terminal.statusDetail);
         this.terminalInstanceRepository.updateLifecycle({
             id: terminal.id,
@@ -619,6 +682,7 @@ export class TerminalService extends EventEmitter {
         });
         this.terminalRuntimeSessionRepository.updateState({
             id: session.id,
+            agentPid: session.agentPid,
             shellPid: event.shellPid,
             state: status === "closed" ? "closed" : "error",
             lastCheckedAt: finishedAt,
@@ -658,7 +722,7 @@ export class TerminalService extends EventEmitter {
                 }, "RUNTIME_SESSION_MISSING");
                 continue;
             }
-            this.ensureTerminalRunning(terminal, session, false);
+            void this.ensureTerminalRunning(terminal, session, false);
         }
     }
     retainTerminalSubscription(terminalId) {
@@ -689,14 +753,134 @@ export class TerminalService extends EventEmitter {
         this.runtimeManager.detach(terminalId);
     }
     flushTerminalLogs(terminalId) {
+        this.flushPendingTerminalOutput(terminalId);
         this.terminalLogSpooler?.flushTerminal(terminalId);
     }
     clearTerminalLogs(terminalId) {
+        const pendingOutput = this.pendingOutputByTerminalId.get(terminalId);
+        if (pendingOutput?.timer) {
+            clearTimeout(pendingOutput.timer);
+        }
+        this.pendingOutputByTerminalId.delete(terminalId);
+        this.pendingInputTraceByTerminalId.delete(terminalId);
         this.outputBuffer.clear(terminalId);
         this.terminalLogSegmentRepository?.deleteByTerminalId(terminalId);
         this.terminalLogFileRepository?.deleteByTerminalId(terminalId);
         this.terminalLogSpooler?.deleteTerminalLogs(terminalId);
     }
+    getOrCreatePendingOutputBatch(terminalId) {
+        let batch = this.pendingOutputByTerminalId.get(terminalId);
+        if (!batch) {
+            batch = {
+                contents: [],
+                timer: null
+            };
+            this.pendingOutputByTerminalId.set(terminalId, batch);
+        }
+        return batch;
+    }
+    flushPendingTerminalOutput(terminalId) {
+        if (terminalId) {
+            const batch = this.pendingOutputByTerminalId.get(terminalId);
+            if (!batch) {
+                return;
+            }
+            if (batch.timer) {
+                clearTimeout(batch.timer);
+                batch.timer = null;
+            }
+            const content = batch.contents.join("");
+            this.pendingOutputByTerminalId.delete(terminalId);
+            this.commitTerminalOutput(terminalId, content);
+            return;
+        }
+        for (const nextTerminalId of [...this.pendingOutputByTerminalId.keys()]) {
+            this.flushPendingTerminalOutput(nextTerminalId);
+        }
+    }
+    commitTerminalOutput(terminalId, content) {
+        const traceQueue = this.pendingInputTraceByTerminalId.get(terminalId) ?? [];
+        const outputReceivedAtMs = traceQueue.length > 0 ? terminalDebugNowMs() : null;
+        const chunks = this.outputBuffer.append(terminalId, content);
+        if (chunks.length === 0) {
+            return;
+        }
+        this.terminalLogSpooler?.appendChunks(terminalId, chunks);
+        this.touchLastActiveAt(terminalId);
+        this.emit("output", {
+            terminalId,
+            chunks
+        });
+        if (traceQueue.length > 0 && outputReceivedAtMs !== null) {
+            for (const trace of traceQueue) {
+                logTerminalDebug("terminal.output.after_input", {
+                    terminalId,
+                    traceId: trace.traceId,
+                    charCount: trace.charCount,
+                    outputBytes: Buffer.byteLength(content, "utf8"),
+                    writeToOutputMs: outputReceivedAtMs - trace.serviceWriteFinishedAtMs,
+                    wsToOutputMs: trace.wsReceivedAtMs === null ? null : outputReceivedAtMs - trace.wsReceivedAtMs,
+                    clientToOutputMs: trace.clientSentAtMs === null ? null : outputReceivedAtMs - trace.clientSentAtMs,
+                    pendingTraceCount: traceQueue.length
+                });
+            }
+            this.pendingInputTraceByTerminalId.delete(terminalId);
+        }
+    }
+    recordPendingInputTrace(terminalId, content, input) {
+        if (!isTerminalDebugEnabled() || !input.clientTraceId) {
+            return;
+        }
+        const queue = this.pendingInputTraceByTerminalId.get(terminalId) ?? [];
+        queue.push({
+            traceId: input.clientTraceId,
+            clientSentAtMs: input.clientSentAtMs ?? null,
+            wsReceivedAtMs: input.wsReceivedAtMs ?? null,
+            serviceWriteStartedAtMs: input.serviceWriteStartedAtMs,
+            serviceWriteFinishedAtMs: input.serviceWriteFinishedAtMs,
+            charCount: content.length
+        });
+        this.pendingInputTraceByTerminalId.set(terminalId, queue);
+    }
+    scheduleActivityFlush() {
+        if (this.activityFlushTimer !== null) {
+            return;
+        }
+        this.activityFlushTimer = setTimeout(() => {
+            this.activityFlushTimer = null;
+            this.flushPendingActivity();
+        }, TERMINAL_ACTIVITY_FLUSH_INTERVAL_MS);
+        this.activityFlushTimer.unref?.();
+    }
+    flushPendingActivity(terminalId) {
+        if (terminalId) {
+            const lastActiveAt = this.pendingActivityByTerminalId.get(terminalId);
+            if (!lastActiveAt) {
+                return;
+            }
+            this.pendingActivityByTerminalId.delete(terminalId);
+            this.terminalInstanceRepository.touchLastActiveAt(terminalId, lastActiveAt);
+            this.clearActivityFlushTimerIfIdle();
+            return;
+        }
+        if (this.pendingActivityByTerminalId.size === 0) {
+            this.clearActivityFlushTimerIfIdle();
+            return;
+        }
+        const entries = [...this.pendingActivityByTerminalId.entries()];
+        this.pendingActivityByTerminalId.clear();
+        for (const [nextTerminalId, lastActiveAt] of entries) {
+            this.terminalInstanceRepository.touchLastActiveAt(nextTerminalId, lastActiveAt);
+        }
+        this.clearActivityFlushTimerIfIdle();
+    }
+    clearActivityFlushTimerIfIdle() {
+        if (this.pendingActivityByTerminalId.size > 0 || this.activityFlushTimer === null) {
+            return;
+        }
+        clearTimeout(this.activityFlushTimer);
+        this.activityFlushTimer = null;
+    }
 }
 function normalizeTerminalHistoryContent(content) {
     return content
@@ -730,17 +914,36 @@ function sanitizeShell(shell) {
     }
     return value;
 }
-function resolveRequestedRuntimeType(input) {
+function resolveRequestedRuntimeType(input, shell) {
     const runtimeType = input ?? (process.platform === "win32" ? "embedded-pty" : "tmux");
-    if (runtimeType !== "embedded-pty" &&
-        runtimeType !== "tmux") {
+    if (runtimeType === "embedded-pty") {
+        return runtimeType;
+    }
+    if (process.platform === "win32") {
+        if (runtimeType === "tmux" || isConptyRuntimeType(runtimeType)) {
+            return resolveWindowsPersistentRuntimeType(shell);
+        }
         throw new AppError({
             statusCode: 400,
             errorCode: "UNSUPPORTED_TERMINAL_RUNTIME",
-            detail: `当前 Host 还未实现 runtime=${runtimeType}`
+            detail: `褰撳墠 Host 杩樻湭瀹炵幇 runtime=${runtimeType}`
         });
     }
-    return runtimeType;
+    if (runtimeType === "tmux") {
+        return runtimeType;
+    }
+    if (isConptyRuntimeType(runtimeType)) {
+        throw new AppError({
+            statusCode: 400,
+            errorCode: "RUNTIME_UNSUPPORTED_PLATFORM",
+            detail: "conpty runtime 浠呮敮鎸?Windows"
+        });
+    }
+    throw new AppError({
+        statusCode: 400,
+        errorCode: "UNSUPPORTED_TERMINAL_RUNTIME",
+        detail: `褰撳墠 Host 杩樻湭瀹炵幇 runtime=${runtimeType}`
+    });
 }
 function buildAttachTarget(runtimeType, runtimeSessionId) {
     if (runtimeType === "embedded-pty") {
@@ -788,6 +991,12 @@ function resolveClosedStatusDetail(reason, currentStatusDetail) {
     }
     return currentStatusDetail;
 }
+function normalizeTerminalErrorDetail(sessionDetail, exitCode) {
+    if (sessionDetail && sessionDetail !== "EMBEDDED_RUNTIME_NOT_RECOVERABLE") {
+        return sessionDetail;
+    }
+    return `终端异常退出，exitCode=${exitCode ?? "unknown"}`;
+}
 function shouldMarkRuntimeLost(terminal, detail) {
     return terminal.runtimeType !== "embedded-pty" && Boolean(detail?.includes("检查失败"));
 }