aws-runtime-bridge 1.7.27 → 1.7.29

package/dist/routes/terminal.js

@@ -15,14 +15,24 @@ import { adapterRegistry, registerSdkProviders, resolveSdkProviderIdByCommand, }
 import { validateToken } from '../middleware/auth.js';
 import { getAgentProcessManager } from '../services/agent-process-manager.js';
 import { enqueueMcpLaunchBinding } from '../services/mcp-launch-binding-queue.js';
-import { findClaudeCodeProcesses } from '../services/process-detector.js';
+import { findClaudeCodeProcesses, isProcessRunning } from '../services/process-detector.js';
 import { sendOutput, sendQuestionRequest, sendStatus } from '../services/session-output.js';
-import { findPersistedSessionByAgentId, removePersistedSession, savePersistedSessions, updatePersistedSessionAutoCommands, upsertPersistedSession, } from '../services/terminal-persistence.js';
+import { findPersistedSessionByAgentId, removePersistedSession, savePersistedSessions, updatePersistedSessionAutoCommands, updatePersistedSessionRuntimeState, upsertPersistedSession, } from '../services/terminal-persistence.js';
 export const terminalRouter = Router();
 // 导出 SDK 会话存储，供其他模块使用（如 sessions.ts）
 export const sdkSessions = new Map();
 const TOOL_RESULT_PREVIEW_MAX_LENGTH = 4000;
 const startingAgents = new Set();
+export function resolveStatusChangeUsage(actionInfo) {
+    const usage = actionInfo?.usage;
+    if (!usage)
+        return undefined;
+    const inputTokens = Number.isFinite(usage.inputTokens) ? usage.inputTokens : 0;
+    const outputTokens = Number.isFinite(usage.outputTokens) ? usage.outputTokens : 0;
+    if (inputTokens <= 0 && outputTokens <= 0)
+        return undefined;
+    return { inputTokens, outputTokens };
+}
 const terminalCommandStates = new Map();
 const DEFAULT_WINDOWS_TERMINAL_OUTPUT_ENCODING = 'gb18030';
 const DEFAULT_TERMINAL_OUTPUT_ENCODING = 'utf-8';
