@shendeguize/remote-dsh-center 0.4.0

package/src/lib/proto.js

@@ -0,0 +1,457 @@
+/**
+ * 远端协议模板构建 + 输出解析（规格 = 12 文档 §1、§3、§7）。
+ *
+ * 统一包装约定（12 §0）：最终 argv 为 spawn('ssh', [...COMMON_SSH_OPTS, host, 'sh -c ' + shq(body)])。
+ * body 为单行 POSIX 脚本，语句以 '; ' 连接；唯一后台化语句 `nohup … &` 必须以 '; ' 与
+ * 前文隔离——若用 && 链接，`A && B &` 会把整个 AND 列表放入后台子壳，$! 拿到的是子壳 PID。
+ */
+
+import { DshError } from './errors.js';
+import { assertEnvKey, assertInt, assertSafeName, shq, workdirToken } from './shq.js';
+import { REMOTE_DIR } from '../defaults.js';
+
+/** 超时与轮询参数（12 §3 汇总）——集中此处便于调优。 */
+export const PROTO_TIMING = Object.freeze({
+  onceTimeoutMs: 15_000, // 单条一次性 ssh 命令（02 §5.3）
+  scpTimeoutMs: 60_000, // 每个 patch 文件
+  startBudgetMs: 90_000, // start 队列任务总预算
+  pollFirstDelayMs: 1_000, // POLL 首拍 T+1s
+  pollIntervalMs: 2_000, // 此后每 2s 一拍
+  pollMaxAttempts: 5, // 最多 5 拍
+  stopGraceSec: 3, // STOP 脚本内 TERM→KILL 间隔
+  logTailLines: 50, // FAIL 收尾取日志尾行数
+});
+
+const remotePath = (rel) => `$HOME/${REMOTE_DIR}/${rel}`;
+
+// ── §1.1 探测协议 ────────────────────────────────────────────────────────
+
+/** 无注入值，模板为常量。 */
+export function buildProbeScript() {
+  return [
+    'echo "DSH_BIN=$(command -v dsh || echo MISSING)"',
+    'if command -v dsh >/dev/null 2>&1; then echo "DSH_VERSION=$(dsh --version 2>/dev/null | head -n 1)"; fi',
+    'H="${DSH_HOME:-$HOME/.dsh}"',
+    "printf 'DSH_HOME=%s\\n' \"$H\"",
+    'if [ -d "$H/profiles/web" ]; then echo "PROFILE_WEB=yes"; else echo "PROFILE_WEB=no"; fi',
+    'echo "RUNNING_DSH_WEB<<EOF"',
+    // `[d]sh` 只躲过 grep 自己；执行本脚本的那层 sh -c 仍会被命中——它的命令行里
+    // 既有 command -v dsh 又有 profiles/web。故再按 $$（本 shell 的 pid，子 shell 中
+    // 不变）排掉自身那行，否则每次探测都凭空多出一个「手动实例」。
+    'ps -eo pid,args | grep "[d]sh.*web" | grep -v "^ *$$ " || true',
+    'echo "EOF"',
+    'echo "PROBE_DONE=yes"',
+  ].join('; ');
+}
+
+// ── §1.2 拉起协议 ────────────────────────────────────────────────────────
+
+/**
+ * @param {{logName:string, port:number|'0', env?:Record<string,string>,
+ *          patchRemoteNames?:string[], extraArgs?:string[], workdir?:string|null}} p
+ */
+export function buildLaunchScript({
+  logName, port, env = {}, patchRemoteNames = [], extraArgs = [], workdir = null,
+}) {
+  assertSafeName(logName);
+  const portTok = assertInt(port, { min: 1, max: 65535, allowZero: true });
+
+  let envp = '';
+  const envEntries = Object.entries(env);
+  if (envEntries.length > 0) {
+    envp = `env ${envEntries.map(([k, v]) => `${assertEnvKey(k)}=${shq(String(v))}`).join(' ')} `;
+  }
+
+  const patchArgs = patchRemoteNames
+    .map((n) => ` --patch "${remotePath(`patches/${assertSafeName(n)}`)}"`)
+    .join('');
+  const extra = extraArgs.map((a) => ` ${shq(String(a))}`).join('');
+
+  // 前置语句以 '; ' 连接到 nohup（12 §0：若用 '&&'，`A && B &` 会把整个 AND 列表放入
+  // 后台子壳，$! 拿到的是子壳 PID）。'&' 本身即后台化语句与 echo 之间的分隔符——
+  // 其后不能再跟 ';'（POSIX 语法错误）。
+  // workdir=null 时整段不生成，模板逐字退回补丁 01 之前的形态（零回归面）。
+  // 落地物路径（日志、patches、--patch 参数）全是 $HOME 绝对形态，cd 影响不到它们。
+  const cdStmt = workdir === null
+    ? null
+    : (() => {
+      const wd = workdirToken(workdir);
+      return `cd -- ${wd} || { echo "ERR=workdir"; printf 'WD=%s\\n' ${wd}; exit 8; }`;
+    })();
+
+  const prelude = [
+    `mkdir -p "${remotePath('patches')}" || { echo "ERR=mkdir"; exit 9; }`,
+    `LOG="${remotePath(logName)}"`,
+    ': > "$LOG"',
+    ...(cdStmt ? [cdStmt] : []),
+  ].join('; ');
+  // --patch 是 dsh 启动器自己的旗标，必须紧跟 `web` 排在 web app 旗标之前：真机
+  // （dsh 0.1.0-rc.7）上 `dsh web --no-open ... --patch P` 会被 web app 判为
+  // unknown option '--patch' 而直接退出。extraArgs 反过来是 app 参数，仍留在尾部。
+  const launch = `nohup ${envp}dsh web${patchArgs} --no-open --host 127.0.0.1 --port ${portTok}${extra} > "$LOG" 2>&1 < /dev/null &`;
+  return `${prelude}; ${launch} echo "PID=$!"`;
+}
+
+/** 一次往返同时取「URL / 进程存活 / 绑定错误」，驱动 §3 状态机少一半 ssh 轮次。 */
+export function buildLaunchPollScript({ logName, pid }) {
+  assertSafeName(logName);
+  const pidTok = assertInt(pid, { min: 1, max: 4_294_967_295 });
+  return [
+    `LOG="${remotePath(logName)}"`,
+    'U=$(grep -o "dsh web: http://127\\.0\\.0\\.1:[0-9][0-9]*" "$LOG" 2>/dev/null | head -n 1)',
+    "if [ -n \"$U\" ]; then printf 'URL=%s\\n' \"$U\"; fi",
+    `if kill -0 ${pidTok} 2>/dev/null; then echo "ALIVE=yes"; else echo "ALIVE=no"; fi`,
+    'if grep -qiE "EADDRINUSE|address already in use" "$LOG" 2>/dev/null; then echo "BIND_ERR=yes"; else echo "BIND_ERR=no"; fi',
+    'echo "POLL_DONE=yes"',
+  ].join('; ');
+}
+
+/** manager 精析：对 kv.URL 再验并抽取 actualPort（12 §1.2 正则终稿）。 */
+const URL_RE = /^dsh web: http:\/\/127\.0\.0\.1:(\d{1,5})$/;
+
+export function parseLaunchUrl(url) {
+  const m = URL_RE.exec(String(url).trim());
+  if (!m) return null;
+  const p = Number(m[1]);
+  return p >= 1 && p <= 65535 ? p : null;
+}
+
+// ── §1.3 复核与停止协议 ──────────────────────────────────────────────────
+
+/**
+ * ALIVE（PID 存活）+ ARGS 块（指纹，manager 侧全等比对）+ LISTEN 三态
+ * （ss 非必然存在，unknown 不作否定证据）+ CWD（进程实际工作目录）。
+ *
+ * CWD 是 best-effort 的**展示与诊断**字段：/proc 不存在或无权读时回 unknown。
+ * 它绝不进不误杀判据集——判据只有 PID 存活与 ARGS 逐字全等（12 §1.3）。
+ */
+export function buildVerifyScript({ pid, port }) {
+  const pidTok = assertInt(pid, { min: 1, max: 4_294_967_295 });
+  const portTok = assertInt(port, { min: 1, max: 65535 });
+  return [
+    `A=$(ps -p ${pidTok} -o args= 2>/dev/null)`,
+    'if [ -n "$A" ]; then echo "ALIVE=yes"; echo "ARGS<<EOF"; printf \'%s\\n\' "$A"; echo "EOF"; else echo "ALIVE=no"; fi',
+    `if command -v ss >/dev/null 2>&1; then if ss -ltn 2>/dev/null | grep -q ":${portTok} "; then echo "LISTEN=yes"; else echo "LISTEN=no"; fi; else echo "LISTEN=unknown"; fi`,
+    `if [ -r /proc/${pidTok}/cwd ]; then printf 'CWD=%s\\n' "$(readlink /proc/${pidTok}/cwd 2>/dev/null || echo unknown)"; else echo "CWD=unknown"; fi`,
+    'echo "VERIFY_DONE=yes"',
+  ].join('; ');
+}
+
+/**
+ * 校验与 kill 在同一条命令内（03 §4.2 反竞态原则），匹配为与记录指纹**逐字全等**
+ * （契约疑议 1 的落地口径）——全等成立必然蕴含「含 dsh」。
+ */
+export function buildStopScript({ pid, fingerprint }) {
+  const pidTok = assertInt(pid, { min: 1, max: 4_294_967_295 });
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new DshError('VALIDATION', '停止协议缺少命令行指纹，拒绝拼装（防误杀）');
+  }
+  return [
+    `A=$(ps -p ${pidTok} -o args= 2>/dev/null)`,
+    'if [ -z "$A" ]; then echo "KILLED=already-dead"',
+    `elif [ "$A" = ${shq(fingerprint)} ]; then kill ${pidTok} 2>/dev/null; sleep ${PROTO_TIMING.stopGraceSec}; if kill -0 ${pidTok} 2>/dev/null; then kill -9 ${pidTok} 2>/dev/null; echo "KILLED=force"; else echo "KILLED=term"; fi`,
+    'else echo "KILLED=no"; echo "REASON=fingerprint-mismatch"; echo "ARGS<<EOF"; printf \'%s\\n\' "$A"; echo "EOF"; fi',
+    'echo "STOP_DONE=yes"',
+  ].join('; ');
+}
+
+// ── §1.4 日志获取 ────────────────────────────────────────────────────────
+
+/** 输出为裸日志文本，不走 KEY=VALUE 解析。 */
+export function buildLogTailScript({ logName, lines }) {
+  assertSafeName(logName);
+  const n = assertInt(lines, { min: 1, max: 10_000 });
+  return `tail -n ${n} "${remotePath(logName)}" 2>/dev/null || echo "(no log)"`;
+}
+
+// ── §1.5 patch 目录清理 ──────────────────────────────────────────────────
+
+/**
+ * 兼职保证 patches/ 目录存在（scp 无 mkdir -p 能力），因此**清理协议先于 scp 执行**。
+ * 文件名是 manager 自造 [name] 字符集（无空格无引号），空格包裹匹配法安全。
+ */
+export function buildPatchCleanupScript({ keepNames = [] }) {
+  const keep = keepNames.map((n) => assertSafeName(n)).join(' ');
+  return [
+    `mkdir -p "${remotePath('patches')}" || { echo "ERR=mkdir"; exit 9; }`,
+    `cd "${remotePath('patches')}" || exit 9`,
+    `for f in *; do [ -e "$f" ] || continue; case " ${keep} " in *" $f "*) ;; *) rm -f -- "$f" ;; esac; done`,
+    'echo "CLEAN_DONE=yes"',
+  ].join('; ');
+}
+
+// ── settings.yaml 固定路径读写协议 ───────────────────────────────────────
+
+const SETTINGS_TXN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const SETTINGS_CHECKSUM_RE = /^cksum-v1:(0|[1-9][0-9]{0,9}):(0|[1-9][0-9]{0,6})$/;
+
+function settingsTxnToken(txn) {
+  if (typeof txn !== 'string' || !SETTINGS_TXN_RE.test(txn)) {
+    throw new DshError('VALIDATION', `非法 settings 事务号：${JSON.stringify(txn)}`, {
+      detail: `事务号须匹配 ${SETTINGS_TXN_RE}`,
+    });
+  }
+  return shq(txn);
+}
+
+function settingsBase(baseChecksum) {
+  if (baseChecksum === null) {
+    return { expect: shq('no'), crc: shq(''), size: shq('') };
+  }
+  if (typeof baseChecksum !== 'string') {
+    throw new DshError('VALIDATION', 'settings baseChecksum 必须是 cksum-v1 token 或 null');
+  }
+  const match = SETTINGS_CHECKSUM_RE.exec(baseChecksum);
+  if (!match || Number(match[1]) > 4_294_967_295 || Number(match[2]) > 524_288) {
+    throw new DshError('VALIDATION', `非法 settings checksum：${JSON.stringify(baseChecksum)}`, {
+      detail: 'checksum 须为 cksum-v1:<0..4294967295>:<0..524288>，且十进制数不得有前导零',
+    });
+  }
+  return { expect: shq('yes'), crc: shq(match[1]), size: shq(match[2]) };
+}
+
+/**
+ * 固定读取 `${DSH_HOME:-$HOME/.dsh}/settings.yaml`。
+ * 内容经 POSIX od 输出 hex；txn 只派生管理目录内的短命快照名。
+ */
+export function buildSettingsReadScript({ txn } = {}) {
+  const txnTok = settingsTxnToken(txn);
+  return [
+    'LC_ALL=C',
+    'export LC_ALL',
+    'umask 077',
+    'set -f',
+    `T=${txnTok}`,
+    'H="${DSH_HOME:-$HOME/.dsh}"',
+    'P="$H/settings.yaml"',
+    'R="$HOME/.dsh_center_remote"',
+    'S="$R/settings-staging"',
+    'SNAP="$S/read-$T.data"',
+    'HEX_RAW="$S/read-$T.hex-raw"',
+    'HEX="$S/read-$T.hex"',
+    'unsupported() { echo "ERR=settings-unsupported"; exit 1; }',
+    'read_fail() { echo "ERR=settings-read"; exit 1; }',
+    'is_uint() { case "$1" in ""|*[!0-9]*) return 1 ;; *) return 0 ;; esac; }',
+    'parse_cksum() { set -- $1; [ "$#" -eq 2 ] || return 1; is_uint "$1" || return 1; is_uint "$2" || return 1; CK_CRC=$1; CK_SIZE=$2; }',
+    'ensure_dir() { D=$1; if [ -L "$D" ]; then return 1; elif [ -e "$D" ]; then [ -d "$D" ] || return 1; else mkdir "$D" || return 1; fi; chmod 700 "$D" || return 1; }',
+    'cleanup_staging() { set +f; rm -f "$S"/read-*.data "$S"/read-*.hex "$S"/read-*.hex-raw "$S"/write-*.data; RC=$?; set -f; return "$RC"; }',
+    'cleanup_commit() { set +f; rm -f "$H"/.settings.yaml.dshc-*.tmp; RC=$?; set -f; return "$RC"; }',
+    'emit_path() { printf \'%s\' "$P" | od -A n -v -t x1 > "$HEX_RAW" 2>/dev/null || read_fail; tr -d \'[:space:]\' < "$HEX_RAW" > "$HEX" || read_fail; echo "PATH_HEX<<DSHC_PATH"; cat "$HEX" || { echo; echo "DSHC_PATH"; read_fail; }; echo; echo "DSHC_PATH"; }',
+    'echo "SETTINGS_PROTO=1"',
+    'printf \'SETTINGS_TXN=%s\\n\' "$T"',
+    'case "$HOME" in /*) ;; *) unsupported ;; esac',
+    'case "$H" in /*) ;; *) unsupported ;; esac',
+    'for C in command test printf mkdir chmod rm dd wc cksum od tr cat mv; do command -v "$C" >/dev/null 2>&1 || unsupported; done',
+    'OD_PROBE=$(printf \'\\001\\377\' | od -A n -v -t x1 2>/dev/null | tr -d \'[:space:]\') || unsupported',
+    '[ "$OD_PROBE" = 01ff ] || unsupported',
+    'CK_OUT=$(printf x | cksum 2>/dev/null) || unsupported',
+    'parse_cksum "$CK_OUT" || unsupported',
+    '[ "$CK_CRC" = 12738659 ] && [ "$CK_SIZE" = 1 ] || unsupported',
+    'ensure_dir "$R" || read_fail',
+    'ensure_dir "$S" || read_fail',
+    'cleanup_staging || read_fail',
+    'if [ -d "$H" ]; then cleanup_commit || read_fail; fi',
+    'trap \'rm -f "$SNAP" "$HEX_RAW" "$HEX"\' 0',
+    'trap \'read_fail\' 1 2 3 15',
+    'if [ -L "$P" ]; then read_fail; fi',
+    'if [ ! -e "$P" ]; then echo "EXISTS=no"; echo "SIZE=0"; emit_path; echo "CONTENT_HEX<<DSHC_CONTENT"; echo "DSHC_CONTENT"; echo "SETTINGS_READ_DONE=yes"; exit 0; fi',
+    '[ -f "$P" ] || read_fail',
+    'dd if="$P" of="$SNAP" bs=524289 count=1 2>/dev/null || read_fail',
+    'chmod 600 "$SNAP" || read_fail',
+    'SIZE_RAW=$(wc -c < "$SNAP" 2>/dev/null) || read_fail',
+    'SIZE=$(printf \'%s\' "$SIZE_RAW" | tr -d \'[:space:]\') || read_fail',
+    'is_uint "$SIZE" || read_fail',
+    '[ "$SIZE" -le 524288 ] || { echo "ERR=settings-too-large"; exit 10; }',
+    'CK_OUT=$(cksum < "$SNAP" 2>/dev/null) || read_fail',
+    'parse_cksum "$CK_OUT" || read_fail',
+    '[ "$CK_SIZE" = "$SIZE" ] || read_fail',
+    'echo "EXISTS=yes"',
+    'printf \'SIZE=%s\\n\' "$SIZE"',
+    'printf \'CRC=%s\\n\' "$CK_CRC"',
+    'emit_path',
+    'od -A n -v -t x1 "$SNAP" > "$HEX_RAW" 2>/dev/null || read_fail',
+    'tr -d \'[:space:]\' < "$HEX_RAW" > "$HEX" || read_fail',
+    'HEX_SIZE_RAW=$(wc -c < "$HEX" 2>/dev/null) || read_fail',
+    'HEX_SIZE=$(printf \'%s\' "$HEX_SIZE_RAW" | tr -d \'[:space:]\') || read_fail',
+    '[ "$HEX_SIZE" -eq "$((SIZE * 2))" ] || read_fail',
+    'echo "CONTENT_HEX<<DSHC_CONTENT"',
+    'cat "$HEX" || { echo; echo "DSHC_CONTENT"; read_fail; }',
+    'echo',
+    'echo "DSHC_CONTENT"',
+    'echo "SETTINGS_READ_DONE=yes"',
+  ].join('; ');
+}
+
+/**
+ * 从 stdin 接收新内容并以 cksum-v1 双复核 CAS 提交到固定 settings 路径。
+ * baseChecksum=null 表示只允许创建；string 表示只允许替换逐字相同的基线 token。
+ */
+export function buildSettingsWriteScript({ txn, baseChecksum } = {}) {
+  const txnTok = settingsTxnToken(txn);
+  const base = settingsBase(baseChecksum);
+  return [
+    'LC_ALL=C',
+    'export LC_ALL',
+    'umask 077',
+    'set -f',
+    `T=${txnTok}`,
+    `EXPECT=${base.expect}`,
+    `BASE_CRC=${base.crc}`,
+    `BASE_SIZE=${base.size}`,
+    'H="${DSH_HOME:-$HOME/.dsh}"',
+    'P="$H/settings.yaml"',
+    'R="$HOME/.dsh_center_remote"',
+    'S="$R/settings-staging"',
+    'B="$R/settings-backup"',
+    'STAGE="$S/write-$T.data"',
+    'TEMP="$H/.settings.yaml.dshc-$T.tmp"',
+    'PREV="$B/previous.yaml"',
+    'ABSENT="$B/previous.absent"',
+    'BTMP="$B/previous-$T.tmp"',
+    'ATMP="$B/absent-$T.tmp"',
+    'COMMITTED=no',
+    'commit_state() { if [ "$COMMITTED" = no ]; then echo "COMMIT_STATE=not-committed"; else echo "COMMIT_STATE=unknown"; fi; }',
+    'unsupported() { echo "ERR=settings-unsupported"; exit 1; }',
+    'write_fail() { echo "ERR=settings-write"; commit_state; exit 12; }',
+    'stale() { echo "ERR=settings-stale"; commit_state; exit 11; }',
+    'too_large() { echo "ERR=settings-too-large"; commit_state; exit 10; }',
+    'is_uint() { case "$1" in ""|*[!0-9]*) return 1 ;; *) return 0 ;; esac; }',
+    'parse_cksum() { set -- $1; [ "$#" -eq 2 ] || return 1; is_uint "$1" || return 1; is_uint "$2" || return 1; CK_CRC=$1; CK_SIZE=$2; }',
+    'ensure_dir() { D=$1; if [ -L "$D" ]; then return 1; elif [ -e "$D" ]; then [ -d "$D" ] || return 1; else mkdir "$D" || return 1; fi; chmod 700 "$D" || return 1; }',
+    'cleanup_managed() { set +f; rm -f "$S"/read-*.data "$S"/read-*.hex "$S"/read-*.hex-raw "$S"/write-*.data "$B"/previous-*.tmp "$B"/absent-*.tmp; RC=$?; set -f; return "$RC"; }',
+    'cleanup_commit() { set +f; rm -f "$H"/.settings.yaml.dshc-*.tmp; RC=$?; set -f; return "$RC"; }',
+    'emit_path() { echo "PATH_HEX<<DSHC_PATH"; if printf \'%s\' "$P" | od -A n -v -t x1; then :; else echo "DSHC_PATH"; write_fail; fi; echo "DSHC_PATH"; }',
+    'read_current() { CUR_EXISTS=no; CUR_CRC=; CUR_SIZE=; if [ -L "$P" ]; then return 2; fi; if [ ! -e "$P" ]; then return 0; fi; [ -f "$P" ] || return 2; CUR_RAW=$(wc -c < "$P" 2>/dev/null) || return 3; CUR_SIZE=$(printf \'%s\' "$CUR_RAW" | tr -d \'[:space:]\') || return 3; is_uint "$CUR_SIZE" || return 3; [ "$CUR_SIZE" -le 524288 ] || return 4; CUR_OUT=$(cksum < "$P" 2>/dev/null) || return 3; parse_cksum "$CUR_OUT" || return 3; [ "$CK_SIZE" = "$CUR_SIZE" ] || return 5; CUR_EXISTS=yes; CUR_CRC=$CK_CRC; CUR_SIZE=$CK_SIZE; return 0; }',
+    'load_current() { read_current; RC=$?; case "$RC" in 0) return 0 ;; 4) too_large ;; 5) stale ;; *) write_fail ;; esac; }',
+    'match_base() { if [ "$EXPECT" = no ]; then [ "$CUR_EXISTS" = no ]; else [ "$CUR_EXISTS" = yes ] && [ "$CUR_CRC" = "$BASE_CRC" ] && [ "$CUR_SIZE" = "$BASE_SIZE" ]; fi; }',
+    'echo "SETTINGS_PROTO=1"',
+    'printf \'SETTINGS_TXN=%s\\n\' "$T"',
+    'case "$HOME" in /*) ;; *) unsupported ;; esac',
+    'case "$H" in /*) ;; *) unsupported ;; esac',
+    'for C in command test printf mkdir chmod rm dd wc cksum od tr cat mv; do command -v "$C" >/dev/null 2>&1 || unsupported; done',
+    'OD_PROBE=$(printf \'\\001\\377\' | od -A n -v -t x1 2>/dev/null | tr -d \'[:space:]\') || unsupported',
+    '[ "$OD_PROBE" = 01ff ] || unsupported',
+    'CK_OUT=$(printf x | cksum 2>/dev/null) || unsupported',
+    'parse_cksum "$CK_OUT" || unsupported',
+    '[ "$CK_CRC" = 12738659 ] && [ "$CK_SIZE" = 1 ] || unsupported',
+    'ensure_dir "$R" || write_fail',
+    'ensure_dir "$S" || write_fail',
+    'ensure_dir "$B" || write_fail',
+    'for F in "$PREV" "$ABSENT"; do if [ -L "$F" ]; then write_fail; fi; if [ -e "$F" ] && [ ! -f "$F" ]; then write_fail; fi; done',
+    'cleanup_managed || write_fail',
+    'trap \'rm -f "$STAGE" "$TEMP" "$BTMP" "$ATMP"\' 0',
+    'trap \'write_fail\' 1 2 3 15',
+    'cat > "$STAGE" || write_fail',
+    'chmod 600 "$STAGE" || write_fail',
+    'NEW_RAW=$(wc -c < "$STAGE" 2>/dev/null) || write_fail',
+    'NEW_SIZE=$(printf \'%s\' "$NEW_RAW" | tr -d \'[:space:]\') || write_fail',
+    'is_uint "$NEW_SIZE" || write_fail',
+    '[ "$NEW_SIZE" -le 524288 ] || too_large',
+    'NEW_OUT=$(cksum < "$STAGE" 2>/dev/null) || write_fail',
+    'parse_cksum "$NEW_OUT" || write_fail',
+    '[ "$CK_SIZE" = "$NEW_SIZE" ] || write_fail',
+    'NEW_CRC=$CK_CRC',
+    'NEW_SIZE=$CK_SIZE',
+    'load_current',
+    'match_base || stale',
+    '[ -d "$H" ] || write_fail',
+    'cd "$H" || write_fail',
+    'cleanup_commit || write_fail',
+    'cat "$STAGE" > "$TEMP" || write_fail',
+    'chmod 600 "$TEMP" || write_fail',
+    'TEMP_OUT=$(cksum < "$TEMP" 2>/dev/null) || write_fail',
+    'parse_cksum "$TEMP_OUT" || write_fail',
+    '[ "$CK_CRC" = "$NEW_CRC" ] && [ "$CK_SIZE" = "$NEW_SIZE" ] || write_fail',
+    'if [ "$CUR_EXISTS" = yes ]; then if [ -L "$P" ] || [ ! -f "$P" ]; then write_fail; fi; cat "$P" > "$BTMP" || write_fail; chmod 600 "$BTMP" || write_fail; BACK_OUT=$(cksum < "$BTMP" 2>/dev/null) || write_fail; parse_cksum "$BACK_OUT" || write_fail; [ "$CK_CRC" = "$BASE_CRC" ] && [ "$CK_SIZE" = "$BASE_SIZE" ] || stale; mv -f "$BTMP" "$PREV" || write_fail; rm -f "$ABSENT" || write_fail; else : > "$ATMP" || write_fail; chmod 600 "$ATMP" || write_fail; mv -f "$ATMP" "$ABSENT" || write_fail; rm -f "$PREV" || write_fail; fi',
+    'load_current',
+    'match_base || stale',
+    'COMMITTED=unknown',
+    'mv -f "$TEMP" "$P" || write_fail',
+    'COMMITTED=yes',
+    'load_current',
+    '[ "$CUR_EXISTS" = yes ] || write_fail',
+    '[ "$CUR_CRC" = "$NEW_CRC" ] && [ "$CUR_SIZE" = "$NEW_SIZE" ] || stale',
+    'emit_path',
+    'printf \'NEW_SIZE=%s\\n\' "$NEW_SIZE"',
+    'printf \'NEW_CRC=%s\\n\' "$NEW_CRC"',
+    'echo "SETTINGS_WRITE_DONE=yes"',
+  ].join('; ');
+}
+
+// ── §7 协议输出解析器 ────────────────────────────────────────────────────
+
+const KV_RE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
+const BLOCK_OPEN_RE = /^([A-Z][A-Z0-9_]*)<<([A-Za-z_]+)$/;
+
+/**
+ * @typedef {{kv: Record<string, string[]>, blocks: Record<string, string>, stray: string[]}} ProtoOutput
+ * @param {string} stdout
+ * @param {{requireDone?:string}} [opts] 如 'PROBE_DONE'——缺哨兵抛 PROTO_PARSE
+ * @returns {ProtoOutput}
+ */
+export function parseProtoOutput(stdout, { requireDone } = {}) {
+  const text = String(stdout ?? '').replace(/\r/g, '');
+  const lines = text.split('\n');
+
+  /** @type {Record<string,string[]>} */
+  const kv = {};
+  /** @type {Record<string,string>} */
+  const blocks = {};
+  const stray = [];
+
+  let blockKey = null;
+  let blockDelim = null;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (blockKey !== null) {
+      if (line === blockDelim) {
+        blocks[blockKey] = blockLines.join('\n');
+        blockKey = null;
+        blockDelim = null;
+        blockLines = [];
+      } else {
+        blockLines.push(line);
+      }
+      continue;
+    }
+
+    if (line === '') continue;
+
+    const open = BLOCK_OPEN_RE.exec(line);
+    if (open) {
+      blockKey = open[1];
+      blockDelim = open[2];
+      blockLines = [];
+      continue;
+    }
+
+    const pair = KV_RE.exec(line);
+    if (pair) {
+      (kv[pair[1]] ??= []).push(pair[2]);
+      continue;
+    }
+
+    stray.push(line);
+  }
+
+  if (blockKey !== null) {
+    throw new DshError('PROTO_PARSE', `远端输出的 ${blockKey} 块未闭合（缺 ${blockDelim} 界符行）`, {
+      detail: text,
+    });
+  }
+
+  if (requireDone && kv[requireDone]?.[0] !== 'yes') {
+    throw new DshError('PROTO_PARSE', `远端输出缺少 ${requireDone} 哨兵（输出被截断或连接中断）`, {
+      detail: text,
+    });
+  }
+
+  return { kv, blocks, stray };
+}
+
+/** 取单值（重复键取最后一个，缺失返回 fallback）。 */
+export function kvOne(out, key, fallback = null) {
+  const arr = out.kv[key];
+  return arr && arr.length > 0 ? arr[arr.length - 1] : fallback;
+}

