@winmatrix/supervisor 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winmatrix/supervisor",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "main": "src/run-agent-engine.mjs",
   "bin": {
@@ -14,10 +14,6 @@
     "build": "node -e \"console.log('no build step')\"",
     "test": "node --test tests/**/*.test.mjs"
   },
-  "dependencies": {
-    "@winmatrix/agent-sdk": "^1.0.5",
-    "@winmatrix/protocol": "^1.0.5"
-  },
   "engines": {
     "node": ">=20"
   }

package/src/claude-session-lib.mjs

@@ -15,6 +15,7 @@ import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 
 export const TRUNCATE_LEN = 4096;
+export const SESSION_DETAIL_TRANSPORT_MAX_BYTES = 48 * 1024;
 export const REDACTED = '[REDACTED]';
 export const SENSITIVE_KEY_PATTERN =
   /(authorization|password|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|session[_-]?key|jwt)/i;
@@ -326,6 +327,89 @@ export function previewValue(value, max = 1000) {
   return text.length > max ? text.slice(0, max) + `…[${text.length - max} chars]` : text;
 }
 
+/**
+ * 将 session-get 结果压缩到 Sandbox exec 的安全传输预算内，避免 stdout 截断后产生非法 JSON。
+ * @param {Record<string, unknown>} detail
+ * @param {number} maxBytes
+ * @returns {Record<string, unknown>}
+ */
+export function compactSessionDetailForTransport(detail, maxBytes = SESSION_DETAIL_TRANSPORT_MAX_BYTES) {
+  const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+  if (serializedBytes(detail) <= maxBytes) return detail;
+
+  const compacted = {
+    ...detail,
+    messages: Array.isArray(detail.messages)
+      ? detail.messages.map((message) => ({
+        ...message,
+        content: Array.isArray(message.content)
+          ? message.content.map((block) => ({
+            ...block,
+            ...(typeof block.text === 'string' && block.text.length > 1200
+              ? { text: `${block.text.slice(0, 1200)}…[transport-truncated]` }
+              : {}),
+          }))
+          : message.content,
+      }))
+      : [],
+    metadata: detail.metadata && typeof detail.metadata === 'object'
+      ? {
+        ...detail.metadata,
+        ...(typeof detail.metadata.assistantText === 'string'
+          ? { assistantText: detail.metadata.assistantText.slice(0, 8000) }
+          : {}),
+        ...(Array.isArray(detail.metadata.userPrompts)
+          ? { userPrompts: detail.metadata.userPrompts.slice(-20).map((prompt) => (
+            typeof prompt === 'string' && prompt.length > 800
+              ? `${prompt.slice(0, 800)}…[transport-truncated]`
+              : prompt
+          )) }
+          : {}),
+        ...(detail.metadata.diagnostics && typeof detail.metadata.diagnostics === 'object'
+          ? {
+            diagnostics: {
+              ...detail.metadata.diagnostics,
+              ...(Array.isArray(detail.metadata.diagnostics.toolCalls)
+                ? { toolCalls: detail.metadata.diagnostics.toolCalls.slice(-20) }
+                : {}),
+              ...(Array.isArray(detail.metadata.diagnostics.toolResults)
+                ? { toolResults: detail.metadata.diagnostics.toolResults.slice(-20) }
+                : {}),
+              ...(Array.isArray(detail.metadata.diagnostics.timeline)
+                ? { timeline: detail.metadata.diagnostics.timeline.slice(-40) }
+                : {}),
+            },
+          }
+          : {}),
+        ...(Array.isArray(detail.metadata.rawMessages) ? { rawMessages: undefined, rawMessagesIncluded: false } : {}),
+        transportCompacted: true,
+      }
+      : detail.metadata,
+  };
+
+  if (serializedBytes(compacted) <= maxBytes) return compacted;
+
+  const minimal = {
+    ...compacted,
+    messages: [],
+    metadata: compacted.metadata && typeof compacted.metadata === 'object'
+      ? {
+        ...compacted.metadata,
+        assistantText: typeof compacted.metadata.assistantText === 'string'
+          ? compacted.metadata.assistantText.slice(0, 4000)
+          : compacted.metadata.assistantText,
+        userPrompts: Array.isArray(compacted.metadata.userPrompts)
+          ? compacted.metadata.userPrompts.map((prompt) => (
+            typeof prompt === 'string' ? prompt.slice(0, 800) : prompt
+          ))
+          : compacted.metadata.userPrompts,
+        diagnostics: undefined,
+      }
+      : compacted.metadata,
+  };
+  return minimal;
+}
+
 /** @param {string} text */
 export function redactPreviewText(text) {
   return text

package/src/engine-run-success.mjs

@@ -0,0 +1,118 @@
+/**
+ * 工作站引擎终态成败：不得只看进程 exitCode。
+ *
+ * recover-workstation-context-overflow D2：SDK result 帧 `is_error` /
+ * 失败 `subtype`（至少 error_during_execution / error_max_turns）须写成失败，
+ * 失败原因进 error，可见正文仍保留。缺字段时回退 exitCode（旧镜像靠 server P0 短语）。
+ */
+
+/** @type {ReadonlySet<string>} */
+export const SDK_FAILURE_SUBTYPES = Object.freeze(new Set([
+  'error_during_execution',
+  'error_max_turns',
+]));
+
+/**
+ * @param {unknown} subtype
+ * @returns {subtype is string}
+ */
+export function isSdkFailureSubtype(subtype) {
+  return typeof subtype === 'string' && SDK_FAILURE_SUBTYPES.has(subtype);
+}
+
+/**
+ * 从 events.jsonl 条目（envelope 或裸事件）提取最后一条 result 上的 SDK 成败信号。
+ *
+ * @param {unknown[]} events
+ * @returns {{
+ *   isError: boolean,
+ *   subtype: string | undefined,
+ *   visibleText: string | undefined,
+ *   error: string | undefined,
+ *   sessionId: string | undefined,
+ * }}
+ */
+export function extractSdkResultSignals(events) {
+  const empty = {
+    isError: false,
+    subtype: undefined,
+    visibleText: undefined,
+    error: undefined,
+    sessionId: undefined,
+  };
+  if (!Array.isArray(events)) return empty;
+
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const raw = events[i];
+    const evt = raw && typeof raw === 'object' && raw.event && typeof raw.event === 'object'
+      ? raw.event
+      : raw;
+    if (!evt || typeof evt !== 'object' || evt.type !== 'result') continue;
+
+    const payload = evt.result && typeof evt.result === 'object' && !Array.isArray(evt.result)
+      ? evt.result
+      : evt;
+
+    const isError = payload.is_error === true || payload.isError === true;
+    const subtype = typeof payload.subtype === 'string'
+      ? payload.subtype
+      : typeof payload.sdkSubtype === 'string'
+        ? payload.sdkSubtype
+        : undefined;
+    const visibleText = typeof payload.text === 'string'
+      ? payload.text
+      : typeof payload.content === 'string'
+        ? payload.content
+        : undefined;
+    const error = typeof payload.error === 'string' ? payload.error : undefined;
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+
+    return { isError, subtype, visibleText, error, sessionId };
+  }
+
+  return empty;
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} [input.cancelled]
+ * @param {number | null | undefined} [input.exitCode]
+ * @param {boolean} [input.isError]
+ * @param {string} [input.subtype]
+ * @param {string} [input.visibleText]
+ * @param {string} [input.existingError]
+ * @returns {{ success: boolean, status: 'cancelled' | 'completed' | 'failed', error?: string }}
+ */
+export function resolveEngineRunOutcome({
+  cancelled = false,
+  exitCode,
+  isError = false,
+  subtype,
+  visibleText,
+  existingError,
+} = {}) {
+  if (cancelled) {
+    return { success: false, status: 'cancelled', error: 'cancelled' };
+  }
+
+  const sdkFailed = isError === true || isSdkFailureSubtype(subtype);
+  if (sdkFailed) {
+    const trimmedVisible = typeof visibleText === 'string' ? visibleText.trim() : '';
+    const trimmedExisting = typeof existingError === 'string' ? existingError.trim() : '';
+    const error = trimmedExisting
+      || trimmedVisible
+      || (isSdkFailureSubtype(subtype) ? `SDK result subtype=${subtype}` : 'SDK result is_error=true');
+    return { success: false, status: 'failed', error };
+  }
+
+  if (exitCode !== 0) {
+    const trimmedExisting = typeof existingError === 'string' ? existingError.trim() : '';
+    return {
+      success: false,
+      status: 'failed',
+      error: trimmedExisting || `Engine exited with code ${exitCode}`,
+    };
+  }
+
+  return { success: true, status: 'completed' };
+}

