@winmatrix/supervisor 1.0.5

package/src/run-agent-engine.mjs

@@ -0,0 +1,1580 @@
+#!/usr/bin/env node
+/**
+ * Agent Engine Supervisor CLI（task 5.1）
+ *
+ * 工作站容器内常驻 Agent Engine Supervisor，通过 Unix socket 提供统一接口。
+ * 实现幂等启动、子进程监管、状态/结果文件、callback、cancel marker。
+ *
+ * 用法：
+ *   node run-agent-engine.mjs launch <json-payload>           # 启动 Agent Engine
+ *   node run-agent-engine.mjs status <runKey>                 # 查询运行状态
+ *   node run-agent-engine.mjs cancel <runKey>                 # 取消运行
+ *   node run-agent-engine.mjs list-active                     # 列出活跃运行
+ *   node run-agent-engine.mjs health                          # 健康检查
+ *
+ * 设计约束（design D14）：
+ * - 幂等启动：相同 runKey+fingerprint 返回 existing，不同 fingerprint 拒绝
+ * - 状态文件：<runDir>/<runKey>/status.json（running/completed/failed）
+ * - 结果文件：<runDir>/<runKey>/result.json
+ * - callback：完成后通过 HTTP POST 通知 Server
+ * - cancel marker：<runDir>/<runKey>/cancel.marker
+ */
+
+import { createRequire } from 'module';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+// Claude Session 查询公共纯函数（task 7.15）
+import {
+  loadSdk,
+  getOptValue,
+  hasFlag,
+  clampInt,
+  parseLimit,
+  encodeOffsetCursor,
+  decodeOffsetCursor,
+  toIsoString,
+  lastActivityMs,
+  buildSessionMeta,
+  extractText,
+  cloneMessagesForJson,
+  buildCliReplayGuide,
+  buildDiagnostics,
+  maybeTruncate,
+  resolveDirViaGlobalListSessions,
+} from './claude-session-lib.mjs';
+
+// D11.2-D11.4: Engine Driver 增强模块
+import { getEngineDriverConfig } from './engine-driver-config.mjs';
+import { sanitizeEnv, getFilteredEnvKeys } from './env-sanitizer.mjs';
+import { filterBlockedArgs, formatBlockedArgsAudit } from './blocked-args-filter.mjs';
+import { createDeliverableState, updateDeliverable, extractDeliverable, computeDeliverableFromEvents } from './deliverable-tracker.mjs';
+import { extractTokenUsage } from './token-usage.mjs';
+import { isResumeRejected, buildContinuityNotice, buildResumeDegradedEvent, isResumeFailureOnExit } from './resume-degradation.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 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';
+const CALLBACK_TIMEOUT_MS = Number(process.env.WINMATRIX_CALLBACK_TIMEOUT_MS) || 5000;
+const MAX_ACTIVE_RUNS = Number(process.env.WINMATRIX_MAX_ACTIVE_RUNS) || 100;
+
+// 确保根目录存在
+if (!fs.existsSync(SUPERVISOR_ROOT)) {
+  fs.mkdirSync(SUPERVISOR_ROOT, { recursive: true });
+}
+
+// 运行状态注册表（内存中，重启后从文件系统恢复）
+const activeRuns = new Map();
+
+/**
+ * 持久化活跃运行列表到 active-runs.json
+ */
+function saveActiveRuns() {
+  const activeRunsFile = path.join(SUPERVISOR_ROOT, 'active-runs.json');
+  const data = Array.from(activeRuns.entries()).map(([runKey, { metadata }]) => ({
+    runKey,
+    metadata,
+  }));
+  fs.writeFileSync(activeRunsFile, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * 从 active-runs.json 恢复活跃运行列表
+ */
+function loadActiveRuns() {
+  const activeRunsFile = path.join(SUPERVISOR_ROOT, 'active-runs.json');
+  if (!fs.existsSync(activeRunsFile)) {
+    return;
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(activeRunsFile, 'utf8'));
+    for (const { runKey, metadata } of data) {
+      // 只恢复 running 状态的 run
+      if (metadata.status === 'running') {
+        activeRuns.set(runKey, { child: null, metadata });
+      }
+    }
+  } catch (error) {
+    console.error('[run-agent-engine] Failed to load active-runs.json:', error.message);
+  }
+}
+
+// 启动时恢复活跃运行列表
+loadActiveRuns();
+
+/**
+ * Run 元数据（持久化到 status.json）
+ * @typedef {Object} RunMetadata
+ * @property {string} runKey - 运行唯一标识（instanceId:attemptNo）
+ * @property {string} invocationFingerprint - 调用指纹（SHA-256）
+ * @property {string} engineId - Engine ID（claude-code/codex/hermes）
+ * @property {string} status - 运行状态（running/completed/failed/cancelled）
+ * @property {number} pid - 子进程 PID
+ * @property {string} startTime - 启动时间（ISO 8601）
+ * @property {string} [endTime] - 结束时间（ISO 8601）
+ * @property {number} [exitCode] - 退出码
+ * @property {string} [error] - 错误信息
+ */
+
+/**
+ * 递归排序对象的所有 key（与 Server 端 canonicalJson 一致）
+ * @param {any} obj - 要排序的对象
+ * @returns {any} 排序后的对象
+ */
+function canonicalize(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(canonicalize);
+  }
+  const out = {};
+  for (const key of Object.keys(obj).sort()) {
+    out[key] = canonicalize(obj[key]);
+  }
+  return out;
+}
+
+/**
+ * 计算 invocation fingerprint（SHA-256）
+ * 使用递归 key 排序，与 Server 端 canonicalJsonStringify 一致
+ * @param {object} launchSpec - Launch spec
+ * @returns {string} SHA-256 hash
+ */
+function computeFingerprint(launchSpec) {
+  const canonical = canonicalize(launchSpec);
+  const json = JSON.stringify(canonical);
+  return createHash('sha256').update(json).digest('hex');
+}
+
+/**
+ * 获取 run 目录路径
+ * @param {string} runKey - Run key
+ * @returns {string} Run directory path
+ */
+function getRunDir(runKey) {
+  assertSafeRunKey(runKey);
+  // 保留现有目录命名兼容，同时拒绝任何路径分隔符和遍历片段。
+  const safeKey = runKey.replace(/:/g, '_');
+  return path.join(SUPERVISOR_ROOT, safeKey);
+}
+
+function assertSafeRunKey(runKey) {
+  if (typeof runKey !== 'string' || !/^[A-Za-z0-9._-]+:[1-9][0-9]*$/.test(runKey)) {
+    throw new Error('Invalid runKey: expected safe <recordId>:<positive-attemptNo>');
+  }
+}
+
+function assertSafeSessionId(sessionId) {
+  if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]{1,256}$/.test(sessionId)) {
+    throw new Error('Invalid sessionId');
+  }
+}
+
+/**
+ * 保存 run 元数据到 status.json
+ * @param {string} runKey - Run key
+ * @param {RunMetadata} metadata - Run metadata
+ */
+function saveRunMetadata(runKey, metadata) {
+  const runDir = getRunDir(runKey);
+  if (!fs.existsSync(runDir)) {
+    fs.mkdirSync(runDir, { recursive: true });
+  }
+  const statusFile = path.join(runDir, 'status.json');
+  fs.writeFileSync(statusFile, JSON.stringify(metadata, null, 2), 'utf8');
+}
+
+/**
+ * 加载 run 元数据
+ * @param {string} runKey - Run key
+ * @returns {RunMetadata|null} Run metadata or null
+ */
+function loadRunMetadata(runKey) {
+  const runDir = getRunDir(runKey);
+  const statusFile = path.join(runDir, 'status.json');
+  if (!fs.existsSync(statusFile)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+  } catch (error) {
+    console.error(`[run-agent-engine] Failed to load status.json for ${runKey}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * 保存结果到 result.json
+ * @param {string} runKey - Run key
+ * @param {object} result - Result data
+ */
+function saveResult(runKey, result) {
+  const runDir = getRunDir(runKey);
+  if (!fs.existsSync(runDir)) {
+    fs.mkdirSync(runDir, { recursive: true });
+  }
+  const resultFile = path.join(runDir, 'result.json');
+  fs.writeFileSync(resultFile, JSON.stringify(result, null, 2), 'utf8');
+}
+
+/**
+ * 加载结果
+ * @param {string} runKey - Run key
+ * @returns {object|null} Result data or null
+ */
+function loadResult(runKey) {
+  const runDir = getRunDir(runKey);
+  const resultFile = path.join(runDir, 'result.json');
+  if (!fs.existsSync(resultFile)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+  } catch (error) {
+    console.error(`[run-agent-engine] Failed to load result.json for ${runKey}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * 创建 cancel marker
+ * @param {string} runKey - Run key
+ */
+function createCancelMarker(runKey) {
+  const runDir = getRunDir(runKey);
+  if (!fs.existsSync(runDir)) {
+    fs.mkdirSync(runDir, { recursive: true });
+  }
+  const cancelFile = path.join(runDir, 'cancel.marker');
+  fs.writeFileSync(cancelFile, new Date().toISOString(), 'utf8');
+}
+
+/**
+ * 检查 cancel marker 是否存在
+ * @param {string} runKey - Run key
+ * @returns {boolean} True if cancel marker exists
+ */
+function hasCancelMarker(runKey) {
+  const runDir = getRunDir(runKey);
+  const cancelFile = path.join(runDir, 'cancel.marker');
+  return fs.existsSync(cancelFile);
+}
+
+/**
+ * 构建 workstation 任务终态 callback payload（merge-workstation-tools R11 / 9b.5）。
+ *
+ * 对齐 V1 run-claude-agent.mjs 的字段语义，满足 Server 端
+ * /api/v1/workstation-task-callbacks 的 zod schema（recordId 必填、attemptNo 正整数）。
+ * runKey 形如 <recordId>:<attemptNo>，据此回解 record 身份。
+ *
+ * @param {string} runKey - Run key（<recordId>:<attemptNo>）
+ * @param {RunMetadata} endMetadata - 终态元数据（status/endTime/exitCode/...）
+ * @param {object} result - 终态结果（success/text/sessionId/error/usage）
+ * @param {RunMetadata} startMetadata - 启动元数据（startTime）
+ * @returns {object} Callback payload
+ */
+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;
+  const attemptNo = Number.isInteger(parsedAttempt) && parsedAttempt > 0 ? parsedAttempt : 1;
+  const runDir = getRunDir(runKey);
+
+  const startMs = Date.parse(startMetadata?.startTime ?? '');
+  const endMs = Date.parse(endMetadata?.endTime ?? '');
+  const durationSeconds = Number.isFinite(startMs) && Number.isFinite(endMs) && endMs >= startMs
+    ? Math.round((endMs - startMs) / 1000)
+    : undefined;
+
+  const text = typeof result?.text === 'string' ? result.text : undefined;
+  return {
+    recordId,
+    attemptNo,
+    runKey,
+    status: endMetadata.status,
+    summary: text ? text.slice(0, 800) : undefined,
+    result: text,
+    error: typeof result?.error === 'string' ? result.error : undefined,
+    durationSeconds,
+    claudeSessionId: typeof result?.sessionId === 'string' ? result.sessionId : undefined,
+    statusFilePath: path.join(runDir, 'status.json'),
+    resultFilePath: path.join(runDir, 'result.json'),
+    completedAt: endMetadata.endTime,
+    metadata: {
+      exitCode: endMetadata.exitCode,
+      ...(endMetadata.signal ? { signal: endMetadata.signal } : {}),
+      ...(endMetadata.resumeDegraded ? { resumeDegraded: true } : {}),
+      ...(result?.usage ? { usage: result.usage } : {}),
+    },
+  };
+}
+
+/**
+ * 发送 callback 到 Server
+ * @param {string} callbackUrl - Callback URL
+ * @param {string} token - Callback token
+ * @param {object} payload - Callback payload
+ * @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 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}`));
+      }
+    });
+
+    req.on('error', (error) => {
+      console.error(`[run-agent-engine] Callback error:`, error.message);
+      reject(error);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Callback timeout'));
+    });
+
+    req.write(data);
+    req.end();
+  });
+}
+
+/**
+ * 启动 Agent Engine
+ * @param {object} payload - Launch payload
+ * @returns {Promise<object>} Launch result
+ */
+async function runOwned(payload) {
+  const { runKey, invocationFingerprint, launchSpec, privateBindings } = payload;
+
+  if (!runKey || !invocationFingerprint || !launchSpec) {
+    throw new Error('Missing required fields: runKey, invocationFingerprint, launchSpec');
+  }
+
+  // 幂等性检查：相同 runKey 是否已存在
+  const existingMetadata = loadRunMetadata(runKey);
+  if (existingMetadata) {
+    // 验证 fingerprint 是否匹配
+    if (existingMetadata.invocationFingerprint === invocationFingerprint) {
+      console.log(`[run-agent-engine] Run already exists: ${runKey}`);
+      return {
+        disposition: 'existing',
+        ref: {
+          runKey,
+          invocationFingerprint,
+          engineId: launchSpec.engineId,
+          instance: { instanceId: payload.instanceId, hostKind: 'workstation' },
+          executionSnapshot: {
+            hostProfile: 'coding',
+            digitalEmployeeId: payload.instanceId,
+          },
+        },
+        executionDurability: 'host_persistent',
+        eventStreamMode: 'replay',
+      };
+    } else {
+      throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
+    }
+  }
+
+  // 验证 fingerprint
+  const computedFingerprint = computeFingerprint(launchSpec);
+  if (computedFingerprint !== invocationFingerprint) {
+    throw new Error(`Invalid invocation fingerprint: expected=${computedFingerprint}, got=${invocationFingerprint}`);
+  }
+
+  // 检查并发限制
+  if (activeRuns.size >= MAX_ACTIVE_RUNS) {
+    throw new Error(`Max active runs limit reached: ${MAX_ACTIVE_RUNS}`);
+  }
+
+  // 构建 argv（D11.3: 自动过滤 blocked args）
+  const argv = buildEngineArgv(launchSpec);
+
+  // D11.3: 使用 sanitized 环境变量，过滤 Supervisor 内部标记
+  const filteredEnvKeys = getFilteredEnvKeys();
+  if (filteredEnvKeys.length > 0) {
+    console.log(`[run-agent-engine] Filtering ${filteredEnvKeys.length} env vars from child process: ${filteredEnvKeys.join(', ')}`);
+  }
+  const env = sanitizeEnv({
+    // Gateway/Supervisor owns durable completion and callback delivery. The
+    // legacy Claude runner must not mutate project-local hook settings here.
+    WIN_AGENT_ENGINE_GATEWAY_RUN: 'true',
+    ...launchSpec.nonSensitiveEnv,
+  });
+
+  // 准备 stdin（包含 sensitive bindings）
+  const stdinData = privateBindings ? JSON.stringify(privateBindings) : '';
+
+  // 启动子进程
+  const runDir = getRunDir(runKey);
+  if (!fs.existsSync(runDir)) {
+    fs.mkdirSync(runDir, { recursive: true });
+  }
+
+  const logFile = path.join(runDir, 'stdout.log');
+  const errFile = path.join(runDir, 'stderr.log');
+  // 先清空旧 stdout 日志
+  try { fs.writeFileSync(logFile, '', 'utf8'); } catch { /* ignore */ }
+
+  const child = spawn(argv[0], argv.slice(1), {
+    env,
+    cwd: launchSpec.workDir || process.cwd(),
+    stdio: ['pipe', 'pipe', fs.openSync(errFile, 'a')],
+    // D11.2: detached=true 用于创建独立进程组，两阶段关闭时可 SIGTERM 整组
+    detached: process.platform !== 'win32',
+  });
+
+  // 写入 stdin
+  if (stdinData) {
+    child.stdin.write(stdinData);
+    child.stdin.end();
+  }
+
+  // 读取 stdout JSONL 事件，同时写入 stdout.log
+  const stdoutWriteStream = fs.createWriteStream(logFile, { flags: 'a' });
+  const rl = readline.createInterface({ input: child.stdout });
+  rl.on('line', (line) => {
+    stdoutWriteStream.write(`${line}\n`);
+    if (!line.trim()) return;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      // 非 JSON 行视为 stderr 风格诊断输出，不进入事件流
+      return;
+    }
+    appendEvent(runKey, metadata, event);
+    deliverableState = updateDeliverable(deliverableState, event);
+  });
+  child.stdout.on('close', () => {
+    stdoutWriteStream.end();
+  });
+
+  // 保存元数据
+  const metadata = {
+    runKey,
+    invocationFingerprint,
+    engineId: launchSpec.engineId,
+    status: 'running',
+    pid: child.pid,
+    startTime: new Date().toISOString(),
+    instanceId: payload.instanceId,
+    lastSequence: 0,
+  };
+  saveRunMetadata(runKey, metadata);
+  activeRuns.set(runKey, { child, metadata });
+  saveActiveRuns();
+
+  console.log(`[run-agent-engine] Launched run: ${runKey} (pid=${child.pid})`);
+
+  appendEvent(runKey, metadata, { type: 'status', text: 'running' });
+
+  // D11.2: 获取 Engine driver 配置（gracefulShutdownTimeoutMs 等）
+  const driverConfig = getEngineDriverConfig(launchSpec.engineId);
+
+  // D11.4: 初始化 deliverable tracker
+  let deliverableState = createDeliverableState();
+
+  // D11.5: 跟踪 stderr 用于 resume 降级检测
+  let stderrAccumulator = '';
+
+  // D11.2: 两阶段优雅关闭函数
+  function gracefulShutdown(killSignal) {
+    if (child.killed || child.exitCode !== null) return;
+
+    console.log(`[run-agent-engine] D11.2: Phase 1 graceful shutdown for ${runKey} (stdin.close)`);
+
+    // Phase 1: stdin.Close() → 让 Engine 自行写状态文件并退出
+    try {
+      child.stdin.end();
+    } catch {
+      // stdin 可能已经关闭
+    }
+
+    // Phase 1 超时后进入 Phase 2
+    const phase1Timer = setTimeout(() => {
+      if (child.exitCode !== null) return; // Engine 已退出
+
+      console.log(`[run-agent-engine] D11.2: Phase 1 timeout (${driverConfig.gracefulShutdownTimeoutMs}ms), entering Phase 2 (SIGTERM)`);
+
+      // Phase 2: SIGTERM 进程组
+      try {
+        if (process.platform !== 'win32' && child.pid) {
+          // Unix: 发送到进程组
+          try { process.kill(-child.pid, 'SIGTERM'); } catch { /* 进程组可能不存在 */ }
+        } else {
+          child.kill('SIGTERM');
+        }
+      } catch {
+        // 进程可能已退出
+      }
+
+      // Phase 2 超时后进入 Phase 3
+      const phase2Timer = setTimeout(() => {
+        if (child.exitCode !== null) return;
+
+        console.log(`[run-agent-engine] D11.2: Phase 2 timeout (${driverConfig.phase2TimeoutMs}ms), entering Phase 3 (SIGKILL)`);
+
+        // Phase 3: SIGKILL 进程组
+        try {
+          if (process.platform !== 'win32' && child.pid) {
+            try { process.kill(-child.pid, 'SIGKILL'); } catch { /* 进程组可能不存在 */ }
+          } else {
+            child.kill('SIGKILL');
+          }
+        } catch {
+          // 进程可能已退出
+        }
+      }, driverConfig.phase2TimeoutMs);
+
+      // 确保 phase2Timer 不阻止进程退出
+      if (phase2Timer.unref) phase2Timer.unref();
+    }, driverConfig.gracefulShutdownTimeoutMs);
+
+    // 确保 phase1Timer 不阻止进程退出
+    if (phase1Timer.unref) phase1Timer.unref();
+  }
+
+  // D11.2: cancel marker 轮询使用两阶段关闭
+  const cancelPoll = setInterval(() => {
+    if (hasCancelMarker(runKey) && !child.killed && child.exitCode === null) {
+      gracefulShutdown('SIGTERM');
+    }
+  }, 500);
+
+  const completion = new Promise((resolve) => child.on('exit', async (code, signal) => {
+    clearInterval(cancelPoll);
+    console.log(`[run-agent-engine] Run exited: ${runKey} (code=${code}, signal=${signal})`);
+
+    const cancelled = hasCancelMarker(runKey);
+
+    // D11.2: Resume 降级检测
+    // 检查是否是 resume session 且 Engine 输出包含拒绝模式
+    const isResume = launchSpec.session?.mode === 'resume';
+    const resumeFailed = isResume && (
+      isResumeFailureOnExit(launchSpec.engineId, code, stderrAccumulator)
+    );
+
+    // D11.4: 从事件文件计算 deliverable 和 token usage
+    let resultText = '';
+    let usage = null;
+    let resultSessionId = null;
+    try {
+      const eventsFile = path.join(getRunDir(runKey), 'events.jsonl');
+      if (fs.existsSync(eventsFile)) {
+        const eventLines = fs.readFileSync(eventsFile, 'utf8').split('\n').filter(Boolean);
+        const events = eventLines.map(line => {
+          try { return JSON.parse(line); } catch { return null; }
+        }).filter(Boolean);
+
+        // D11.4: Deliverable 提取
+        resultText = computeDeliverableFromEvents(events);
+
+        // D11.4: Token Usage 多路获取
+        usage = extractTokenUsage(events, {
+          engineId: launchSpec.engineId,
+          sessionId: launchSpec.session?.session?.sessionId,
+        });
+
+        // 提取 fresh run 产生的新 sessionId（最后一个 result 事件携带；
+        // 行可能是 envelope（{event}）或裸事件，与 token-usage 解析保持一致）
+        for (let i = events.length - 1; i >= 0; i -= 1) {
+          const evt = events[i]?.event ?? events[i];
+          if (evt?.type === 'result' && typeof evt?.result?.sessionId === 'string') {
+            resultSessionId = evt.result.sessionId;
+            break;
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[run-agent-engine] Failed to compute deliverable/usage for ${runKey}:`, err.message);
+    }
+
+    const endMetadata = {
+      ...metadata,
+      status: cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed',
+      endTime: new Date().toISOString(),
+      exitCode: code,
+      ...(signal ? { signal } : {}),
+      ...(resumeFailed ? { resumeDegraded: true } : {}),
+    };
+    saveRunMetadata(runKey, endMetadata);
+    activeRuns.delete(runKey);
+    saveActiveRuns();
+
+    // D11.4: 构建包含 deliverable 和 usage 的结果
+    const result = {
+      success: !cancelled && code === 0,
+      text: resultText || undefined,
+      ...(resultSessionId ? { sessionId: resultSessionId } : {}),
+      ...(usage ? { usage } : {}),
+      ...(cancelled ? { error: 'cancelled' } : code === 0 ? {} : { error: `Engine exited with code ${code}` }),
+      metadata: {
+        exitCode: code,
+        ...(signal ? { signal } : {}),
+        ...(resumeFailed ? { resumeDegraded: true } : {}),
+        ...(usage?.source ? { usageSource: usage.source } : {}),
+      },
+    };
+    saveResult(runKey, result);
+    appendEvent(runKey, endMetadata, { type: 'result', result });
+
+    // 发送 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) {
+      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);
+      });
+    }
+    resolve();
+  }));
+
+  return { ack: {
+    disposition: 'accepted',
+    ref: {
+      runKey,
+      invocationFingerprint,
+      engineId: launchSpec.engineId,
+      instance: { instanceId: payload.instanceId, hostKind: 'workstation' },
+      executionSnapshot: {
+        hostProfile: 'coding',
+        digitalEmployeeId: payload.instanceId,
+      },
+    },
+    executionDurability: 'host_persistent',
+    eventStreamMode: 'replay',
+    eventRetention: { maxEvents: 10000 },
+    runtimeVersion: 'run-agent-engine/1',
+    protocolVersion: '1',
+  }, completion };
+}
+
+function appendEvent(runKey, metadata, event) {
+  const sequence = Number(metadata.lastSequence ?? 0) + 1;
+  metadata.lastSequence = sequence;
+  saveRunMetadata(runKey, metadata);
+  const envelope = {
+    runKey,
+    engineId: metadata.engineId,
+    invocationFingerprint: metadata.invocationFingerprint,
+    sequence,
+    timestamp: new Date().toISOString(),
+    event,
+  };
+  fs.appendFileSync(path.join(getRunDir(runKey), 'events.jsonl'), `${JSON.stringify(envelope)}\n`, 'utf8');
+}
+
+function buildRunAck(payload, disposition) {
+  return {
+    disposition,
+    ref: {
+      runKey: payload.runKey,
+      invocationFingerprint: payload.invocationFingerprint,
+      engineId: payload.launchSpec.engineId,
+      instance: { instanceId: payload.instanceId, hostKind: 'workstation' },
+      executionSnapshot: {},
+    },
+    executionDurability: 'host_persistent',
+    eventStreamMode: 'replay',
+    eventRetention: { maxEvents: 10000 },
+    runtimeVersion: 'run-agent-engine/1',
+    protocolVersion: '1',
+  };
+}
+
+async function launch(payload) {
+  const { runKey, invocationFingerprint, launchSpec, instanceId } = payload;
+  if (!runKey || !invocationFingerprint || !launchSpec || !instanceId) {
+    throw new Error('Missing required fields: runKey, invocationFingerprint, launchSpec, instanceId');
+  }
+  assertSafeRunKey(runKey);
+  if (computeFingerprint(launchSpec) !== invocationFingerprint) {
+    throw new Error('Invalid invocation fingerprint');
+  }
+
+  const existing = loadRunMetadata(runKey);
+  if (existing) {
+    if (existing.invocationFingerprint !== invocationFingerprint) {
+      throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
+    }
+    return buildRunAck(payload, 'existing');
+  }
+
+  const claimFile = path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.launch`);
+  const waitForClaimedRun = async () => {
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+      const metadata = loadRunMetadata(runKey);
+      if (metadata) {
+        if (metadata.invocationFingerprint !== invocationFingerprint) {
+          throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
+        }
+        return metadata;
+      }
+      if (!fs.existsSync(claimFile)) break;
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    throw new Error(`Claimed run did not start: ${runKey}`);
+  };
+  let claim;
+  try {
+    claim = fs.openSync(claimFile, 'wx', 0o600);
+    fs.writeFileSync(claim, invocationFingerprint, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    const claimedFingerprint = fs.readFileSync(claimFile, 'utf8');
+    if (claimedFingerprint !== invocationFingerprint) {
+      throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
+    }
+    await waitForClaimedRun();
+    return buildRunAck(payload, 'existing');
+  } finally {
+    if (claim !== undefined) fs.closeSync(claim);
+  }
+
+  if (process.env.WINMATRIX_AGENT_ENGINE_TEST_INLINE === 'true') {
+    try {
+      const owned = await runOwned(payload);
+      return owned.ack;
+    } catch (error) {
+      fs.rmSync(claimFile, { force: true });
+      throw error;
+    }
+  }
+
+  const worker = spawn(process.execPath, [SCRIPT_PATH, 'supervise-run'], {
+    detached: true,
+    stdio: ['pipe', 'ignore', 'ignore'],
+    env: process.env,
+  });
+  worker.stdin.end(JSON.stringify(payload));
+  worker.unref();
+  const deadline = Date.now() + 2_000;
+  while (!loadRunMetadata(runKey) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  if (!loadRunMetadata(runKey)) {
+    fs.rmSync(claimFile, { force: true });
+    throw new Error(`Run worker failed to start: ${runKey}`);
+  }
+  return buildRunAck(payload, 'accepted');
+}
+
+function listEvents(runKey, afterSequence = 0) {
+  const file = path.join(getRunDir(runKey), 'events.jsonl');
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)
+    .map((line) => JSON.parse(line))
+    .filter((event) => event.sequence > afterSequence);
+}
+
+/**
+ * 构建 Engine argv（不包含 sensitive bindings）
+ * @param {object} launchSpec - Launch spec
+ * @returns {string[]} argv
+ */
+function buildEngineArgv(launchSpec) {
+  const supportedEngines = ['claude-code', 'codex', 'hermes', 'openclaw'];
+  if (!supportedEngines.includes(launchSpec.engineId)) {
+    throw new Error(`Unsupported engineId: ${launchSpec.engineId}`);
+  }
+  if (process.env.WINMATRIX_AGENT_ENGINE_TEST_HOLD === 'true') {
+    const holdMs = Number(process.env.WINMATRIX_AGENT_ENGINE_TEST_HOLD_MS) || 30000;
+    return [process.execPath, '-e', `setTimeout(() => process.exit(0), ${holdMs})`];
+  }
+  const { engineId, model, permissionMode, allowedTools, session, input, timeoutMs, workDir } = launchSpec;
+
+  const argv = ['node', '/opt/winmatrix/run-engine.mjs', '--engine', engineId];
+
+  // 添加 model
+  if (model) {
+    argv.push('--model', model);
+  }
+
+  // 添加 permission-mode
+  if (permissionMode) {
+    argv.push('--permission-mode', permissionMode);
+  }
+
+  // 添加 allowed-tools
+  if (allowedTools && allowedTools.length > 0) {
+    argv.push('--allowed-tools', allowedTools.join(','));
+  }
+
+  // 添加 work-dir
+  if (workDir) {
+    argv.push('--work-dir', workDir);
+  }
+
+  // 添加 session
+  if (session) {
+    if (session.mode === 'resume' && session.session?.sessionId) {
+      argv.push('--resume', session.session.sessionId);
+    } else if (session.mode === 'fork' && session.session?.sessionId) {
+      argv.push('--fork', session.session.sessionId);
+    }
+  }
+
+  // 添加 input（第一个 text block）
+  if (input?.blocks) {
+    for (const block of input.blocks) {
+      if (block.kind === 'text' && block.text) {
+        argv.push(block.text);
+        break;
+      }
+    }
+  }
+
+  // 添加 timeout
+  if (timeoutMs) {
+    const timeoutSec = Math.floor(timeoutMs / 1000);
+    argv.push('--timeout', String(timeoutSec));
+  }
+
+  // D11.3: 添加用户 customArgs（过滤 blocked args 后）
+  if (launchSpec.engineOptions?.customArgs && Array.isArray(launchSpec.engineOptions.customArgs)) {
+    const { filtered, removed } = filterBlockedArgs(engineId, launchSpec.engineOptions.customArgs);
+    if (removed.length > 0) {
+      const audit = formatBlockedArgsAudit(removed, engineId);
+      console.log(`[run-agent-engine] ${audit}`);
+      // 记录到审计日志（通过 appendEvent，需要 runKey）
+      // 这里只做 console.log，实际审计在 runOwned 中通过 metadata 记录
+    }
+    argv.push(...filtered);
+  }
+
+  return argv;
+}
+
+/**
+ * 查询运行状态
+ * @param {string} runKey - Run key
+ * @returns {object} Run status
+ */
+function status(runKey) {
+  const metadata = loadRunMetadata(runKey);
+  if (!metadata) {
+    throw new Error(`Run not found: ${runKey}`);
+  }
+
+  const result = loadResult(runKey);
+  const cancelled = hasCancelMarker(runKey);
+
+  return {
+    ref: {
+      instance: { instanceId: metadata.instanceId, hostKind: 'workstation' },
+      executionSnapshot: {},
+      runKey: metadata.runKey,
+      engineId: metadata.engineId,
+      invocationFingerprint: metadata.invocationFingerprint,
+    },
+    status: cancelled ? 'cancelled' : metadata.status,
+    executionDurability: 'host_persistent',
+    eventStreamMode: 'replay',
+    eventRetention: { maxEvents: 10000 },
+    lastSequence: Number(metadata.lastSequence ?? 0),
+    pendingInteractions: [],
+    ...(result ? { result } : {}),
+    recoverable: true,
+    runtimeVersion: 'run-agent-engine/1',
+    protocolVersion: '1',
+  };
+}
+
+/**
+ * 取消运行
+ * @param {string} runKey - Run key
+ * @returns {object} Cancel result
+ */
+function cancel(runKey) {
+  const metadata = loadRunMetadata(runKey);
+  if (!metadata) {
+    throw new Error(`Run not found: ${runKey}`);
+  }
+
+  if (metadata.status !== 'running') {
+    return { success: false, message: 'Run is not running' };
+  }
+
+  // 创建 cancel marker
+  createCancelMarker(runKey);
+
+  // D11.2: 两阶段优雅关闭（与 cancel poll 使用相同逻辑）
+  const activeRun = activeRuns.get(runKey);
+  if (activeRun && activeRun.child && activeRun.child.exitCode === null) {
+    const driverConfig = getEngineDriverConfig(activeRun.metadata.engineId);
+
+    // Phase 1: stdin.Close() → 让 Engine 自行写状态文件并退出
+    console.log(`[run-agent-engine] D11.2: Cancel Phase 1 for ${runKey} (stdin.close)`);
+    try { activeRun.child.stdin.end(); } catch { /* 可能已关闭 */ }
+
+    // Phase 1 超时后 Phase 2
+    setTimeout(() => {
+      if (!activeRuns.has(runKey)) return;
+      const child = activeRun.child;
+      if (!child || child.exitCode !== null) return;
+
+      console.log(`[run-agent-engine] D11.2: Cancel Phase 2 for ${runKey} (SIGTERM)`);
+      try {
+        if (process.platform !== 'win32' && child.pid) {
+          try { process.kill(-child.pid, 'SIGTERM'); } catch { /* 进程组可能不存在 */ }
+        } else {
+          child.kill('SIGTERM');
+        }
+      } catch { /* 进程可能已退出 */ }
+
+      // Phase 2 超时后 Phase 3
+      setTimeout(() => {
+        if (!activeRuns.has(runKey)) return;
+        if (!child || child.exitCode !== null) return;
+
+        console.log(`[run-agent-engine] D11.2: Cancel Phase 3 for ${runKey} (SIGKILL)`);
+        try {
+          if (process.platform !== 'win32' && child.pid) {
+            try { process.kill(-child.pid, 'SIGKILL'); } catch { /* 进程组可能不存在 */ }
+          } else {
+            child.kill('SIGKILL');
+          }
+        } catch { /* 进程可能已退出 */ }
+      }, driverConfig.phase2TimeoutMs);
+    }, driverConfig.gracefulShutdownTimeoutMs);
+  }
+
+  return { success: true, message: 'Cancel signal sent' };
+}
+
+/**
+ * 列出活跃运行
+ * @returns {object[]} Active runs
+ */
+function listActive() {
+  const runs = [];
+  for (const [runKey, { metadata }] of activeRuns.entries()) {
+    const current = loadRunMetadata(runKey) ?? metadata;
+    if (!['running', 'starting', 'accepted', 'waiting_interaction', 'cancel_requested'].includes(current.status)) continue;
+    runs.push({
+      ref: {
+        instance: { instanceId: current.instanceId, hostKind: 'workstation' },
+        executionSnapshot: {},
+        runKey: current.runKey,
+        engineId: current.engineId,
+        invocationFingerprint: current.invocationFingerprint,
+      },
+      status: current.status,
+      startedAt: current.startTime,
+      lastSequence: Number(current.lastSequence ?? 0),
+      pendingInteractionCount: 0,
+    });
+  }
+  return { runs };
+}
+
+/**
+ * 健康检查
+ * @returns {object} Health status
+ */
+function health() {
+  return {
+    status: 'ok',
+    activeRuns: activeRuns.size,
+    supervisorRoot: SUPERVISOR_ROOT,
+  };
+}
+
+/* ── Engine 原生 Session 查询子命令（task 7.15） ──
+ *
+ * 这 4 个子命令是无状态、只读（delete 幂等）的 argv-native 入口，
+ * 与 launch/status/cancel/list-active 的耐久性监管正交。
+ * 输出 = protocol DTO JSON（EngineSessionPage / EngineSessionDetail +
+ * metadata / EngineSessionSearchPage / EngineSessionDeleteReceipt）。
+ * Host 透传 instanceId/engineId/sessionId，CLI 仅补充 source/summary 等元数据。
+ *
+ * argv 契约（design §1734-1737）：
+ *   session-list   --engine <id> --limit <n> [--cursor <c>] [--project-id <pid>] [--normalized-work-dir <dir>]
+ *   session-get    --engine <id> --session-id <sid> --limit <n> [--cursor <c>]
+ *                   [--include-raw-messages] [--include-system] [--no-truncate] [--normalized-work-dir <dir>]
+ *   session-search --engine <id> --query <text> --limit <n> [--cursor <c>] [--project-id <pid>] [--normalized-work-dir <dir>]
+ *   session-delete --engine <id> --session-id <sid> --request-id <rid>
+ */
+
+/** instanceId / hostKind 由调用方（Sandbox API）通过环境变量注入（同一 Pod 内）。 */
+const SESSION_INSTANCE_ID = process.env.WINMATRIX_AGENT_ENGINE_INSTANCE_ID || '';
+const SESSION_HOST_KIND = 'workstation';
+
+function redactSessionText(value) {
+  let redacted = false;
+  let text = String(value ?? '');
+  const patterns = [
+    /\b(Bearer\s+)[A-Za-z0-9._~+\/-]+=*/gi,
+    /\b(sk-[A-Za-z0-9_-]{8,})\b/g,
+    /\b(password|passwd|token|secret|api[_-]?key)\s*[:=]\s*([^\s,;]+)/gi,
+  ];
+  text = text.replace(patterns[0], (_match, prefix) => { redacted = true; return `${prefix}[REDACTED]`; });
+  text = text.replace(patterns[1], () => { redacted = true; return '[REDACTED]'; });
+  text = text.replace(patterns[2], (_match, key) => { redacted = true; return `${key}=[REDACTED]`; });
+  return { text, redacted };
+}
+
+function deepRedactSessionValue(value, key = '') {
+  if (/password|passwd|token|secret|api[_-]?key/i.test(key)) return '[REDACTED]';
+  if (typeof value === 'string') return redactSessionText(value).text;
+  if (Array.isArray(value)) return value.map((item) => deepRedactSessionValue(item));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [
+      childKey, deepRedactSessionValue(child, childKey),
+    ]));
+  }
+  return value;
+}
+
+/**
+ * 把 SDK 宽松 session 记录适配为结构化 EngineSessionSummary（含 ref）。
+ * instanceId/engineId/sessionId 由 Host 决定，CLI 不覆盖。
+ * @param {object} meta buildSessionMeta 产出的元数据
+ * @param {string} engineId
+ */
+function sessionSummary(meta, engineId) {
+  const sessionId = meta.id != null ? String(meta.id) : '';
+  const title =
+    meta.customTitle != null ? meta.customTitle
+    : meta.summary != null ? meta.summary
+    : meta.firstPrompt != null ? meta.firstPrompt
+    : undefined;
+  const workDir = meta.cwd ?? meta.projectPath;
+
+  /** @type {Record<string, unknown>} */
+  const summary = {
+    ref: {
+      instance: { instanceId: SESSION_INSTANCE_ID, hostKind: SESSION_HOST_KIND },
+      engineId,
+      sessionId,
+    },
+    source: 'engine_native',
+  };
+  if (title !== undefined) summary.title = title;
+  if (meta.projectPath !== undefined) summary.projectId = undefined; // protocol projectId 为产品项目 id；此处不暴露
+  if (workDir !== undefined) summary.workDir = workDir;
+  if (meta.createdAt !== undefined) summary.createdAt = meta.createdAt;
+  if (meta.lastActivityAt !== undefined) summary.lastActivityAt = meta.lastActivityAt;
+  if (meta.messageCount !== undefined) summary.messageCount = meta.messageCount;
+  return summary;
+}
+
+/**
+ * session-list：SDK listSessions({dir?}) → EngineSessionPage。
+ * dir = --normalized-work-dir（语义=SDK 的 dir=projectPath，非 HOME）。
+ */
+async function sessionList() {
+  const argv = process.argv;
+  const engineId = getOptValue(argv, '--engine') || 'claude-code';
+  const limit = parseLimit(argv, 80, 200);
+  const cursor = getOptValue(argv, '--cursor');
+  const projectId = getOptValue(argv, '--project-id');
+  const normalizedWorkDir = getOptValue(argv, '--normalized-work-dir');
+  const offset = decodeOffsetCursor(cursor);
+
+  const { sdk, error } = loadSdk();
+  if (!sdk || typeof sdk.listSessions !== 'function') {
+    return { sessions: [], error: error ?? 'SDK 不支持 listSessions' };
+  }
+
+  /** @type {Record<string, unknown>} */
+  const opts = { limit: Math.min(400, limit * 2 + 20) };
+  if (normalizedWorkDir) opts.dir = normalizedWorkDir;
+
+  const list = await sdk.listSessions(opts);
+  const arr = Array.isArray(list) ? list : [];
+  const sorted = [...arr].sort(
+    (a, b) =>
+      lastActivityMs(/** @type {Record<string, unknown>} */ (b)) -
+      lastActivityMs(/** @type {Record<string, unknown>} */ (a)),
+  );
+  const sessions = sorted
+    .slice(offset, offset + limit)
+    .map((s) => sessionSummary(buildSessionMeta(/** @type {Record<string, unknown>} */ (s)), engineId));
+  const result = { sessions };
+  if (offset + limit < sorted.length) result.nextCursor = encodeOffsetCursor(offset + limit);
+  return result;
+}
+
+function probeEngine(engineId, instanceId = 'unknown') {
+  const command = engineId === 'claude-code' ? 'claude' : engineId;
+  if (!['claude-code', 'codex', 'hermes'].includes(engineId)) {
+    return {
+      engineId, instanceId, hostKind: 'workstation', checkedAt: new Date().toISOString(),
+      status: 'unavailable', binaryStatus: 'missing', credentialStatus: 'unknown',
+      issues: [{ code: 'unsupported_engine', message: `Unsupported engine: ${engineId}` }],
+    };
+  }
+  const result = spawnSync(command, ['--version'], { encoding: 'utf8', timeout: 5000 });
+  const found = !result.error || result.error.code !== 'ENOENT';
+  return {
+    engineId, instanceId, hostKind: 'workstation', checkedAt: new Date().toISOString(),
+    status: found ? 'ready' : 'unavailable',
+    binaryStatus: found ? 'found' : 'missing',
+    credentialStatus: 'unknown',
+    ...(found ? { version: String(result.stdout || result.stderr || '').trim() || undefined } : {}),
+    issues: found ? [] : [{ code: 'binary_missing', message: `${command} binary not found` }],
+  };
+}
+
+function listEngines() {
+  const engines = ['claude-code', 'codex', 'hermes'].map((engineId) => {
+    const readiness = probeEngine(engineId);
+    return {
+      engineId,
+      availability: readiness.status === 'ready' ? 'ready' : 'unavailable',
+      ...(readiness.version ? { version: readiness.version } : {}),
+    };
+  });
+  return { engines };
+}
+
+function listModels() {
+  // CLI 没有稳定的离线模型发现命令时返回空目录，不用静态列表伪造实例能力。
+  return { models: [] };
+}
+
+function engineOptions(engineId) {
+  return {
+    engineId,
+    modes: [],
+    configOptions: [],
+    commands: [],
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * session-get：SDK getSessionInfo + getSessionMessages → EngineSessionDetail + metadata。
+ * metadata 透传富诊断（diagnostics/cliReplayGuide/userPrompts/assistantText/...）。
+ */
+async function sessionGet() {
+  const argv = process.argv;
+  const engineId = getOptValue(argv, '--engine') || 'claude-code';
+  const sessionId = getOptValue(argv, '--session-id');
+  if (!sessionId) throw new Error('session-get: --session-id 必填');
+  assertSafeSessionId(sessionId);
+
+  const limit = clampInt(getOptValue(argv, '--limit') ?? '', 100, 1, 1000);
+  const cursor = getOptValue(argv, '--cursor');
+  const offset = decodeOffsetCursor(cursor);
+  const includeRawMessages = hasFlag(argv, '--include-raw-messages');
+  const includeSystem = hasFlag(argv, '--include-system');
+  const noTruncate = hasFlag(argv, '--no-truncate');
+  const normalizedWorkDir = getOptValue(argv, '--normalized-work-dir');
+
+  const { sdk, error } = loadSdk();
+  if (!sdk || typeof sdk.getSessionInfo !== 'function' || typeof sdk.getSessionMessages !== 'function') {
+    return {
+      session: null,
+      messages: [],
+      rawMessagesIncluded: false,
+      metadata: { error: error ?? 'SDK 不支持 getSessionInfo/getSessionMessages' },
+    };
+  }
+
+  /** @type {Record<string, unknown>} */
+  const infoOpts = {};
+  if (normalizedWorkDir) infoOpts.dir = normalizedWorkDir;
+
+  /** @type {Record<string, unknown>} */
+  const msgOpts = { limit, offset, includeSystemMessages: includeSystem };
+  if (normalizedWorkDir) msgOpts.dir = normalizedWorkDir;
+
+  const info = await sdk.getSessionInfo(sessionId, infoOpts);
+  if (!info) {
+    return {
+      session: null,
+      messages: [],
+      rawMessagesIncluded: false,
+      metadata: { error: `未找到 sessionId=${sessionId}` },
+    };
+  }
+
+  const sessionMeta = buildSessionMeta(/** @type {Record<string, unknown>} */ (info));
+
+  // 未显式传 dir 时用 session 元数据路径补齐（与旧 detail mjs 行为一致）
+  /** @type {'cli' | 'sessionMeta' | 'listSessionsGlobal' | undefined} */
+  let dirSource;
+  if (normalizedWorkDir) {
+    dirSource = 'cli';
+  } else {
+    const autoDir = sessionMeta.projectPath || sessionMeta.cwd;
+    if (autoDir) {
+      msgOpts.dir = autoDir;
+      dirSource = 'sessionMeta';
+    }
+  }
+
+  /** @type {unknown[]} */
+  let messages = [];
+  try {
+    const raw = await sdk.getSessionMessages(sessionId, msgOpts);
+    messages = Array.isArray(raw) ? raw : [];
+    // 三级 dir 回退：sessionMeta 路径取不到时，用 listSessions 全局列表里的 cwd 再试
+    if (messages.length === 0 && typeof sdk.listSessions === 'function') {
+      const fromList = await resolveDirViaGlobalListSessions(sdk, sessionId);
+      const tried = msgOpts.dir ? String(msgOpts.dir).replace(/\/+$/, '') : '';
+      if (fromList && fromList !== tried) {
+        msgOpts.dir = fromList;
+        const raw2 = await sdk.getSessionMessages(sessionId, msgOpts);
+        messages = Array.isArray(raw2) ? raw2 : [];
+        if (messages.length > 0) dirSource = 'listSessionsGlobal';
+      } else if (fromList && !tried) {
+        msgOpts.dir = fromList;
+        const raw3 = await sdk.getSessionMessages(sessionId, msgOpts);
+        messages = Array.isArray(raw3) ? raw3 : [];
+        if (messages.length > 0) dirSource = 'listSessionsGlobal';
+      }
+    }
+  } catch (e) {
+    return {
+      session: sessionSummary(sessionMeta, engineId),
+      messages: [],
+      rawMessagesIncluded: false,
+      metadata: {
+        sessionRaw: sessionMeta,
+        error: `getSessionMessages 失败: ${e.message}`,
+        sessionMessagesDirSource: dirSource,
+      },
+    };
+  }
+
+  // 结构化 messages（user/assistant/system 文本块）
+  /** @type {Array<{role: string; content: Array<{kind:'text'; text:string}>; redacted: boolean}>} */
+  const structuredMessages = [];
+  const userPrompts = [];
+  const assistantTexts = [];
+  let lastAssistantText = '';
+  let anyTruncated = false;
+
+  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);
+    const { text: shownBeforeRedaction, truncated } = maybeTruncate(text, noTruncate);
+    const { text: shown, redacted } = redactSessionText(shownBeforeRedaction);
+    if (truncated) anyTruncated = true;
+    const role = type === 'user' ? 'user' : type === 'assistant' ? 'assistant' : type === 'system' ? 'system' : 'unknown';
+    if (text) {
+      structuredMessages.push({
+        role,
+        content: [{ kind: 'text', text: shown }],
+        redacted,
+      });
+    }
+    if (type === 'user') userPrompts.push(shown);
+    else if (type === 'assistant') {
+      assistantTexts.push(shown);
+      lastAssistantText = shown;
+    }
+  }
+
+  const cliReplayGuide = buildCliReplayGuide(sessionMeta, sessionId);
+  const diagnostics = deepRedactSessionValue(buildDiagnostics(messages, noTruncate));
+
+  /** @type {Record<string, unknown>} */
+  const detail = {
+    session: sessionSummary(sessionMeta, engineId),
+    messages: structuredMessages,
+    rawMessagesIncluded: includeRawMessages,
+  };
+
+  /** @type {Record<string, unknown>} */
+  const metadata = {
+    messageCount: messages.length,
+    truncated: anyTruncated,
+    userPrompts,
+    assistantText: assistantTexts.join('\n\n'),
+    lastAssistantText,
+    diagnostics,
+    cliReplayGuide,
+    sessionMessagesProjectDir: msgOpts.dir != null ? String(msgOpts.dir) : undefined,
+    sessionMessagesDirSource: dirSource,
+  };
+
+  if (includeRawMessages) {
+    const { list, ok } = cloneMessagesForJson(messages);
+    metadata.rawMessages = deepRedactSessionValue(list);
+    if (!ok && messages.length > 0) metadata.rawMessagesSerializationFailed = true;
+  }
+
+  return { ...detail, metadata };
+}
+
+/**
+ * session-search：SDK 无原生搜索，用 listSessions 内存过滤。
+ * 命中 summary/customTitle/firstPrompt/cwd/projectName/projectPath/gitBranch/tag（大小写不敏感）。
+ */
+async function sessionSearch() {
+  const argv = process.argv;
+  const engineId = getOptValue(argv, '--engine') || 'claude-code';
+  const text = getOptValue(argv, '--query');
+  if (!text) throw new Error('session-search: --query 必填');
+  const limit = parseLimit(argv, 50, 200);
+  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' };
+  }
+
+  /** @type {Record<string, unknown>} */
+  const opts = { limit: 800 };
+  if (normalizedWorkDir) opts.dir = normalizedWorkDir;
+
+  const list = await sdk.listSessions(opts);
+  const arr = Array.isArray(list) ? list : [];
+  const needle = text.toLowerCase();
+  const matched = [];
+  for (const raw of arr) {
+    const meta = buildSessionMeta(/** @type {Record<string, unknown>} */ (raw));
+    const fields = [
+      meta.summary, meta.customTitle, meta.firstPrompt, meta.cwd,
+      meta.projectName, meta.projectPath, meta.gitBranch, meta.tag,
+    ];
+    const hitField = fields.find((f) => typeof f === 'string' && f.toLowerCase().includes(needle));
+    if (hitField !== undefined) {
+      const summary = sessionSummary(meta, engineId);
+      const snippet = String(hitField);
+      matched.push({
+        session: summary,
+        matches: [{ snippet: snippet.length > 200 ? snippet.slice(0, 200) + '…' : snippet }],
+      });
+    }
+  }
+  const start = Math.min(offset, matched.length);
+  const hits = matched.slice(start, start + limit);
+  const nextOffset = start + hits.length;
+  const result = { hits };
+  if (nextOffset < matched.length) {
+    result.nextCursor = encodeOffsetCursor(nextOffset);
+  }
+  return result;
+}
+
+/**
+ * session-delete：优先 SDK deleteSession，兜底删 jsonl 文件（幂等 already_deleted）。
+ */
+async function sessionDelete() {
+  const argv = process.argv;
+  const sessionId = getOptValue(argv, '--session-id');
+  if (!sessionId) throw new Error('session-delete: --session-id 必填');
+  assertSafeSessionId(sessionId);
+  const requestId = getOptValue(argv, '--request-id');
+  if (!requestId) throw new Error('session-delete: --request-id 必填');
+
+  const { sdk } = loadSdk();
+
+  // 优先 SDK 原生删除（若可用）
+  if (sdk && typeof sdk.deleteSession === 'function') {
+    try {
+      const res = await sdk.deleteSession(sessionId, { requestId });
+      if (res && typeof res === 'object' && 'status' in res) {
+        const status = /** @type {{ status?: string }} */ (res).status;
+        if (status === 'deleted' || status === 'already_deleted' || status === 'rejected') {
+          return { status };
+        }
+      }
+    } catch (e) {
+      // SDK 删除失败，回退到文件删除
+      void e;
+    }
+  }
+
+  // 兜底：删除 $HOME/.claude/projects/<encoded-cwd>/<sessionId>.jsonl
+  const home = process.env.HOME?.trim();
+  if (!home) {
+    return {
+      status: 'rejected',
+      error: { code: 'no_home', message: 'session-delete: HOME 未设置，无法定位会话文件', retryable: false },
+    };
+  }
+
+  const projectsDir = path.join(home, '.claude', 'projects');
+  let deleted = false;
+  try {
+    if (fs.existsSync(projectsDir)) {
+      for (const entry of fs.readdirSync(projectsDir)) {
+        const file = path.join(projectsDir, entry, `${sessionId}.jsonl`);
+        if (fs.existsSync(file)) {
+          fs.unlinkSync(file);
+          deleted = true;
+        }
+      }
+    }
+    // best-effort 清理 ~/.claude/sessions/*.json 索引
+    const sessionsDir = path.join(home, '.claude', 'sessions');
+    if (fs.existsSync(sessionsDir)) {
+      for (const entry of fs.readdirSync(sessionsDir)) {
+        if (!entry.endsWith('.json')) continue;
+        const idxFile = path.join(sessionsDir, entry);
+        try {
+          const idx = JSON.parse(fs.readFileSync(idxFile, 'utf8'));
+          if (idx && String(idx.session_id ?? idx.sessionId ?? '') === sessionId) {
+            fs.unlinkSync(idxFile);
+          }
+        } catch {
+          // 索引文件损坏，跳过
+        }
+      }
+    }
+  } catch (e) {
+    return {
+      status: 'rejected',
+      error: { code: 'delete_failed', message: `session-delete: ${e.message}`, retryable: true },
+    };
+  }
+
+  return { status: deleted ? 'deleted' : 'already_deleted' };
+}
+
+/**
+ * CLI 入口
+ */
+async function main() {
+  const command = process.argv[2];
+  const arg = process.argv[3];
+  const fileFlag = process.argv[4];
+
+  if (!command) {
+    console.error('[run-agent-engine] Usage: node run-agent-engine.mjs <command> [args]');
+    console.error('Commands: launch <json> | launch --file <path> | status <runKey> | cancel <runKey> | list-active | health');
+    console.error('         session-list | session-get | session-search | session-delete  (task 7.15)');
+    process.exit(1);
+  }
+
+  try {
+    let result;
+    switch (command) {
+      case 'launch': {
+        let payload;
+        if (arg === '--file' && fileFlag) {
+          // 从文件读取 JSON payload
+          const fs = await import('node:fs');
+          const content = fs.readFileSync(fileFlag, 'utf8');
+          payload = JSON.parse(content);
+        } else if (arg === '--stdin') {
+          payload = JSON.parse(await readStdin());
+        } else if (arg) {
+          // 直接解析 JSON 参数
+          payload = JSON.parse(arg);
+        } else {
+          throw new Error('Missing JSON payload for launch');
+        }
+        result = await launch(payload);
+        break;
+      }
+      case 'supervise-run': {
+        const payload = JSON.parse(await readStdin());
+        const owned = await runOwned(payload);
+        await owned.completion;
+        return;
+      }
+      case 'status':
+        if (!arg) {
+          throw new Error('Missing runKey for status');
+        }
+        result = status(arg);
+        break;
+      case 'cancel':
+        if (!arg) {
+          throw new Error('Missing runKey for cancel');
+        }
+        result = cancel(arg);
+        break;
+      case 'list-active':
+        result = listActive();
+        break;
+      case 'health':
+        result = health();
+        break;
+      case 'events':
+        if (!arg) throw new Error('Missing runKey for events');
+        result = listEvents(arg, Number(process.argv[4] ?? 0));
+        break;
+      case 'engine-list':
+        result = listEngines();
+        break;
+      case 'model-list':
+        if (!arg) throw new Error('Missing engineId for model-list');
+        result = listModels(arg);
+        break;
+      case 'engine-options':
+        if (!arg) throw new Error('Missing engineId for engine-options');
+        result = engineOptions(arg);
+        break;
+      case 'probe-engine':
+        if (!arg) throw new Error('Missing engineId for probe-engine');
+        result = probeEngine(arg, process.argv[4]);
+        break;
+      case 'session-list':
+        result = await sessionList();
+        break;
+      case 'session-get':
+        result = await sessionGet();
+        break;
+      case 'session-search':
+        result = await sessionSearch();
+        break;
+      case 'session-delete':
+        result = await sessionDelete();
+        break;
+      default:
+        throw new Error(`Unknown command: ${command}`);
+    }
+
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (error) {
+    console.error('[run-agent-engine] Error:', error.message);
+    process.exit(1);
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+main().catch((error) => {
+  console.error('[run-agent-engine] Fatal error:', error);
+  process.exit(1);
+});