@dsh-fly/dsh-plugin-fly-mode 0.1.8 → 0.1.9

package/README.md

@@ -11,8 +11,8 @@
   - **Fly 标准模式** `preset-fly-standard`（行表 = **上游 `standard` 的行表** + 一行 smart，33 行）——
     由生成器从**引擎自己的组合结果**里取上游行表（不手抄），所以引擎升级后行表跟着走、漂了 `--check` 会红。
   其中
-  **7 个 Fly 工具**（binary / reverse / pwn / diag / recon / blackbox / guard）的源码**内联在包内
-  `tools/`**，行表用**本包子路径**引用它们 —— 装这个包**不会**在 npm 上再拉这 7 个包；
+  **8 个 Fly 工具**（binary / reverse / pwn / diag / recon / blackbox / artifact / guard）的源码**内联在包内
+  `tools/`**，行表用**本包子路径**引用它们 —— 装这个包**不会**在 npm 上再拉这 8 个包；
   **`fly-smart` 单独一个 plugin**：它是本包 `dependencies` 里**唯一**一项，行表保持裸名，
   由 npm 装进 profile 的 `node_modules`（它变化最快，且与工作台面板是一个整体，不适合内联）。
 - **不是**：不带 `dsh.client`（模式是 agent 平面，没有浏览器半边）；不带 Fly 工作台
@@ -76,7 +76,7 @@ dsh plugin --profile=web add @dsh-fly/dsh-plugin-fly-mode@0.1.3 --registry=https
 
 ## 仓库状态（2026-10-11）
 
-- 形状定稿：一条 `- insert:` 声明 + 包内 `tools/`（7 个工具内联，行表用本包子路径引用）+
+- 形状定稿：一条 `- insert:` 声明 + 包内 `tools/`（8 个工具内联，行表用本包子路径引用）+
   `dsh-plugin-fly-smart` 作为**唯一** npm 依赖。声明由 `dsh-fly` 仓的
   `scripts/build-fly-mode-bundle.mjs` 生成，门禁用 `--check` 断漂移（含多出来的文件）。
 - `.github/workflows/{ci,release}.yml` **已适配本仓**（纯声明包：不装依赖、直接跑

package/cordis.patch.yml

@@ -5,7 +5,6 @@
 # 是同一条）；8 个工具的行名被改写成**本包的子路径**（tools/**，随包一起发布）。
 # 门禁用 --check 断言本文件与 tools/** 都 == 生成器输出。
 # 不含三模型路由（用户机器状态）、不写 registry default（默认归上游 standard）。
-- insert:
 - insert:
     - id: preset-fly
       name: '@deepseek-ai/dsh-agent-preset'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-fly/dsh-plugin-fly-mode",