package/src/env-sanitizer.mjs

@@ -69,6 +69,10 @@ export function isFilteredEnvKey(key) {
   // 精确匹配的过滤项（优先级最高）
   if (FILTERED_EXACT_KEYS.has(key)) return true;
 
+  // Pod 创建时注入的 Claude 持久根目录必须和 HOME 一起传给 Engine。
+  // 其余 CLAUDE_CODE_* 仍按下方规则过滤，避免 Supervisor 内部标记泄漏。
+  if (/^CLAUDE_CODE_HOME$/i.test(key)) return false;
+
   // 先检查是否匹配过滤模式（过滤优先于白名单）
   // 这样 CLAUDE_CODE_ENTRYPOINT 被过滤，即使 CLAUDE_ 在白名单中
   for (const pattern of FILTERED_ENV_PATTERNS) {

package/src/run-agent-engine.mjs

@@ -39,6 +39,7 @@ import {
   cloneMessagesForJson,
   buildCliReplayGuide,
   buildDiagnostics,
+  compactSessionDetailForTransport,
   maybeTruncate,
   resolveDirViaGlobalListSessions,
 } from './claude-session-lib.mjs';
@@ -50,19 +51,29 @@ import { filterBlockedArgs, formatBlockedArgsAudit } from './blocked-args-filter
 import { createDeliverableState, updateDeliverable, extractDeliverable, computeDeliverableFromEvents } from './deliverable-tracker.mjs';
 import { extractTokenUsage } from './token-usage.mjs';
 import { isResumeRejected, buildContinuityNotice, buildResumeDegradedEvent, isResumeFailureOnExit } from './resume-degradation.mjs';
+import { extractSdkResultSignals, resolveEngineRunOutcome } from './engine-run-success.mjs';
 
 const require = createRequire(import.meta.url);
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawn, spawnSync } = require('node:child_process');
 const http = require('node:http');
+const https = require('node:https');
 const readline = require('node:readline');
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 
-// Supervisor 根目录（每个 runKey 一个子目录）
-const SUPERVISOR_ROOT = process.env.WINMATRIX_SUPERVISOR_ROOT || '/tmp/agent-engine-supervisor';
+// Supervisor 根目录（每个 runKey 一个子目录）。必须位于 Pod 的持久 agent-home，
+// 容器重建后可继续读取状态与事件；禁止回退到 /tmp，避免表面成功但状态丢失。
+const SUPERVISOR_HOME = process.env.HOME?.trim();
+const SUPERVISOR_ROOT = process.env.WINMATRIX_SUPERVISOR_ROOT?.trim()
+  || (SUPERVISOR_HOME ? path.join(SUPERVISOR_HOME, '.winmatrix', 'agent-engine-supervisor') : '');
+if (!SUPERVISOR_ROOT) {
+  throw new Error('WINMATRIX_SUPERVISOR_ROOT 或 HOME 必须指向持久 agent-home');
+}
 const CALLBACK_TIMEOUT_MS = Number(process.env.WINMATRIX_CALLBACK_TIMEOUT_MS) || 5000;
 const MAX_ACTIVE_RUNS = Number(process.env.WINMATRIX_MAX_ACTIVE_RUNS) || 100;
+/** 单次 events 请求返回的最大事件数，避免大量事件堆积导致响应超限。 */
+const MAX_EVENTS_PAGE_SIZE = 500;
 
 // 确保根目录存在
 if (!fs.existsSync(SUPERVISOR_ROOT)) {
@@ -316,6 +327,9 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
   };
 }
 
