@winmatrix/supervisor 1.0.5 → 1.0.7

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,30 @@ 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;
+const LAUNCH_ACK_TIMEOUT_MS = Number(process.env.WINMATRIX_LAUNCH_ACK_TIMEOUT_MS) || 10_000;
+/** 单次 events 请求返回的最大事件数，避免大量事件堆积导致响应超限。 */
+const MAX_EVENTS_PAGE_SIZE = 500;
 
 // 确保根目录存在
 if (!fs.existsSync(SUPERVISOR_ROOT)) {
@@ -81,7 +93,27 @@ function saveActiveRuns() {
     runKey,
     metadata,
   }));
-  fs.writeFileSync(activeRunsFile, JSON.stringify(data, null, 2), 'utf8');
+  atomicWriteFile(activeRunsFile, JSON.stringify(data, null, 2));
+}
+
+function atomicWriteFile(filePath, content) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  fs.writeFileSync(tempPath, content, 'utf8');
+  try {
+    fs.renameSync(tempPath, filePath);
+  } finally {
+    try { fs.rmSync(tempPath, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+function atomicCreateExclusive(filePath, content) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  fs.writeFileSync(tempPath, content, { encoding: 'utf8', mode: 0o600 });
+  try {
+    fs.linkSync(tempPath, filePath);
+  } finally {
+    try { fs.rmSync(tempPath, { force: true }); } catch { /* best effort */ }
+  }
 }
 
 /**
@@ -188,7 +220,7 @@ function saveRunMetadata(runKey, metadata) {
     fs.mkdirSync(runDir, { recursive: true });
   }
   const statusFile = path.join(runDir, 'status.json');
-  fs.writeFileSync(statusFile, JSON.stringify(metadata, null, 2), 'utf8');
+  atomicWriteFile(statusFile, JSON.stringify(metadata, null, 2));
 }
 
 /**
@@ -221,7 +253,7 @@ function saveResult(runKey, result) {
     fs.mkdirSync(runDir, { recursive: true });
   }
   const resultFile = path.join(runDir, 'result.json');
-  fs.writeFileSync(resultFile, JSON.stringify(result, null, 2), 'utf8');
+  atomicWriteFile(resultFile, JSON.stringify(result, null, 2));
 }
 
 /**
@@ -280,7 +312,7 @@ function hasCancelMarker(runKey) {
  * @param {RunMetadata} startMetadata - 启动元数据（startTime）
  * @returns {object} Callback payload
  */
-function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata) {
+function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata) {
   const sep = runKey.lastIndexOf(':');
   const recordId = sep > 0 ? runKey.slice(0, sep) : runKey;
   const parsedAttempt = sep > 0 ? Number(runKey.slice(sep + 1)) : NaN;
@@ -293,8 +325,10 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
     ? Math.round((endMs - startMs) / 1000)
     : undefined;
 
-  const text = typeof result?.text === 'string' ? result.text : undefined;
-  return {
+  const text = typeof result?.text === 'string' ? result.text : undefined;
+  const engineId = typeof startMetadata?.engineId === 'string' ? startMetadata.engineId : undefined;
+  const engineSessionId = typeof result?.sessionId === 'string' ? result.sessionId : undefined;
+  return {
     recordId,
     attemptNo,
     runKey,
@@ -303,7 +337,7 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
     result: text,
     error: typeof result?.error === 'string' ? result.error : undefined,
     durationSeconds,
-    claudeSessionId: typeof result?.sessionId === 'string' ? result.sessionId : undefined,
+    claudeSessionId: engineId === 'claude-code' ? engineSessionId : undefined,
     statusFilePath: path.join(runDir, 'status.json'),
     resultFilePath: path.join(runDir, 'result.json'),
     completedAt: endMetadata.endTime,
@@ -311,10 +345,16 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
       exitCode: endMetadata.exitCode,
       ...(endMetadata.signal ? { signal: endMetadata.signal } : {}),
       ...(endMetadata.resumeDegraded ? { resumeDegraded: true } : {}),
-      ...(result?.usage ? { usage: result.usage } : {}),
-    },
-  };
-}
+      ...(result?.usage ? { usage: result.usage } : {}),
+      ...(engineId && engineId !== 'claude-code' && engineSessionId
+        ? { agentEngine: { engineId, sessionId: engineSessionId } }
+        : {}),
+    },
+  };
+}
+
+/** 重定向最大跳数，防重定向环。 */
+const MAX_CALLBACK_REDIRECTS = 5;
 
 /**
  * 发送 callback 到 Server
@@ -324,44 +364,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 +521,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' });
@@ -487,6 +559,10 @@ async function runOwned(payload) {
     instanceId: payload.instanceId,
     lastSequence: 0,
   };
+  const testStartDelayMs = Number(process.env.WINMATRIX_AGENT_ENGINE_TEST_START_DELAY_MS) || 0;
+  if (testStartDelayMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, testStartDelayMs));
+  }
   saveRunMetadata(runKey, metadata);
   activeRuns.set(runKey, { child, metadata });
   saveActiveRuns();
@@ -585,6 +661,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 +688,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 +721,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();
   }));
@@ -714,7 +828,7 @@ function buildRunAck(payload, disposition) {
   };
 }
 
-async function launch(payload) {
+async function launch(payload, retryCount = 0) {
   const { runKey, invocationFingerprint, launchSpec, instanceId } = payload;
   if (!runKey || !invocationFingerprint || !launchSpec || !instanceId) {
     throw new Error('Missing required fields: runKey, invocationFingerprint, launchSpec, instanceId');
@@ -733,8 +847,32 @@ async function launch(payload) {
   }
 
   const claimFile = path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.launch`);
+  const readClaim = () => {
+    let raw;
+    try {
+      raw = fs.readFileSync(claimFile, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return { fingerprint: parsed.fingerprint, ownerPid: parsed.ownerPid };
+    } catch {
+      return { fingerprint: raw.trim(), ownerPid: undefined };
+    }
+  };
+  const isPidAlive = (pid) => {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
   const waitForClaimedRun = async () => {
-    const deadline = Date.now() + 2_000;
+    const deadline = Date.now() + LAUNCH_ACK_TIMEOUT_MS;
     while (Date.now() < deadline) {
       const metadata = loadRunMetadata(runKey);
       if (metadata) {
@@ -744,24 +882,44 @@ async function launch(payload) {
         return metadata;
       }
       if (!fs.existsSync(claimFile)) break;
+      const claim = readClaim();
+      if (!claim) continue;
+      const ownerPid = claim.ownerPid;
+      if (ownerPid && !isPidAlive(ownerPid)) {
+        fs.rmSync(claimFile, { force: true });
+        break;
+      }
       await new Promise((resolve) => setTimeout(resolve, 20));
     }
-    throw new Error(`Claimed run did not start: ${runKey}`);
+    throw new Error(`Launch ack timeout: runKey=${runKey} code=launch_ack_timeout`);
   };
-  let claim;
   try {
-    claim = fs.openSync(claimFile, 'wx', 0o600);
-    fs.writeFileSync(claim, invocationFingerprint, 'utf8');
+    atomicCreateExclusive(claimFile, JSON.stringify({
+      fingerprint: invocationFingerprint,
+      ownerPid: process.pid,
+      createdAt: new Date().toISOString(),
+    }));
   } catch (error) {
     if (error?.code !== 'EEXIST') throw error;
-    const claimedFingerprint = fs.readFileSync(claimFile, 'utf8');
+    const claimed = readClaim();
+    if (!claimed) {
+      if (retryCount < 1) return launch(payload, retryCount + 1);
+      throw new Error(`Launch claim disappeared: runKey=${runKey}`);
+    }
+    const claimedFingerprint = claimed.fingerprint;
     if (claimedFingerprint !== invocationFingerprint) {
       throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
     }
-    await waitForClaimedRun();
-    return buildRunAck(payload, 'existing');
-  } finally {
-    if (claim !== undefined) fs.closeSync(claim);
+    try {
+      await waitForClaimedRun();
+      return buildRunAck(payload, 'existing');
+    } catch (waitError) {
+      if (String(waitError?.message ?? '').includes('launch_ack_timeout') && !fs.existsSync(claimFile)) {
+        if (retryCount < 1) return launch(payload, retryCount + 1);
+        throw waitError;
+      }
+      throw waitError;
+    }
   }
 
   if (process.env.WINMATRIX_AGENT_ENGINE_TEST_INLINE === 'true') {
@@ -776,20 +934,41 @@ async function launch(payload) {
 
   const worker = spawn(process.execPath, [SCRIPT_PATH, 'supervise-run'], {
     detached: true,
-    stdio: ['pipe', 'ignore', 'ignore'],
+    stdio: ['pipe', 'ignore', fs.openSync(path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.worker.log`), 'a')],
     env: process.env,
   });
+  atomicWriteFile(claimFile, JSON.stringify({
+    fingerprint: invocationFingerprint,
+    ownerPid: worker.pid,
+    createdAt: new Date().toISOString(),
+  }));
+  let workerExited = false;
+  let workerExitCode;
+  let workerSignal;
+  let workerError;
+  worker.once('error', (error) => {
+    workerError = error;
+  });
+  worker.once('exit', (code, signal) => {
+    workerExited = true;
+    workerExitCode = code;
+    workerSignal = signal;
+  });
   worker.stdin.end(JSON.stringify(payload));
   worker.unref();
-  const deadline = Date.now() + 2_000;
-  while (!loadRunMetadata(runKey) && Date.now() < deadline) {
+  const deadline = Date.now() + LAUNCH_ACK_TIMEOUT_MS;
+  while (!loadRunMetadata(runKey) && !workerExited && !workerError && Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, 20));
   }
-  if (!loadRunMetadata(runKey)) {
+  if (loadRunMetadata(runKey)) {
+    return buildRunAck(payload, 'accepted');
+  }
+  if (workerError || workerExited) {
     fs.rmSync(claimFile, { force: true });
-    throw new Error(`Run worker failed to start: ${runKey}`);
+    const detail = workerError?.message ?? `exitCode=${workerExitCode ?? 'null'} signal=${workerSignal ?? 'none'}`;
+    throw new Error(`Run worker failed to start: runKey=${runKey} code=worker_start_failed ${detail}; log=${path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.worker.log`)}`);
   }
-  return buildRunAck(payload, 'accepted');
+  throw new Error(`Launch ack timeout: runKey=${runKey} code=launch_ack_timeout workerPid=${worker.pid ?? 'unknown'}`);
 }
 
 function listEvents(runKey, afterSequence = 0) {
@@ -797,7 +976,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 +1027,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 +1071,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 +1398,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 +1445,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 +1527,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 +1575,7 @@ async function sessionGet() {
     if (!ok && messages.length > 0) metadata.rawMessagesSerializationFailed = true;
   }
 
-  return { ...detail, metadata };
+  return compactSessionDetailForTransport({ ...detail, metadata });
 }
 
 /**
@@ -1349,7 +1591,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' };