-  "version": "0.1.8",
-  "description": "Fly 模式作为一个可安装的包：**两个 preset** —— Fly 安全模式（preset-fly，7 个安全工具内联 + smart）与 Fly 标准模式（preset-fly-standard，上游 standard 的行表 + smart，无安全工具）；依赖单独发布的 dsh-plugin-fly-smart。",
+  "version": "0.1.9",
+  "description": "Fly 模式作为一个可安装的包：**两个 preset** —— Fly 安全模式（preset-fly，8 个安全工具内联 + smart）与 Fly 标准模式（preset-fly-standard，上游 standard 的行表 + smart，无安全工具）；依赖单独发布的 dsh-plugin-fly-smart。",
   "type": "module",
   "license": "MIT",
   "repository": {

package/tools/dsh-plugin-fly-artifact/index.js

@@ -39,6 +39,12 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
  *
  * 两个入口都在 P1 的"结论要能回指源码位置"那条要求下：清单的每条成员给**相对路径**，
  * 边界的每条命中给 **file:line**。
+ *
+ * **起因**（为什么这个包存在）：`morluto/rea` 那边有 APK/JADX、固件/Binwalk、.NET、**JS/ASAR 与 HAR**
+ * 这些"看得懂打包产物"的能力，而 fly 这边此前只有原生二进制三件套 —— 一个 Electron 应用的
+ * 150MB `app.asar` 摆在面前，只能靠 `bin_strings` 碰运气。安全模式的定位是客户端黑盒排查，
+ * 所以这一面必须在拆仓之前补上（规划 §3.2）：先把"清单 + 字面量边界"两层做出来，
+ * 再谈 AST 与 CDP（P2）。**不抄代码，只在设计上对齐**（分层、覆盖率、bounds 三件）。
  */
 
 export const name = 'fly-artifact'
@@ -59,6 +65,19 @@ function shq(value) {
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回。加 `./` 之后它就是一个普通相对路径：
+ * 不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -632,7 +651,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('artifact_asar_inventory 需要 path（.asar 的路径）')
       const top = readTop(args.top, 'artifact_asar_inventory')
 
@@ -770,7 +789,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('artifact_js_boundaries 需要 path（.asar 的路径，或解包后的 JS 目录）')
       const top = readTop(args.top, 'artifact_js_boundaries')
       const scope = args.scope === undefined ? 'app' : args.scope

package/tools/dsh-plugin-fly-binary/index.js

@@ -5,6 +5,14 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
  * Registers model-facing analysis tools on ctx.tools. All command execution
  * goes through the host `shell` capability seam so the sandbox confines it;
  * a tool never shells out via node:child_process directly.
+ *
+ * **失败面的口径是"大声"**（Q5）：缺 `readelf`/`objdump`/`strings`/`file`/`wc` 时**不静默降级** ——
+ *   · 能在仓库内补的就补：没有 GNU readelf 就用**仓库内置的原生解析器**算头部/段/动态（并在
+ *     结果的 `limitations` 里明说"这是内置解析器算的，不是 readelf 的输出"）；
+ *   · 补不了的就**抛**：`requireOk` 让缺命令以 `CommandError` 报出来（历史教训：`pwn_checksec`
+ *     曾在缺工具时静默回退，对**任何**二进制都报 `pie=no`）；
+ *   · "没有"要**说成没有**：`bin_strings` 一条都没匹配时返回"no printable strings matching …"，
+ *     绝不返回空串（空串会被读成"这个文件没有字符串"）；节表读不到时同理。
  */
 export const name = 'fly-binary'
 export const inject = ['tools', 'shell']
@@ -24,6 +32,19 @@ function shq(value) {
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回（`bin_sections { path: '--version' }`
+ * 真发生过）。加 `./` 之后它就是一个普通相对路径：不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -54,9 +75,19 @@ async function runCmd(shell, argv, exec, opts = {}) {
  */
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -432,10 +463,23 @@ export function apply(ctx) {
       render: (_args, value) => [{ type: 'text', text: value }],
     },
     async execute(args, exec) {
-      const wc = await runCmd(shell, ['wc', '-c', args.path], exec)
+      const path = safePath(args.path)
+      const wc = await runCmd(shell, ['wc', '-c', path], exec)
       const size = requireOk(wc, 'wc -c').trim().split(/\s+/)[0] ?? '0'
-      const identify = await runCmd(shell, ['file', '-b', args.path], exec)
-      return `size=${size}\n${requireOk(identify, 'file -b').trim()}`
+      const identify = await runCmd(shell, ['file', '-b', path], exec)
+      // 证据形状（规划 §5.1）：信封 JSON，原文本原样进 observed.dump。
+      const text = `size=${size}\n${requireOk(identify, 'file -b').trim()}`
+      return JSON.stringify({
+        tool: 'bin_file',
+        target: args.path,
+        operation: 'one wc -c + one file -b (no parsing of the file content)',
+        observed: { bytes: Number(size), dump: text },
+        confidence: 'observed',
+        limitations: [
+          '只报 wc -c 的字节数与 file(1) 的判断：**不解析文件内部**（要字段另用 bin_readelf / bin_sections）',
+          'file(1) 的判断来自魔数与片段匹配：损坏或被裁剪的文件也可能被认成某种格式',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -453,18 +497,39 @@ export function apply(ctx) {
     },
     async execute(args, exec) {
       const min = String(args.min ?? 4)
-      const run = await runCmd(shell, ['strings', '-n', min, args.path], exec, { stdoutMaxBytes: 1048576 })
+      const path = safePath(args.path)
+      const run = await runCmd(shell, ['strings', '-n', min, path], exec, { stdoutMaxBytes: 1048576 })
       let lines = requireOk(run, `strings -n ${min}`).split('\n').filter(Boolean)
       if (args.grep) {
         const g = args.grep.toLowerCase()
         lines = lines.filter((l) => l.toLowerCase().includes(g))
       }
       if (lines.length === 0) {
-        return args.grep === undefined
-          ? `no printable strings of length ${min} or more in ${args.path}`
-          : `no printable strings matching ${JSON.stringify(args.grep)} (min length ${min}) in ${args.path}`
+        return JSON.stringify({
+          tool: 'bin_strings',
+          target: args.path,
+          operation: `strings -n ${min}` + (args.grep === undefined ? '' : ` filtered by ${JSON.stringify(args.grep)}`),
+          observed: { matched: 0, min: Number(min), grep: args.grep ?? null, dump: args.grep === undefined
+            ? `no printable strings of length ${min} or more in ${args.path}`
+            : `no printable strings matching ${JSON.stringify(args.grep)} (min length ${min}) in ${args.path}` },
+          confidence: 'observed',
+          limitations: [
+            '一条都没匹配上 ⇒ 这是「没有这样的字符串」，不是「这个文件里没有字符串」',
+            'strings(1) 只看可打印字节序列：加密/压缩/UTF-16 里的字符串它看不到',
+          ],
+        }, null, 2)
       }
-      return lines.slice(0, 400).join('\n')
+      return JSON.stringify({
+        tool: 'bin_strings',
+        target: args.path,
+        operation: `strings -n ${min}` + (args.grep === undefined ? '' : ` filtered by ${JSON.stringify(args.grep)}`),
+        observed: { matched: lines.length, shown: Math.min(lines.length, 400), min: Number(min), grep: args.grep ?? null, dump: lines.slice(0, 400).join('\n') },
+        confidence: 'observed',
+        limitations: [
+          lines.length > 400 ? '只给前 400 条（observed.matched 是匹配总数）：要更多就加 grep 缩小范围' : '这次没有截断（匹配数 ≤ 400）',
+          'strings(1) 只看可打印字节序列：加密/压缩/UTF-16 里的字符串它看不到',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -480,26 +545,48 @@ export function apply(ctx) {
       render: (_args, value) => [{ type: 'text', text: value }],
     },
     async execute(args, exec) {
+      // 证据形状（规划 §5.1）：四个分支都产出同一个信封；两条方法（GNU readelf / 仓库内置解析器）
+      // 必须写进 limitations，否则"本机没有 readelf"会被读成"这份 ELF 就是这样"。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'bin_readelf',
+        target: args.path,
+        operation: `read ELF ${mode} (${flag}) and report it verbatim or via the built-in reader)`,
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
       const mode = args.mode === 'segments' || args.mode === 'dynamic' ? args.mode : 'headers'
       const flag = mode === 'segments' ? '-l' : mode === 'dynamic' ? '-d' : '-h'
       // GNU binutils is not part of macOS. When readelf is absent (or refuses the
       // file) the ELF is parsed here instead: the previous revision threw
       // "command not found" on every Mac, which made four of the five binary
       // tools useless on the platform this app ships for.
-      const real = await runCmd(shell, ['readelf', flag, args.path], exec)
-      if (real.exitCode === 0 && real.stdout.trim() !== '') return real.stdout
-      const elf = await elfProbe(rawRun(shell, exec), args.path)
+      const path = safePath(args.path)
+      const real = await runCmd(shell, ['readelf', flag, path], exec)
+      if (real.exitCode === 0 && real.stdout.trim() !== '') {
+        return envelope({ method: 'readelf', dump: real.stdout }, [
+          'GNU readelf 的输出原样返回，本工具不改写它',
+        ])
+      }
+      const elf = await elfProbe(rawRun(shell, exec), path)
       if (elf === null) {
-        const kind = requireOk(await runCmd(shell, ['file', '-b', args.path], exec), 'file -b').trim()
-        return [
+        const kind = requireOk(await runCmd(shell, ['file', '-b', path], exec), 'file -b').trim()
+        return envelope({ method: null, dump: [
           `readelf ${flag} is unavailable on this host (${real.exitCode === 127 ? 'not installed' : `exit ${real.exitCode}`})`,
           `${args.path} is not ELF, so a native ELF reader has nothing to report either — file(1) says: ${kind}`,
           'for Mach-O use rev_disasm / rev_imports (objdump, otool and nm ship with macOS)',
-        ].join('\n')
+        ].join('\n') }, [
+          '本机没有可用的 readelf，而这个文件也不是 ELF ⇒ 两条路都给不出读数（observed.dump 里是原因）',
+        ])
       }
-      if (mode === 'segments') return renderElfSegments(elf)
-      if (mode === 'dynamic') return await renderElfDynamic(elf)
-      return renderElfHeader(elf)
+      // 本机没有 GNU readelf ⇒ 下面三支都是**仓库内置解析器**算的，limitations 要说清。
+      const native = [
+        '本机没有 GNU readelf（macOS 不带 binutils）⇒ 这份读数是仓库内置原生解析器算的，不是 readelf 的输出',
+        '内置解析器只覆盖本工具声明的字段；readelf 的其它开关（--notes/--relocs 等）它不做',
+      ]
+      if (mode === 'segments') return envelope({ method: 'native', dump: renderElfSegments(elf) }, native)
+      if (mode === 'dynamic') return envelope({ method: 'native', dump: await renderElfDynamic(elf) }, native)
+      return envelope({ method: 'native', dump: renderElfHeader(elf) }, native)
     },
   }))
 
@@ -517,11 +604,12 @@ export function apply(ctx) {
       // 证据形状（规划 §5.1 的第一个试点）：返回值是**信封 JSON**，不再是裸表格文本。
       // 真值判据不变（observed.dump 里是 objdump 原文），新增 confidence 与 limitations ——
       // 逼这个工具回答"这个结论看不见什么"（本仓最贵的那条教训）。
-      const run = await runCmd(shell, ['objdump', '-h', args.path], exec)
+      const path = safePath(args.path)
+      const run = await runCmd(shell, ['objdump', '-h', path], exec)
       const ok = run.exitCode === 0 && run.stdout.trim() !== ''
       // GNU binutils is not part of macOS. Instead of an opaque "command not found",
       // say which method failed and what to use instead (same shape as bin_readelf).
-      const kind = ok ? null : await runCmd(shell, ['file', '-b', args.path], exec)
+      const kind = ok ? null : await runCmd(shell, ['file', '-b', path], exec)
       return JSON.stringify({
         tool: 'bin_sections',
         target: args.path,

package/tools/dsh-plugin-fly-blackbox/index.js

@@ -306,6 +306,19 @@ function assertNotPrivileged(command) {
  * 这一点（本仓既有五个插件的 `runCmd` 正是这个写法；门禁桩现在按真接缝的形状发布
  * `result()`，所以这类"桩和真接缝不同形"的假绿会在这一层被抓住）。
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回。加 `./` 之后它就是一个普通相对路径：
+ * 不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const command = typeof argv === 'string' ? argv : argv.map(shq).join(' ')
   assertNotPrivileged(command)
@@ -968,11 +981,17 @@ export function readHarDocument(buffer, path) {
   try {
     parsed = JSON.parse(payload.toString('utf8').replace(/^\uFEFF/u, ''))
   } catch (error) {
-    throw new Error(`${path} 不是合法 JSON${gzip ? '（已按 gzip magic 解压）' : ''}：${error.message}`)
+    // Q6（2026-10-13）：失败文案要对读它的模型可行动 —— what + why + **what to try next**，
+    // 且不臆断具体原因（写错的「为什么」比没有更糟）。
+    throw new Error(`${path} 不是合法 JSON${gzip ? '（已按 gzip magic 解压）' : ''}：${error.message}`
+      + ' —— 修法：确认这是 HAR 导出（浏览器 DevTools 的 Save all as HAR，或 mitmproxy 的硬拷贝转 HAR）；' 
+      + '只做普通 JSON 校验的话，先看它是不是别的格式。')
   }
   const entries = parsed?.log?.entries
   if (!Array.isArray(entries)) {
-    throw new Error(`${path} 不像 HAR：log.entries 不是数组（HAR 1.2 的条目都在 log.entries 下）。`)
+    throw new Error(`${path} 不像 HAR：log.entries 不是数组（HAR 1.2 的条目都在 log.entries 下）。`
+      + ' —— 修法：重新导出一份 HAR，或确认导出的是 HAR 而不是本仓自己的 mitmproxy dump' 
+      + '（`.mitm` 那种用 bx_flows 读）。')
   }
   const creator = parsed.log.creator
   return {
@@ -1696,7 +1715,7 @@ export function apply(ctx) {
       const root = workspaceRoot(exec)
       const state = readState(root)
       const action = String(args.action ?? '')
-      const dump = args.path ?? state?.dump ?? join(root, '.fly-blackbox', 'flows.mitm')
+      const dump = safePath(args.path ?? state?.dump ?? join(root, '.fly-blackbox', 'flows.mitm'))
 
       const size = await statSizeVia(shell, exec, dump, 'dump')
       if (size > 32 * 1024 * 1024) {
@@ -1773,7 +1792,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('bx_har 需要 path（.har 或 .har.gz 的路径）')
       const groupBy = args.groupBy ?? 'host'
       if (!HAR_GROUPINGS.includes(groupBy)) {

package/tools/dsh-plugin-fly-diag/index.js

@@ -30,7 +30,26 @@ function shq(value) {
  * `TypeError: shell.run is not a function` on every call, in every engine
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
+ *
+ * **失败面的口径是"大声"**（Q5）：这一包全是**活读数**，"没量到"绝不能读成"没有" ——
+ *   · 缺 `ps` / `lsof` / `netstat` / `ping` 时各自走已登记的路径：能换方法的换（`lsof` 不通换
+ *     `netstat`，并在结果里说清"netstat 的表更粗、没有进程名/PID"），换不了就 `requireOk` 抛错；
+ *   · "成功却没输出"是一等状态：`diag_procs` 会明说"ps 成功却没有任何输出 ⇒ 这张表是被读空的"；
+ *   · `diag_net_watch` 读到**半个样本**就跳过并**报出跳过数**（静默丢数据比丢数据更糟），
+ *     停止是**异步**的（写完信号文件就返回），这些都在各支的 `limitations` 里。
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-14）。
+ *
+ * 与六个安全包里的同名助手同源（§5.4.1/§5.4.3）：不插 `--`（本机 objdump/base64/otool 不支持），
+ * 而是把它变成一个普通相对路径。这里用于 `diag_net_watch` 的 `dir` —— 同一族的**无伤**版本
+ * （裸 `-o/tmp/x` 进 `mkdir` 只会响亮报错），本笔是**一致性收尾**，不是安全修复。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -60,9 +79,19 @@ async function runCmd(shell, argv, exec, opts = {}) {
  */
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -382,8 +411,7 @@ export function apply(ctx) {
     async execute(_args, exec) {
       exec.signal.throwIfAborted()
       const mem = os.totalmem()
-      return JSON.stringify(
-        {
+      const hostSnapshot = {
           hostname: os.hostname(),
           platform: os.platform(),
           release: os.release(),
@@ -394,10 +422,18 @@ export function apply(ctx) {
           freeMemGB: +(os.freemem() / 1024 ** 3).toFixed(2),
           loadavg: os.loadavg().map((n) => +n.toFixed(2)),
           uptimeHours: +(os.uptime() / 3600).toFixed(2),
-        },
-        null,
-        2,
-      )
+      }
+      return JSON.stringify({
+        tool: 'diag_host',
+        target: 'this host',
+        operation: 'read local host identity, CPU and memory counters (read-only, no probing)',
+        observed: hostSnapshot,
+        confidence: 'observed',
+        limitations: [
+          '只看得到本机：没有对端/邻居的信息（对端要用 recon_* 或 diag_net_rtt 单独量）',
+          '负载与内存是瞬时读数：不说明趋势，也不说明是不是刚刚才变（趋势要用 diag_net_watch 那类记录仪）',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -412,11 +448,24 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
+      // 证据形状（规划 §5.1）：两支都产出信封。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'diag_procs',
+        target: 'this host',
+        operation: 'take one ps aux snapshot and return the top rows by %CPU',
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
       const limit = Math.max(1, Math.min(50, Number(args.limit) || 15))
       const stdout = requireOk(await runCmd(shell, ['ps', 'aux'], exec, { stdoutMaxBytes: 1048576 }), 'ps aux')
       const lines = stdout.split('\n').filter(Boolean)
       const [header, ...rest] = lines
-      if (header === undefined) return 'ps aux produced no output (the command succeeded, which is suspicious)'
+      if (header === undefined) {
+        return envelope({ method: 'ps', rows: 0, dump: 'ps aux produced no output (the command succeeded, which is suspicious)' }, [
+          'ps 成功却没有任何输出 ⇒ 这张表是被读空的：**不能**读成「本机没有进程」',
+        ])
+      }
       const body = rest
         .sort((a, b) => {
           const pa = parseFloat(a.split(/\s+/)[2] || '0')
@@ -424,7 +473,10 @@ export function apply(ctx) {
           return pb - pa
         })
         .slice(0, limit)
-      return [header, ...body].join('\n')
+      return envelope({ method: 'ps', limit, rows: body.length, dump: [header, ...body].join('\n') }, [
+        'ps aux 的表格原样返回，本工具只做两件事：按第 3 列（%CPU）降序、取前 limit 行',
+        '这是**一次快照**：不说明进程的历史、持续时间或趋势（要趋势得自己隔一段时间再取一次）',
+      ])
     },
   }))
 
@@ -437,12 +489,33 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(_args, exec) {
+      // 证据形状（规划 §5.1）：三支都产出信封。两条方法（lsof / netstat）与"什么都没读到"都要说清。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'diag_net',
+        target: 'this host',
+        operation: 'snapshot TCP listening sockets (read-only, no probing)',
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
       const lsof = await runCmd(shell, ['lsof', '-nP', '-iTCP', '-sTCP:LISTEN'], exec)
-      if (lsof.exitCode === 0) return lsof.stdout.slice(0, 8000)
+      if (lsof.exitCode === 0) {
+        return envelope({ method: 'lsof', dump: lsof.stdout.slice(0, 8000), truncated: lsof.stdout.length > 8000 }, [
+          'lsof 的输出原样返回（截断到 8000 字符；truncated=true 表示后面还有没给出来的内容）',
+          '这是**一次快照**：不说明套接字的历史，也不说明谁在连它',
+        ])
+      }
       const listeners = requireOk(await runCmd(shell, ['netstat', '-an'], exec), 'netstat -an')
         .split('\n').filter((l) => l.includes('LISTEN')).slice(0, 80)
-      if (listeners.length > 0) return listeners.join('\n')
-      return 'no listening TCP sockets (lsof failed and netstat reported no LISTEN lines)'
+      if (listeners.length > 0) {
+        return envelope({ method: 'netstat', dump: listeners.join('\n'), truncated: true }, [
+          'lsof 没跑通，这份读数是 netstat -an 里含 LISTEN 的行（只取前 80 行）',
+          'netstat 的表格比 lsof 粗：没有进程名/PID，只说「有东西在这个地址上听」',
+        ])
+      }
+      return envelope({ method: null, dump: '' }, [
+        'lsof 与 netstat 都没有给出 LISTEN 行 —— 这句话的前提是**两条命令都真的跑过了**；否则「没量到」会被读成「没有」',
+      ])
     },
   }))
 
@@ -538,7 +611,7 @@ export function apply(ctx) {
           : delta > 30
             ? `外网比网关多 ${delta.toFixed(1)}ms：这段差值来自光猫/路由器的排队与路径，跟 Wi-Fi 空口无关。`
             : `外网与网关只差 ${delta.toFixed(1)}ms，路径干净。此时若仍感到卡，更可能在空口 —— 用 diag_wifi_link 看协商速率与抖动。`
-      return JSON.stringify({
+      const snapshot = {
         gateway: { target: gateway, ...gw, line: pingLine(`网关 ${gateway}`, gw) },
         wan: { target: wanTarget, ...wan, line: pingLine(`外网 ${wanTarget}`, wan) },
         deltaMs: delta,
@@ -546,6 +619,20 @@ export function apply(ctx) {
         jitterNote: gw.stddevMs !== null && gw.stddevMs > 2
           ? `网关抖动 ${gw.stddevMs}ms 偏大：空口在被抢，看 diag_wifi_channels 里有没有同频邻居。`
           : null,
+      }
+      // 证据形状（规划 §5.1）：信封 JSON —— 一次 RTT 采样（网关 + 外网）。
+      // limitations 必须说清"这几个数字各自是什么、以及它们看不见什么"。
+      return JSON.stringify({
+        tool: 'diag_net_rtt',
+        target: gateway + ' (gateway) + ' + wanTarget + ' (wan)',
+        operation: 'send ICMP echoes to both targets and report min/avg/max, loss and jitter',
+        observed: snapshot,
+        confidence: 'observed',
+        limitations: [
+          '回环 / 网关 / 外网是三个不同的东西：别把回环的 0.1ms 当成\u201c网好\u201d',
+          'ICMP 会被中间设备限速或直接丢弃 ⇒ 丢包不等于链路断（要用 TCP 层再证一次）',
+          '一次采样的 min/avg/max 不说明抖动趋势 —— 要趋势得用 diag_net_watch 那类记录仪',
+        ],
       }, null, 2)
     },
   }))
@@ -587,7 +674,7 @@ export function apply(ctx) {
       }
       const aggregateBps = measured.reduce((sum, sample) => sum + sample.bps, 0)
       const totalBytes = samples.reduce((sum, sample) => sum + sample.bytes, 0)
-      return JSON.stringify({
+      const snapshot = {
         url,
         streams,
         seconds,
@@ -597,6 +684,20 @@ export function apply(ctx) {
         totalBytes,
         totalMiB: Number((totalBytes / 1048576).toFixed(1)),
         note: '默认按「跑满」配置（8 流 × 10 秒）；totalBytes 是本次实际消耗的流量。测出来的是「无线链路 + 外网」合起来的上限，不是链路理论值。',
+      }
+      // 证据形状（规划 §5.1）：信封 JSON。这个工具是七个里**唯一会产生真实流量**的，
+      // 所以 limitations 要讲清"这次花了你多少流量"与"速率读数看不见什么"。
+      return JSON.stringify({
+        tool: 'diag_net_throughput',
+        target: url,
+        operation: 'run ' + streams + ' parallel curl streams for up to ' + seconds + 's each and report throughput',
+        observed: snapshot,
+        confidence: 'observed',
+        limitations: [
+          '这是一次**真实流量**测量：observed.totalBytes 就是本次消耗的字节数（默认档位是 8 流 × 10 秒）',
+          '读的是链路**容量**：不说明时延、丢包或抖动 —— 那些用 diag_net_rtt / diag_net_watch 量',
+          '聚合速率受对端与服务端共同限制：它只证明"这条路径此刻能跑到多少"，不区分是谁的限制',
+        ],
       }, null, 2)
     },
   }))
@@ -616,11 +717,21 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
     async execute(args, exec) {
-      const paths = watchPaths(args.dir)
+      // undefined 必须保持 undefined（否则默认目录就没了）：只规范化"给了且以 - 开头"的那种。
+      const paths = watchPaths(args.dir === undefined ? undefined : safePath(args.dir))
       const action = String(args.action ?? 'status').trim() === '' ? 'status' : String(args.action).trim()
       const gateway = requireHost(args.gateway, '192.168.1.1')
       const wan = requireHost(args.wan, '223.5.5.5')
       const count = clampInteger(args.count, 8, 4, 30)
+      // 证据形状（规划 §5.1）：逐支迁移 —— 本轮只把 status 支包上（没有消费方读它的裸文本）。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'diag_net_watch',
+        target: paths.dir,
+        operation: 'long-running link/RTT recorder: ' + action,
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
 
       if (action === 'start') {
         const interval = clampInteger(args.interval, 10, 3, 600)
@@ -635,7 +746,7 @@ export function apply(ctx) {
           timeoutMs: 7 * 24 * 3600 * 1000,
           signal: exec.signal,
         }))
-        return [
+        return envelope({ method: 'start', log: paths.log, interval, linkEvery, count, gateway, wan, dump: [
           `记录仪已启动`,
           `日志：${paths.log}`,
           `间隔 ${interval}s；每 ${linkEvery} 次采样取一次链路；每次每目标 ${count} 个包`,
@@ -644,7 +755,10 @@ export function apply(ctx) {
           `卡住时立刻打标记：diag_net_watch action=mark message="电视卡了"`,
           `停止：diag_net_watch action=stop`,
           `回看：diag_net_watch action=report`,
-        ].join('\n')
+        ].join('\n') }, [
+          '这是**后台**记录仪：本工具返回的时候采样循环才刚开始 ⇒ 日志会一直长，随时用 action=report 回看', 
+          'observed 里带着它的节奏（间隔 / 每 N 次取链路 / 每目标包数）—— 以后看报告时能对上它是按什么节奏记的', 
+        ])
       }
 
       if (action === 'stop') {
@@ -655,7 +769,10 @@ export function apply(ctx) {
           { timeoutMs: 20000 },
         )
         requireOk(run, '写停止文件')
-        return `停止信号已写入 ${paths.stop}\n采样循环会在当前这一轮 sleep 结束后退出，最多等一个采样间隔。用 action=status 确认。`
+        return envelope({ method: 'stop', stopFile: paths.stop, dump: `停止信号已写入 ${paths.stop}\n采样循环会在当前这一轮 sleep 结束后退出，最多等一个采样间隔。用 action=status 确认。` }, [
+          '这是**异步**停止：写完信号文件就返回了，采样循环要等当前这一轮 sleep 结束才退出',
+          '要确认它真的停了，用 action=status 看最后写入时间，或再 action=report 比样本数',
+        ])
       }
 
       if (action === 'sample') {
@@ -666,7 +783,10 @@ export function apply(ctx) {
           { timeoutMs: 30000 },
         )
         requireOk(run, '采样')
-        return `已采样并追加到 ${paths.log}\n用 action=report 看，或 action=mark 标一下刚才发生了什么。`
+        return envelope({ method: 'sample', log: paths.log, dump: `已采样并追加到 ${paths.log}\n用 action=report 看，或 action=mark 标一下刚才发生了什么。` }, [
+          '这一次采样写进了日志；它的**内容**要看 action=report（这里只报"写成功了"）',
+          '样本是往日志尾部**追加**的：这个动作不会覆盖历史，也不会改变记录仪是否在跑',
+        ])
       }
 
       if (action === 'mark') {
@@ -683,7 +803,10 @@ export function apply(ctx) {
           { timeoutMs: 20000 },
         )
         requireOk(run, '写标记')
-        return `已标记「${message}」@ ${stampOf(Math.floor(Date.now() / 1000))}\n日志：${paths.log}`
+        return envelope({ method: 'mark', log: paths.log, dump: `已标记「${message}」@ ${stampOf(Math.floor(Date.now() / 1000))}\n日志：${paths.log}` }, [
+          '标记是你打的**锚点**，它本身不是测量 —— report 会把它对齐到最近的样本（误差 ≤ 一个采样间隔）',
+          '标记只往日志里追加一行，不改变采样节奏，也不影响记录仪是否在跑',
+        ])
       }
 
       if (action === 'report') {
@@ -695,13 +818,27 @@ export function apply(ctx) {
           { timeoutMs: 30000, stdoutMaxBytes: 8388608 },
         )
         if (run.stdout.trim() === '') {
-          return `还没有样本（${paths.log} 不存在或为空）。先 action=start 起记录仪，或 action=sample 取一个。`
+          return envelope({ method: 'report', samples: 0, dump: '', log: paths.log }, [
+            '日志不存在或为空 ⇒ 这是「还没有样本」，不是「网络没问题」',
+            `先 action=start 起记录仪，或 action=sample 取一个（看的是 ${paths.log}）`,
+          ])
         }
         const { rows, marks, skipped } = readWatch(run.stdout)
         if (rows.length === 0) {
-          return skipped > 0
-            ? `日志里有 ${skipped} 个样本还没写完（记录仪正在写），暂时没有完整的样本可看。稍后再试。`
-            : `日志里没解析出完整样本（${paths.log}）：文件可能刚被截断。`
+          return envelope({
+            method: 'report',
+            samples: 0,
+            skipped,
+            log: paths.log,
+            dump: skipped > 0
+              ? `日志里有 ${skipped} 个样本还没写完（记录仪正在写），暂时没有完整的样本可看。稍后再试。`
+              : `日志里没解析出完整样本（${paths.log}）：文件可能刚被截断。`,
+          }, [
+            '一个完整样本都没有 ⇒ 这份报告里**没有任何测量**，不是「这一段时间网络正常」',
+            skipped > 0
+              ? '只有半截样本 —— 读到一半的记录会得出凭空的故障结论，所以它不算证据'
+              : '文件可能刚被截断，也可能记录仪根本没在跑 —— 这两种要分开查',
+          ])
         }
         const first = rows[0]
         const last = rows[rows.length - 1]
@@ -756,7 +893,13 @@ export function apply(ctx) {
             + ` 外网 ${nearest.wan.avgMs ?? '无回应'}ms（抖动 ${nearest.wan.stddevMs ?? '—'}ms）`
             + ` 链路 ${nearest.link.channel ?? '—'}/${nearest.link.widthMhz ?? '—'}MHz 协商 ${nearest.link.transmitRateMbps ?? '—'}Mbps`)
         }
-        return lines.join('\n')
+        // 报告文本原样进 observed.dump（消费方都是子串正则，不需要改读法）。
+        return envelope({ method: 'report', samples: rows.length, skipped, dump: lines.join('\n') }, [
+          '报告覆盖的是**日志里记着的那段时间** —— 记录仪没起着的时段，它什么都不知道',
+          skipped > 0
+            ? '有未写完的样本被跳过（数量见 observed.skipped）：那些时刻只有半个样本，不能当证据'
+            : '这次没有跳过未写完的样本；但"没跳过"只说明这次读的时候没有半截样本',
+        ])
       }
 
       // status（默认）：永远给出可读结论，绝不返回空字符串。
@@ -784,7 +927,13 @@ export function apply(ctx) {
         '  echo "还没有日志文件"',
         'fi',
       ].join('\n')], exec, { timeoutMs: 20000, stdoutMaxBytes: 262144 })
-      return run.stdout.trim() === '' ? '记录仪状态未知：状态命令没有输出。' : run.stdout.trim()
+      const statusText = run.stdout.trim()
+      // 「未知」与「没在跑」是两件事：状态命令没输出时不许说成没在跑。
+      return envelope({ method: 'status', dump: statusText, known: statusText !== '' }, [
+        statusText === ''
+          ? '状态命令没有输出 ⇒ 这是「未知」，不是「没在跑」'
+          : '这是记录仪自己报的状态，不是从日志推断的；它只说这一刻，不说明采样准不准',
+      ])
     },
   }))
 

package/tools/dsh-plugin-fly-pwn/index.js

@@ -18,7 +18,28 @@ function shq(value) {
  * `TypeError: shell.run is not a function` on every call, in every engine
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
+ *
+ * **失败面的口径是"大声"**（Q5）：
+ *   · 没有 `checksec`（macOS 就是）⇒ 走**仓库内置的原生解析器**算 PIE/NX/RELRO/canary，并在
+ *     `limitations` 里明说"这是内置解析器算的"；**绝不**再出现"缺工具 ⇒ 静默回退 ⇒ 对所有文件
+ *     都报 pie=no"那种事故（2026-10-01 的原始缺陷正是它）；
+ *   · `pwn_cyclic` 的长度会被夹到 1..4096 —— 夹取是**读数**（`observed.clamped`），不是沉默；
+ *   · `pwn_rop_hint` **不看文件**：它的清单用 `confidence: 'inferred'` 标出来，并在 `limitations`
+ *     里写清"前提必须先由 pwn_checksec / rev_* / bin_* 验过"。
+ */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回。加 `./` 之后它就是一个普通相对路径：
+ * 不存在就正常报错，存在就是那个文件。
  */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -50,9 +71,19 @@ async function runCmd(shell, argv, exec, opts = {}) {
  */
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -534,9 +565,35 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
-      const ck = await runCmd(shell, ['checksec', '--file=' + args.path], exec)
-      if (ck.exitCode === 0) return ck.stdout
-      return (await mitigationLines(shell, args.path, exec)).join('\n')
+      const path = safePath(args.path)
+      const ck = await runCmd(shell, ['checksec', '--file=' + path], exec)
+      if (ck.exitCode === 0) {
+        return JSON.stringify({
+          tool: 'pwn_checksec',
+          target: args.path,
+          operation: 'read mitigations with the installed checksec',
+          observed: { method: 'checksec', dump: ck.stdout },
+          confidence: 'observed',
+          limitations: [
+            'checksec 的输出原样返回（本工具不改写它）',
+            'checksec 的判断基于它自己支持的格式/段：**没提到的项不代表不存在**（要逐条核就用 bin_readelf）',
+          ],
+        }, null, 2)
+      }
+      // 本机没有 checksec（macOS 就是）：这份读数来自仓库内置的原生解析器。
+      const nativeLines = (await mitigationLines(shell, path, exec)).join('\n')
+      return JSON.stringify({
+        tool: 'pwn_checksec',
+        target: args.path,
+        operation: 'compute mitigations from the file itself (no checksec on this host)',
+        observed: { method: 'native', dump: nativeLines },
+        confidence: 'observed',
+        limitations: [
+          '**本机没有 checksec** ⇒ 这份读数是**仓库内置解析器**算的，不是 checksec 的输出',
+          '内置解析器只覆盖本工具声明的字段（arch/pie/nx/relro/canary）；checksec 的其它判断（如 fortify）它不做',
+          '它对 Mach-O 与 ELF 各有一套路子：看 method 与 dump 里的措辞，别把 macho 的 relro=n/a 读成"没开"',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -552,7 +609,19 @@ export function apply(ctx) {
     },
     async execute(args) {
       const n = Math.max(1, Math.min(4096, Number(args.length) || 64))
-      return cyclic(n)
+      // 证据形状（规划 §5.1）：信封 JSON（模式本身进 observed，不塞进 dump 的文本里）。
+      return JSON.stringify({
+        tool: 'pwn_cyclic',
+        target: 'de Bruijn pattern',
+        operation: 'generate a cyclic pattern for offset discovery (pwntools-compatible alphabet)',
+        observed: { length: n, clamped: n !== (Number(args.length) || 64), dump: cyclic(n) },
+        confidence: 'observed',
+        limitations: [
+          '模式只帮你**定位**偏移：它不告诉你偏移在哪，也不说明那条路径可达（配合真实崩溃日志/调试器才有意义）',
+          '长度会被夹到 1..4096：传大了会**静默变短** ⇒ 用 observed.length（或 clamped=true）核对实际给的位数',
+          '字母表与 pwntools 的 cyclic 一致，但**只保证前缀相同**：拿别处的 offset 表来查时，先确认两边是同一套字母表',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -568,7 +637,12 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args) {
-      return [
+      // 证据形状（规划 §5.1）：清单型工具 —— 清单本身就是它给出的东西（进 dump）。
+      return JSON.stringify({
+        tool: 'pwn_rop_hint',
+        target: args.binary,
+        operation: 'produce a ret2libc/ROP planning checklist (does not read the binary at all)',
+        observed: { binary: args.binary, goal: args.goal ?? 'shell', dump: [
         `# ROP plan for ${args.binary}`,
         `goal: ${args.goal ?? 'shell'}`,
         '1. confirm overflow offset via cyclic + crash RIP',
@@ -577,7 +651,15 @@ export function apply(ctx) {
         '4. second payload: pop rdi; ret → binsh → system (align stack with extra ret)',
         '5. prefer local lab targets only; never against unauthorized hosts',
         'note: this tool is a planning checklist only — it does not inspect the binary; pair it with pwn_checksec, rev_imports and rev_gadget_scan',
-      ].join('\n')
+        ].join('\n') },
+        confidence: 'inferred',
+        limitations: [
+          '**这是清单，不是结论**：本工具**根本不看文件** —— 不读 ELF、不找 gadget、不算偏移',
+          '所以它的前提（PIE/NX/canary/RELRO、溢出偏移、libc 版本）必须先由 pwn_checksec / rev_* / bin_* 验过；没验过就不能按它动手',
+          '步骤顺序是**一种**常见打法（ret2libc），不是唯一解：目标有 seccomp、特殊 libc 或栈保护时整条路可能不成立',
+          '只用在与授权范围一致的目标上（本地 lab 优先）',
+        ],
+      }, null, 2)
     },
   }))
 }

package/tools/dsh-plugin-fly-recon/index.js

@@ -12,6 +12,17 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
  * Command execution goes through the host `shell` seam so the sandbox confines
  * it (and the FLY_ALLOW_RECON gate is an ADDITIONAL authorization layer on top
  * of the sandbox, not a replacement for it).
+ *
+ * **失败面的口径是"大声"**（Q5）：
+ *   · 没有 `nmap`（macOS 常态）⇒ 用系统自带的 `nc` 扫，并在结果里标明"这是 nc 扫的"，且**明说
+ *     `no-response` 分不清 closed 与 filtered**（要区分必须换 nmap）；端口数超过内置回退的 64 上限时
+ *     **一个都不扫**并说清上限与出路，绝不扫一半交差；
+ *   · 目标 URL **先校验再用**（`requireHttpUrl`：只允许 http/https）—— 2026-10-13 补：此前这条只有
+ *     `diag_net_throughput` 有，`recon_http_fingerprint` 会放行 `file://`，而 curl 能把本地文件读出来
+ *     回显进工具结果；Q5 那次我在本注释里先写了这条保护，**当时它并不成立**，现在它成立了；
+ *   · `curl` 失败 ⇒ `requireOk` 抛 `CommandError`，不给"空指纹"；
+ *   · `recon_http_fingerprint` 只读响应头与 `<title>`：**不执行 JS** —— 由 JS 搭出来的界面在这把尺子里
+ *     等于不存在（AGENTS.md 里那台摄像头的负结论就是这么来的），这一点写进了它的 `limitations`。
  */
 export const name = 'fly-recon'
 export const inject = ['tools', 'shell']
@@ -58,11 +69,60 @@ async function runCmd(shell, argv, exec, opts = {}) {
  * tools must say so instead of reporting an empty scan, because an empty scan
  * reads as "target closed".
  */
+/**
+ * 只接受主机名或 IP 字面量。2026-10-13 补：此前 `recon_ports` 的 `host` **没有**这道校验，
+ * 而 diag_* 三个工具都有 —— 于是 `-oN=/tmp/x` 这种"以 - 开头的目标"会被 nmap 当成**选项**
+ * （写出文件）。同族性质必须在**每个**工具上都有。
+ */
+function requireHost(value) {
+  const host = String(value ?? '').trim()
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._:-]*[A-Za-z0-9])?$/u.test(host)) {
+    const error = new Error(
+      `拒绝目标 ${JSON.stringify(host)}：只接受主机名或 IP 字面量 ——`
+      + ' 不许有空格或 shell 元字符（; | & $ ` 引号 括号），也不许以 "-" 开头'
+      + '（会被当成命令参数：nmap、nc 会把 `-oN=file` 之类的选项当真）。',
+    )
+    error.name = 'ArgumentError'
+    throw error
+  }
+  return host
+}
+
+/** 只允许 http/https：`file:` 会让 curl 把本地文件读出来回显进工具结果（2026-10-13 发现并补上）。 */
+const ALLOWED_URL_SCHEMES = ['http:', 'https:']
+function requireHttpUrl(value) {
+  const text = String(value ?? '').trim()
+  let parsed
+  try {
+    parsed = new URL(text)
+  } catch {
+    const error = new Error(`不是合法的 URL：${text}`)
+    error.name = 'ArgumentError'
+    throw error
+  }
+  if (!ALLOWED_URL_SCHEMES.includes(parsed.protocol)) {
+    const error = new Error(`拒绝 ${parsed.protocol} 目标：只允许 http/https（file: 会读本地文件）`)
+    error.name = 'ArgumentError'
+    throw error
+  }
+  return parsed.href
+}
+
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -128,38 +188,59 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
+      // 先校验再构造命令（同族性质：diag_* 三个工具早就有这道门）。
+      const host = requireHost(args.host)
+      // 证据形状（规划 §5.1）：逐分支迁移 —— 本轮只把 nc 回退分支包上。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'recon_ports',
+        target: args.host,
+        operation: 'TCP connect scan of the requested ports (authorized lab targets only)',
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
       const requested = args.ports === undefined || String(args.ports).trim() === '' ? '22,80,443,445,3389,8080' : String(args.ports)
       const expanded = expandPorts(requested)
       if (expanded === null) {
-        return `unparsable port spec ${JSON.stringify(requested)} — use a comma list with optional ranges, e.g. 22,80,8000-8010`
+        return envelope({ requested, dump: `unparsable port spec ${JSON.stringify(requested)} — use a comma list with optional ranges, e.g. 22,80,8000-8010` }, ['端口规格不合法 ⇒ 一个端口都没扫：observed.dump 里是解析失败的原因与可照抄的写法'])
+      }
+      const nmap = await runCmd(shell, ['nmap', '-Pn', '--open', '-p', expanded.join(','), host], exec, { timeoutMs: 60_000 })
+      if (nmap.exitCode === 0) {
+        return envelope({ method: 'nmap', dump: nmap.stdout }, [
+          'nmap 的表格原样返回，本工具不改写它；本轮参数只带 -Pn --open（没有版本探测）',
+          'open 只说明 TCP 连得上，不说明服务身份或版本',
+        ])
       }
-      const nmap = await runCmd(shell, ['nmap', '-Pn', '--open', '-p', expanded.join(','), args.host], exec, { timeoutMs: 60_000 })
-      if (nmap.exitCode === 0) return nmap.stdout
       if (!portMissing(nmap)) return requireOk(nmap, 'nmap')
       // `nmap` is not installed by default on macOS. Instead of failing outright
       // (the previous behaviour) or returning an empty scan that reads as "target
       // closed", scan with `nc`, which ships with the base system. The result is
       // labelled: nc cannot tell closed from filtered, and does no fingerprinting.
       if (expanded.length > 64) {
-        return [
+        return envelope({ method: 'nc', scanned: 0, cap: 64, requested: expanded.length, dump: [
           `nmap is not installed on this host: the built-in fallback scans with the system nc and is capped at 64 ports per call, but ${expanded.length} were requested`,
           'narrow the range, or install nmap for a full scan (no 64-port cap, service and version detection)',
-        ].join('\n')
+        ].join('\n') }, [
+          '请求超过内置回退的 64 端口上限 ⇒ **一个端口都没扫**（不是"扫了、没有开着的端口"）',
+        ])
       }
       const script = expanded
-        .map((port) => `if nc -z -G 1 -w 1 ${shq(args.host)} ${port} >/dev/null 2>&1; then echo '${port}/tcp open'; else echo '${port}/tcp no-response'; fi`)
+        .map((port) => `if nc -z -G 1 -w 1 ${shq(host)} ${port} >/dev/null 2>&1; then echo '${port}/tcp open'; else echo '${port}/tcp no-response'; fi`)
         .join('; ')
       const scan = await runCmd(shell, ['/bin/sh', '-c', script], exec, { timeoutMs: 120_000 })
       if (scan.exitCode !== 0 && scan.stdout.trim() === '') return requireOk(scan, 'nc -z')
       const rows = scan.stdout.split('\n').map((l) => l.trim()).filter(Boolean)
-      return [
+      return envelope({ method: 'nc', scanned: expanded.length, dump: [
         'nmap=not installed (scanned with the system nc: one TCP connect per port, no service or version detection)',
-        `host=${args.host}`,
+        `host=${host}`,
         `ports=${expanded.length}`,
         ...rows,
         `open=${rows.filter((l) => l.endsWith('/tcp open')).length}`,
         'note: `no-response` means closed or filtered — nc cannot tell those two apart; install nmap for a real scan',
-      ].join('\n')
+      ].join('\n') }, [
+        'nmap 不在本机：这是系统 nc 的回退结果（每端口一次 TCP connect，无服务/版本探测）',
+        '**nc 分不清 closed 与 filtered**：no-response 两种都可能 —— 要区分必须换 nmap',
+      ])
     },
   }))
 
@@ -174,11 +255,31 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
-      const headers = requireOk(await runCmd(shell, ['curl', '-sI', '-m', '8', args.url], exec), `curl -sI ${args.url}`)
-      const body = await runCmd(shell, ['curl', '-s', '-m', '8', args.url], exec)
-      if (body.exitCode !== 0) return `${headers.trim()}\nTITLE: unknown (body fetch failed, exit ${body.exitCode})`
+      // 证据形状（规划 §5.1）：两支都产出信封。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'recon_http_fingerprint',
+        target: args.url,
+        operation: 'one-shot HTTP fingerprint: response headers + <title> only',
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
+      // 先校验再构造命令：non-http 目标在**命令构造之前**就被拒（不是事后清洗）。
+      const url = requireHttpUrl(args.url)
+      const headers = requireOk(await runCmd(shell, ['curl', '-sI', '-m', '8', url], exec), `curl -sI ${url}`)
+      const body = await runCmd(shell, ['curl', '-s', '-m', '8', url], exec)
+      if (body.exitCode !== 0) {
+        return envelope({ headers: headers.trim(), title: null, bodyFetched: false, dump: `${headers.trim()}\nTITLE: unknown (body fetch failed, exit ${body.exitCode})` }, [
+          'body 取不到 ⇒ 只有响应头；title 是**未知**，不是「这个页面没有标题」',
+          'curl -sI 不跟随重定向：看到的是**跳转前那一跳**的响应头',
+        ])
+      }
       const title = /<title[^>]*>([^<]*)<\/title>/iu.exec(body.stdout)?.[1]?.trim() ?? ''
-      return `${headers.trim()}\nTITLE: ${title === '' ? '(no <title> element in the body)' : title}`
+      return envelope({ headers: headers.trim(), title, bodyFetched: true, dump: `${headers.trim()}\nTITLE: ${title === '' ? '(no <title> element in the body)' : title}` }, [
+        '只读响应头与第一个 <title>：**不执行 JS** —— 由 JS 搭出来的界面（登录框、动态面板、JS 表格）在这把尺子里等于不存在',
+        '要判 JS 渲染出来的东西，得用真浏览器（仓库有 playwright-core），并断「页面实际请求了什么、状态码是什么」',
+        '标题取的是第一个 <title>；SPA 或没有 title 的页面会给 (no <title> element in the body)',
+      ])
     },
   }))
 }

package/tools/dsh-plugin-fly-reverse/index.js

@@ -18,7 +18,28 @@ function shq(value) {
  * `TypeError: shell.run is not a function` on every call, in every engine
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
+ *
+ * **失败面的口径是"大声"**（Q5）：
+ *   · `objdump -T` 读不出动态符号表（Mach-O 常态）⇒ 换 `nm -u` 这条**回退**，并把"这是回退路径、
+ *     nm 只报未定义的名字、不说是从哪个库来的"写进结果的 `limitations`；
+ *   · **两把尺子都没有** ⇒ 明说"没有可读的未定义符号"，并附上两条命令的 exit 与 stderr，
+ *     绝不说成"这个程序不依赖任何外部符号"（静态链接/已 strip 正是这个形状）；
+ *   · `ROPgadget` 不在 ⇒ 用内置扫描器（只认 pop/leave + ret 的简单序列），并在结果里写明
+ *     "**没找到 ≠ 没有**"；`objdump` 缺失时 `requireOk` 抛错，不给空反汇编。
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回（`bin_sections { path: '--version' }`
+ * 真发生过）。加 `./` 之后它就是一个普通相对路径：不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -49,9 +70,19 @@ async function runCmd(shell, argv, exec, opts = {}) {
  */
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -103,33 +134,67 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
-      const kindRun = await runCmd(shell, ['file', '-b', args.path], exec)
+      const path = safePath(args.path)
+      const kindRun = await runCmd(shell, ['file', '-b', path], exec)
       const kind = kindRun.exitCode === 0 ? kindRun.stdout.trim() : ''
-      const dynamic = await runCmd(shell, ['objdump', '-T', args.path], exec)
+      const dynamic = await runCmd(shell, ['objdump', '-T', path], exec)
       const dynamicLines = dynamic.exitCode === 0
         ? dynamic.stdout.split('\n').filter((l) => l.includes('DF') && l.includes('*UND*')).map((l) => l.trim())
         : []
-      if (dynamicLines.length > 0) return dynamicLines.slice(0, 300).join('\n')
+      if (dynamicLines.length > 0) {
+        return JSON.stringify({
+          tool: 'rev_imports',
+          target: args.path,
+          operation: 'list undefined (imported) symbols: objdump -T (DF *UND*)',
+          observed: { method: 'objdump', shown: Math.min(dynamicLines.length, 300), dump: dynamicLines.slice(0, 300).join('\n') },
+          confidence: 'observed',
+          limitations: [
+            '只列**动态**符号表（.dynsym）里的未定义项：静态链接进来的、或本地定义的符号不在里面',
+            dynamicLines.length > 300 ? '只给前 300 条（要全量就自己按符号名筛）' : '这次没有截断（未定义符号 ≤ 300）',
+          ],
+        }, null, 2)
+      }
       // `objdump -T` exits 0 with a bare table header for Mach-O, and a stripped
       // ELF may have no dynamic symbol table at all. `nm -u` is the portable
       // second opinion (it ships with macOS and the Xcode CLT).
-      const nm = await runCmd(shell, ['nm', '-u', args.path], exec, { stdoutMaxBytes: 4194304 })
+      const nm = await runCmd(shell, ['nm', '-u', path], exec, { stdoutMaxBytes: 4194304 })
       const undefinedSymbols = nm.exitCode === 0
         ? nm.stdout.split('\n').map((l) => l.trim()).filter((l) => /^_?[A-Za-z_][\w$.@]*$/u.test(l))
         : []
       if (undefinedSymbols.length > 0) {
-        return [
+        return JSON.stringify({
+          tool: 'rev_imports',
+          target: args.path,
+          operation: 'list undefined (imported) symbols: nm -u (objdump -T had no dynamic table)',
+          observed: { method: 'nm -u', format: kind === '' ? null : kind, shown: Math.min(undefinedSymbols.length, 300), dump: [
           `${kind === '' ? 'format unknown' : kind}: no ELF dynamic symbol table to read, so these are the undefined symbols from nm -u (${undefinedSymbols.length}):`,
           ...undefinedSymbols.slice(0, 300),
-        ].join('\n')
+          ].join('\n') },
+          confidence: 'observed',
+          limitations: [
+            '走的是 nm -u 这条**回退**路径：objdump -T 在这个文件上没有动态符号表（Mach-O 常见）',
+            'nm -u 只报"未定义"的名字，不告诉你是从哪个库来的（要库映射得看 otool -L / readelf -d）',
+          ],
+        }, null, 2)
       }
-      return [
+      return JSON.stringify({
+        tool: 'rev_imports',
+        target: args.path,
+        operation: 'list undefined (imported) symbols: both objdump -T and nm -u came back empty',
+        observed: { method: null, format: kind === '' ? null : kind, shown: 0, dump: [
         `no undefined symbols for ${args.path}: objdump -T (exit ${dynamic.exitCode}) and nm -u (exit ${nm.exitCode}) both came back empty`,
         `format: ${kind === '' ? 'unknown (file(1) reported nothing)' : kind}`,
         `nm -u stderr: ${nm.stderr.trim().slice(0, 200) || '(empty)'}`,
         `objdump -T output follows (${dynamic.stdout.trim().length} chars), so the emptiness is inspectable:`,
         dynamic.stdout.trim().slice(0, 2000),
-      ].join('\n')
+        ].join('\n') },
+        confidence: 'observed',
+        limitations: [
+          '**两把尺子都没给出符号**：这句话的前提是 objdump -T 与 nm -u **都跑过了**（两条 exit 与 nm 的 stderr 就在 dump 里）',
+          '它说的是「这份文件里没有可读的未定义符号」，不是「这个程序不依赖任何外部符号」—— 静态链接或已 strip 的二进制正是这个形状',
+          '要继续追依赖，先换个体：bin_file 看格式、bin_readelf 看动态段（.dynamic / NEEDED）',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -146,10 +211,23 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
-      const argv = ['-d', args.path]
+      const path = safePath(args.path)
+      const argv = ['-d', path]
       if (args.start && args.stop) argv.splice(1, 0, `--start-address=${args.start}`, `--stop-address=${args.stop}`)
       const stdout = requireOk(await runCmd(shell, ['objdump', ...argv], exec, { stdoutMaxBytes: 1048576 }), 'objdump -d')
-      return stdout.slice(0, 12000)
+      // 证据形状（规划 §5.1）：信封 JSON，objdump 输出原样进 observed.dump。
+      return JSON.stringify({
+        tool: 'rev_disasm',
+        target: args.path,
+        operation: 'objdump -d' + (args.start && args.stop ? ` --start-address=${args.start} --stop-address=${args.stop}` : ' (whole file)'),
+        observed: { window: args.start && args.stop ? { start: args.start, stop: args.stop } : null, truncated: stdout.length > 12000, dump: stdout.slice(0, 12000) },
+        confidence: 'observed',
+        limitations: [
+          stdout.length > 12000 ? '只给前 12000 字符（truncated=true）—— 要看后面请给 start/stop 缩小窗口' : '这次没有截断（输出 ≤ 12000 字符）',
+          '反汇编是**线性扫描**的结果：数据段夹在代码里时，那些字节也会被当成指令打出来（用 start/stop 框住函数能少踩这个）',
+          '不看控制流、不做函数边界识别（要那些得换真正的反编译器）',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -165,14 +243,50 @@ export function apply(ctx) {
       render: (_a, v) => [{ type: 'text', text: v }],
     },
     async execute(args, exec) {
-      const argv = ['--binary', args.path, '--only', 'pop|ret|leave']
+      const path = safePath(args.path)
+      const argv = ['--binary', path, '--only', 'pop|ret|leave']
       if (args.filter) argv.push('--filter', args.filter)
       const rop = await runCmd(shell, ['ROPgadget', ...argv], exec)
-      if (rop.exitCode === 0) return rop.stdout.slice(0, 8000)
-      const disasm = requireOk(await runCmd(shell, ['objdump', '-d', args.path], exec, { stdoutMaxBytes: 1048576 }), 'objdump -d')
+      if (rop.exitCode === 0) {
+        return JSON.stringify({
+          tool: 'rev_gadget_scan',
+          target: args.path,
+          operation: 'ROPgadget --only pop|ret|leave' + (args.filter ? ` --filter ${args.filter}` : ''),
+          observed: { method: 'ROPgadget', shown: null, truncated: rop.stdout.length > 8000, dump: rop.stdout.slice(0, 8000) },
+          confidence: 'observed',
+          limitations: [
+            'ROPgadget 的输出原样返回（本工具只做截断：>8000 字符时 truncated=true）',
+            'ROPgadget 自己会做指令边界识别与去重，但**只扫 --only pop|ret|leave 这几类**（要别的指令得改本工具）',
+          ],
+        }, null, 2)
+      }
+      const disasm = requireOk(await runCmd(shell, ['objdump', '-d', path], exec, { stdoutMaxBytes: 1048576 }), 'objdump -d')
       const gadgets = scanGadgets(disasm, args.filter)
-      if (gadgets.length > 0) return gadgets.slice(0, 80).join('\n')
-      return `no pop/leave/ret gadgets found in ${args.path} (install ROPgadget for a deeper scan)`
+      if (gadgets.length > 0) {
+        return JSON.stringify({
+          tool: 'rev_gadget_scan',
+          target: args.path,
+          operation: 'built-in scanner over objdump -d (ROPgadget not installed)' + (args.filter ? ` filtered by ${args.filter}` : ''),
+          observed: { method: 'builtin', shown: Math.min(gadgets.length, 80), truncated: gadgets.length > 80, dump: gadgets.slice(0, 80).join('\n') },
+          confidence: 'observed',
+          limitations: [
+            '走的是**内置扫描器**（本机没有 ROPgadget）：它只在 objdump 的反汇编里找 pop/leave + 紧跟的 ret 这类**简单序列**',
+            '不做指令边界校验、不做 gadget 去重：地址可能重叠，长链 gadget（多指令 + 中间跳转）它也不会给',
+            gadgets.length > 80 ? '只给前 80 条（observed.truncated=true）' : '这次没有截断（≤ 80 条）',
+          ],
+        }, null, 2)
+      }
+      return JSON.stringify({
+        tool: 'rev_gadget_scan',
+        target: args.path,
+        operation: 'built-in scanner over objdump -d: nothing matched',
+        observed: { method: 'builtin', shown: 0, dump: `no pop/leave/ret gadgets found in ${args.path} (install ROPgadget for a deeper scan)` },
+        confidence: 'observed',
+        limitations: [
+          '**没找到 ≠ 没有**：这条走的是内置扫描器（只认 pop/leave + ret 的简单序列），装 ROPgadget 后同一条命令可能给出几十条',
+          '也不排除这个文件根本没有可执行段（比如被测的是数据文件）—— 先用 bin_file 看它是什么',
+        ],
+      }, null, 2)
     },
   }))
 }