dsh-any-agent 0.5.0 → 0.5.2

package/src/hub.mjs

@@ -19,21 +19,26 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  realpathSync,
   writeFileSync,
   existsSync,
   renameSync,
   statSync,
+  lstatSync,
   rmSync,
   readdirSync,
 } from 'node:fs';
-import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, parse, resolve, sep } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
-import { spawnSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
 import {
   ALLOW_FULL_ACCESS,
   APPROVAL_POLICIES,
   DEFAULT_PERMISSION,
   DEFAULT_REASONING_EFFORT,
+  DEFAULT_REVIEW,
   IDLE_TTL_MS,
   LIST_PROBE_TTL_MS,
   MAX_LIVE,
@@ -42,6 +47,8 @@ import {
   PROMPT_TIMEOUT_MS,
   REAP_INTERVAL_MS,
   REASONING_EFFORTS,
+  REVIEWS_DIR,
+  REVIEW_MODES,
   RUNS_DIR,
   SENTINEL_INCLUDE_REASONING,
   SENTINEL_TTL_MS,
@@ -53,6 +60,16 @@ import {
   assertWritableDir,
   defaultApprovalPolicy,
 } from './config.mjs';
+import {
+  REVIEW_VERDICTS,
+  buildReviewTicket,
+  normalizeReviewMode,
+  readReviewRecord,
+  reviewIdForRun,
+  writeReviewRecord,
+} from './review.mjs';
+import { sanitizeApprovalContext } from './redact.mjs';
+import { assertSafeId } from './ids.mjs';
 import { AcpProcess } from './acp.mjs';
 import { SessionHost } from './host.mjs';
 import { rssMb } from './procstat.mjs';
@@ -176,6 +193,50 @@ const MAX_PROMPT_ECHO = 4000;
 const MAX_RUNS = 20;
 /** 回合记录里 prompt 预览的长度。 */
 const MAX_RUN_PREVIEW = 200;
+/** 每个回合最多保留多少条"自动放行审批"摘要（总数另计，不受此限）。 */
+const MAX_AUTO_APPROVALS_KEPT = 20;
+/** 自动放行审批里命令预览的长度。 */
+const MAX_AUTO_APPROVAL_PREVIEW = 200;
+
+/**
+ * 清掉 `dir` 下超过 TTL 的文件与空会话目录；`.tmp` 残留不论年龄都按同一 cutoff 清。
+ * 只遍历一层会话目录，绝不递归进别处 —— 调用方（哨兵/审核目录）都是本服务自己的。
+ */
+function pruneDirTree(dir, ttlMs) {
+  if (!ttlMs || !existsSync(dir)) return { pruned: 0, dirs_removed: 0 };
+  let pruned = 0;
+  let dirsRemoved = 0;
+  const cutoff = Date.now() - ttlMs;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const sub = join(dir, entry.name);
+      for (const f of readdirSync(sub, { withFileTypes: true })) {
+        if (!f.isFile()) continue;
+        const fp = join(sub, f.name);
+        try {
+          if (statSync(fp).mtimeMs < cutoff) {
+            rmSync(fp, { force: true });
+            pruned++;
+          }
+        } catch {
+          /* 单个文件失败就跳过 */
+        }
+      }
+      try {
+        if (readdirSync(sub).length === 0) {
+          rmSync(sub, { recursive: true, force: true });
+          dirsRemoved++;
+        }
+      } catch {
+        /* 目录清理失败无所谓 */
+      }
+    }
+  } catch {
+    /* 目录读不了就跳过 */
+  }
+  return { pruned, dirs_removed: dirsRemoved };
+}
 
 /** 按 ACP 权限应答的规范形状挑选项。 */
 function pickOption(options, want) {
@@ -184,26 +245,6 @@ function pickOption(options, want) {
   return match?.optionId;
 }
 
-/** Only expose review context in memory; redact common credential fields and literals. */
-function sanitizeApprovalContext(value, key = '') {
-  if (/^(?:api[_-]?key|authorization|proxy[_-]?authorization|cookie|set[_-]?cookie|password|passwd|secret|token|access[_-]?token|refresh[_-]?token|credentials?|headers|env|environment)$/i.test(key)) {
-    return '[REDACTED]';
-  }
-  if (typeof value === 'string') {
-    return value
-      .replace(/\b(?:sk|ak)-[A-Za-z0-9_-]{8,}/g, '[REDACTED]')
-      .replace(/\bBearer\s+[^\s'";]+/gi, 'Bearer [REDACTED]')
-      .replace(/((?:api[_-]?key|password|passwd|secret|(?:access[_-]?)?token)\s*(?:=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s;]+)/gi, '$1[REDACTED]')
-      .replace(/(--(?:api[_-]?key|password|passwd|secret|token)\s+)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s;]+)/gi, '$1[REDACTED]')
-      .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@');
-  }
-  if (Array.isArray(value)) return value.map((item) => sanitizeApprovalContext(item));
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, sanitizeApprovalContext(item, name)]));
-  }
-  return value ?? null;
-}
-
 function approvalContext(params, toolCall, desc, options) {
   const input = toolCall.rawInput ?? toolCall.input ?? null;
   return sanitizeApprovalContext({
@@ -276,6 +317,21 @@ export function sanitizeResultForSentinel(result) {
       return input === undefined ? safeMeta : { ...safeMeta, input: sanitizeApprovalContext(input) };
     });
   }
+  // 自动放行审批摘要记录时已脱敏；落盘前再过一遍，防止将来有人加字段漏掉。
+  if (Array.isArray(rest.auto_approvals)) {
+    rest.auto_approvals = rest.auto_approvals.map((a) => (a && typeof a === 'object' ? sanitizeApprovalContext(a) : a));
+  }
+  // 审核单里可能有原任务预览、审核理由与证据摘要；哨兵会保留 7 天，同样要脱敏。
+  if (rest.review && typeof rest.review === 'object') {
+    const rv = { ...rest.review };
+    for (const key of ['prompt_preview', 'notes']) {
+      if (typeof rv[key] === 'string') rv[key] = sanitizeApprovalContext(rv[key], key);
+    }
+    if (Array.isArray(rv.checklist)) rv.checklist = rv.checklist.map((x) => sanitizeApprovalContext(x));
+    if (Array.isArray(rv.findings)) rv.findings = rv.findings.map((x) => sanitizeApprovalContext(x));
+    if (rv.evidence) rv.evidence = sanitizeApprovalContext(rv.evidence);
+    rest.review = rv;
+  }
   // 始终给出布尔值：调用方才能区分“思考被剥离”与“本来没有思考”。
   const out = { ...rest, thinking_omitted: Boolean(thinking) && !SENTINEL_INCLUDE_REASONING };
   if (SENTINEL_INCLUDE_REASONING && thinking !== undefined) out.thinking = thinking;
@@ -301,6 +357,8 @@ export class Conversation {
       provider: state.provider ?? null,
       model: state.model ?? null,
     };
+    /** 调用方审核策略（off / advisory）。可在 dsh_send 单次覆盖。 */
+    this.review = REVIEW_MODES.includes(state.review) ? state.review : DEFAULT_REVIEW;
     this.lastConfigApplied = null;
     /** 是否已回读并确认会话记录的权限档（null=尚未核对，true/false=结果）。 */
     this.permissionVerified = null;
@@ -367,6 +425,7 @@ export class Conversation {
       reasoningEffort: this.cfg.reasoningEffort,
       provider: this.cfg.provider,
       model: this.cfg.model,
+      review: this.review,
       workspace: this.workspace,
     };
   }