@@ -110,6 +120,10 @@ async function buildExistingSessionResponse(entry) {
     return {
         sessionId: entry.sessionId,
         status: adapter.getSessionStatus(entry.sessionId) || 'running',
+        runtimeStatus: entry.currentRuntimeStatus,
+        runtimeActionType: entry.currentRuntimeActionType,
+        runtimeActionLabel: entry.currentRuntimeActionLabel,
+        runtimeActionDetail: entry.currentRuntimeActionDetail,
         agentId: entry.agentId,
         workspacePath: entry.workspacePath,
         command: entry.config.command,
@@ -118,6 +132,19 @@ async function buildExistingSessionResponse(entry) {
         reused: true,
     };
 }
+/**
+ * 判断持久化 SDK 会话能否在显式启动请求中复用。
+ * 主流程：必须存在 PID 且 OS 仍能确认该进程存活；否则视为重启后遗留的陈旧会话。
+ */
+export function evaluatePersistedSessionReuse(session, isPidRunning = isProcessRunning) {
+    if (!session.pid) {
+        return { reusable: false, reason: 'missing-pid' };
+    }
+    if (!isPidRunning(session.pid)) {
+        return { reusable: false, reason: 'dead-pid' };
+    }
+    return { reusable: true, reason: 'active-pid' };
+}
 function stopTerminalCommandProcess(sessionId) {
     const state = terminalCommandStates.get(sessionId);
     if (!state?.runningProcess) {
@@ -337,15 +364,25 @@ function wireSdkAdapterEvents(adapter, definition) {
                 }
             }
             if (event.type === 'turn_complete' && event.data.usage) {
-                sendStatus(entry.agentId, event.sessionId, 'waiting_input', undefined, event.data.usage);
+                sendStatus(entry.agentId, event.sessionId, 'waiting_input', undefined, resolveStatusChangeUsage({ usage: event.data.usage }));
             }
         }
     });
     adapter.on('status-change', (sessionId, status, actionInfo) => {
         const entry = sdkSessions.get(sessionId);
         if (entry) {
+            entry.currentRuntimeStatus = status;
+            entry.currentRuntimeActionType = actionInfo?.actionType;
+            entry.currentRuntimeActionLabel = actionInfo?.actionLabel;
+            entry.currentRuntimeActionDetail = actionInfo?.actionDetail;
             console.log(`[${definition.displayName} Adapter] Status changed: ${status} for agent ${entry.agentId}`, actionInfo || '');
-            void sendStatus(entry.agentId, sessionId, status, actionInfo);
+            void updatePersistedSessionRuntimeState(sessionId, {
+                runtimeStatus: status,
+                runtimeActionType: actionInfo?.actionType,
+                runtimeActionLabel: actionInfo?.actionLabel,
+                runtimeActionDetail: actionInfo?.actionDetail,
+            });
+            void sendStatus(entry.agentId, sessionId, status, actionInfo, resolveStatusChangeUsage(actionInfo));
         }
     });
     adapter.on('ask-user-question', (data) => {
@@ -410,18 +447,26 @@ async function startSdkSession(req, res) {
         }
         const persistedSession = await findPersistedSessionByAgentId(normalizedAgentId);
         if (persistedSession) {
-            res.json({
-                sessionId: persistedSession.sessionId,
-                status: persistedSession.status,
-                agentId: persistedSession.agentId,
-                workspacePath: persistedSession.workspacePath,
-                command: persistedSession.command,
-                mode: persistedSession.mode || 'sdk',
-                pid: persistedSession.pid,
-                reused: true,
-                persistedOnly: true,
-            });
-            return;
+            const reuseDecision = evaluatePersistedSessionReuse(persistedSession);
+            if (!reuseDecision.reusable) {
+                console.warn(`[Runtime] Ignoring stale persisted SDK session for agentId=${normalizedAgentId}, `
+                    + `sessionId=${persistedSession.sessionId}, reason=${reuseDecision.reason}`);
+                await removePersistedSession(persistedSession.sessionId);
+            }
+            else {
+                res.json({
+                    sessionId: persistedSession.sessionId,
+                    status: persistedSession.status,
+                    agentId: persistedSession.agentId,
+                    workspacePath: persistedSession.workspacePath,
+                    command: persistedSession.command,
+                    mode: persistedSession.mode || 'sdk',
+                    pid: persistedSession.pid,
+                    reused: true,
+                    persistedOnly: true,
+                });
+                return;
+            }
         }
         if (startingAgents.has(normalizedAgentId)) {
             res.status(409).json({ error: 'SDK session is already starting for this agent' });
@@ -489,6 +534,7 @@ async function startSdkSession(req, res) {
             command: config.command,
             startedAt: new Date().toISOString(),
             status: 'running',
+            runtimeStatus: 'running',
             mode: 'sdk',
             pid: sdkPid,
             providerSessionId: adapter.getProviderSessionId(sessionId),

package/dist/routes/terminal.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { SDK_PROVIDER_DEFINITIONS } from '../adapter/SdkProviderSpi.js';
-import { buildRuntimeEnv, createTerminalOutputDecoder, decodeTerminalOutputChunk, formatTerminalPrompt, formatSdkOutputEvent, normalizeTerminalCommandInput, parseTerminalDirectoryChangeTarget, resolveTerminalOutputEncoding, resolveSdkProviderId, } from './terminal.js';
+import { buildRuntimeEnv, createTerminalOutputDecoder, decodeTerminalOutputChunk, evaluatePersistedSessionReuse, formatTerminalPrompt, formatSdkOutputEvent, normalizeTerminalCommandInput, parseTerminalDirectoryChangeTarget, resolveTerminalOutputEncoding, resolveSdkProviderId, resolveStatusChangeUsage, } from './terminal.js';
 describe('terminal route validation', () => {
     it('requires agentId and workspacePath for start', () => {
         const validateStartRequest = (body) => {
@@ -83,6 +83,20 @@ describe('terminal configuration', () => {
         expect(env.AWS_WORKSPACE_PATH).toBe('/workspace');
     });
 });
+describe('persisted SDK session reuse', () => {
+    it('does not reuse a persisted session without a PID', () => {
+        const decision = evaluatePersistedSessionReuse({}, () => true);
+        expect(decision).toEqual({ reusable: false, reason: 'missing-pid' });
+    });
+    it('does not reuse a persisted session when its PID is no longer running', () => {
+        const decision = evaluatePersistedSessionReuse({ pid: 1234 }, () => false);
+        expect(decision).toEqual({ reusable: false, reason: 'dead-pid' });
+    });
+    it('reuses a persisted session only when its PID is still running', () => {
+        const decision = evaluatePersistedSessionReuse({ pid: 1234 }, () => true);
+        expect(decision).toEqual({ reusable: true, reason: 'active-pid' });
+    });
+});
 describe('terminal command helpers', () => {
     it('normalizes carriage-return terminal input into executable command text', () => {
         expect(normalizeTerminalCommandInput('npm test\r')).toBe('npm test');
@@ -130,6 +144,16 @@ describe('resolveSdkProviderId', () => {
         expect(resolveSdkProviderId(undefined)).toBe('claude-code');
     });
 });
+describe('SDK status usage forwarding', () => {
+    it('keeps accumulated usage from status-change action info', () => {
+        expect(resolveStatusChangeUsage({ usage: { inputTokens: 12000, outputTokens: 345 } })).toEqual({
+            inputTokens: 12000,
+            outputTokens: 345,
+        });
+        expect(resolveStatusChangeUsage({ usage: { inputTokens: 0, outputTokens: 0 } })).toBeUndefined();
+        expect(resolveStatusChangeUsage({ actionType: 'mcp', actionLabel: 'Calling MCP' })).toBeUndefined();
+    });
+});
 describe('SDK output forwarding', () => {
     it('formats text and thinking provider events for the terminal output callback path', () => {
         const textEvent = {

package/dist/services/aws-client-agent-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aws-client-agent-mcp.d.ts","sourceRoot":"","sources":["../../src/services/aws-client-agent-mcp.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAqB7C,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,sCAAsC;IACrD,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,sCAAsC;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAaD,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC3C;AAuBD,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAgLD,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,MAAM,GAAG,IAAI,CAoDf;AA2ED,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,kBAAkB,CAEpB;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,sCAA2C,GACnD,kBAAkB,CAsBpB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAsBpB;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAgBtD"}
+{"version":3,"file":"aws-client-agent-mcp.d.ts","sourceRoot":"","sources":["../../src/services/aws-client-agent-mcp.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAqB7C,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,sCAAsC;IACrD,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,sCAAsC;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAaD,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC3C;AAuBD,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAgLD,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,MAAM,GAAG,IAAI,CAoDf;AAgGD,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,kBAAkB,CAEpB;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,sCAA2C,GACnD,kBAAkB,CAsBpB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAsBpB;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAgBtD"}

package/dist/services/aws-client-agent-mcp.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getRuntimeHomeDir, port, schedulerBaseUrl } from "../config.js";
 import { logger } from "../utils/logger.js";
-import { loadRuntimeBinding, normalizeSchedulerBaseUrl, } from "./runtime-binding.js";
+import { loadRuntimeBinding } from "./runtime-binding.js";
 export const AWS_MCP_SERVER_NAME = "aws-mcp";
 const AWS_MCP_ALLOWED_ENV_KEYS = [
     "AWS_PROJECT_NAME",
@@ -233,8 +233,27 @@ function parseAwsClientAgentMcpArgs(raw) {
     logger.warn("[runtime-bridge] AWS_CLIENT_AGENT_MCP_ARGS 必须是 string[] JSON，已忽略");
     return [];
 }
+function normalizeMcpSchedulerBaseUrl(value) {
+    const repaired = value.replace(/^((?:https?|wss?):\/\/(?:\[[^\]]+\]|[^/:?#]+):\d+):\d+(?=\/|$)/i, "$1");
+    try {
+        const url = new URL(repaired);
+        if (url.protocol === "ws:") {
+            url.protocol = "http:";
+        }
+        else if (url.protocol === "wss:") {
+            url.protocol = "https:";
+        }
+        else {
+            url.protocol = url.protocol.toLowerCase();
+        }
+        return url.origin;
+    }
+    catch {
+        return repaired.replace(/\/+$/, "");
+    }
+}
 function toWebSocketUrl(baseUrl) {
-    const url = new URL("/ws/agent", normalizeSchedulerBaseUrl(baseUrl) || baseUrl);
+    const url = new URL("/ws/agent", normalizeMcpSchedulerBaseUrl(baseUrl));
     if (url.protocol === "https:") {
         url.protocol = "wss:";
     }
@@ -244,7 +263,7 @@ function toWebSocketUrl(baseUrl) {
     return url.toString();
 }
 function toMcpHttpUrl(baseUrl) {
-    return new URL("/mcp/call", normalizeSchedulerBaseUrl(baseUrl) || baseUrl).toString();
+    return new URL("/mcp/call", normalizeMcpSchedulerBaseUrl(baseUrl)).toString();
 }
 function resolveSchedulerBaseUrlForMcp() {
     const envSchedulerBaseUrl = String(process.env.AWS_RUNTIME_SCHEDULER_BASE_URL || "").trim();

package/dist/services/mcp-launch-binding-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-launch-binding-queue.d.ts","sourceRoot":"","sources":["../../src/services/mcp-launch-binding-queue.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAmDD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,IAAI,CA+B7F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,uBAAuB,GAAG,IAAI,CA0C3G;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAOpE;AAED,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}
+{"version":3,"file":"mcp-launch-binding-queue.d.ts","sourceRoot":"","sources":["../../src/services/mcp-launch-binding-queue.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA2DD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,IAAI,CA+B7F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,uBAAuB,GAAG,IAAI,CA0C3G;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAOpE;AAED,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/services/mcp-launch-binding-queue.js

@@ -13,6 +13,13 @@ function normalizeWorkspacePath(workspacePath) {
 function normalizeOptionalUrl(value) {
     return String(value || "").trim();
 }
+function canonicalizeSchedulerHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    if (normalized === "localhost" || normalized === "::1" || normalized === "[::1]") {
+        return "127.0.0.1";
+    }
+    return normalized;
+}
 function normalizeSchedulerOrigin(serverUrl) {
     const raw = normalizeSchedulerBaseUrl(serverUrl) || String(serverUrl || "").trim();
     if (!raw) {
@@ -29,7 +36,7 @@ function normalizeSchedulerOrigin(serverUrl) {
         else {
             url.protocol = url.protocol.toLowerCase();
         }
-        url.hostname = url.hostname.toLowerCase();
+        url.hostname = canonicalizeSchedulerHostname(url.hostname);
         return url.origin;
     }
     catch {

package/dist/services/mcp-launch-binding-queue.test.js

@@ -86,6 +86,17 @@ describe('mcp launch binding queue', () => {
             serverUrl: 'ws://127.0.0.1:8080/ws/agent',
         })?.schedulerBaseUrl).toBe('http://127.0.0.1:8080');
     });
+    it('matches localhost and 127.0.0.1 launch binding scheduler aliases', () => {
+        enqueueMcpLaunchBinding({
+            agentId: 'agent-a',
+            workspacePath: 'C:/repo/demo',
+            serverUrl: 'ws://localhost:8080/ws/agent',
+        });
+        expect(claimMcpLaunchBinding({
+            workspacePath: 'C:/repo/demo',
+            serverUrl: 'ws://127.0.0.1:8080/ws/agent',
+        })?.agentId).toBe('agent-a');
+    });
     it('falls back to the only same-workspace binding when scheduler URLs differ', () => {
         enqueueMcpLaunchBinding({
             agentId: 'agent-a',

package/dist/services/orphan-monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orphan-monitor.d.ts","sourceRoot":"","sources":["../../src/services/orphan-monitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyBH;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,gBAAgB,GAChB,sBAAsB,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,OAAO,CAAkB;IAEjC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0E3B;;OAEG;YACW,oBAAoB;IA8BlC;;OAEG;YACW,iBAAiB;IAgC/B;;OAEG;YACW,eAAe;IA0B7B;;OAEG;YACW,mBAAmB;IAsBjC;;OAEG;YACW,iBAAiB;IA8C/B;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAIrD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAOtD;;OAEG;IACH,OAAO,CAAC,IAAI;IAUZ;;OAEG;IACH,SAAS,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAO3E;AAKD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}
+{"version":3,"file":"orphan-monitor.d.ts","sourceRoot":"","sources":["../../src/services/orphan-monitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,gBAAgB,GAChB,sBAAsB,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,OAAO,CAAkB;IAEjC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0E3B;;OAEG;YACW,oBAAoB;IAoClC;;OAEG;YACW,iBAAiB;IAwC/B;;OAEG;YACW,eAAe;IA0B7B;;OAEG;YACW,mBAAmB;IAsBjC;;OAEG;YACW,iBAAiB;IA8C/B;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAIrD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAOtD;;OAEG;IACH,OAAO,CAAC,IAAI;IAUZ;;OAEG;IACH,SAAS,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAO3E;AAKD;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}

package/dist/services/orphan-monitor.js

@@ -8,6 +8,7 @@ import { loadPersistedSessions, savePersistedSessions } from './terminal-persist
 import { detectOrphanProcesses, checkAllSessionsHealth, terminateProcessTree, waitForProcessExit } from './process-detector.js';
 import { ORPHAN_SCAN_INTERVAL, ORPHAN_AUTO_CLEAN_MODE, ORPHAN_SCAN_ENABLED, schedulerBaseUrl } from '../config.js';
 import { getRuntimeAccessToken } from './runtime-binding.js';
+import { shouldAutoCleanOrphanProcesses } from './runtime-lifecycle-policy.js';
 const logger = createLogger('orphan-monitor');
 /**
  * 孤儿进程监控器
@@ -126,11 +127,16 @@ export class OrphanMonitor {
         };
         this.emit(event);
         logger.warn(`检测到孤儿进程: agentId=${agentId}, pid=${pid}`);
-        // 根据模式处理
+        // 根据模式处理。auto 模式也必须经过显式清理开关，避免重启恢复时误杀保留会话。
         switch (ORPHAN_AUTO_CLEAN_MODE) {
             case 'auto':
-                // 自动终止
-                await this.autoCleanOrphan(agentId, pid);
+                if (shouldAutoCleanOrphanProcesses()) {
+                    await this.autoCleanOrphan(agentId, pid);
+                }
+                else {
+                    logger.warn('auto 模式未启用破坏性清理开关，改为告警并保留孤儿进程');
+                    await this.reportToScheduler(agentId, 'orphan_detected', { pid });
+                }
                 break;
             case 'alert':
                 // 告警并等待处理
@@ -167,11 +173,16 @@ export class OrphanMonitor {
             cpu: health.cpu,
             memoryMB: health.memoryMB,
         });
-        // auto 模式下可以考虑终止异常进程
-        if (ORPHAN_AUTO_CLEAN_MODE === 'auto' && health.status !== 'healthy') {
+        // auto 模式下也只有显式启用破坏性清理开关时才终止异常进程。
+        if (ORPHAN_AUTO_CLEAN_MODE === 'auto'
+            && health.status !== 'healthy'
+            && shouldAutoCleanOrphanProcesses()) {
             logger.warn(`auto 模式: 终止异常进程 ${health.pid} (${health.status})`);
             await this.autoCleanOrphan(agentId, health.pid);
         }
+        else if (ORPHAN_AUTO_CLEAN_MODE === 'auto' && health.status !== 'healthy') {
+            logger.warn(`auto 模式未启用破坏性清理开关，保留异常进程 ${health.pid} (${health.status})`);
+        }
     }
     /**
      * 自动清理孤儿进程

package/dist/services/runtime-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-binding.d.ts","sourceRoot":"","sources":["../../src/services/runtime-binding.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2DF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqB5E;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAiCD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,CAYR;AAsCD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAWT;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,OAAO,CAeT;AAcD,wBAAgB,kBAAkB,IAAI,mBAAmB,CAgBxD;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAClD,mBAAmB,EACnB,WAAW,GAAG,aAAa,CAC5B,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAWtB;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcnE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,OAAO,GACtB,MAAM,GAAG,SAAS,CAyBpB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,mBAAmB,CAwCtB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAkB1C"}
+{"version":3,"file":"runtime-binding.d.ts","sourceRoot":"","sources":["../../src/services/runtime-binding.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAmEF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqB5E;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAiCD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,CAYR;AAsCD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAWT;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,OAAO,CAeT;AAcD,wBAAgB,kBAAkB,IAAI,mBAAmB,CAgBxD;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAClD,mBAAmB,EACnB,WAAW,GAAG,aAAa,CAC5B,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAWtB;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcnE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,OAAO,GACtB,MAAM,GAAG,SAAS,CAyBpB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,mBAAmB,CAwCtB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAkB1C"}

package/dist/services/runtime-binding.js

@@ -49,6 +49,13 @@ function normalizeToken(token) {
 function repairDuplicatePort(raw) {
     return raw.replace(/^((?:https?|wss?):\/\/(?:\[[^\]]+\]|[^/:?#]+):\d+):\d+(?=\/|$)/i, "$1");
 }
+function canonicalizeSchedulerHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    if (normalized === "localhost" || normalized === "::1" || normalized === "[::1]") {
+        return "127.0.0.1";
+    }
+    return normalized;
+}
 export function normalizeSchedulerBaseUrl(value) {
     const raw = normalizeToken(value);
     if (!raw) {
@@ -66,7 +73,7 @@ export function normalizeSchedulerBaseUrl(value) {
         else {
             url.protocol = url.protocol.toLowerCase();
         }
-        url.hostname = url.hostname.toLowerCase();
+        url.hostname = canonicalizeSchedulerHostname(url.hostname);
         return url.origin;
     }
     catch {

package/dist/services/runtime-binding.test.js

@@ -28,6 +28,10 @@ describe('runtime binding scheduler URL normalization', () => {
         expect(normalizeSchedulerBaseUrl('ws://127.0.0.1:8080/ws/agent')).toBe('http://127.0.0.1:8080');
         expect(normalizeSchedulerBaseUrl('wss://example.com/ws/agent')).toBe('https://example.com');
     });
+    it('canonicalizes loopback scheduler aliases to one origin', () => {
+        expect(normalizeSchedulerBaseUrl('ws://localhost:8080/ws/agent')).toBe('http://127.0.0.1:8080');
+        expect(normalizeSchedulerBaseUrl('http://localhost:8080')).toBe('http://127.0.0.1:8080');
+    });
     it("returns paired binding token only when requested scheduler URL matches", async () => {
         useRuntimeHome();
         const { saveRuntimeBinding } = await import("./runtime-binding.js");
@@ -60,4 +64,15 @@ describe('runtime binding scheduler URL normalization', () => {
         expect(getScopedRuntimeAccessToken("user-a", "http://scheduler.local:7380")).toBeUndefined();
         expect(getScopedRuntimeAccessToken("user-a", "http://scheduler.local:8080")).toBe("runtime-token-8080-123456");
     });
+    it("uses the same scoped runtime token for localhost and 127.0.0.1", () => {
+        useRuntimeHome();
+        const key = saveScopedRuntimeAccessToken({
+            userId: "user-a",
+            serverBaseUrl: "http://localhost:8080",
+            accessToken: "runtime-token-loopback-123456",
+        });
+        expect(buildRuntimeTokenKey("user-a", "ws://127.0.0.1:8080/ws/agent")).toBe(key);
+        expect(getScopedRuntimeAccessToken("user-a", "http://127.0.0.1:8080")).toBe("runtime-token-loopback-123456");
+        expect(getRuntimeAccessToken("user-a", "ws://localhost:8080/ws/agent")).toBe("runtime-token-loopback-123456");
+    });
 });

package/dist/services/runtime-lifecycle-policy.d.ts

@@ -0,0 +1,26 @@
+export interface GracefulShutdownPlan {
+    terminateSdkSessions: boolean;
+    closePtySessions: boolean;
+    terminateResidualProcesses: boolean;
+    unregisterInstance: boolean;
+    clearPersistedSessions: boolean;
+}
+/**
+ * Build shutdown side-effect policy from the requested restart mode.
+ * Main flow: explicit bridge shutdown cleans resources; scheduler restart keeps
+ * SDK/PTY processes and persisted metadata so the scheduler can restore state.
+ */
+export declare function buildGracefulShutdownPlan(preserveSessions: boolean): GracefulShutdownPlan;
+/**
+ * Decide whether startup may destructively clean persisted runtime sessions.
+ * Main flow: default bridge restart is non-destructive; operators can opt into
+ * legacy cleanup with AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP=true.
+ */
+export declare function shouldCleanupPersistedSessionsOnStartup(preserveSessions: boolean, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Decide whether background orphan monitoring may terminate persisted sessions.
+ * Main flow: process termination is an explicit cleanup action, not a default
+ * monitoring behavior, so restart recovery cannot be undone by auto-clean mode.
+ */
+export declare function shouldAutoCleanOrphanProcesses(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=runtime-lifecycle-policy.d.ts.map

package/dist/services/runtime-lifecycle-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-lifecycle-policy.d.ts","sourceRoot":"","sources":["../../src/services/runtime-lifecycle-policy.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0BAA0B,EAAE,OAAO,CAAC;IACpC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,gBAAgB,EAAE,OAAO,GACxB,oBAAoB,CAUtB;AAED;;;;GAIG;AACH,wBAAgB,uCAAuC,CACrD,gBAAgB,EAAE,OAAO,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAET"}

package/dist/services/runtime-lifecycle-policy.js

@@ -0,0 +1,34 @@
+/**
+ * Build shutdown side-effect policy from the requested restart mode.
+ * Main flow: explicit bridge shutdown cleans resources; scheduler restart keeps
+ * SDK/PTY processes and persisted metadata so the scheduler can restore state.
+ */
+export function buildGracefulShutdownPlan(preserveSessions) {
+    const shouldCleanRuntimeState = !preserveSessions;
+    return {
+        terminateSdkSessions: shouldCleanRuntimeState,
+        closePtySessions: shouldCleanRuntimeState,
+        terminateResidualProcesses: shouldCleanRuntimeState,
+        unregisterInstance: shouldCleanRuntimeState,
+        clearPersistedSessions: shouldCleanRuntimeState,
+    };
+}
+/**
+ * Decide whether startup may destructively clean persisted runtime sessions.
+ * Main flow: default bridge restart is non-destructive; operators can opt into
+ * legacy cleanup with AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP=true.
+ */
+export function shouldCleanupPersistedSessionsOnStartup(preserveSessions, env = process.env) {
+    if (preserveSessions) {
+        return false;
+    }
+    return env.AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP === "true";
+}
+/**
+ * Decide whether background orphan monitoring may terminate persisted sessions.
+ * Main flow: process termination is an explicit cleanup action, not a default
+ * monitoring behavior, so restart recovery cannot be undone by auto-clean mode.
+ */
+export function shouldAutoCleanOrphanProcesses(env = process.env) {
+    return env.AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP === "true";
+}

package/dist/services/runtime-lifecycle-policy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-lifecycle-policy.test.d.ts.map

package/dist/services/runtime-lifecycle-policy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-lifecycle-policy.test.d.ts","sourceRoot":"","sources":["../../src/services/runtime-lifecycle-policy.test.ts"],"names":[],"mappings":""}

package/dist/services/runtime-lifecycle-policy.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { buildGracefulShutdownPlan, shouldAutoCleanOrphanProcesses, shouldCleanupPersistedSessionsOnStartup, } from "./runtime-lifecycle-policy.js";
+describe("runtime lifecycle policy", () => {
+    it("keeps agent processes and persisted state during scheduler restart preservation", () => {
+        expect(buildGracefulShutdownPlan(true)).toEqual({
+            terminateSdkSessions: false,
+            closePtySessions: false,
+            terminateResidualProcesses: false,
+            unregisterInstance: false,
+            clearPersistedSessions: false,
+        });
+    });
+    it("cleans runtime state for explicit bridge shutdown", () => {
+        expect(buildGracefulShutdownPlan(false)).toEqual({
+            terminateSdkSessions: true,
+            closePtySessions: true,
+            terminateResidualProcesses: true,
+            unregisterInstance: true,
+            clearPersistedSessions: true,
+        });
+    });
+    it("does not destructively clean persisted sessions on startup unless explicitly enabled", () => {
+        expect(shouldCleanupPersistedSessionsOnStartup(false, {})).toBe(false);
+        expect(shouldCleanupPersistedSessionsOnStartup(false, {
+            AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP: "true",
+        })).toBe(true);
+        expect(shouldCleanupPersistedSessionsOnStartup(true, {
+            AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP: "true",
+        })).toBe(false);
+    });
+    it("does not let orphan monitor terminate preserved sessions unless cleanup is explicit", () => {
+        expect(shouldAutoCleanOrphanProcesses({})).toBe(false);
+        expect(shouldAutoCleanOrphanProcesses({
+            AWS_ORPHAN_AUTO_CLEAN_MODE: "auto",
+        })).toBe(false);
+        expect(shouldAutoCleanOrphanProcesses({
+            AWS_ORPHAN_AUTO_CLEAN_MODE: "auto",
+            AWS_BRIDGE_CLEAN_ORPHANS_ON_STARTUP: "true",
+        })).toBe(true);
+    });
+});

package/dist/services/terminal-persistence.d.ts

@@ -37,6 +37,18 @@ export declare function updatePersistedSessionAutoCommands(agentId: string, comm
     idleInputAutoCommand: string;
     nonInputAutoCommand: string;
 }): Promise<boolean>;
+/**
+ * 更新指定 SDK 会话的细粒度运行状态。
+ *
+ * 主流程：命中 sessionId 后仅替换 runtimeStatus/runtimeAction* 字段，保留会话 PID、命令和工作目录，
+ * 让 scheduler/server 重启后可以从 /runtime/sessions 恢复 Agent 卡片上的具体状态标签。
+ */
+export declare function updatePersistedSessionRuntimeState(sessionId: string, runtimeState: {
+    runtimeStatus: string;
+    runtimeActionType?: string;
+    runtimeActionLabel?: string;
+    runtimeActionDetail?: string;
+}): Promise<boolean>;
 /**
  * 移除持久化会话（从完整文件中删除，包括 stopped 状态的）
  *

package/dist/services/terminal-persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-persistence.d.ts","sourceRoot":"","sources":["../../src/services/terminal-persistence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA8BpD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAOzE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQrF;AAED;;;;GAIG;AACH,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IAAE,oBAAoB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7E;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAKvC;AAED;;;;;GAKG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBpF"}
+{"version":3,"file":"terminal-persistence.d.ts","sourceRoot":"","sources":["../../src/services/terminal-persistence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA8BpD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAOzE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQrF;AAED;;;;GAIG;AACH,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IAAE,oBAAoB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;GAKG;AACH,wBAAsB,kCAAkC,CACtD,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GACA,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7E;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAKvC;AAED;;;;;GAKG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBpF"}

package/dist/services/terminal-persistence.js

@@ -96,6 +96,29 @@ export async function updatePersistedSessionAutoCommands(agentId, commands) {
     }));
     return updated;
 }
+/**
+ * 更新指定 SDK 会话的细粒度运行状态。
+ *
+ * 主流程：命中 sessionId 后仅替换 runtimeStatus/runtimeAction* 字段，保留会话 PID、命令和工作目录，
+ * 让 scheduler/server 重启后可以从 /runtime/sessions 恢复 Agent 卡片上的具体状态标签。
+ */
+export async function updatePersistedSessionRuntimeState(sessionId, runtimeState) {
+    let updated = false;
+    await updatePersistedSessions((sessions) => sessions.map((session) => {
+        if (session.sessionId !== sessionId) {
+            return session;
+        }
+        updated = true;
+        return {
+            ...session,
+            runtimeStatus: runtimeState.runtimeStatus,
+            runtimeActionType: runtimeState.runtimeActionType,
+            runtimeActionLabel: runtimeState.runtimeActionLabel,
+            runtimeActionDetail: runtimeState.runtimeActionDetail,
+        };
+    }));
+    return updated;
+}
 /**
  * 移除持久化会话（从完整文件中删除，包括 stopped 状态的）
  *

package/dist/services/terminal-persistence.test.js

@@ -117,6 +117,24 @@ describe('terminal-persistence service', () => {
         expect(sessions).toHaveLength(1);
         expect(sessions[0].sessionId).toBe('session-new');
     });
+    it('persists latest runtime action state for restart recovery', async () => {
+        await persistence.upsertPersistedSession(makeSession('session-1', 'agent-1'));
+        const updated = await persistence.updatePersistedSessionRuntimeState('session-1', {
+            runtimeStatus: 'tool_using',
+            runtimeActionType: 'mcp',
+            runtimeActionLabel: 'poll_message',
+            runtimeActionDetail: '等待群聊消息',
+        });
+        const sessions = await persistence.loadPersistedSessions();
+        expect(updated).toBe(true);
+        expect(sessions[0]).toMatchObject({
+            sessionId: 'session-1',
+            runtimeStatus: 'tool_using',
+            runtimeActionType: 'mcp',
+            runtimeActionLabel: 'poll_message',
+            runtimeActionDetail: '等待群聊消息',
+        });
+    });
     it('serializes concurrent upserts without losing sessions', async () => {
         await Promise.all([
             persistence.upsertPersistedSession(makeSession('session-1', 'agent-1')),

package/dist/types.d.ts

@@ -230,6 +230,10 @@ export interface PersistedSession {
     command: string;
     startedAt: string;
     status: 'running' | 'stopped';
+    runtimeStatus?: string;
+    runtimeActionType?: string;
+    runtimeActionLabel?: string;
+    runtimeActionDetail?: string;
     pid?: number;
     providerSessionId?: string;
     mode?: 'sdk';
@@ -243,6 +247,10 @@ export interface SessionsListResponse {
         agentId: string;
         workspacePath: string;
         status: string;
+        runtimeStatus?: string;
+        runtimeActionType?: string;
+        runtimeActionLabel?: string;
+        runtimeActionDetail?: string;
         startedAt: string | null;
     }>;
     persisted: PersistedSession[];