+/** 重定向最大跳数，防重定向环。 */
+const MAX_CALLBACK_REDIRECTS = 5;
+
 /**
  * 发送 callback 到 Server
  * @param {string} callbackUrl - Callback URL
@@ -324,44 +338,76 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
  * @returns {Promise<void>}
  */
 async function sendCallback(callbackUrl, token, payload) {
-  return new Promise((resolve, reject) => {
-    const url = new URL(callbackUrl);
-    const data = JSON.stringify(payload);
-    const options = {
-      hostname: url.hostname,
-      port: url.port || 80,
-      path: url.pathname + url.search,
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(data),
-        'Authorization': `Bearer ${token}`,
-      },
-      timeout: CALLBACK_TIMEOUT_MS,
-    };
+  const data = JSON.stringify(payload);
+  let currentUrl = new URL(callbackUrl);
+  const originalHostname = currentUrl.hostname;
+
+  for (let redirects = 0; redirects <= MAX_CALLBACK_REDIRECTS; redirects += 1) {
+    const result = await new Promise((resolve, reject) => {
+      const isHttps = currentUrl.protocol === 'https:';
+      const client = isHttps ? https : http;
+      const options = {
+        hostname: currentUrl.hostname,
+        port: currentUrl.port || (isHttps ? 443 : 80),
+        path: currentUrl.pathname + currentUrl.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+          'Authorization': `Bearer ${token}`,
+        },
+        timeout: CALLBACK_TIMEOUT_MS,
+      };
 
-    const req = http.request(options, (res) => {
-      if (res.statusCode >= 200 && res.statusCode < 300) {
-        console.log(`[run-agent-engine] Callback sent successfully: ${callbackUrl}`);
-        resolve();
-      } else {
-        reject(new Error(`Callback failed with status ${res.statusCode}`));
-      }
-    });
+      const req = client.request(options, (res) => {
+        const redirectStatus = [301, 302, 307, 308];
+        const location = res.headers.location;
+        if (redirectStatus.includes(res.statusCode) && location) {
+          res.resume();
+          resolve({ redirect: location });
+          return;
+        }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          res.resume();
+          resolve({ ok: true });
+          return;
+        }
+        res.resume();
+        resolve({ ok: false, status: res.statusCode });
+      });
 
-    req.on('error', (error) => {
-      console.error(`[run-agent-engine] Callback error:`, error.message);
-      reject(error);
-    });
+      req.on('error', (error) => {
+        reject(error);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Callback timeout'));
+      });
 
-    req.on('timeout', () => {
-      req.destroy();
-      reject(new Error('Callback timeout'));
+      req.write(data);
+      req.end();
     });
 
-    req.write(data);
-    req.end();
-  });
+    if (result.ok) {
+      console.log(`[run-agent-engine] Callback sent successfully: ${callbackUrl}`);
+      return;
+    }
+    if (result.ok === false) {
+      throw new Error(`Callback failed with status ${result.status}`);
+    }
+
+    // 跟随重定向：仅允许同 hostname 的 http↔https 跳转（防 SSRF）。
+    const nextUrl = new URL(result.redirect, currentUrl);
+    if (nextUrl.hostname !== originalHostname) {
+      throw new Error(`Callback redirect to different host rejected: ${nextUrl.hostname}`);
+    }
+    if (redirects === MAX_CALLBACK_REDIRECTS) {
+      throw new Error(`Callback redirect limit exceeded (${MAX_CALLBACK_REDIRECTS})`);
+    }
+    currentUrl = nextUrl;
+  }
+  throw new Error(`Callback redirect limit exceeded (${MAX_CALLBACK_REDIRECTS})`);
 }
 
 /**
@@ -449,12 +495,12 @@ async function runOwned(payload) {
     // D11.2: detached=true 用于创建独立进程组，两阶段关闭时可 SIGTERM 整组
     detached: process.platform !== 'win32',
   });
+  // 链路日志走 stderr：stdout 是协议通道（ack JSON），console.log 会污染
+  console.error(`[run-agent-engine] runKey=${runKey} engine spawn: engineId=${launchSpec.engineId} pid=${child.pid} argv=${argv.join(' ')} workDir=${launchSpec.workDir || '(cwd)'}`);
 
   // 写入 stdin
-  if (stdinData) {
-    child.stdin.write(stdinData);
-    child.stdin.end();
-  }
+  if (stdinData) child.stdin.write(stdinData);
+  child.stdin.end();
 
   // 读取 stdout JSONL 事件，同时写入 stdout.log
   const stdoutWriteStream = fs.createWriteStream(logFile, { flags: 'a' });
@@ -585,6 +631,7 @@ async function runOwned(payload) {
     let resultText = '';
     let usage = null;
     let resultSessionId = null;
+    let sdkSignals = extractSdkResultSignals([]);
     try {
       const eventsFile = path.join(getRunDir(runKey), 'events.jsonl');
       if (fs.existsSync(eventsFile)) {
@@ -611,14 +658,30 @@ async function runOwned(payload) {
             break;
           }
         }
+
+        sdkSignals = extractSdkResultSignals(events);
+        if (!resultSessionId && sdkSignals.sessionId) {
+          resultSessionId = sdkSignals.sessionId;
+        }
+        if (!resultText?.trim() && sdkSignals.visibleText) {
+          resultText = sdkSignals.visibleText;
+        }
       }
     } catch (err) {
       console.error(`[run-agent-engine] Failed to compute deliverable/usage for ${runKey}:`, err.message);
     }
+    const outcome = resolveEngineRunOutcome({
+      cancelled,
+      exitCode: code,
+      isError: sdkSignals.isError,
+      subtype: sdkSignals.subtype,
+      visibleText: resultText,
+      existingError: sdkSignals.error,
+    });
 
     const endMetadata = {
       ...metadata,
-      status: cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed',
+      status: outcome.status,
       endTime: new Date().toISOString(),
       exitCode: code,
       ...(signal ? { signal } : {}),
@@ -628,35 +691,56 @@ async function runOwned(payload) {
     activeRuns.delete(runKey);
     saveActiveRuns();
 
-    // D11.4: 构建包含 deliverable 和 usage 的结果
+    // D2：success 综合 SDK is_error / 失败 subtype，exitCode === 0 不得单独判成功
     const result = {
-      success: !cancelled && code === 0,
+      success: outcome.success,
       text: resultText || undefined,
       ...(resultSessionId ? { sessionId: resultSessionId } : {}),
       ...(usage ? { usage } : {}),
-      ...(cancelled ? { error: 'cancelled' } : code === 0 ? {} : { error: `Engine exited with code ${code}` }),
+      ...(outcome.error ? { error: outcome.error } : {}),
       metadata: {
         exitCode: code,
         ...(signal ? { signal } : {}),
         ...(resumeFailed ? { resumeDegraded: true } : {}),
         ...(usage?.source ? { usageSource: usage.source } : {}),
+        ...(sdkSignals.isError ? { is_error: true } : {}),
+        ...(sdkSignals.subtype ? { subtype: sdkSignals.subtype } : {}),
       },
     };
     saveResult(runKey, result);
     appendEvent(runKey, endMetadata, { type: 'result', result });
+    console.error(`[run-agent-engine] runKey=${runKey} run terminal: status=${endMetadata.status} exitCode=${code}${signal ? ` signal=${signal}` : ''} success=${result.success} deliverableLen=${(resultText || '').length} sessionId=${resultSessionId ?? 'none'}${resumeFailed ? ' resumeDegraded=true' : ''}`);
 
     // 发送 callback（如果有）
     // merge-workstation-tools R11 / 9b.5：payload 对齐 V1 run-claude-agent.mjs
     // 字段语义，满足 /api/v1/workstation-task-callbacks 的 zod schema（recordId 必填），
     // 使 HTTP callback 快路径对 V2 run 也能闭合（此前仅 observer 投影 + reconcile 兜底）。
     if (privateBindings?.callback) {
+      console.error(`[run-agent-engine] runKey=${runKey} callback 发送: url=${privateBindings.callback.url} status=${endMetadata.status}`);
       sendCallback(
         privateBindings.callback.url,
         privateBindings.callback.token,
         buildTerminalCallbackPayload(runKey, endMetadata, result, metadata),
       ).catch((error) => {
-        console.error(`[run-agent-engine] Callback failed for ${runKey}:`, error.message);
+        // callback 失败必须可观测：失败原因写入既有 result.json（reconcile 已读该文件），
+        // 而非仅 console.error（worker stdio 被上层 ignore，会静默吞掉）。
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.error(`[run-agent-engine] Callback failed for ${runKey}:`, errorMsg);
+        try {
+          const current = loadResult(runKey) ?? {};
+          saveResult(runKey, {
+            ...current,
+            metadata: {
+              ...(current.metadata && typeof current.metadata === 'object' ? current.metadata : {}),
+              callbackError: errorMsg,
+            },
+          });
+        } catch (persistError) {
+          console.error(`[run-agent-engine] Callback failed to persist for ${runKey}:`, persistError.message);
+        }
       });
+    } else {
+      console.error(`[run-agent-engine] runKey=${runKey} 无 callback 配置，终态依赖 observer 投影/reconcile`);
     }
     resolve();
   }));
@@ -797,7 +881,8 @@ function listEvents(runKey, afterSequence = 0) {
   if (!fs.existsSync(file)) return [];
   return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)
     .map((line) => JSON.parse(line))
-    .filter((event) => event.sequence > afterSequence);
+    .filter((event) => event.sequence > afterSequence)
+    .slice(0, MAX_EVENTS_PAGE_SIZE);
 }
 
 /**
@@ -847,6 +932,11 @@ function buildEngineArgv(launchSpec) {
     }
   }
 
+  // G9: 透传上下文预算
+  if (launchSpec.contextBudget) {
+    argv.push('--context-budget', JSON.stringify(launchSpec.contextBudget));
+  }
+
   // 添加 input（第一个 text block）
   if (input?.blocks) {
     for (const block of input.blocks) {
@@ -886,7 +976,26 @@ function buildEngineArgv(launchSpec) {
 function status(runKey) {
   const metadata = loadRunMetadata(runKey);
   if (!metadata) {
-    throw new Error(`Run not found: ${runKey}`);
+    // status.json 尚未写入，说明 run 还在启动阶段（launch 中 saveRunMetadata 之前的耗时操作）。
+    // 返回 starting 状态而非抛异常，避免 inspect 轮询返回 502。
+    return {
+      ref: {
+        instance: { instanceId: '', hostKind: 'workstation' },
+        executionSnapshot: {},
+        runKey,
+        engineId: '',
+        invocationFingerprint: '',
+      },
+      status: 'starting',
+      executionDurability: 'host_persistent',
+      eventStreamMode: 'replay',
+      eventRetention: { maxEvents: 10000 },
+      lastSequence: 0,
+      pendingInteractions: [],
+      recoverable: true,
+      runtimeVersion: 'run-agent-engine/1',
+      protocolVersion: '1',
+    };
   }
 
   const result = loadResult(runKey);
@@ -1194,6 +1303,8 @@ async function sessionGet() {
   const includeRawMessages = hasFlag(argv, '--include-raw-messages');
   const includeSystem = hasFlag(argv, '--include-system');
   const noTruncate = hasFlag(argv, '--no-truncate');
+  const noMessages = hasFlag(argv, '--no-messages');
+  const joinedMessages = hasFlag(argv, '--joined-messages');
   const normalizedWorkDir = getOptValue(argv, '--normalized-work-dir');
 
   const { sdk, error } = loadSdk();
@@ -1239,6 +1350,20 @@ async function sessionGet() {
     }
   }
 
+  // --no-messages：仅返回 session 元数据，跳过消息体（避免大 payload 触发 sandbox stdout 截断）。
+  if (noMessages) {
+    return {
+      session: sessionSummary(sessionMeta, engineId),
+      messages: [],
+      rawMessagesIncluded: false,
+      metadata: {
+        messageCount: sessionMeta.messageCount,
+        sessionMessagesProjectDir: msgOpts.dir != null ? String(msgOpts.dir) : undefined,
+        sessionMessagesDirSource: dirSource,
+      },
+    };
+  }
+
   /** @type {unknown[]} */
   let messages = [];
   try {
@@ -1307,12 +1432,34 @@ async function sessionGet() {
   const cliReplayGuide = buildCliReplayGuide(sessionMeta, sessionId);
   const diagnostics = deepRedactSessionValue(buildDiagnostics(messages, noTruncate));
 
+  // --joined-messages：拼接消息文本，替代结构化 messages[]，避免大会话 stdout 截断。
+  let joinedMessagesText = '';
+  if (joinedMessages) {
+    const parts = [];
+    for (const m of messages) {
+      if (m == null || typeof m !== 'object') continue;
+      const rec = /** @type {Record<string, unknown>} */ (m);
+      const type = String(rec.type ?? '');
+      const text = extractText(rec.message);
+      if (text) {
+        parts.push(`${type}: ${text}`);
+      }
+    }
+    joinedMessagesText = parts.join('\n\n');
+  }
+
   /** @type {Record<string, unknown>} */
   const detail = {
     session: sessionSummary(sessionMeta, engineId),
-    messages: structuredMessages,
     rawMessagesIncluded: includeRawMessages,
   };
+  // joinedMessages 模式：messages 置空数组（schema 必填），正文走 joinedMessages 文本。
+  if (joinedMessages) {
+    detail.messages = [];
+    detail.joinedMessages = joinedMessagesText;
+  } else {
+    detail.messages = structuredMessages;
+  }
 
   /** @type {Record<string, unknown>} */
   const metadata = {
@@ -1333,7 +1480,7 @@ async function sessionGet() {
     if (!ok && messages.length > 0) metadata.rawMessagesSerializationFailed = true;
   }
 
-  return { ...detail, metadata };
+  return compactSessionDetailForTransport({ ...detail, metadata });
 }
 
 /**
@@ -1349,7 +1496,6 @@ async function sessionSearch() {
   const cursor = getOptValue(argv, '--cursor');
   const offset = decodeOffsetCursor(cursor);
   const normalizedWorkDir = getOptValue(argv, '--normalized-work-dir');
-
   const { sdk, error } = loadSdk();
   if (!sdk || typeof sdk.listSessions !== 'function') {
     return { hits: [], error: error ?? 'SDK 不支持 listSessions' };

package/src/run-engine.mjs

@@ -6,6 +6,7 @@
  *        --engine <claude-code|codex|hermes|openclaw> \
  *        [--model <model>] [--permission-mode <mode>] \
  *        [--allowed-tools <tool1,tool2>] [--resume <sessionId>|--fork <sessionId>] \
+ *        [--context-budget <json>] \
  *        [--timeout <seconds>] [--work-dir <dir>] \
  *        <prompt>
  *
@@ -13,11 +14,75 @@
  * 输出到 stdout，供 run-agent-engine.mjs 解析并写入 events.jsonl。
  */
 import { createRequire } from 'node:module';
+import { isSdkFailureSubtype } from './engine-run-success.mjs';
 
 const require = createRequire(import.meta.url);
 
 const SDK_PATH = process.env.WINMATRIX_AGENT_SDK_PATH
   || '/home/node/.local/lib/node_modules/@winmatrix/agent-sdk';
+const MAX_PRIVATE_BINDINGS_BYTES = 64 * 1024;
+const MCP_DYNAMIC_SECRET_KEYS = new Set([
+  'WINMATRIX_TOOL_PROXY_URL',
+  'WINMATRIX_TOOL_PROXY_TOKEN',
+  'WINMATRIX_TOOL_PROXY_PROJECT_ID',
+]);
+
+function normalizeEventText(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  if (Array.isArray(value)) {
+    return value.map(normalizeEventText).filter(Boolean).join('\n');
+  }
+  if (typeof value === 'object') {
+    if (typeof value.text === 'string') return value.text;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '';
+    }
+  }
+  return String(value);
+}
+
+async function readMcpBinding() {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > MAX_PRIVATE_BINDINGS_BYTES) {
+      return { error: 'MCP_BINDING_REQUIRED: 私有控制绑定超过允许大小。' };
+    }
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return {};
+
+  try {
+    const raw = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!raw || raw.hostKind !== 'workstation') {
+      return { error: 'MCP_BINDING_REQUIRED: 私有控制绑定 hostKind 无效。' };
+    }
+    const dynamicSecrets = raw.dynamicSecrets;
+    if (dynamicSecrets === undefined) {
+      return { error: 'MCP_BINDING_REQUIRED: 工作站缺少 MCP 绑定。' };
+    }
+    if (!dynamicSecrets || typeof dynamicSecrets !== 'object' || Array.isArray(dynamicSecrets)) {
+      return { error: 'MCP_BINDING_REQUIRED: MCP 绑定格式无效。' };
+    }
+    for (const [key, value] of Object.entries(dynamicSecrets)) {
+      if (!MCP_DYNAMIC_SECRET_KEYS.has(key) || typeof value !== 'string') {
+        return { error: 'MCP_BINDING_REQUIRED: MCP 绑定包含不允许字段。' };
+      }
+    }
+    const url = dynamicSecrets.WINMATRIX_TOOL_PROXY_URL?.trim();
+    const token = dynamicSecrets.WINMATRIX_TOOL_PROXY_TOKEN?.trim();
+    if (!url || !token) {
+      return { error: 'MCP_BINDING_REQUIRED: MCP 绑定不完整。' };
+    }
+    return { binding: { url, token } };
+  } catch {
+    return { error: 'MCP_BINDING_REQUIRED: 私有控制绑定不是有效 JSON。' };
+  }
+}
 
 function parseArgs(argv) {
   const options = {
@@ -29,6 +94,7 @@ function parseArgs(argv) {
     fork: undefined,
     timeoutSec: undefined,
     workDir: undefined,
+    contextBudget: undefined,
   };
   const positionals = [];
 
@@ -50,6 +116,18 @@ function parseArgs(argv) {
       options.timeoutSec = argv[++i];
     } else if (arg === '--work-dir') {
       options.workDir = argv[++i];
+    } else if (arg === '--context-budget') {
+      const raw = argv[++i];
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+          options.contextBudget = parsed;
+        } else {
+          console.error('[run-engine] --context-budget 不是有效 JSON 对象, 已忽略');
+        }
+      } catch {
+        console.error('[run-engine] --context-budget JSON 解析失败, 已忽略');
+      }
     } else if (arg.startsWith('--')) {
       // 忽略未来可能透传的 engine-specific 选项；后续可按 engineId 路由
       console.error(`[run-engine] 忽略未知选项: ${arg}`);
@@ -78,6 +156,13 @@ async function main() {
     process.exit(1);
   }
 
+  const mcpBinding = await readMcpBinding();
+  if (mcpBinding.error) {
+    writeEvent({ type: 'error', error: mcpBinding.error, code: 'MCP_CONNECTION_FAILED' });
+    process.exitCode = 1;
+    return;
+  }
+
   let sdk;
   try {
     sdk = require(SDK_PATH);
@@ -92,8 +177,19 @@ async function main() {
     CodexAdapter,
     HermesAdapter,
     OpenClawAdapter,
+    validateMcpBridgeUrl,
   } = sdk;
 
+  if (mcpBinding.binding) {
+    try {
+      validateMcpBridgeUrl(mcpBinding.binding.url);
+    } catch (err) {
+      writeEvent({ type: 'error', error: `MCP_BINDING_REQUIRED: MCP URL 无效: ${err.message}`, code: 'MCP_CONNECTION_FAILED' });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   const registry = new AdapterRegistry();
   registry.register('claude-code', ClaudeAdapter);
   registry.register('codex', CodexAdapter);
@@ -105,7 +201,7 @@ async function main() {
     process.exit(1);
   }
 
-  const adapterConfig = {};
+  const adapterConfig = mcpBinding.binding ? { mcpBridgeUrl: mcpBinding.binding.url } : {};
   const adapter = registry.create(options.engineId, adapterConfig);
 
   /** @type {import('@winmatrix/agent-sdk').AgentTaskContext} */
@@ -116,9 +212,13 @@ async function main() {
     engineId: options.engineId,
     workDir: options.workDir,
   };
+  if (mcpBinding.binding) task.mcpToken = mcpBinding.binding.token;
+  if (options.contextBudget) task.contextBudget = options.contextBudget;
 
   if (options.engineId === 'claude-code') {
-    task.claude = {};
+    // Coding workstation 使用 Agent SDK 路径：任务 MCP 仅随 query() 显式传入，
+    // 不落盘到 artifact，也不改写 Pod 注入的持久 agent-home。
+    task.claude = { useAgentSdk: true };
     if (options.permissionMode) task.claude.permissionMode = options.permissionMode;
     if (options.allowedTools) task.claude.tools = options.allowedTools.split(',').map((s) => s.trim());
   } else if (options.engineId === 'hermes') {
@@ -150,28 +250,53 @@ async function main() {
   }
 
   try {
+    const startedAt = Date.now();
+    // 链路日志走 stderr：stdout 是 JSONL 协议通道
+    console.error(`[run-engine] pid=${process.pid} adapter.execute 开始: engineId=${options.engineId} workDir=${options.workDir ?? '(cwd)'} resume=${options.resume ?? 'none'} fork=${options.fork ?? 'none'} timeoutSec=${options.timeoutSec ?? 'none'}`);
+    let eventCount = 0;
     for await (const event of adapter.execute(task, abortController?.signal)) {
+      eventCount += 1;
       switch (event.type) {
         case 'delta':
-          writeEvent({ type: 'content_delta', text: event.content });
+          if (event.engineEvent) {
+            writeEvent(event.engineEvent);
+          } else {
+            writeEvent({ type: 'content_delta', text: normalizeEventText(event.content) });
+          }
           break;
         case 'thinking':
-          writeEvent({ type: 'thinking_delta', text: event.content });
+          if (event.engineEvent) {
+            writeEvent(event.engineEvent);
+          } else {
+            writeEvent({ type: 'thinking_delta', text: normalizeEventText(event.content) });
+          }
           break;
         case 'tool_call':
           writeEvent({ type: 'tool_call', name: event.name, input: event.args });
           break;
-        case 'result':
+        case 'result': {
+          const isError = event.isError === true;
+          const subtype = typeof event.sdkSubtype === 'string' ? event.sdkSubtype : undefined;
+          const sdkFailed = isError || isSdkFailureSubtype(subtype);
+          const text = normalizeEventText(event.content);
+          const error = sdkFailed
+            ? (text.trim() || (subtype ? `SDK result subtype=${subtype}` : 'SDK result is_error=true'))
+            : undefined;
+          console.error(`[run-engine] pid=${process.pid} adapter.execute 结束: engineId=${options.engineId} events=${eventCount} durationMs=${Date.now() - startedAt} sessionId=${event.sessionId ?? 'none'} success=${!sdkFailed} subtype=${subtype ?? 'none'}`);
           writeEvent({
             type: 'result',
             result: {
-              success: true,
-              text: event.content,
+              success: !sdkFailed,
+              text,
               ...(event.sessionId ? { sessionId: event.sessionId } : {}),
               ...(event.usage ? { usage: event.usage } : {}),
+              ...(isError ? { is_error: true } : {}),
+              ...(subtype ? { subtype } : {}),
+              ...(error ? { error } : {}),
             },
           });
           break;
+        }
         case 'error':
           writeEvent({ type: 'error', error: event.message, code: event.code });
           break;
@@ -182,6 +307,7 @@ async function main() {
     }
     process.exit(0);
   } catch (e) {
+    console.error(`[run-engine] pid=${process.pid} adapter.execute 异常: engineId=${options.engineId} error=${e instanceof Error ? e.message : String(e)}`);
     writeEvent({ type: 'error', error: e instanceof Error ? e.message : String(e) });
     process.exit(1);
   } finally {