@@ -398,6 +457,8 @@ export class Conversation {
       title_hint: this.titleHint ?? null,
       cwd: this.cwd,
       permission: this.permission,
+      /** 会话默认审核策略；单次 dsh_send 可以覆盖。 */
+      review: this.review,
       /** true=已回读会话记录且一致；false/null=缓存暂时没有记录（read-only 仍由审批层兜底）。 */
       permission_verified: this.permissionVerified,
       on_approval: this.onApproval,
@@ -772,6 +833,9 @@ export class Conversation {
     }
     if (this.onApproval === 'auto-allow') {
       this.#hub.log.info(`[conv ${this.id}] 审批放行: ${desc}`);
+      // ★ 自动放行必须对调用方可见：DSH 会借审批把沙箱提升到 danger-full-access，
+      //   不记下来的话 workspace-write 会话事后看起来像从未越界（实测一轮 6 次提权无人知晓）。
+      if (allowId) this.#recordAutoApproval(params, toolCall, desc, options);
       return allowId
         ? { outcome: { outcome: 'selected', optionId: allowId } }
         : { outcome: { outcome: 'cancelled' } };
@@ -804,6 +868,35 @@ export class Conversation {
     });
   }
 
+  /**
+   * 记一条"被自动放行的审批"到本回合收集器（只记摘要，且先脱敏）。
+   * 回合外到来的审批（没有收集器）不记 —— 没有结果可挂。
+   */
+  #recordAutoApproval(params, toolCall, desc, options) {
+    const c = this.collector;
+    if (!c) return;
+    c.autoApprovalTotal = (c.autoApprovalTotal ?? 0) + 1;
+    const input = toolCall.rawInput ?? toolCall.input ?? null;
+    const escalation =
+      input && typeof input === 'object' && typeof input.sandbox_permissions === 'string'
+        ? input.sandbox_permissions
+        : null;
+    if (escalation) c.autoEscalationTotal = (c.autoEscalationTotal ?? 0) + 1;
+    if (!Array.isArray(c.autoApprovals)) c.autoApprovals = [];
+    if (c.autoApprovals.length >= MAX_AUTO_APPROVALS_KEPT) return;
+    const ctx = approvalContext(params, toolCall, desc, options);
+    const cmd = input && typeof input === 'object' ? input.command ?? input.cmd ?? null : null;
+    c.autoApprovals.push({
+      tool: ctx.tool ?? desc,
+      tool_call_id: ctx.tool_call_id ?? null,
+      escalation,
+      reason: typeof ctx.reason === 'string' ? ctx.reason.slice(0, 300) : null,
+      command_preview:
+        typeof cmd === 'string' ? sanitizeApprovalContext(cmd, 'command').slice(0, MAX_AUTO_APPROVAL_PREVIEW) : null,
+      at: new Date().toISOString(),
+    });
+  }
+
   /** 调用方裁决一个待决审批。 */
   decideApproval(approvalId, decision) {
     const p = this.pendingApprovals.get(approvalId);
@@ -854,6 +947,17 @@ export class Conversation {
       workspace_changed: false,
       elapsed_ms: 0,
     };
+    const reviewMode = runRecord.review_mode ?? this.review;
+    if (reviewMode !== 'off') {
+      runRecord.result.review = buildReviewTicket({
+        conversationId: this.id,
+        runId: runRecord.run_id,
+        promptPreview: runRecord.prompt_preview,
+        result: runRecord.result,
+        mode: reviewMode,
+        permission: this.permission,
+      });
+    }
     try {
       if (typeof this.#hub.writeRunSentinel === 'function') {
         const file = this.#hub.writeRunSentinel(this.id, runRecord);
@@ -902,27 +1006,34 @@ export class Conversation {
    *
    * @returns 等到回合结束 → 完整 result；没等到（wait=false 或等超时）→ 收据对象
    */
-  async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true } = {}) {
+  async prompt(text, { reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, run, wait = true, review } = {}) {
     if (this.busy) {
       throw new Error(
         `会话 ${this.id} 正在跑另一个回合。可以：dsh_interject 插话（打断并改口 / 排队），或 dsh_interrupt 打断。`,
       );
     }
-    const runRecord = run ?? this.createRun(text);
+    const runRecord = run ?? this.createRun(text, { review });
+    const reviewMode = runRecord.review_mode ?? normalizeReviewMode(review ?? this.review);
+    runRecord.review_mode = reviewMode;
     runRecord.status = 'running';
     runRecord.started_at = now();
     this.currentRun = runRecord;
-    const before = gitStatus(this.cwd);
+    let before = null;
     let proc;
     // ★ `busy` 必须在 ensureAlive **之前**置位。
     //   否则"把进程拉起来"这段（spawn + initialize + resume，可能好几秒）是一个**裸奔窗口**：
     //     ① reaper 看到 busy=false 且 lastUsedAt 还是上一轮的时刻（已过期），会把这个**刚拉起来**
     //        的进程当空闲回收掉 → 紧接着 resume 就报"DSH 进程未运行"（test/cycle.mjs 实测抓到）；
     //     ② 第二个 dsh_send 同样能通过 busy 检查，于是为同一会话再拉一个子进程 → 互相撞锁 + 泄漏。
+    //   ★ 同理，git 快照的 await 也必须放在 busy 置位**之后**（见下面的 Promise.all）。
     this.busy = true;
     this.lastUsedAt = now();
+    const beforePromise = gitStatus(this.cwd);
     try {
-      proc = await this.ensureAlive();
+      // 快照与拉起进程并行：快照只是读盘，不改变生命周期，早取晚取语义一致。
+      const [beforeSnap, liveProc] = await Promise.all([beforePromise, this.ensureAlive()]);
+      before = beforeSnap;
+      proc = liveProc;
     } catch (e) {
       // 起不来（撞写锁 / 会话损坏）就**必须放开 busy**，否则这个会话被永久占住；
       // 同时别留一条永远 "running" 的幽灵记录。
@@ -950,105 +1061,166 @@ export class Conversation {
       usage: null,
       plan: null,
       otherUpdates: [],
+      /** 本回合被 auto-allow 放行的审批摘要（最多 MAX_AUTO_APPROVALS_KEPT 条）与总数。 */
+      autoApprovals: [],
+      autoApprovalTotal: 0,
+      autoEscalationTotal: 0,
     };
     this.collector = c;
     const t0 = now();
     let settled = false;
 
-    /** 回合真正结束时收尾。无论有没有人在等，都**只执行一次**。 */
+    /**
+     * 把"调用方审核单"挂到回合结果上。
+     *
+     * 审核单必须随结果一起返回（正文、structuredContent、哨兵都是同一份 result），
+     * 否则调用方在异步收活时只会看到一段自述，很容易直接把它当成完成事实。
+     */
+    const attachReview = (result) => {
+      if (reviewMode !== 'off') {
+        result.review = buildReviewTicket({
+          conversationId: this.id,
+          runId: runRecord.run_id,
+          promptPreview: runRecord.prompt_preview,
+          result,
+          mode: reviewMode,
+          permission: this.permission,
+        });
+      }
+      return result;
+    };
+
+    /**
+     * 回合真正结束时收尾。无论有没有人在等，都**只执行一次**。
+     *
+     * 现在是异步的（git 快照走异步子进程），但保持了三个不变量：
+     *   1. 幂等：重复调用返回同一个 Promise，不会重复写哨兵；
+     *   2. 不拖累生命周期：`busy=false`、唤醒 idleWaiters、#scheduleDrain
+     *      都在**第一个 await 之前**同步完成，git 最慢 8s 也影响不到 reaper/插话；
+     *   3. 防弹：内部异常一律兜底成 error 结果 + 哨兵，返回的 Promise 不会 reject
+     *      （wait=false 的调用方不会 await 它，不能让 unhandled rejection 杀掉服务）。
+     */
+    let finalizePromise = null;
     const finalize = (stopReason, failure) => {
-      if (settled) return runRecord.result;
+      if (finalizePromise) return finalizePromise;
       settled = true;
-      // ★ 收尾本身也必须防弹：它跑在 ACP 的异步回调里，一旦抛出去就是 unhandled
-      //   rejection —— Node ≥15 会直接杀掉进程，连带丢掉所有会话的活进程；
-      //   而且调用方会永远等不到哨兵。所以出错也要落一个"收尾异常"的哨兵。
-      try {
-        this.busy = false;
-        if (this.currentRun === runRecord) this.currentRun = null;
-        this.collector = null;
-        this.currentTool = null;
-        // 回合结束后，任何仍挂着的审批都已失效：统一取消并清空，避免状态里
-        // 留下一个 dsh_approval_decide 只会回"没有待决审批"的幽灵。
-        for (const [, p] of this.pendingApprovals) {
-          try {
-            p.resolve({ outcome: { outcome: 'cancelled' } });
-          } catch {}
+      finalizePromise = (async () => {
+        // ★ 先启动 after 快照：调用 gitStatus 时子进程立刻 spawn，但**不 await**；
+        //   这样 snapshot 的时间点仍贴近回合结束，而 busy 释放/唤醒不必等 git。
+        const afterPromise = gitStatus(this.cwd);
+        try {
+          this.busy = false;
+          if (this.currentRun === runRecord) this.currentRun = null;
+          this.collector = null;
+          this.currentTool = null;
+          // 回合结束后，任何仍挂着的审批都已失效：统一取消并清空，避免状态里
+          // 留下一个 dsh_approval_decide 只会回"没有待决审批"的幽灵。
+          for (const [, p] of this.pendingApprovals) {
+            try {
+              p.resolve({ outcome: { outcome: 'cancelled' } });
+            } catch {}
+          }
+          this.pendingApprovals.clear();
+          this.pushOut('turn', `第 ${this.currentTurn} 轮结束（${stopReason ?? 'unknown'}）`, {
+            phase: 'end',
+            stop_reason: stopReason,
+            error: failure ?? undefined,
+          });
+          this.turnCount += 1;
+          this.lastUsedAt = now();
+          this.#hub.save();
+          // 唤醒所有"等本轮结束"的插话请求（busy 已置 false，它们可以安全地发下一轮）
+          const waiters = this.idleWaiters;
+          this.idleWaiters = [];
+          for (const w of waiters) w();
+          this.#scheduleDrain();
+          // 到这里才允许被 git 拖慢；结果/审核单/哨兵必须等快照完成后再落。
+          const after = await afterPromise;
+          const result = {
+            conversation_id: this.id,
+            run_id: runRecord.run_id,
+            stop_reason: stopReason,
+            error: failure,
+            answer: c.answer,
+            thinking: formatReasoning(c, reasoning),
+            thinking_stats: {
+              hidden: reasoning === 'hide' || reasoning === 'marker',
+              chars: c.reasoning.length,
+              chunks: c.reasoningChunks,
+              ms: c.reasoningStartedAt ? now() - c.reasoningStartedAt : 0,
+            },
+            tools_used: [...c.tools.values()],
+            usage: c.usage,
+            auto_approvals_total: c.autoApprovalTotal,
+            auto_escalations_total: c.autoEscalationTotal,
+            auto_approvals: c.autoApprovals,
+            workspace_changed: !sameWorkspaceSnapshot(before, after),
+            diff_stat: after,
+            elapsed_ms: now() - t0,
+          };
+          attachReview(result);
+          runRecord.ended_at = now();
+          runRecord.elapsed_ms = result.elapsed_ms;
+          runRecord.status = failure ? 'error' : stopReason === 'cancelled' ? 'cancelled' : 'done';
+          runRecord.result = result;
+          // ★ 无条件写哨兵：**一个回合 = 一个哨兵文件**，没有例外。
+          //   之前只在"调用方没在原地等"时才写，于是插话那一轮没有哨兵 —— 调用方的
+          //   等待逻辑（等文件出现）就永远空等，即使 run 早已 status=done（真实事故）。
+          //   统一规则也消除了整类"有 run_id 却没有哨兵"的坑。
+          const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
+          result.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
+          if (!sentinelFile) result.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
+          return result;
+        } catch (e) {
+          this.#hub.log.info(`[conv ${this.id}] 回合收尾异常（已兜底）: ${e.message}`);
+          this.busy = false;
+          if (this.currentRun === runRecord) this.currentRun = null;
+          this.collector = null;
+          const waiters = this.idleWaiters;
+          this.idleWaiters = [];
+          for (const w of waiters) w();
+          this.#scheduleDrain();
+          const fallback = {
+            conversation_id: this.id,
+            run_id: runRecord.run_id,
+            stop_reason: 'error',
+            error: `回合收尾异常: ${e.message}`,
+            answer: c.answer ?? '',
+            thinking_stats: { hidden: true, chars: 0, chunks: 0, ms: 0 },
+            tools_used: [...(c.tools?.values?.() ?? [])],
+            workspace_changed: false,
+            elapsed_ms: now() - t0,
+          };
+          attachReview(fallback);
+          runRecord.ended_at = now();
+          runRecord.status = 'error';
+          runRecord.error = fallback.error;
+          runRecord.result = fallback;
+          const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
+          fallback.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
+          if (!sentinelFile) fallback.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
+          return fallback;
         }
-        this.pendingApprovals.clear();
-        this.pushOut('turn', `第 ${this.currentTurn} 轮结束（${stopReason ?? 'unknown'}）`, {
-          phase: 'end',
-          stop_reason: stopReason,
-          error: failure ?? undefined,
-        });
-        this.turnCount += 1;
-        this.lastUsedAt = now();
-        this.#hub.save();
-        // 唤醒所有"等本轮结束"的插话请求（busy 已置 false，它们可以安全地发下一轮）
-        const waiters = this.idleWaiters;
-        this.idleWaiters = [];
-        for (const w of waiters) w();
-        this.#scheduleDrain();
-        const after = gitStatus(this.cwd);
-        const result = {
-          conversation_id: this.id,
-          run_id: runRecord.run_id,
-          stop_reason: stopReason,
-          error: failure,
-          answer: c.answer,
-          thinking: formatReasoning(c, reasoning),
-          thinking_stats: {
-            hidden: reasoning === 'hide' || reasoning === 'marker',
-            chars: c.reasoning.length,
-            chunks: c.reasoningChunks,
-            ms: c.reasoningStartedAt ? now() - c.reasoningStartedAt : 0,
-          },
-          tools_used: [...c.tools.values()],
-          usage: c.usage,
-          workspace_changed: !sameWorkspaceSnapshot(before, after),
-          diff_stat: after,
-          elapsed_ms: now() - t0,
-        };
-        runRecord.ended_at = now();
-        runRecord.elapsed_ms = result.elapsed_ms;
-        runRecord.status = failure ? 'error' : stopReason === 'cancelled' ? 'cancelled' : 'done';
-        runRecord.result = result;
-        // ★ 无条件写哨兵：**一个回合 = 一个哨兵文件**，没有例外。
-        //   之前只在"调用方没在原地等"时才写，于是插话那一轮没有哨兵 —— 调用方的
-        //   等待逻辑（等文件出现）就永远空等，即使 run 早已 status=done（真实事故）。
-        //   统一规则也消除了整类"有 run_id 却没有哨兵"的坑。
-        const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
-        result.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
-        if (!sentinelFile) result.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
-        return result;
-      } catch (e) {
-        this.#hub.log.info(`[conv ${this.id}] 回合收尾异常（已兜底）: ${e.message}`);
-        this.busy = false;
-        if (this.currentRun === runRecord) this.currentRun = null;
-        this.collector = null;
-        const waiters = this.idleWaiters;
-        this.idleWaiters = [];
-        for (const w of waiters) w();
-        this.#scheduleDrain();
-        const fallback = {
-          conversation_id: this.id,
-          run_id: runRecord.run_id,
-          stop_reason: 'error',
-          error: `回合收尾异常: ${e.message}`,
-          answer: c.answer ?? '',
-          thinking_stats: { hidden: true, chars: 0, chunks: 0, ms: 0 },
-          tools_used: [...(c.tools?.values?.() ?? [])],
-          workspace_changed: false,
-          elapsed_ms: now() - t0,
-        };
-        runRecord.ended_at = now();
-        runRecord.status = 'error';
-        runRecord.error = fallback.error;
-        runRecord.result = fallback;
-        const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
-        fallback.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
-        if (!sentinelFile) fallback.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
-        return fallback;
-      }
+      })().catch((e) => {
+        // 最后一层保险：收尾连兜底都失败时也绝不把 rejection 丢给事件循环。
+        this.#hub.log.info(`[conv ${this.id}] 回合收尾二次异常（已忽略）: ${e.message}`);
+        if (!runRecord.result) {
+          runRecord.result = {
+            conversation_id: this.id,
+            run_id: runRecord.run_id,
+            stop_reason: 'error',
+            error: `回合收尾异常: ${e.message}`,
+            answer: c.answer ?? '',
+            thinking_stats: { hidden: true, chars: 0, chunks: 0, ms: 0 },
+            tools_used: [],
+            workspace_changed: false,
+            elapsed_ms: now() - t0,
+          };
+          runRecord.status = 'error';
+        }
+        return runRecord.result;
+      });
+      return finalizePromise;
     };
 
     /** 没等到结果时给调用方的收据（它靠 run_id + 哨兵文件事后验收）。 */
@@ -1065,30 +1237,40 @@ export class Conversation {
 
     // 关键：第三个参数传 0 = **不设超时**。回合只能由它自己结束，或由 session/cancel 结束。
     const acp = proc.request('session/prompt', { sessionId: this.id, prompt: [{ type: 'text', text }] }, 0);
-    acp.then(
-      (res) => {
-        if (res?.usage) c.usage = c.usage ?? res.usage;
-        finalize(res?.stopReason ?? null, null);
-      },
-      (e) => finalize('error', e.message),
-    );
+    // 这个 Promise 在 finalize **真正完成**（含 workspace_changed、审核单、哨兵）后才 settle。
+    // 等待方必须等它，而不是只等 acp —— 否则会拿到还没填完的 runRecord.result。
+    const finished = acp
+      .then(
+        (res) => {
+          if (res?.usage) c.usage = c.usage ?? res.usage;
+          return finalize(res?.stopReason ?? null, null);
+        },
+        (e) => finalize('error', e.message),
+      )
+      .catch((e) => {
+        // finalize 自己是防弹的；这里只兜住同步抛出的极端情况。
+        this.#hub.log.info(`[conv ${this.id}] 回合回调异常（已兜底）: ${e.message}`);
+        return runRecord.result ?? null;
+      });
 
-    if (!wait) return settled ? runRecord.result : receipt(0);
+    if (!wait) {
+      // 同步走到这里时 finalize 还没开始（ACP 回调在微任务里），返回收据即可。
+      // 若极端情况下已经收尾，则等它给出完整结果，不要返回半成品。
+      return settled ? await (finalizePromise ?? runRecord.result) : receipt(0);
+    }
     if (timeoutMs <= 0) {
-      await acp.then(
-        () => {},
-        () => {},
-      );
+      await finished;
       return runRecord.result;
     }
     const timedOut = await Promise.race([
-      acp.then(
+      finished.then(
         () => false,
         () => false,
       ),
       new Promise((r) => setTimeout(() => r(true), timeoutMs)),
     ]);
-    if (timedOut && !settled) return receipt(timeoutMs);
+    // 超时发生在 finalize 完成之前（包括 git 快照还在跑）：给收据，不返回半成品结果。
+    if (timedOut) return receipt(timeoutMs);
     return runRecord.result;
   }
 
@@ -1152,13 +1334,15 @@ export class Conversation {
   }
 
   /** 建一条回合记录。派活时先建，好让调用方立刻拿到 run_id（异步模式的关键）。 */
-  createRun(text, { clientRunId = null } = {}) {
+  createRun(text, { clientRunId = null, review = this.review } = {}) {
     const run = {
       run_id: `run-${Date.now().toString(36)}-${++this.runSeq}`,
       conversation_id: this.id,
       client_run_id: clientRunId ?? null,
       prompt_preview: text.length > MAX_RUN_PREVIEW ? `${text.slice(0, MAX_RUN_PREVIEW)}…` : text,
       status: 'queued',
+      /** 本回合的审核策略（off / advisory）；由 dsh_send / dsh_interject 或会话默认决定。 */
+      review_mode: normalizeReviewMode(review, this.review),
       started_at: null,
       ended_at: null,
       elapsed_ms: null,
@@ -1189,7 +1373,7 @@ export class Conversation {
   // ── 会话级队列（忙时非阻塞入队）────────────────────────────────
 
   /** 入队；返回 run 记录与 1-based 位置。队列只在内存，重启丢失。 */
-  enqueue(text, { reasoning = 'hide', clientRunId = null, preview = null } = {}) {
+  enqueue(text, { reasoning = 'hide', clientRunId = null, preview = null, review = this.review } = {}) {
     const MAX_QUEUE = 8;
     if (clientRunId) {
       const existing = this.getRunByClientId(clientRunId);
@@ -1199,7 +1383,7 @@ export class Conversation {
       throw new Error(`队列已满（最多 ${MAX_QUEUE} 条）；先用 dsh_queue list 清理，或等当前回合结束`);
     }
     // 预览用调用方原文，执行用可能已注入团队前缀的 text。
-    const run = this.createRun(preview ?? text, { clientRunId });
+    const run = this.createRun(preview ?? text, { clientRunId, review });
     run.status = 'queued';
     this.queue.push({ run, text, reasoning, clientRunId, enqueued_at: now() });
     return { run, position: this.queue.length, deduped: false };
@@ -1236,6 +1420,16 @@ export class Conversation {
         workspace_changed: false,
         elapsed_ms: 0,
       };
+      if (run.review_mode !== 'off') {
+        run.result.review = buildReviewTicket({
+          conversationId: this.id,
+          runId: run.run_id,
+          promptPreview: run.prompt_preview,
+          result: run.result,
+          mode: run.review_mode,
+          permission: this.permission,
+        });
+      }
       // 取消也是终态 → 写哨兵，避免等待方永远空等。
       const file = this.#hub.writeRunSentinel(this.id, run);
       run.result.sentinel_file = file ?? this.#hub.runSentinelPath(this.id, run.run_id);
@@ -1289,6 +1483,142 @@ export class Conversation {
     return this.runs.length ? this.runs[this.runs.length - 1] : null;
   }
 
+  /**
+   * 异步收据里的"待审核"审核单：回合还没结束，只有清单和 run_id，
+   * 告诉调用方"拿到哨兵结果后先审核，再当完成"。
+   */
+  pendingReviewTicket(runId) {
+    const run = this.runs.find((x) => x.run_id === runId) ?? null;
+    const mode = run?.review_mode ?? this.review;
+    if (mode === 'off') return null;
+    return buildReviewTicket({
+      conversationId: this.id,
+      runId,
+      promptPreview: run?.prompt_preview ?? null,
+      result: null,
+      mode,
+      permission: this.permission,
+      pending: true,
+    });
+  }
+
+  /**
+   * 记录调用方对某个已完成回合的审核裁决。
+   *
+   * 三种来源按优先级取事实：
+   *   1) 内存里的 run（含完整 result）；
+   *   2) 哨兵文件（服务重启 / run 记录被挤出内存后仍然可审核）；
+   *   3) 已有的审核记录（允许修订裁决）。
+   *
+   * 注意：**不阻塞后续派活，也不自动回灌给 DSH**。审核只是把"调用方已经看过并给出结论"
+   * 这件事落成可审计的事实；要修就由调用方再 dsh_send。
+   */
+  submitReview(runId, { verdict, notes, findings } = {}) {
+    if (typeof runId !== 'string' || runId.trim() === '') {
+      throw new Error('run_id 不能为空');
+    }
+    assertSafeId(runId, 'run_id');
+    if (!REVIEW_VERDICTS.includes(verdict)) {
+      throw new Error(`verdict 必须是 ${REVIEW_VERDICTS.join(' | ')} 之一`);
+    }
+    const cleanNotes = typeof notes === 'string' ? notes.trim() : '';
+    const cleanFindings = Array.isArray(findings)
+      ? findings.filter((f) => typeof f === 'string' && f.trim() !== '').map((f) => f.trim())
+      : [];
+    if (verdict !== 'pass' && !cleanNotes && !cleanFindings.length) {
+      throw new Error('verdict=fail/partial 时必须提供 notes（或 findings）说明理由');
+    }
+
+    const run = this.runs.find((x) => x.run_id === runId) ?? null;
+    let result = run?.result ?? null;
+    let promptPreview = run?.prompt_preview ?? null;
+    let mode = run?.review_mode ?? this.review;
+
+    if (run) {
+      if (run.status === 'running' || run.status === 'queued') {
+        throw new Error(`回合 ${runId} 还没结束，不能审核（等哨兵文件出现或 dsh_get 显示完成后重试）`);
+      }
+      if (!result) throw new Error(`回合 ${runId} 没有可用结果，无法审核`);
+    } else {
+      // 内存里没有这条 run：以哨兵为准。它只在回合终止时写入，所以天然是"已完成"。
+      let sentinel = null;
+      try {
+        sentinel = JSON.parse(readFileSync(this.#hub.runSentinelPath(this.id, runId), 'utf8'));
+      } catch {
+        /* 下面的审核记录回退会给出更准确的错误 */
+      }
+      if (sentinel) {
+        result = sentinel.result ?? null;
+        if (result?.review && typeof result.review === 'object') {
+          promptPreview = result.review.prompt_preview ?? promptPreview;
+          mode = result.review.mode ?? mode;
+        }
+      }
+    }
+
+    const existing = readReviewRecord(this.id, runId);
+    if (!result && !existing) {
+      throw new Error(
+        `未知 run_id: ${runId}（内存里没有、也没有哨兵/审核记录；请确认 run_id 是否正确，` +
+          `或先用 dsh_get / 哨兵文件取回结果）`,
+      );
+    }
+
+    const ticket =
+      result?.review && typeof result.review === 'object'
+        ? { ...result.review }
+        : existing
+          ? { ...existing }
+          : buildReviewTicket({
+              conversationId: this.id,
+              runId,
+              promptPreview,
+              result: result ?? {},
+              mode,
+              permission: this.permission,
+            });
+    if (!ticket.review_id) ticket.review_id = reviewIdForRun(runId);
+    ticket.conversation_id = ticket.conversation_id ?? this.id;
+    ticket.run_id = ticket.run_id ?? runId;
+    ticket.mode = ticket.mode ?? mode;
+
+    const reviewedAt = new Date().toISOString();
+    const { file, payload } = writeReviewRecord({
+      ticket,
+      verdict,
+      notes: cleanNotes,
+      findings: cleanFindings,
+      reviewedAt,
+    });
+    const review = {
+      ...ticket,
+      status: verdict,
+      verdict,
+      notes: payload.notes,
+      findings: payload.findings,
+      reviewed_at: reviewedAt,
+      review_file: file,
+    };
+    if (run) {
+      run.review = review;
+      if (run.result && typeof run.result === 'object') run.result.review = review;
+    }
+    // 哨兵是调用方异步收活的来源；把裁决回写进去，避免它一直显示 pending。
+    this.#hub.updateRunSentinelReview(this.id, runId, {
+      status: review.status,
+      verdict: review.verdict,
+      notes: review.notes,
+      findings: review.findings,
+      reviewed_at: reviewedAt,
+      review_file: file,
+    });
+    return {
+      ...review,
+      review_file: file,
+      sentinel_file: this.#hub.runSentinelPath(this.id, runId),
+    };
+  }
+
   /** 等到当前回合结束（不忙则立即返回 true；`timeoutMs <= 0` 一直等；超时返回 false）。 */
   async waitIdle(timeoutMs = 30 * 60 * 1000) {
     if (!this.busy) return true;
@@ -1327,9 +1657,9 @@ export class Conversation {
    * 之所以无竞态：dsh-acp 在让 prompt 请求返回**之前**就清空了 inflight 槽位，
    * 且只在 agent 完全 idle 后才 settle（lib/index.js:1003-1011）。
    */
-  async interject(message, { mode = 'interject', reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, clientRunId = null } = {}) {
+  async interject(message, { mode = 'interject', reasoning = 'hide', timeoutMs = PROMPT_TIMEOUT_MS, clientRunId = null, review } = {}) {
     // 先建 run：幂等键要在"等待上一轮"之前就登记，否则重试会造出第二个 run。
-    const run = this.createRun(message, { clientRunId });
+    const run = this.createRun(message, { clientRunId, review });
     if (!this.busy) {
       const r = await this.prompt(message, { reasoning, timeoutMs, run });
       return { ...r, interjected: 'idle', waited_ms: 0 };
@@ -1338,7 +1668,7 @@ export class Conversation {
     if (mode === 'interject') {
       this.proc?.notify('session/cancel', { sessionId: this.id });
     }
-    // 排队等待的时长跟随调用方的 timeout_ms（0 = 一直等），不再固定 30 分钟。
+    // 排队等待的时长跟随调用方的 timeoutMs（0 = 一直等），不再固定 30 分钟。
     const idle = await this.waitIdle(timeoutMs);
     const waited = now() - t0;
     if (!idle) {
@@ -1358,6 +1688,17 @@ export class Conversation {
         workspace_changed: false,
         elapsed_ms: 0,
       };
+      // 取消同样是一次终态结果：审核单照挂，调用方仍可记录"这次没跑成"。
+      if (run.review_mode !== 'off') {
+        run.result.review = buildReviewTicket({
+          conversationId: this.id,
+          runId: run.run_id,
+          promptPreview: run.prompt_preview,
+          result: run.result,
+          mode: run.review_mode,
+          permission: this.permission,
+        });
+      }
       const file = this.#hub.writeRunSentinel?.(this.id, run);
       run.result.sentinel_file = file ?? this.#hub.runSentinelPath?.(this.id, run.run_id) ?? null;
       throw err;
@@ -1423,30 +1764,178 @@ export class Conversation {
   }
 }
 
-/** 两次 git status 快照是否表示同一组工作区变更。 */
+/**
+ * 两次 workspace 快照是否表示同一组工作区变更。
+ *
+ * 优先比较 `fingerprint`（覆盖**全量**条目：状态行 + 每个路径的 size/mtime，
+ * 未跟踪目录递归展开）。只比较前 40 条 entries 会把"同一状态行但内容变了"
+ * 和第 41 条之后的改动都漏掉（workspace_changed 假阴性）。
+ */
 export function sameWorkspaceSnapshot(a, b) {
   if (!a && !b) return true;
   if (!a || !b) return false;
+  if (typeof a.fingerprint === 'string' && typeof b.fingerprint === 'string') {
+    return a.fingerprint === b.fingerprint;
+  }
+  // 兼容旧快照/测试里手写的 { changed_files, entries }。
   return JSON.stringify(a.entries ?? []) === JSON.stringify(b.entries ?? []);
 }
 
-/** 收集当前工作区的 git 变更摘要（非 git 目录返回 null）。 */
-export function gitStatus(cwd) {
+const GIT_TIMEOUT_MS = 8000;
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+const MAX_UNTRACKED_DIR_ENTRIES = 2000;
+const execFileAsync = promisify(execFile);
+
+/**
+ * 安全 git 参数（放 subcommand 之前）。
+ *
+ * `--no-optional-locks` 是 **git 全局选项**，放在 `status` 之后会被 git 当成
+ * 未知参数直接退出 129 —— 那样快照永远是 null，workspace_changed 恒为 false。
+ */
+const GIT_SAFE = ['--no-optional-locks', '-c', 'core.fsmonitor=false'];
+
+function gitEnv() {
+  return { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+}
+
+/** 异步跑一次 git 并取 stdout；非 git 目录/超时/输出过大都抛给调用方。 */
+async function gitOutput(cwd, args) {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: GIT_MAX_BUFFER,
+    windowsHide: true,
+    env: gitEnv(),
+  });
+  return stdout;
+}
+
+/** 解析 porcelain v1 -z 状态行；rename/copy 的“原路径”是下一个 NUL 段。 */
+function parsePorcelainZ(stdout) {
+  const tokens = String(stdout ?? '').split('\0');
+  const rows = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token) continue;
+    // 形如 "XY path"；posix 允许路径里有空格，所以只切前三个字符。
+    if (token.length < 4 || token[2] !== ' ') continue;
+    const status = token.slice(0, 2);
+    const path = token.slice(3);
+    let orig = null;
+    if (/[RC]/.test(status)) orig = tokens[++i] || null;
+    rows.push({ status, path, orig });
+  }
+  return rows;
+}
+
+/**
+ * 把一个路径的当前状态（类型 + size + mtimeMs）混进指纹。
+ *
+ * - 普通文件：size + mtimeMs 足以识别"状态行没变、内容变了"；
+ * - 未跟踪目录（`?? dir/`）：目录 mtime 只在直接子项增删时变，光看它不够，
+ *   所以递归展开（只用 lstat，不跟随符号链接/不钻 .git，且有预算上限）；
+ * - 已跟踪的目录条目（子模块）：只看它自己的 lstat，避免把子模块整个走一遍。
+ */
+function hashPathStat(hash, full, label, budget) {
+  let st;
+  try {
+    st = lstatSync(full);
+  } catch {
+    hash.update(`${label}\0missing\0`);
+    return;
+  }
+  if (st.isDirectory() && budget) {
+    hash.update(`${label}\0dir\0${st.mtimeMs}\0`);
+    let entries;
+    try {
+      entries = readdirSync(full, { withFileTypes: true });
+    } catch {
+      hash.update('unreadable\0');
+      return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const ent of entries) {
+      if (ent.name === '.git') continue;
+      if (budget.left <= 0) {
+        hash.update(`${label}\0truncated\0`);
+        return;
+      }
+      budget.left -= 1;
+      hashPathStat(hash, join(full, ent.name), `${label}/${ent.name}`, budget);
+    }
+    return;
+  }
+  const kind = st.isSymbolicLink() ? 'link' : st.isFile() ? 'file' : st.isDirectory() ? 'dir' : 'other';
+  hash.update(`${label}\0${kind}\0${st.size}\0${st.mtimeMs}\0`);
+}
+
+/**
+ * 收集当前工作区的 git 变更摘要（非 git 目录返回 null）。
+ *
+ * 异步实现：`execFile` 不占用事件循环 —— 一个 MCP 服务进程承载多个会话，
+ * 同步 `spawnSync` 最长 8s 会把所有会话的 ACP 消息/审批一起卡住。
+ *
+ * 返回对象向后兼容：`changed_files` = 全量状态条目数，`entries` = 前 40 条
+ * 展示用状态行；新增 `fingerprint` 覆盖**全量**条目（含逐路径 size/mtime），
+ * 供 `sameWorkspaceSnapshot` 判断"内容是否真的变了"。
+ */
+export async function gitStatus(cwd) {
   if (process.env.DSH_MCP_GIT_STATUS === '0') return null;
   try {
     // ★ 在不可信仓库里 `git status` 可能触发仓库配置的 fsmonitor/filter；这些
     //   命令发生在 DSH 沙箱与审批层之外。禁用可选锁与 fsmonitor，并允许用
     //   DSH_MCP_GIT_STATUS=0 完全关掉。
-    const r = spawnSync('git', ['-c', 'core.fsmonitor=false', 'status', '--porcelain', '--no-optional-locks'], {
-      cwd,
-      encoding: 'utf8',
-      timeout: 8000,
-      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
-    });
-    if (r.status !== 0 || !r.stdout) return null;
-    const lines = r.stdout.split('\n').filter(Boolean);
-    if (!lines.length) return null;
-    return { changed_files: lines.length, entries: lines.slice(0, 40) };
+    // porcelain 的路径相对 **仓库根**（cwd 是子目录时也是），所以同时取 top-level。
+    const [statusOut, rootOut] = await Promise.all([
+      gitOutput(cwd, [...GIT_SAFE, 'status', '--porcelain', '-z']),
+      gitOutput(cwd, [...GIT_SAFE, 'rev-parse', '--show-toplevel']),
+    ]);
+    const rows = parsePorcelainZ(statusOut);
+    if (!rows.length) return null;
+    // git 输出的是 `C:/...` 风格，统一成原生分隔符，后面 startsWith 才不会误判越界。
+    const root = resolve(String(rootOut ?? '').trim() || cwd);
+
+    // 状态行按路径排序后参与指纹，避免依赖 git 的输出顺序。
+    const sorted = rows
+      .slice()
+      .sort((a, b) =>
+        a.path === b.path
+          ? a.status < b.status
+            ? -1
+            : a.status > b.status
+              ? 1
+              : 0
+          : a.path < b.path
+            ? -1
+            : 1,
+      );
+
+    const hash = createHash('sha256');
+    const budget = { left: MAX_UNTRACKED_DIR_ENTRIES };
+    const entries = [];
+    const rootPrefix = root.endsWith(sep) ? root : root + sep;
+    for (const row of sorted) {
+      const display = row.orig ? `${row.status} ${row.orig} -> ${row.path}` : `${row.status} ${row.path}`;
+      if (entries.length < 40) entries.push(display);
+      hash.update(display);
+      hash.update('\0');
+
+      const cleanPath = row.path.endsWith('/') ? row.path.slice(0, -1) : row.path;
+      const full = resolve(root, cleanPath);
+      if (full !== root && !full.startsWith(rootPrefix)) {
+        hash.update('outside-worktree\0');
+        continue;
+      }
+      // 只有未跟踪目录需要递归；已跟踪条目（含子模块）看 lstat 即可。
+      hashPathStat(hash, full, cleanPath, row.status === '??' ? budget : null);
+    }
+
+    return {
+      changed_files: rows.length,
+      entries,
+      fingerprint: hash.digest('hex'),
+    };
   } catch {
     return null;
   }
@@ -1511,9 +2000,26 @@ export function homeWorkspaceProblem(cwd, permission) {
   if (!home) return null;
   const caseInsensitive = process.platform === 'win32' || fsCaseInsensitive();
   const norm = (p) => {
-    const r = resolve(p);
+    // 解析 symlink：一个指向家目录/根目录的软链不能绕过这两个边界。
+    // 路径不存在时（测试里的 "some-project"）回落到 resolve。
+    let r;
+    try {
+      r = realpathSync(p);
+    } catch {
+      r = resolve(p);
+    }
     return caseInsensitive ? r.toLowerCase() : r;
   };
+  // 根目录 = 整个磁盘。workspace-write 的沙箱根会跟着 cwd 走，
+  // 于是“只写工作区”退化成“可写全盘”，必须显式要求 danger-full-access。
+  const fsRoot = resolve(parse(cwd).root);
+  if (norm(cwd) === norm(fsRoot)) {
+    return [
+      'cwd 不能是文件系统根目录: ' + cwd,
+      '  workspace-write 的沙箱根会变成整个磁盘，等于绕过“只写工作区”的权限档。',
+      '  请传一个具体的项目目录；确实要全盘访问请显式用 permission=danger-full-access。',
+    ].join('\n');
+  }
   if (norm(cwd) !== norm(home)) return null;
 
   const temp = tmpdir();
@@ -1557,6 +2063,7 @@ export class Hub {
     //   看起来正常，但注册表/哨兵/锁登记全部丢失，异步等待永远醒不过来。
     assertWritableDir(dirname(STATE_FILE), '状态目录');
     assertWritableDir(RUNS_DIR, '哨兵目录');
+    assertWritableDir(REVIEWS_DIR, '审核记录目录');
     assertWritableDir(LOCKS_DIR, '锁登记目录');
 
     // 旧版本的默认状态文件在包安装目录里；一次性迁移到新的用户可写目录。
@@ -1631,6 +2138,8 @@ export class Hub {
 
   /** 某个 run 的完成哨兵文件路径。 */
   runSentinelPath(conversationId, runId) {
+    assertSafeId(conversationId, 'conversation_id');
+    assertSafeId(runId, 'run_id');
     return join(RUNS_DIR, conversationId, `${runId}.json`);
   }
 
@@ -1666,6 +2175,34 @@ export class Hub {
     }
   }
 
+  /**
+   * 把调用方的审核裁决回写进该 run 的哨兵文件（best-effort）。
+   *
+   * 为什么回写：异步调用方收活主要靠读哨兵。若审核后哨兵仍写着 `review.status=pending`，
+   * 下一次读文件会得到一个与事实相反的状态。原子重写不破坏闩锁语义：文件始终存在，
+   * 内容要么是旧的完整版本，要么是新的完整版本。
+   */
+  updateRunSentinelReview(conversationId, runId, review) {
+    const file = this.runSentinelPath(conversationId, runId);
+    try {
+      const payload = JSON.parse(readFileSync(file, 'utf8'));
+      const result = payload.result && typeof payload.result === 'object' ? payload.result : {};
+      result.review = {
+        ...(result.review && typeof result.review === 'object' ? result.review : {}),
+        ...review,
+      };
+      payload.result = result;
+      payload.reviewed_at = review.reviewed_at ?? null;
+      const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+      writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+      renameSync(tmp, file);
+      return true;
+    } catch (e) {
+      this.log.info(`[hub] 回写哨兵审核状态失败（${file}）: ${e.message}`);
+      return false;
+    }
+  }
+
   /**
    * 启动时清理过期哨兵（默认 7 天前）与崩溃残留的 .tmp 文件。
    *
@@ -1673,39 +2210,16 @@ export class Hub {
    * 只在服务启动时做一次，因此绝不会删掉"当前正在等待的"哨兵（那时它还不需要存在）。
    */
   pruneSentinels({ ttlMs = SENTINEL_TTL_MS } = {}) {
-    if (!ttlMs || !existsSync(RUNS_DIR)) return { pruned: 0, dirs_removed: 0 };
-    let pruned = 0;
-    let dirsRemoved = 0;
-    const cutoff = Date.now() - ttlMs;
-    try {
-      for (const entry of readdirSync(RUNS_DIR, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const dir = join(RUNS_DIR, entry.name);
-        for (const f of readdirSync(dir, { withFileTypes: true })) {
-          if (!f.isFile()) continue;
-          const fp = join(dir, f.name);
-          try {
-            if (statSync(fp).mtimeMs < cutoff) {
-              rmSync(fp, { force: true });
-              pruned++;
-            }
-          } catch {
-            /* 单个文件失败就跳过 */
-          }
-        }
-        try {
-          if (readdirSync(dir).length === 0) {
-            rmSync(dir, { recursive: true, force: true });
-            dirsRemoved++;
-          }
-        } catch {
-          /* 目录清理失败无所谓 */
-        }
-      }
-    } catch (e) {
-      this.log.info(`[hub] 清理哨兵失败: ${e.message}`);
-    }
-    return { pruned, dirs_removed: dirsRemoved };
+    const runs = pruneDirTree(RUNS_DIR, ttlMs);
+    // 审核记录同样含正文/理由，按同一 TTL 清理；目录分开是为了语义清晰，
+    // 也避免一次清理把"刚提交的裁决"和"已完成的哨兵"混为一谈。
+    const reviews = pruneDirTree(REVIEWS_DIR, ttlMs);
+    return {
+      pruned: runs.pruned,
+      dirs_removed: runs.dirs_removed,
+      reviews_pruned: reviews.pruned,
+      review_dirs_removed: reviews.dirs_removed,
+    };
   }
 
   /** 删除某个 run 的哨兵（起跑前防御性清残留；调用方消费后也可自行删）。 */
@@ -1718,6 +2232,8 @@ export class Hub {
   }
 
   async get(id) {
+    // 会话 id 会参与 meta/tombstone/会话存储的路径拼接；先挡住路径分隔符与 `..`。
+    assertSafeId(id, 'conversation_id');
     // ★ forget 是终态：墓碑存在时，任何按 id 的查询都必须明确失败，
     //   否则 DSH 会话存储里的记录会让它悄悄复活（"forget 不持久"）。
     if (isForgotten(id)) {
@@ -1793,6 +2309,7 @@ export class Hub {
             createdAt: persisted?.createdAt,
             lastUsedAt: persisted?.lastUsedAt,
             turnCount: persisted?.turnCount,
+            review: REVIEW_MODES.includes(persisted?.review) ? persisted.review : DEFAULT_REVIEW,
             workspace: persisted?.workspace ?? null,
           },
           this,
@@ -1880,7 +2397,7 @@ export class Hub {
   }
 
   /** 新建一个会话：拉起进程 + ACP 初始化 + session/new。 */
-  async create({ cwd, permission = DEFAULT_PERMISSION, onApproval, titleHint, reasoningEffort, provider, model, keepAlive = false } = {}) {
+  async create({ cwd, permission = DEFAULT_PERMISSION, onApproval, titleHint, reasoningEffort, provider, model, keepAlive = false, review } = {}) {
     if (!cwd) {
       throw new Error(
         '没有可用的工作目录。你既没传 cwd，客户端也没有提供当前打开的项目（MCP roots）。\n' +
@@ -1898,6 +2415,12 @@ export class Hub {
     if (!PERMISSION_TIERS.includes(permission)) {
       throw new Error(`permission 必须是 ${PERMISSION_TIERS.join(' | ')} 之一`);
     }
+    // title_hint 会写进注册表与侧车，每一轮 save() 都会重复落盘；不设上限就是一个
+    // 稳定的磁盘/内存放大点（调用方可以传任意长度）。可读标签 200 字足够。
+    if (titleHint !== undefined && titleHint !== null) {
+      if (typeof titleHint !== 'string') throw new Error('title_hint 必须是字符串');
+      if (titleHint.length > 200) throw new Error('title_hint 最长 200 字符');
+    }
     // ★ 0.5.0：danger-full-access 不再默认可用。它把整机写权限交给调用方，
     //   而本服务可能被任何 MCP 客户端拉起；必须由机器所有者显式放行。
     if (permission === 'danger-full-access' && !ALLOW_FULL_ACCESS) {
@@ -1922,6 +2445,10 @@ export class Hub {
     if (!REASONING_EFFORTS.includes(effort)) {
       throw new Error(`reasoning_effort 必须是 ${REASONING_EFFORTS.join(' | ')} 之一`);
     }
+    const reviewMode = normalizeReviewMode(review ?? DEFAULT_REVIEW);
+    if (!REVIEW_MODES.includes(reviewMode)) {
+      throw new Error(`review 必须是 ${REVIEW_MODES.join(' | ')} 之一`);
+    }
     if (model && !provider) {
       throw new Error('指定 model 时必须同时给 provider（ACP 的模型标识是 [provider, model] 二元组）');
     }
@@ -1957,6 +2484,7 @@ export class Hub {
           reasoningEffort: effort,
           provider: provider ?? null,
           model: model ?? null,
+          review: reviewMode,
         },
         this,
       );