@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/deliver-customer.mjs

@@ -0,0 +1,932 @@
+#!/usr/bin/env node
+/**
+ * deliver-customer —— **第三件事：往客户机 / 远端克隆投递**（2026-10-08）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、为什么有它：三个投递口各管一件事，⛔ 不许互相顶替
+ * ══════════════════════════════════════════════════════════════════════════
+ * | # | 投递口 | 目标 | 面 | 本脚本与它的关系 |
+ * |---|---|---|---|---|
+ * | 一 | `scripts/sync-scripts.sh` | **本机**安装克隆 `~/.argent-dsh` | 读**同一份**面清单 | 面清单唯一真源 `scripts/delivery-faces.txt`（⛔ 不另写第二份） |
+ * | 二 | `scripts/release-argent.sh` | **下载服务器** `whyshu.com/dl` | `install-*.mjs/ps1/sh`（`--full` 再带 skills/plugins） | **无关**：目标机与面都不同，本脚本⛔ 不读它、不改它 |
+ * | 三 | **本脚本** | **客户机 / 远端克隆**（rsync over ssh） | 同上（默认六面） | 面清单共用；语义各自独立 |
+ * 客户机**没有仓库** ⇒ `sync-scripts.sh` 在客户机上必然 exit 2（它是"本机克隆"专用）；本脚本才是
+ * "把仓库这一批改动送到客户机"的那一件。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、它把 2026-10-08 当天靠人工纪律做的七件事，变成一次可复跑的投递
+ * ══════════════════════════════════════════════════════════════════════════
+ * ① **面缺失**：面清单此前散在脚本里 ⇒ `deploy/` 漂移一整批（`deploy/customer/roles.spec.json`
+ *    会被 `check-role-mapping.mjs` 第 ⑥ 项按 `REPO/deploy/…` **真读**）。现在面清单是**唯一真源**
+ *    文件，本脚本与 `sync-scripts.sh` 读**同一份**；面为空 ⇒ exit 3（绝不"没面也算成功"）。
+ * ② **带垃圾**：naive rsync 会把开发树 `__pycache__/*.pyc`（本机 python 3.14 的字节码）推给跑 3.11 的
+ *    生产机。排除表 = `__pycache__` / `*.pyc` / `.DS_Store` / `*.bak-*`（`--exclude` 可追加），
+ *    并且**同时**作用于"文件清单"与 rsync 的 `--exclude`（双保险）。
+ * ③ **权限漂移**：`rsync -a` 会把开发树 umask（实测 600/711）带进生产 ⇒ 投递后按 **git 索引模式**
+ *    （`100644→644`、`100755→755`）归一，并核"模式不符 = 0"（不符 ⇒ exit 1 并点名）。
+ * ④ **硬链接陷阱**：rsync/编辑器换 inode ⇒ `~/.dsh/profiles/<p>/node_modules/argent-*` 仍是旧字节 ⇒
+ *    "重启即生效"是假的且**无报错**。投递面含 `plugins/` 或 `presets/` 时**自动**核 profile 副本
+ *    （同 inode / nlink≥2 / md5）并自动 `ln -f` 修复（`--no-profile` 可关）；**新增文件同样落 profile**
+ *    （漏了就是插件 import 崩、服务起不来）。
+ * ⑤ **静默失败**：喂 stdin 时若给 `ssh` 加 `-n`，stdin 被顶成 `/dev/null` ⇒ 落成**空文件**。
+ *    本脚本**全部**远端动作都走 `ssh <target> bash -s -- …` + stdin 喂脚本，且**绝不加 `-n`**；
+ *    并且**每次投递都做双端 sha256 逐文件核对**（含新增/缺失），任一不符 ⇒ exit 1 并点名。
+ * ⑥ **回滚耦合**：例：日志移出 `/tmp` 后，只回滚读 `/tmp` 的旧唤醒脚本 ⇒ 四条流程全哑。
+ *    `--coupled <组>` 声明耦合回滚组，回滚输出里**明确写出**"这几件必须一起回滚"。
+ * ⑦ **备份先行**：投递前在客户机打面 tar（`600` + 时间戳 tag + sha256 + `MANIFEST.txt`），
+ *    落 `<backup-dir>/<tag>/`，并**生成可执行的回滚脚本**（同目录 `rollback.sh`，700）——
+ *    它会把面解包回投递前、删掉本次新增文件、恢复模式、复核 sha、重链 profile。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 三、用法与退出码
+ * ══════════════════════════════════════════════════════════════════════════
+ * ```
+ * node scripts/deliver-customer.mjs --target <user@host> [选项]        # 默认 dry-run（零写入）
+ * node scripts/deliver-customer.mjs --target <user@host> --apply      # 真投递
+ * ```
+ * | 选项 | 说明 |
+ * |---|---|
+ * | `--target <user@host>` | 投递目标（必填；也可用环境变量 `ARGENT_CUSTOMER_TARGET`）。⛔ 脚本里**不写死**任何客户机名 |
+ * | `--face <名>` | 投递面（可重复）；缺省读唯一真源 `scripts/delivery-faces.txt` |
+ * | `--exclude <glob>` | 追加排除（可重复）；缺省表：`__pycache__` `*.pyc` `.DS_Store` `*.bak-*` |
+ * | `--source <dir>` | 源树（缺省 = 本脚本所在的仓库） |
+ * | `--remote-dir <path>` | 客户机落点（缺省 `~/.argent-dsh`；`~/` 会按客户机 `$HOME` 展开） |
+ * | `--backup-dir <path>` | 备份根（缺省 `~/.dsh/argent/backup`） |
+ * | `--profile <名>` | profile 名（缺省 `web`；面含 plugins/presets 时用它核副本） |
+ * | `--profile-root <path>` | profile 根（缺省 `~/.dsh/profiles`） |
+ * | `--presets-root <path>` | preset 副本根（缺省 `<profile-root>/../.agent-presets`） |
+ * | `--no-profile` | 关掉 profile 副本核对/修复（⛔ 只在明确知道不需要时用） |
+ * | `--coupled <说明>` | 声明一个耦合回滚组（可重复）——回滚输出里会点名"必须一起回滚" |
+ * | `--self-check` | 投递后跑**仓库既有**的连续性判据（客户机侧只读；异常 ⇒ exit 1 并提示回滚） |
+ * | `--apply` | 真执行（缺省 dry-run：只做**只读**远端探测 + 打印计划，**零写入**） |
+ * | `-h, --help` | 打印本段 |
+ *
+ * 退出码：`0` 成功 ｜ `1` 投递或核对失败（sha/模式/profile/自检不符，**逐条点名**）｜
+ *        `2` 用法错（参数/目标缺失）｜ `3` 被前置条件挡住（目标不可达、面清单为空、源树非 git 仓…）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 四、纪律（都是踩过的坑，改动本文件前先读）
+ * ══════════════════════════════════════════════════════════════════════════
+ * · **⛔ 不用 `scp`**：一律 rsync over ssh（`-az --no-owner --no-group --files-from=…`）。
+ * · **⛔ 管道喂 stdin 时绝不加 `ssh -n`**：`-n` 会把 stdin 顶成 `/dev/null` ⇒ 远端脚本变成空脚本、
+ *   文件落成空文件，而且**看起来成功**（实测：`role-gateway-exemptions.json` 首次就是空文件，
+ *   靠双端 sha 才当场拦下）。本文件只在 `sshRun()` 一处拼 ssh 参数，那里有显式注释。
+ * · **⛔ 不用 `--delete`**：远端可能有带外资产；本次投递只覆盖"清单里的文件"。
+ * · **文件与模式都取自 git 索引**（`git ls-files -z -s`）⇒ 清单里不可能出现未跟踪的构建垃圾
+ *   （`__pycache__`/`.DS_Store`），模式也不需要"猜"。
+ * · **落盘是 rsync 的默认语义**（临时文件 + rename），本脚本不额外做 `tmp + mv`。
+ * · **本脚本不重启任何东西**：`plugins/`（host）与 plist 改动必须由**用户手动**重启才生效；
+ *   投递器/驱动器改动不必重启（`flow-trigger*` 每轮从磁盘重读）⇒ 回滚输出里写明这条边界。
+ * · **只读探测**：dry-run 只跑 `printf`/`stat`/`shasum`（不改任何字节、不建目录、不写备份）。
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_REPO = resolve(HERE, '..')
+
+/** 退出码（与文件头一致；⛔ 语义固定，不许"复用"成别的东西）。 */
+export const EXIT = { OK: 0, FAIL: 1, USAGE: 2, BLOCKED: 3 }
+
+/** 排除表（2026-10-08 的"带垃圾"教训）：目录名 / basename glob。`--exclude` 追加。 */
+export const DEFAULT_EXCLUDES = ['__pycache__', '*.pyc', '.DS_Store', '*.bak-*']
+
+/** 面清单唯一真源（与 `scripts/sync-scripts.sh` 共用同一份）。 */
+export const FACES_REL = 'scripts/delivery-faces.txt'
+
+/** 需要核 profile 副本的面（面清单里出现它们 ⇒ 自动核；见文件头 ④）。 */
+export const PROFILE_FACES = ['plugins', 'presets']
+
+/** 远端文件清单哨兵（heredoc 结束标记；与路径校验配合，避免清单被"内容里恰好有一行 EOF"截断）。 */
+const SENTINEL = '__ARGENT_DELIVER_LIST__'
+
+class UsageError extends Error {}
+class Blocked extends Error {}
+class DeliveryFailure extends Error {}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 输出
+// ══════════════════════════════════════════════════════════════════════════
+const say = (s = '') => console.log(s)
+const ok = (m) => say(`  ✅ ${m}`)
+const warn = (m) => say(`  ⚠️ ${m}`)
+const bad = (m) => say(`  ❌ ${m}`)
+const info = (m) => say(`  · ${m}`)
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex')
+const sha256File = (p) => sha256(readFileSync(p))
+
+/**
+ * 工作树文件的 **git blob sha1**（`sha1("blob <len>\0" + content)`）。
+ * 用途：与 `git ls-files -s` 的 blob sha 比对 ⇒ 判"工作树是否与索引一致"。
+ * ⚠️ 不能拿 sha256 去比索引里的 sha1（算法不同 ⇒ 恒"不一致"，那是假警告）。
+ */
+const gitBlobSha1 = (p) => {
+  const buf = readFileSync(p)
+  return createHash('sha1').update(`blob ${buf.length}\0`).update(buf).digest('hex')
+}
+
+/** bash 单引号安全引用（路径里可能有空格/中文/`$`）。 */
+const shq = (s) => `'${String(s).split("'").join(`'\\''`)}'`
+
+// ══════════════════════════════════════════════════════════════════════════
+// 一、参数与面清单（纯函数，测试可直接 import）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 读面清单（**唯一真源**）。
+ * 格式与 `sync-scripts.sh#read_faces` **逐字同语义**：一行一个面，`#` 起注释，空行忽略。
+ * @returns {{faces: string[], error: string|null}}
+ */
+export function readFaces(repoRoot) {
+  const p = join(repoRoot, FACES_REL)
+  if (!existsSync(p)) return { faces: [], error: `面清单不存在：${FACES_REL}（唯一真源；与 scripts/sync-scripts.sh 共用同一份）` }
+  const faces = []
+  for (const raw of readFileSync(p, 'utf8').split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim()
+    if (!line) continue
+    if (!faces.includes(line)) faces.push(line)
+  }
+  if (!faces.length) return { faces: [], error: `面清单为空：${FACES_REL}（空清单必然投递不全 ⇒ 拒绝执行）` }
+  return { faces, error: null }
+}
+
+/** 一个相对路径是否命中排除表：路径的任一段等于目录名，或 basename 命中 glob。 */
+export function matchesExclude(rel, patterns) {
+  const segs = String(rel).split('/')
+  const base = segs[segs.length - 1]
+  const globRe = (g) => new RegExp(`^${String(g).replace(/[.+^${}()|[\]\\?]/g, '\\$&').split('*').join('[^/]*')}$`)
+  for (const pat of patterns) {
+    if (!pat) continue
+    if (!pat.includes('*') && !pat.includes('?')) {
+      if (segs.includes(pat)) return pat        // 目录名（`__pycache__`）
+      if (base === pat) return pat              // 文件名（`.DS_Store`）
+      continue
+    }
+    if (globRe(pat).test(base)) return pat      // basename glob（`*.pyc` / `*.bak-*`）
+  }
+  return null
+}
+
+/** `git ls-files -s` 的 mode → 目标权限位。 */
+export function modeOf(gitMode) {
+  if (gitMode === '100644') return '644'
+  if (gitMode === '100755') return '755'
+  return null                                   // 120000(symlink)/160000(submodule) 等：不归一，只提示
+}
+
+function parseArgs(argv) {
+  const o = {
+    target: process.env.ARGENT_CUSTOMER_TARGET || '',
+    source: SELF_REPO, remoteDir: '~/.argent-dsh', backupDir: '~/.dsh/argent/backup',
+    profile: 'web', profileRoot: '~/.dsh/profiles', presetsRoot: '', profileCheck: true,
+    apply: false, selfCheck: false, faces: [], excludes: [], coupled: [],
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const val = () => { const v = argv[++i]; if (v === undefined || v.startsWith('--')) throw new UsageError(`选项缺取值：${a}`); return v }
+    switch (a) {
+      case '--target': o.target = val(); break
+      case '--face': o.faces.push(val()); break
+      case '--exclude': o.excludes.push(val()); break
+      case '--source': o.source = resolve(val()); break
+      case '--remote-dir': o.remoteDir = val(); break
+      case '--backup-dir': o.backupDir = val(); break
+      case '--profile': o.profile = val(); break
+      case '--profile-root': o.profileRoot = val(); break
+      case '--presets-root': o.presetsRoot = val(); break
+      case '--coupled': o.coupled.push(val()); break
+      case '--no-profile': o.profileCheck = false; break
+      case '--apply': o.apply = true; break
+      case '--self-check': o.selfCheck = true; break
+      default: throw new UsageError(`未知参数：${a}（用 --help 看用法）`)
+    }
+  }
+  if (!o.target) throw new UsageError('缺 --target <user@host>（或设 ARGENT_CUSTOMER_TARGET）——本脚本不写死客户机名')
+  return o
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二、投递集（文件 + 模式 = **git 索引**）
+// ══════════════════════════════════════════════════════════════════════════
+
+function git(repo, args) {
+  const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 })
+  return { code: r.status, out: (r.stdout || Buffer.alloc(0)).toString('utf8'), err: (r.stderr || Buffer.alloc(0)).toString('utf8') }
+}
+
+/**
+ * 投递集 = `git ls-files -s -- <faces>` ∩ ¬排除表。
+ * 为什么用 git 索引：① 它是"这批文件该是什么模式"的**唯一真源**（权限归一的判据）；
+ * ② 未跟踪的构建垃圾（`__pycache__`/`.DS_Store`）**天然不在**清单里 —— 但仍显式过一遍排除表，
+ * 因为仓库里**真有**被跟踪的 `.bak-*` 备份件（某个发票运行器的历史备份，`git ls-files | grep '\.bak-'` 可查）那类东西。
+ * @returns {{files: {rel:string,mode:string,sha:string}[], excluded:{rel:string,pat:string}[],
+ *            untracked:string[], odd Modes:{rel:string,mode:string}[], error:string|null}}
+ */
+export function collectDeliverySet(repo, faces, excludes) {
+  if (!existsSync(join(repo, '.git'))) {
+    return { error: `源树不是 git 仓库（缺 .git）：${repo} —— 投递集与权限都取自 git 索引，没有它无法归一权限` }
+  }
+  const ls = git(repo, ['ls-files', '-z', '-s', '--', ...faces])
+  if (ls.code !== 0) return { error: `git ls-files 失败（exit ${ls.code}）：${ls.err.trim().slice(0, 300)}` }
+  const files = [], excluded = [], oddModes = []
+  for (const rec of ls.out.split('\0')) {
+    if (!rec) continue
+    const m = /^(\d{6}) ([0-9a-f]+) (\d)\t([\s\S]*)$/.exec(rec)
+    if (!m) return { error: `git ls-files 输出无法解析（协议变化？）：${rec.slice(0, 120)}` }
+    const [, gitMode, blob, , rel] = m
+    const pat = matchesExclude(rel, excludes)
+    if (pat) { excluded.push({ rel, pat }); continue }
+    const mode = modeOf(gitMode)
+    if (!mode) { oddModes.push({ rel, mode: gitMode }); continue }   // symlink/submodule：不归一、不核对
+    files.push({ rel, mode, sha: blob })
+  }
+  const un = git(repo, ['ls-files', '-z', '--others', '--exclude-standard', '--', ...faces])
+  const untracked = un.code === 0 ? un.out.split('\0').filter(Boolean) : []
+  return { files, excluded, untracked, oddModes, error: null }
+}
+
+function assertSafePaths(paths) {
+  const hit = paths.filter((p) => /[\n\r\t]/.test(p) || p === SENTINEL)
+  if (hit.length) throw new Blocked(`路径含换行/制表符（或与哨兵同名），投递协议无法安全表达：${hit[0]}`)
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 三、远端执行（**唯一**拼 ssh 的地方）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 远端执行一段 bash（脚本走 **stdin**，参数走 argv）。
+ *
+ * ⛔ **绝不给 ssh 加 `-n`**：`-n` 把 stdin 重定向到 `/dev/null`，于是这里喂进去的脚本变成**空脚本**，
+ * 远端"成功退出"却什么都没做（或把文件落成空文件）—— 2026-10-08 实测踩到，靠双端 sha 才拦下。
+ * 本函数是全脚本**唯一**拼 ssh argv 的地方，纪律集中在这里守。
+ */
+export function sshRun(target, script, args = [], { timeoutMs = 180000 } = {}) {
+  // 排障口子：`ARGENT_DELIVER_DUMP=1` 把**远端脚本原文**打到 stderr。
+  // 为什么值得留：远端脚本走 stdin（本地不落盘）⇒ 出问题时要能看见"客户机到底收到了什么"
+  // （空脚本 / 被截断 / 变量没展开 —— 这三类都只能靠看原文定位）。
+  if (process.env.ARGENT_DELIVER_DUMP) process.stderr.write(`\n──── 远端脚本（target=${target}）────\n${script}\n──── 脚本结束 ────\n`)
+  const argv = [target, 'bash', '-s', '--', ...args]      // ⛔ 这里不许出现 '-n'
+  const r = spawnSync('ssh', argv, {
+    input: script, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: timeoutMs,
+  })
+  if (r.error) return { code: 255, out: '', err: `ssh 执行失败：${r.error.message}`, timeout: r.error.code === 'ETIMEDOUT' }
+  return { code: r.status === null ? 255 : r.status, out: r.stdout || '', err: r.stderr || '' }
+}
+
+/** 远端脚本公共前导：平台自适应的 stat/md5 + sha（客户机是 macOS，Linux 走 fallback）。 */
+const REMOTE_PREAMBLE = `set -uo pipefail
+export LC_ALL=C
+case "$(uname -s)" in
+  Darwin)
+    st_mode() { stat -f '%Lp' "$1"; }; st_ino() { stat -f '%i' "$1"; }
+    st_nlink() { stat -f '%l' "$1"; }; md5_of() { md5 -q "$1"; } ;;
+  *)
+    st_mode() { stat -c '%a' "$1"; }; st_ino() { stat -c '%i' "$1"; }
+    st_nlink() { stat -c '%h' "$1"; }; md5_of() { md5sum "$1" | cut -d' ' -f1; } ;;
+esac
+sha_of() { if command -v shasum >/dev/null 2>&1; then shasum -a 256 -- "$1" | cut -d' ' -f1; else sha256sum -- "$1" | cut -d' ' -f1; fi }
+`
+
+/** 远端只读探测：HOME / 平台 / 落点 / 台账（可选）+ 每个投递文件的 sha 与模式。 */
+function probeScript(root, files, ledgerProbe) {
+  return `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+printf 'REMOTE_HOME\\t%s\\n' "$HOME"
+printf 'REMOTE_UNAME\\t%s\\n' "$(uname -s)"
+printf 'REMOTE_ROOT\\t%s\\n' "$([ -d "$ROOT" ] && printf 1 || printf 0)"
+${ledgerProbe}
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  p="$ROOT/$rel"
+  if [ -f "$p" ]; then printf 'PRE\\t%s\\t%s\\t%s\\n' "$rel" "$(sha_of "$p")" "$(st_mode "$p")"
+  else printf 'PRE\\t%s\\t-\\t-\\n' "$rel"; fi
+done <<'${SENTINEL}'
+${files.join('\n')}
+${SENTINEL}
+`
+}
+
+/** 远端台账探测（`--self-check` 用；**只读**，走仓库自己的判据）。 */
+const LEDGER_PROBE = `led=""
+if command -v node >/dev/null 2>&1 && [ -f "$ROOT/core/lib/argent-datadir.mjs" ]; then
+  led="$(ARGENT_ROOT="$ROOT" node -e "import(process.env.ARGENT_ROOT + '/core/lib/argent-datadir.mjs').then(m => process.stdout.write(String(m.resolveDataDir().dir))).catch(() => {})" 2>/dev/null)"
+fi
+if [ -n "$led" ] && [ -f "$led/flow-ledger.jsonl" ]; then
+  printf 'LEDGER_SHA\\t%s\\n' "$(sha_of "$led/flow-ledger.jsonl")"
+else
+  printf 'LEDGER_SHA\\t-\\n'
+fi
+PY=""
+for cand in "$HOME/.dsh/argent/venv/bin/python3" "$(command -v python3 || true)"; do
+  [ -n "$cand" ] && [ -x "$cand" ] && { PY="$cand"; break; }
+done
+if [ -n "$PY" ] && [ -f "$ROOT/scripts/flow_ledger.py" ] && [ -n "$led" ]; then
+  printf 'LEDGER_PLANNED\\t%s\\n' "$("$PY" "$ROOT/scripts/flow_ledger.py" --ledger "$led/flow-ledger.jsonl" --status --json 2>/dev/null | "$PY" -c 'import json,sys
+try:
+  d = json.load(sys.stdin)
+  print(len([1 for e in (d.get("last") or {}).values() if e.get("event") == "planned"]))
+except Exception:
+  print("-")' 2>/dev/null)"
+else
+  printf 'LEDGER_PLANNED\\t-\\n'
+fi
+`
+
+function parseTsv(out) {
+  const rows = []
+  for (const line of String(out).split('\n')) {
+    if (!line) continue
+    const f = line.split('\t')
+    rows.push(f)
+  }
+  return rows
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 四、主流程
+// ══════════════════════════════════════════════════════════════════════════
+
+function printHelp() {
+  const src = readFileSync(fileURLToPath(import.meta.url), 'utf8')
+  // 取文件头那段块注释（**从 `/**` 起**：别把 shebang 也打出来）
+  const header = src.slice(src.indexOf('/**')).split('*/')[0].replace(/^\/\*\*/, '')
+    .split('\n').map((l) => l.replace(/^ \* ?/, '')).join('\n')
+  say(header.trim())
+}
+
+function main() {
+  const argv = process.argv.slice(2)
+  if (argv.includes('-h') || argv.includes('--help')) { printHelp(); return EXIT.OK }
+  const opt = parseArgs(argv)
+  const excludes = [...DEFAULT_EXCLUDES, ...opt.excludes]
+
+  say('▸ 客户机投递（第三件事：往客户机 / 远端克隆投递）')
+  say(`  模式：${opt.apply ? '**真执行**（--apply）' : 'dry-run（默认；真执行需 --apply）'}`)
+  say(`  目标：${opt.target}    落点：${opt.remoteDir}`)
+  say(`  源树：${opt.source}`)
+
+  // ── ① 面清单（唯一真源）────────────────────────────────────────────────
+  let faces = opt.faces
+  if (!faces.length) {
+    const r = readFaces(opt.source)
+    if (r.error) throw new Blocked(r.error)
+    faces = r.faces
+    say(`  面清单：${faces.join(' ')}（来自 ${FACES_REL} —— 与 sync-scripts.sh **同一份**真源）`)
+  } else {
+    say(`  面清单：${faces.join(' ')}（--face 覆盖；真源仍是 ${FACES_REL}）`)
+  }
+  say(`  排除表：${excludes.join(' ')}${opt.excludes.length ? `（含 --exclude 追加 ${opt.excludes.length} 条）` : ''}`)
+  const missingFace = faces.filter((f) => !existsSync(join(opt.source, f)))
+  if (missingFace.length) throw new Blocked(`面清单里的目录在源树里不存在：${missingFace.join(' ')}（源树 ${opt.source}）`)
+
+  // ── ② 投递集（git 索引 = 文件 + 模式）──────────────────────────────────
+  const set = collectDeliverySet(opt.source, faces, excludes)
+  if (set.error) throw new Blocked(set.error)
+  if (!set.files.length) throw new Blocked(`投递集为空（面：${faces.join(' ')}）—— 空集投递必然"看起来成功"，拒绝执行`)
+  assertSafePaths(set.files.map((f) => f.rel))
+  const localSha = new Map(set.files.map((f) => [f.rel, sha256File(join(opt.source, f.rel))]))
+  const mismatchBlob = set.files.filter((f) => gitBlobSha1(join(opt.source, f.rel)) !== f.sha)
+  info(`投递集：${set.files.length} 个文件（git 索引模式）｜排除命中 ${set.excluded.length} 个｜未跟踪（不投）${set.untracked.length} 个`)
+  if (set.excluded.length) {
+    const sample = set.excluded.slice(0, 3).map((e) => `${e.rel}（命中 ${e.pat}）`).join('、')
+    info(`排除命中（**不投**）：${sample}${set.excluded.length > 3 ? ` …另有 ${set.excluded.length - 3} 个` : ''}`)
+  }
+  if (set.untracked.length) {
+    // naive `rsync -a` 会把这些一起推过去 —— 正是"带垃圾"的形态；这里只报告
+    const sample = set.untracked.slice(0, 3).join('、')
+    warn(`源树里有 ${set.untracked.length} 个**未跟踪**文件落在投递面内（不投）：${sample}${set.untracked.length > 3 ? ' …' : ''}`)
+  }
+  if (set.oddModes.length) warn(`非 644/755 的索引模式 ${set.oddModes.length} 个（不归一、不核对）：${set.oddModes.slice(0, 3).map((e) => `${e.rel}=${e.mode}`).join('、')}`)
+  if (mismatchBlob.length) warn(`本地文件与 git 索引 blob 不一致（工作树有未提交改动）${mismatchBlob.length} 个：${mismatchBlob.slice(0, 3).map((e) => e.rel).join('、')}`)
+  info(`双端核对口径：逐文件 sha256（${set.files.length} 个）+ 模式不符 = 0`)
+
+  // ── ③ 前置：目标可达 + 远端只读探测 ────────────────────────────────────
+  const home = remoteHome(opt.target)
+  const root = expandTilde(opt.remoteDir, home)
+  const backupRoot = expandTilde(opt.backupDir, home)
+  const pre = probeTarget(opt, root, set.files)
+  const preMap = pre.pre
+
+  // ── ④ 计划分类（新增/更新/一致）────────────────────────────────────────
+  const plan = { added: [], changed: [], same: [], missingMode: [] }
+  for (const f of set.files) {
+    const p = preMap.get(f.rel)
+    if (!p || p.sha === '-') plan.added.push(f.rel)
+    else if (p.sha !== localSha.get(f.rel)) plan.changed.push(f.rel)
+    else plan.same.push(f.rel)
+  }
+  info(`计划：新增 ${plan.added.length} ｜ 更新 ${plan.changed.length} ｜ 内容一致 ${plan.same.length}`)
+  for (const rel of plan.added.slice(0, 5)) info(`  ＋ ${rel}`)
+  for (const rel of plan.changed.slice(0, 5)) info(`  ～ ${rel}`)
+
+  const needProfile = opt.profileCheck && faces.some((f) => PROFILE_FACES.includes(f))
+  const profilePlan = needProfile ? profileRows(opt, root, home, faces, set.files) : []
+  // profile 副本**只读**预检（apply 与 dry-run 都跑）：dry-run 里它就是"这条会不会被修"的答案
+  // ⚠️ 预检只在 dry-run 跑：apply 模式下"源文件还没投递"是**预期的中间态**（rsync 之后才有真相），
+  // 而 apply 的 profile 修复步骤本身就会报告 漂移/修复/新增落地 的真实数字。
+  const profileProbe = (needProfile && !opt.apply) ? probeProfile(opt, root, profilePlan) : null
+  if (profileProbe) {
+    if (profileProbe.drifted.length) warn(`profile 副本漂移（内容/硬链接不符）${profileProbe.drifted.length} 个：${profileProbe.drifted.slice(0, 3).join('、')}`)
+    if (profileProbe.missing.length) warn(`profile 缺文件（新增文件必须落 profile）${profileProbe.missing.length} 个：${profileProbe.missing.slice(0, 3).join('、')}`)
+    if (profileProbe.skipped.length) info(`profile 副本跳过 ${profileProbe.skipped.length} 个（该 profile 未安装对应包）`)
+    if (profileProbe.bad.length) bad(`profile 副本异常 ${profileProbe.bad.length} 个：${profileProbe.bad.slice(0, 3).join('、')}`)
+  }
+
+  if (!opt.apply) return dryRun(opt, faces, set, plan, profilePlan, root, backupRoot, pre, profileProbe)
+
+  // ── ⑤ 备份（先备份，再投递）───────────────────────────────────────────
+  const tag = `${tagStamp()}-${faces.join('-')}`
+  const bak = backupRemote(opt, root, backupRoot, tag, faces, set, plan)
+
+  // ── ⑥ rsync（无 --delete；排除表双保险）────────────────────────────────
+  rsyncDeliver(opt, root, set, excludes)
+
+  // ── ⑦ 权限归一（按 git 索引模式）+ 复核 ────────────────────────────────
+  const modeBad = normalizeModes(opt, root, set.files)
+
+  // ── ⑧ 双端 sha256（逐文件；含新增/缺失）───────────────────────────────
+  const shaBad = verifyShas(opt, root, set.files, localSha)
+
+  // ── ⑨ profile 副本（面含 plugins/presets 时）───────────────────────────
+  const prof = needProfile ? applyProfile(opt, root, profilePlan) : null
+
+  // ── ⑩ 回滚命令（落远端 + 打印；声明耦合组）────────────────────────────
+  const rollback = writeRollback(opt, root, backupRoot, bak.tag, faces, set, plan, profilePlan, preMap)
+
+  // ── ⑪ 连续性自检（可选）───────────────────────────────────────────────
+  const selfRes = opt.selfCheck ? selfCheck(opt, root, pre) : null
+
+  // ── 结论 ──────────────────────────────────────────────────────────────
+  say('')
+  say('  ── 结论 ──')
+  ok(`投递完成：${set.files.length} 个文件（新增 ${plan.added.length} / 更新 ${plan.changed.length} / 一致 ${plan.same.length}）`)
+  ok(`模式不符 = ${modeBad.length}（按 git 索引模式归一 644/755）`)
+  ok(`双端 sha256 不符 = ${shaBad.length}`)
+  if (prof) ok(`profile 副本：修复 ${prof.fixed} ｜ 新增落地 ${prof.linked} ｜ 跳过（未安装）${prof.skipped} ｜ 仍不符 ${prof.stillBad.length}`)
+  else if (!opt.profileCheck) info('profile 副本核对：已用 --no-profile **关闭**（面里含 plugins/presets，但本次不核）')
+  else info('profile 副本核对：投递面不含 plugins/presets ⇒ 不适用（这是正常姿态）')
+  info(`备份：${bak.dir}（tar sha256 ${bak.tarSha.slice(0, 12)}…，MANIFEST.txt 已写）`)
+  say('')
+  printRollback(rollback, opt)
+  if (selfRes) printSelfCheck(selfRes)
+
+  const hardFail = modeBad.length > 0 || shaBad.length > 0 || (prof && prof.stillBad.length > 0) || (selfRes && !selfRes.ok)
+  if (hardFail) {
+    bad('投递后核对未全绿 ⇒ 走回滚（上面的命令可直接粘贴）')
+    throw new DeliveryFailure('投递或核对失败')
+  }
+  ok('全部核对通过（双端 sha / 模式 / profile / 回滚脚本已就位）')
+  say('  提示：本脚本**不重启**任何东西 —— plugins/(host) 与 plist 改动需**用户手动**重启才生效；')
+  say('        flow-trigger* 每轮从磁盘重读 ⇒ 投递器/驱动器改动不必重启。')
+  return EXIT.OK
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 五、步骤实现
+// ══════════════════════════════════════════════════════════════════════════
+
+const tagStamp = () => {
+  const d = new Date()
+  const p = (n, w = 2) => String(n).padStart(w, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+
+const expandTilde = (p, home) => (p === '~' ? home : p.startsWith('~/') ? `${home}/${p.slice(2)}` : p)
+
+/** 取远端 HOME（前置：目标可达；exit 3 挡住了"不可达"）。 */
+function remoteHome(target) {
+  const r = sshRun(target, 'printf \'%s\\n\' "$HOME"\n', [], { timeoutMs: 30000 })
+  if (r.code !== 0 || !r.out.trim()) {
+    const why = r.timeout ? '超时' : `exit ${r.code}`
+    throw new Blocked(`目标不可达（${target}，${why}）：${(r.err || r.out).trim().split('\n').slice(-1)[0] || '无输出'}`)
+  }
+  return r.out.trim().split('\n').pop().trim()
+}
+
+function probeTarget(opt, root, files, _unused) {
+  const script = probeScript(root, files.map((f) => f.rel), opt.selfCheck ? LEDGER_PROBE : '')
+  const r = sshRun(opt.target, script)
+  if (r.code !== 0) throw new Blocked(`远端只读探测失败（exit ${r.code}）：${r.err.trim().split('\n').slice(-1)[0] || ''}`)
+  const rows = parseTsv(r.out)
+  const meta = {}; const pre = new Map()
+  for (const f of rows) {
+    if (f[0] === 'PRE') pre.set(f[1], { sha: f[2], mode: f[3] })
+    else if (f[0]) meta[f[0]] = f.slice(1).join('\t')
+  }
+  if (meta.REMOTE_ROOT !== '1') warn(`远端落点还不存在（${root}）—— 将由 rsync 创建（首次投递形态）`)
+  info(`远端：${meta.REMOTE_UNAME || '?'} ｜ HOME=${meta.REMOTE_HOME || '?'}`)
+  return { meta, pre }
+}
+
+/** dry-run：**零写入** —— 只打印将要执行的命令与分类，不跑 rsync、不 chmod、不建备份。 */
+function dryRun(opt, faces, set, plan, profilePlan, root, backupRoot, pre, profileProbe) {
+  say('')
+  say('  ── dry-run 计划（**零写入**：不跑 rsync、不 chmod、不建备份目录）──')
+  const tag = `${tagStamp()}-${faces.join('-')}`
+  info(`备份将落：${backupRoot}/${tag}/（faces.tar.gz 600 + MANIFEST.txt）`)
+  const listRel = writeFilesFrom(set.files)                  // 本地临时清单（不在远端写任何东西）
+  info(`rsync 命令：${rsyncArgs(opt, root, listRel, [], true).join(' ')}`)
+  rmSync(dirname(listRel), { recursive: true, force: true })
+  info(`权限归一：按 git 索引模式 chmod（644×${set.files.filter((f) => f.mode === '644').length} / 755×${set.files.filter((f) => f.mode === '755').length}）`)
+  info(`双端 sha256：逐文件核对 ${set.files.length} 个（含新增/缺失）`)
+  if (profilePlan.length) {
+    const p = profileProbe || { ok: 0, drifted: [], missing: [], skipped: [] }
+    info(`profile 副本：将核 ${profilePlan.length} 个（面含 ${faces.filter((f) => PROFILE_FACES.includes(f)).join('/')}）`
+      + `｜一致 ${p.ok} ｜待 ln -f 修复 ${p.drifted.length} ｜待落地（新增）${p.missing.length}`
+      + ` ｜待投递后核对 ${(p.pre || []).length} ｜跳过 ${p.skipped.length}`)
+  }
+  if (pre && pre.meta && pre.meta.LEDGER_SHA) info(`台账：sha ${String(pre.meta.LEDGER_SHA).slice(0, 12)}… ｜ planned=${pre.meta.LEDGER_PLANNED}`)
+  say('')
+  say('  ── 回滚 ──')
+  info('dry-run 未投递 ⇒ 无需回滚（真执行时会生成并落远端 rollback.sh，控制台原样打印）')
+  if (opt.coupled.length) printCoupled(opt.coupled)
+  say('')
+  ok(`dry-run 结束：**零写入**（远端只做了 printf/stat/shasum 只读探测；新增 ${plan.added.length} / 更新 ${plan.changed.length} / 一致 ${plan.same.length}）`)
+  return EXIT.OK
+}
+
+/** 本地临时 `--files-from` 清单（只列文件，不列目录 ⇒ `-a` 不会顺手推整棵树）。 */
+function writeFilesFrom(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'deliver-customer-'))
+  const p = join(dir, 'files-from.txt')
+  writeFileSync(p, files.map((f) => f.rel).join('\n') + '\n')
+  return p
+}
+
+function rsyncArgs(opt, root, listFile, excludes, dryRun) {
+  const a = ['-az', '--no-owner', '--no-group', `--files-from=${listFile}`]
+  if (dryRun) a.push('--dry-run')
+  for (const e of excludes) a.push(`--exclude=${e}`)         // 双保险：清单生成有 bug 也不推垃圾
+  a.push('-e', 'ssh', `${opt.source}/`, `${opt.target}:${root}/`)
+  return a                                                  // ⛔ 永不出现 --delete
+}
+
+function rsyncDeliver(opt, root, set, excludes) {
+  const listRel = writeFilesFrom(set.files)
+  try {
+    const r = spawnSync('rsync', rsyncArgs(opt, root, listRel, excludes, false), { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 600000 })
+    if (r.error || r.status !== 0) {
+      throw new DeliveryFailure(`rsync 失败（exit ${r.status}）：${String(r.stderr || r.error?.message || '').trim().split('\n').slice(-1)[0]}`)
+    }
+    ok(`rsync 投递完成（-az --no-owner --no-group --files-from，无 --delete）`)
+  } finally {
+    rmSync(dirname(listRel), { recursive: true, force: true })
+  }
+}
+
+/** 远端备份：面 tar（600）+ sha256 + MANIFEST.txt（含投递前逐文件 sha/模式/新增标记）。 */
+function backupRemote(opt, root, backupRoot, tag, faces, set, plan) {
+  const newSet = new Set(plan.added)
+  const manifest = set.files.map((f) => `${f.rel}\t${newSet.has(f.rel) ? '(新增)' : (plan.changed.includes(f.rel) ? 'update' : 'same')}`).join('\n')
+  const script = `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+BAK=${shq(backupRoot)}
+TAG=${shq(tag)}
+mkdir -p "$BAK" || { printf 'ERR\\tmkdir\\n'; exit 3; }
+# tag 唯一化：同一秒内两次投递（或两个运维同时投）不许互相覆盖备份
+keep="$TAG"; n=1
+while [ -e "$BAK/$TAG" ]; do TAG="$keep-$n"; n=$((n + 1)); done   # ⚠️ 后缀加在**名字**上，不是路径上
+mkdir -p "$BAK/$TAG" || { printf 'ERR\tmkdir\n'; exit 3; }
+printf 'TAG\t%s\n' "$TAG"
+faces=(); absent=()
+${faces.map((f) => `[ -e "$ROOT/${f}" ] && faces+=(${shq(f)}) || absent+=(${shq(f)})`).join('\n')}
+# 首次投递形态：远端可能**一个面都还没有**（全新客户机）⇒ 这不是失败 —— 备份里没有 tar，
+# 回滚 = 删掉本次新增的文件（rollback.sh 会跳过解包）。⛔ 不能因为"没得备份"就拒绝投递。
+if [ "\${#faces[@]}" -gt 0 ]; then
+  tar -czf "$BAK/$TAG/faces.tar.gz" -C "$ROOT" "\${faces[@]}" || { printf 'ERR\\ttar\\n'; exit 1; }
+  chmod 600 "$BAK/$TAG/faces.tar.gz"
+  tar_sha="$(sha_of "$BAK/$TAG/faces.tar.gz")"
+  printf '%s\\n' "$tar_sha" > "$BAK/$TAG/faces.tar.gz.sha256"; chmod 600 "$BAK/$TAG/faces.tar.gz.sha256"
+else
+  tar_sha='-'
+fi
+{
+  printf 'tag\\t%s\\n' "$TAG"
+  printf 'at\\t%s\\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  printf 'root\\t%s\\n' "$ROOT"
+  # ⚠️ 末尾的 :- 是**必须**的：客户机默认 bash 是 3.2（macOS /bin/bash），set -u 下**空数组**的
+  #    [*] 展开会报 unbound variable（本批实测踩到：首次投递时 faces / absent 都可能为空）
+  printf 'faces\\t%s\\n' "\${faces[*]:-}"
+  printf 'absent_faces\\t%s\\n' "\${absent[*]:-}"
+  printf 'tar_sha256\\t%s\\n' "$tar_sha"
+  printf 'coupled\\t%s\\n' ${shq(opt.coupled.join(' | ') || '(未声明)')}
+  printf -- '--- 投递前逐文件状态（rel<TAB>state；sha/模式见 rollback.sh）\\n'
+  cat <<'__ARGENT_MANIFEST__'
+${manifest}
+__ARGENT_MANIFEST__
+} > "$BAK/$TAG/MANIFEST.txt"
+chmod 600 "$BAK/$TAG/MANIFEST.txt"
+printf 'TAR\\t%s\\t%s\\n' "$tar_sha" "$BAK/$TAG/faces.tar.gz"
+`
+  const r = sshRun(opt.target, script)
+  const rows = parseTsv(r.out)
+  const finalTag = (rows.find((x) => x[0] === 'TAG') || [])[1] || tag
+  const row = rows.find((x) => x[0] === 'TAR')
+  if (r.code !== 0 || !row) {
+    const err = parseTsv(r.out).find((x) => x[0] === 'ERR')
+    const why = (r.err || r.out).trim().split('\n').slice(-1)[0] || '无输出'
+    throw new DeliveryFailure(`备份失败（exit ${r.code}${err ? `，${err.slice(1).join(' ')}` : ''}）：${why} —— ⛔ 不投递：先备份再投递是硬顺序`)
+  }
+  if (row[1] === '-') {
+    warn('远端**一个投递面都还不存在**（首次投递形态）⇒ 备份无 tar（回滚 = 删掉本次新增文件）')
+    return { dir: `${backupRoot}/${finalTag}`, tarSha: '-', tarPath: '-', tag: finalTag }
+  }
+  ok(`备份完成：${row[2]}（sha256 ${row[1].slice(0, 12)}…，600，MANIFEST.txt）`)
+  return { dir: `${backupRoot}/${finalTag}`, tarSha: row[1], tarPath: row[2], tag: finalTag }
+}
+
+/** 权限归一（按 git 索引模式）+ 复核"模式不符 = 0"。 */
+function normalizeModes(opt, root, files) {
+  const chmod = (mode, list) => {
+    if (!list.length) return
+    const script = `ROOT=${shq(root)}
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  chmod ${mode} "$ROOT/$rel" 2>/dev/null || printf 'CHMOD_FAIL\\t%s\\n' "$rel"
+done <<'${SENTINEL}'
+${list.join('\n')}
+${SENTINEL}
+`
+    const r = sshRun(opt.target, script)
+    for (const row of parseTsv(r.out)) if (row[0] === 'CHMOD_FAIL') bad(`chmod 失败：${row[1]}`)
+  }
+  chmod('755', files.filter((f) => f.mode === '755').map((f) => f.rel))
+  chmod('644', files.filter((f) => f.mode === '644').map((f) => f.rel))
+  // 复核：远端实际模式 vs git 索引模式
+  const script = `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  p="$ROOT/$rel"
+  if [ -f "$p" ]; then printf 'MODE\\t%s\\t%s\\n' "$rel" "$(st_mode "$p")"
+  else printf 'MODE\\t%s\\t-\\n' "$rel"; fi
+done <<'${SENTINEL}'
+${files.map((f) => f.rel).join('\n')}
+${SENTINEL}
+`
+  const r = sshRun(opt.target, script)
+  const want = new Map(files.map((f) => [f.rel, f.mode]))
+  const mism = []
+  for (const row of parseTsv(r.out)) {
+    if (row[0] !== 'MODE') continue
+    if (want.get(row[1]) !== row[2]) mism.push(`${row[1]}（期望 ${want.get(row[1])} 实际 ${row[2]}）`)
+  }
+  for (const m of mism.slice(0, 10)) bad(`模式不符：${m}`)
+  return mism
+}
+
+/** 双端 sha256：逐文件（含**新增/缺失**），任一不符即点名。 */
+function verifyShas(opt, root, files, localSha) {
+  const script = `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  p="$ROOT/$rel"
+  if [ -f "$p" ]; then printf 'SHA\\t%s\\t%s\\n' "$rel" "$(sha_of "$p")"
+  else printf 'MISSING\\t%s\\t-\\n' "$rel"; fi
+done <<'${SENTINEL}'
+${files.map((f) => f.rel).join('\n')}
+${SENTINEL}
+`
+  const r = sshRun(opt.target, script)
+  if (r.code !== 0) throw new DeliveryFailure(`远端 sha 计算失败（exit ${r.code}）：${r.err.trim().split('\n').slice(-1)[0] || ''}`)
+  const rows = parseTsv(r.out)
+  const seen = new Set()
+  const badList = []
+  for (const row of rows) {
+    if (row[0] === 'MISSING') { badList.push(`${row[1]}（远端缺失）`); continue }
+    if (row[0] !== 'SHA') continue
+    seen.add(row[1])
+    if (localSha.get(row[1]) !== row[2]) badList.push(`${row[1]}（本地 ${String(localSha.get(row[1])).slice(0, 12)}… ≠ 远端 ${String(row[2]).slice(0, 12)}…）`)
+  }
+  for (const f of files) if (!seen.has(f.rel)) badList.push(`${f.rel}（未核对到 —— 远端无输出）`)
+  for (const b of badList.slice(0, 20)) bad(`双端 sha 不符：${b}`)
+  if (badList.length > 20) bad(`…另有 ${badList.length - 20} 个未列出`)
+  return badList
+}
+
+/** 面含 plugins/presets 时的 profile 副本行（远端路径在 node 侧算好）。 */
+function profileRows(opt, root, home, faces, files) {
+  const profRoot = expandTilde(opt.profileRoot, home)
+  const presetsRoot = opt.presetsRoot ? expandTilde(opt.presetsRoot, home) : `${dirname(profRoot)}/.agent-presets`
+  const rows = []
+  for (const f of files) {
+    const [face, ...rest] = f.rel.split('/')
+    if (face === 'plugins') {
+      const pkg = rest[0]
+      if (!pkg || rest.length < 2) continue
+      rows.push({ kind: 'PLUGIN', rel: f.rel, dst: `${profRoot}/${opt.profile}/node_modules/${rest.join('/')}`, guard: `${profRoot}/${opt.profile}/node_modules/${pkg}`, pkg })
+    } else if (face === 'presets') {
+      const id = rest[0]
+      if (!id || rest.length < 2) continue
+      rows.push({ kind: 'PRESET', rel: f.rel, dst: `${presetsRoot}/${rest.join('/')}`, guard: `${presetsRoot}/${id}`, pkg: id })
+    }
+  }
+  return rows
+}
+
+/** profile 副本核对/修复块（forward 与 rollback 共用：同 inode + nlink≥2 + md5，`ln -f` 修复）。 */
+function profileScript(root, rows, apply) {
+  return `ROOT=${shq(root)}
+APPLY=${apply ? 1 : 0}
+while IFS=$'\\t' read -r kind rel dst guard; do
+  [ -n "$rel" ] || continue
+  src="$ROOT/$rel"
+  if [ ! -d "$guard" ]; then printf 'PROF_SKIP\\t%s\\t%s\\n' "$rel" "\${guard##*/} 未安装"; continue; fi
+  if [ ! -f "$src" ]; then printf 'PROF_PRE\\t%s\\t待投递后核对（源文件还没到客户机）\\n' "$rel"; continue; fi
+  if [ -f "$dst" ]; then
+    m1="$(md5_of "$src")"; m2="$(md5_of "$dst")"
+    i1="$(st_ino "$src")"; i2="$(st_ino "$dst")"; nl="$(st_nlink "$dst")"
+    if [ "$m1" = "$m2" ] && [ "$i1" = "$i2" ] && [ "$nl" -ge 2 ]; then printf 'PROF_OK\\t%s\\t-\\n' "$rel"; continue; fi
+    if [ "$APPLY" != "1" ]; then printf 'PROF_DRIFT\\t%s\\tmd5=%s inode=%s nlink=%s（将 ln -f）\\n' "$rel" "$([ "$m1" = "$m2" ] && printf same || printf diff)" "$([ "$i1" = "$i2" ] && printf same || printf diff)" "$nl"; continue; fi
+    mkdir -p "$(dirname "$dst")"
+    ln -f "$src" "$dst" 2>/dev/null || cp -p "$src" "$dst"
+    if [ "$(md5_of "$src")" = "$(md5_of "$dst")" ] && [ "$(st_ino "$src")" = "$(st_ino "$dst")" ] && [ "$(st_nlink "$dst")" -ge 2 ]; then
+      printf 'PROF_FIX\\t%s\\t-\\n' "$rel"
+    elif [ "$(md5_of "$src")" = "$(md5_of "$dst")" ]; then
+      printf 'PROF_WARN\\t%s\\tmd5 已一致但拿不到硬链接（跨设备/权限？）\\n' "$rel"
+    else
+      printf 'PROF_BAD\\t%s\\t修复后 md5 仍不一致\\n' "$rel"
+    fi
+  else
+    if [ "$APPLY" != "1" ]; then printf 'PROF_NEW\\t%s\\tprofile 缺该文件（将 ln -f 落地）\\n' "$rel"; continue; fi
+    mkdir -p "$(dirname "$dst")"
+    ln -f "$src" "$dst" 2>/dev/null || cp -p "$src" "$dst"
+    if [ -f "$dst" ] && [ "$(md5_of "$src")" = "$(md5_of "$dst")" ]; then printf 'PROF_LINK\\t%s\\t-\\n' "$rel"
+    else printf 'PROF_BAD\\t%s\\t新增文件落 profile 失败\\n' "$rel"; fi
+  fi
+done <<'${SENTINEL}'
+${rows.map((r) => `${r.kind}\t${r.rel}\t${r.dst}\t${r.guard}`).join('\n')}
+${SENTINEL}
+`
+}
+
+/** profile 副本**只读**预检（APPLY=0）：dry-run 的答案，也是 apply 前的现状快照。 */
+function probeProfile(opt, root, rows) {
+  if (!rows.length) return { ok: 0, drifted: [], missing: [], skipped: [], bad: [], pre: [] }
+  const r = sshRun(opt.target, `${REMOTE_PREAMBLE}${profileScript(root, rows, false)}`)
+  const out = { ok: 0, drifted: [], missing: [], skipped: [], bad: [], pre: [] }
+  for (const row of parseTsv(r.out)) {
+    if (row[0] === 'PROF_OK') out.ok += 1
+    else if (row[0] === 'PROF_PRE') out.pre.push(row[1])
+    else if (row[0] === 'PROF_DRIFT') out.drifted.push(`${row[1]}（${row[2]}）`)
+    else if (row[0] === 'PROF_NEW') out.missing.push(row[1])
+    else if (row[0] === 'PROF_SKIP') out.skipped.push(row[1])
+    else if (row[0] === 'PROF_BAD') out.bad.push(`${row[1]}（${row[2]}）`)
+  }
+  return out
+}
+
+function applyProfile(opt, root, rows) {
+  const r = sshRun(opt.target, `${REMOTE_PREAMBLE}${profileScript(root, rows, true)}`)
+  const out = { fixed: 0, linked: 0, skipped: 0, warned: 0, stillBad: [], drifted: 0 }
+  for (const row of parseTsv(r.out)) {
+    if (row[0] === 'PROF_OK') continue
+    if (row[0] === 'PROF_FIX') out.fixed += 1
+    else if (row[0] === 'PROF_LINK') out.linked += 1
+    else if (row[0] === 'PROF_SKIP') out.skipped += 1
+    else if (row[0] === 'PROF_WARN') { out.warned += 1; warn(`profile 硬链接未建立（内容已一致）：${row[1]} —— ${row[2]}`) }
+    else if (row[0] === 'PROF_BAD') out.stillBad.push(`${row[1]}（${row[2]}）`)
+    else if (row[0] === 'PROF_DRIFT') out.drifted += 1
+  }
+  for (const b of out.stillBad) bad(`profile 副本：${b}`)
+  return out
+}
+
+/** 生成回滚脚本（落远端 700 + 控制台可粘贴），内含：解包 → 删新增 → 恢复模式 → 复核 sha → 重链 profile。 */
+function writeRollback(opt, root, backupRoot, tag, faces, set, plan, profileRowsAll, preMap) {
+  const newSet = new Set(plan.added)
+  const existed = set.files.filter((f) => !newSet.has(f.rel))
+  // ⚠️ 核对基准必须是**投递前**的 sha 与模式（`preMap`），不是投递后的新值 ——
+  // 回滚后内容 = 投递前内容；拿新 sha 去比会把"回滚成功"判成失败（本次实测踩到）。
+  const expected = existed.map((f) => `${f.rel}\t${(preMap.get(f.rel) || {}).sha || '-'}`).join('\n')
+  const dir = `${backupRoot}/${tag}`
+  const script = `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+BAK=${shq(dir)}
+if [ -f "$BAK/faces.tar.gz" ]; then
+  tar -xzf "$BAK/faces.tar.gz" -C "$ROOT" || { printf 'ROLLBACK_FAIL\\ttar 解包失败\\n'; exit 1; }
+else
+  printf 'ROLLBACK_INFO\\t无 tar（首次投递形态）：只删本次新增文件\\n'
+fi
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  rm -f "$ROOT/$rel"
+done <<'${SENTINEL}'
+${plan.added.join('\n')}
+${SENTINEL}
+while IFS=$'\\t' read -r mode rel; do
+  [ -n "$rel" ] || continue
+  [ -e "$ROOT/$rel" ] && chmod "$mode" "$ROOT/$rel"
+done <<'${SENTINEL}'
+${existed.map((f) => `${(preMap.get(f.rel) || {}).mode || f.mode}\t${f.rel}`).join('\n')}
+${SENTINEL}
+bad=0
+while IFS=$'\\t' read -r rel want; do
+  [ -n "$rel" ] || continue
+  p="$ROOT/$rel"
+  if [ ! -f "$p" ]; then printf 'ROLLBACK_BAD\\t%s\\t缺文件\\n' "$rel"; bad=$((bad + 1)); continue; fi
+  got="$(sha_of "$p")"
+  [ "$got" = "$want" ] || { printf 'ROLLBACK_BAD\\t%s\\tsha 不符\\n' "$rel"; bad=$((bad + 1)); }
+done <<'${SENTINEL}'
+${expected}
+${SENTINEL}
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  [ -e "$ROOT/$rel" ] && { printf 'ROLLBACK_BAD\\t%s\\t本次新增文件未被删除\\n' "$rel"; bad=$((bad + 1)); }
+done <<'${SENTINEL}'
+${plan.added.join('\n')}
+${SENTINEL}
+${profileRowsAll.length ? profileScript(root, profileRowsAll, true) : ''}
+if [ "$bad" -eq 0 ]; then printf 'ROLLBACK_OK\\t%s\\n' "$ROOT"; exit 0; fi
+printf 'ROLLBACK_FAIL\\t%s 个文件未恢复到投递前\\n' "$bad"; exit 1
+`
+  // 落远端（700），并把"怎么用"写进备份目录
+  const r = sshRun(opt.target, `BAK=${shq(dir)}
+mkdir -p "$BAK"
+cat > "$BAK/rollback.sh" <<'__ARGENT_ROLLBACK__'
+${script}
+__ARGENT_ROLLBACK__
+chmod 700 "$BAK/rollback.sh"
+printf 'WROTE\\t%s\\n' "$BAK/rollback.sh"
+`)
+  const wrote = parseTsv(r.out).find((x) => x[0] === 'WROTE')
+  if (r.code !== 0 || !wrote) throw new DeliveryFailure(`回滚脚本落盘失败（exit ${r.code}）：${r.err.trim().split('\n').slice(-1)[0] || ''}`)
+  return { dir, tag, path: wrote[1], selfRun: `ssh ${opt.target} bash ${wrote[1]}`, tarSha: null }
+}
+
+function printRollback(rb, opt) {
+  say('  ── 回滚（可直接粘贴；脚本已落客户机，700）──')
+  say(`    ssh ${opt.target} bash ${rb.path}`)
+  info(`备份目录：${rb.dir}（faces.tar.gz 600 + sha256 + MANIFEST.txt + rollback.sh）`)
+  info('回滚做什么：解包回投递前 → 删掉本次**新增**的文件 → 按投递前模式 chmod → 逐文件复核 sha → 重链 profile 副本')
+  if (opt.coupled.length) printCoupled(opt.coupled)
+  info('⛔ 本脚本**不重启**服务：若本次改动含 plugins/(host) 或 plist，回滚后需**用户手动**重启才生效')
+}
+
+function printCoupled(groups) {
+  say('')
+  say('  ⚠️ 耦合回滚组（**必须一起回滚**，只回一半会让流程变哑）：')
+  for (const g of groups) say(`     ⇄ ${g}`)
+  info('例：日志移出 /tmp 后只回滚"读 /tmp 的旧唤醒脚本" ⇒ 四条流程全哑 —— 必须连同 plist 一起回滚并重启')
+}
+
+const selfCheckLedgerLine = (pre) => (pre && pre.meta ? pre.meta : {})
+
+/** 连续性自检：跑**仓库既有**判据（只读），异常 ⇒ 结论 + 提示回滚。 */
+function selfCheck(opt, root, pre) {
+  say('')
+  say('  ── 连续性自检（客户机侧**只读**，跑仓库既有判据）──')
+  const script = `${REMOTE_PREAMBLE}ROOT=${shq(root)}
+if command -v node >/dev/null 2>&1 && [ -f "$ROOT/scripts/check-production-home.mjs" ]; then
+  out="$(cd "$ROOT" && node scripts/check-production-home.mjs --role production 2>&1)"; rc=$?
+  printf 'PRODHOME\\t%s\\t%s\\n' "$rc" "$(printf '%s' "$out" | tail -1)"
+else
+  printf 'PRODHOME\\t-\\tnode 或 check-production-home.mjs 不在位\\n'
+fi
+${LEDGER_PROBE}`
+  const r = sshRun(opt.target, script)
+  const rows = parseTsv(r.out)
+  const get = (k) => (rows.find((x) => x[0] === k) || [])[1]
+  const rc = get('PRODHOME')
+  const prodLine = (rows.find((x) => x[0] === 'PRODHOME') || [])[2] || ''
+  const led = get('LEDGER_SHA')
+  const planned = get('LEDGER_PLANNED')
+  const preLed = selfCheckLedgerLine(pre).LEDGER_SHA
+  const prePlanned = selfCheckLedgerLine(pre).LEDGER_PLANNED
+  const dPlanned = (planned !== '-' && prePlanned !== undefined && prePlanned !== '-') ? String(Number(planned) - Number(prePlanned)) : '?'
+  const prodOk = rc === '0'
+  const unknown = rc === '-'
+  if (prodOk) ok(`生产归属（check-production-home --role production）：${prodLine}`)
+  else if (unknown) warn(`生产归属：**未判定**（无法自检 —— ${prodLine}）；按"没有坏证据"处理，不算失败`)
+  else bad(`生产归属异常（exit ${rc}）：${prodLine}`)
+  info(`台账 sha：${led === '-' || !led ? '不可读' : led.slice(0, 12) + '…'}${preLed && preLed !== '-' ? `（投递前 ${preLed.slice(0, 12)}… ${preLed === led ? '未变' : '**已变**'}）` : ''}`)
+  info(`planned：${planned}｜Δplanned=${dPlanned}${dPlanned !== '0' && dPlanned !== '?' ? '（投递窗口内台账有变动：生产在跑属正常，但若**本不该**触发流程请人工核）' : ''}`)
+  return { ok: prodOk || unknown, unknown, rc, prodLine, led, planned, dPlanned }
+}
+
+function printSelfCheck(s) {
+  say('')
+  const verdict = s.ok ? (s.unknown ? '⚠️ 未判定（没有坏证据，但也没能自证）' : '✅ 正常') : '❌ 异常 ⇒ 建议回滚（上面的命令可直接粘贴）'
+  say(`  ── 自检结论：${verdict} ──`)
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 入口
+// ══════════════════════════════════════════════════════════════════════════
+function runCli() {
+  try {
+    return main()
+  } catch (e) {
+    if (e instanceof UsageError) { bad(e.message); return EXIT.USAGE }
+    if (e instanceof Blocked) { bad(e.message); say('  （前置条件不满足 ⇒ exit 3；未做任何投递）'); return EXIT.BLOCKED }
+    if (e instanceof DeliveryFailure) { bad(e.message); return EXIT.FAIL }
+    bad(`内部错误：${e && e.stack ? e.stack : e}`)
+    return EXIT.FAIL
+  }
+}
+
+if (isDirectRun(import.meta.url)) process.exit(runCli())