package/src/lib/semver.js

@@ -0,0 +1,103 @@
+/**
+ * SemVer 解析与比较（含 pre-release 优先级）—— 纯内核，零 import。
+ *
+ * 自己写而不抄一份三方实现，是因为零依赖底线；只写更新逻辑真正需要的部分：
+ * 解析、比较、从一堆版本里挑最新。唯一不能凭直觉写对的是 pre-release 的优先级
+ * （数字段按数值比、字母段按字典序、数字段永远小于字母段、字段少的更小、
+ * 正式版大于同核心号的任何预发布），所以每条规则都在 tests/lib/semver.test.js
+ * 里有对应用例。build 元数据（`+xxx`）按规范不参与比较。
+ */
+
+const SHAPE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+
+/** 数字段不许有前导零——否则 `1.0.01` 与 `1.0.1` 会各自成立，比较结果说不清。 */
+const hasLeadingZero = (id) => /^\d+$/.test(id) && id.length > 1 && id.startsWith('0');
+
+/**
+ * @param {unknown} input 形如 `0.2.0` / `v0.2.0-rc.1` / `1.0.0+build.5`
+ * @returns {{major:number, minor:number, patch:number, prerelease:readonly string[],
+ *   build:string|null, version:string}|null} 形状不对给 null（调用方自己决定怎么报错）
+ */
+export function parseVersion(input) {
+  const raw = String(input ?? '').trim();
+  const m = SHAPE.exec(raw);
+  if (!m) return null;
+
+  const [, major, minor, patch, pre, build] = m;
+  if ([major, minor, patch].some(hasLeadingZero)) return null;
+
+  const prerelease = pre === undefined ? [] : pre.split('.');
+  if (prerelease.some((id) => id === '' || hasLeadingZero(id))) return null;
+
+  return Object.freeze({
+    major: Number(major),
+    minor: Number(minor),
+    patch: Number(patch),
+    prerelease: Object.freeze(prerelease),
+    build: build ?? null,
+    // 规整形态（去掉 v 前缀与 build 元数据），比较与展示都用它
+    version: `${Number(major)}.${Number(minor)}.${Number(patch)}${pre ? `-${pre}` : ''}`,
+  });
+}
+
+/** @returns {boolean} 合法且带 pre-release 后缀 */
+export function isPrerelease(input) {
+  const parsed = parseVersion(input);
+  return Boolean(parsed) && parsed.prerelease.length > 0;
+}
+
+function compareIdentifiers(a, b) {
+  const aNum = /^\d+$/.test(a);
+  const bNum = /^\d+$/.test(b);
+  if (aNum && bNum) return Math.sign(Number(a) - Number(b));
+  if (aNum !== bNum) return aNum ? -1 : 1; // 数字段永远小于字母段
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}
+ * @throws {TypeError} 任一侧不是合法版本号
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) throw new TypeError(`不是合法版本号：${pa ? b : a}`);
+
+  for (const key of ['major', 'minor', 'patch']) {
+    if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
+  }
+
+  const na = pa.prerelease.length;
+  const nb = pb.prerelease.length;
+  if (na === 0 && nb === 0) return 0;
+  if (na === 0 || nb === 0) return na === 0 ? 1 : -1; // 正式版 > 预发布
+
+  for (let i = 0; i < Math.max(na, nb); i += 1) {
+    const x = pa.prerelease[i];
+    const y = pb.prerelease[i];
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1; // 字段少的更小
+    const verdict = compareIdentifiers(x, y);
+    if (verdict !== 0) return verdict;
+  }
+  return 0;
+}
+
+/**
+ * 从候选里挑最新的一个。非法版本号一律忽略（Release 页面上难免有杂项 tag）。
+ * @param {Iterable<string>} versions
+ * @param {{includePrerelease?:boolean}} [opts] 默认只看正式版——「稳定用户不该被动吃到 rc」
+ * @returns {string|null} 原样返回入选的那个字符串；无可用候选给 null
+ */
+export function pickLatest(versions, { includePrerelease = false } = {}) {
+  let best = null;
+  for (const candidate of versions) {
+    const parsed = parseVersion(candidate);
+    if (!parsed) continue;
+    if (!includePrerelease && parsed.prerelease.length > 0) continue;
+    if (best === null || compareVersions(candidate, best) > 0) best = candidate;
+  }
+  return best;
+}

package/src/lib/shq.js

@@ -0,0 +1,112 @@
+/**
+ * POSIX 单引号转义与命名校验（12 §2）。
+ *
+ * 转义防不了的两件事（12 §2.4，设计边界）：
+ * 1. 参数语义注入：extraArgs 里的 '--port 9999' 转义后仍是合法参数，会与 manager 的
+ *    --port 冲突。不禁止（用户自担），launcher 拼装时发 warn；actualPort 以日志解析为准。
+ * 2. ssh 参数位注入：Host 名以 '-' 开头会被 ssh 当选项。由 assertSafeHost 统一把关。
+ */
+
+import { DshError } from './errors.js';
+
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SAFE_NAME_RE = /^[A-Za-z0-9._-]+$/;
+const SAFE_HOST_RE = /^[A-Za-z0-9._-]+$/;
+const INT_RE = /^[1-9][0-9]{0,9}$/;
+
+/**
+ * 任意字符串 → 可作为单个 shell 单词安全嵌入。
+ * 算法：两端加 '，内部每个 ' 替换为 '\''（关引-转义引-开引）。
+ * @param {string} s 任意 JS 字符串（含空串、换行、任意 Unicode）
+ * @returns {string} 保证经任何 POSIX sh 解析后逐字还原 s
+ */
+export function shq(s) {
+  if (typeof s !== 'string') throw new DshError('VALIDATION', `shq 只接受字符串，收到 ${typeof s}`);
+  return `'${s.split("'").join("'\\''")}'`;
+}
+
+/**
+ * env 键白名单校验。键不做转义——转义救不了不合法键，因为 `env K='v'` 的 `K=` 段在引号外。
+ * @throws {DshError} VALIDATION
+ */
+export function assertEnvKey(k) {
+  if (typeof k !== 'string' || !ENV_KEY_RE.test(k)) {
+    throw new DshError('VALIDATION', `非法环境变量名：${JSON.stringify(k)}`, {
+      detail: `环境变量名须匹配 ${ENV_KEY_RE}`,
+    });
+  }
+  return k;
+}
+
+/** manager 自造文件名校验（logName / patch 远端名）。 */
+export function assertSafeName(n) {
+  if (typeof n !== 'string' || !SAFE_NAME_RE.test(n) || n.startsWith('-') || n.startsWith('.')) {
+    throw new DshError('VALIDATION', `非法远端文件名：${JSON.stringify(n)}`, {
+      detail: `文件名须匹配 ${SAFE_NAME_RE} 且不以 - 或 . 开头`,
+    });
+  }
+  return n;
+}
+
+/** ssh Host 名校验（12 §2.4 第 2 条）。 */
+export function assertSafeHost(h) {
+  if (typeof h !== 'string' || !SAFE_HOST_RE.test(h) || h.startsWith('-')) {
+    throw new DshError('VALIDATION', `主机名不适合作为 ssh 参数：${JSON.stringify(h)}`, {
+      detail: `主机名须匹配 ${SAFE_HOST_RE} 且不以 - 开头（改 ~/.ssh/config 里的 Host 名）`,
+    });
+  }
+  return h;
+}
+
+/**
+ * 远端启动目录（工作区根）的形态判定。
+ * 只认绝对路径与 `~` 前缀：相对路径「相对于什么」在 sshd 侧无从定义，拦在此处比
+ * 让用户对着 `ERR=workdir` 猜要省心。其余字符 shq 都能安全引用，故不再多设字符集限制。
+ */
+export function isWorkdirPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return false;
+  if (/[\0\n\r]/.test(p)) return false;
+  return p.startsWith('/') || p === '~' || p.startsWith('~/');
+}
+
+/** @throws {DshError} VALIDATION */
+export function assertWorkdir(p) {
+  if (!isWorkdirPath(p)) {
+    throw new DshError('VALIDATION', `非法远端启动目录：${JSON.stringify(p)}`, {
+      detail: '须为绝对路径（/ 开头）或 ~、~/… 形态；不接受相对路径、空串与含换行/NUL 的值',
+    });
+  }
+  return p;
+}
+
+/**
+ * workdir → 可嵌入 `cd -- <TOK>` 的单个 shell 词。
+ * `~` 不能进单引号（引号内不展开），改用 `"$HOME"` 与 shq 段相邻拼接——
+ * POSIX 相邻字符串自然连成一个词，展开永远发生在远端。
+ */
+export function workdirToken(p) {
+  assertWorkdir(p);
+  if (p === '~') return '"$HOME"';
+  if (p.startsWith('~/')) return `"$HOME"${shq(p.slice(1))}`;
+  return shq(p);
+}
+
+/**
+ * 整数校验后原样拼接（12 §1 的 [int] 标注）。数字不需转义，校验杜绝一切非数字。
+ * @param {number|string} v
+ * @param {{min?:number, max?:number, allowZero?:boolean}} [opts]
+ */
+export function assertInt(v, { min = 1, max = 65535, allowZero = false } = {}) {
+  const s = String(v);
+  if (allowZero && s === '0') return '0';
+  if (!INT_RE.test(s)) {
+    throw new DshError('VALIDATION', `期望整数，收到 ${JSON.stringify(v)}`);
+  }
+  const n = Number(s);
+  if (n < min || n > max) {
+    throw new DshError('VALIDATION', `整数越界：${n} 不在 ${min}..${max}`);
+  }
+  return s;
+}
+
+export { ENV_KEY_RE, SAFE_NAME_RE, SAFE_HOST_RE };