@whyshu/argent 0.1.26 → 0.2.0

package/lib/index.mjs

@@ -1,604 +0,0 @@
-/**
- * @whyshu/argent 启动器内核（纯函数，便于单测；bin 只做 CLI 编排）。
- *
- * 职责：
- *   · exact pin 的 dsh 版本（0.2.1-rc.2）——启动前校验，避免混合版本事故；
- *   · 生成/更新 $DSH_HOME/profiles/argent（bundles + 用户层 patch）——本地仓库用 file: 装配；
- *   · runner 配置路径与 launchd/systemd 常驻单元生成；
- *   · 状态自检（版本/profile/runner 配置/端口）。
- * ⛔ 不读写任何凭据内容（runner.json 由首跑引导写，权限 600）。
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, cpSync, readdirSync, chmodSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { homedir, hostname as osHostname } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
-
-export const DSH_EXACT_VERSION = '0.2.1-rc.2';
-export const PROFILE_NAME = 'argent';
-export const BASE_BUNDLES = [
-  '@deepseek-ai/dsh-base',
-  '@deepseek-ai/dsh-web-app',
-  '@whyshu/argent-presets',
-];
-export const DEFAULT_PRESET = 'argent-general';
-/** 生产 profile 追加 bundles（--bundles prod 展开；版本见启动器 package.json 依赖） */
-export const PROD_BUNDLES = [
-  '@whyshu/argent-core', '@whyshu/argent-dsh', '@whyshu/argent-skin',
-  '@whyshu/argent-gateway', '@whyshu/argent-flow', '@whyshu/argent-ml',
-  '@michengai/dsh-im-connect', '@linxin666/dsh-client-ui-task-board',
-];
-export const RUNNER_LABEL = 'com.whyshu.argent-runner';
-
-/** 启动器自身版本（写进 argent.json 的 writtenBy，便于事后追溯是谁写的契约） */
-export const LAUNCHER_VERSION = (() => {
-  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version } catch { return '' }
-})();
-
-/** 仓库根：launcher/lib → ../../（本地联调）；发布包内由 ARGENT_REPO 覆盖 */
-export function repoRoot({ repo } = {}) {
-  if (repo) return resolve(repo);
-  if (process.env.ARGENT_REPO) return resolve(process.env.ARGENT_REPO);
-  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-}
-
-export function dshHomeOf(value) {
-  return resolve(value || process.env.DSH_HOME || join(homedir(), '.dsh'));
-}
-
-/** 解析 `dsh --version` 输出（只取第一行，去掉 v 前缀） */
-export function parseVersion(text) {
-  const line = String(text || '').trim().split('\n')[0] || '';
-  return line.replace(/^v/, '').trim();
-}
-
-export function versionMatches(version, expected = DSH_EXACT_VERSION) {
-  return parseVersion(version) === parseVersion(expected);
-}
-
-/** 跑 `dsh --version`（可注入 bin；默认 PATH 上的 dsh） */
-export function probeDshVersion({ dshBin = 'dsh', spawn = spawnSync } = {}) {
-  const r = spawn(dshBin, ['--version'], { encoding: 'utf8', timeout: 15000 });
-  if (r.error || r.status !== 0) return { ok: false, version: '', error: r.error?.message || `exit ${r.status}` };
-  return { ok: true, version: parseVersion(r.stdout), error: '' };
-}
-
-/** 仓库内插件目录（本地 file: 装配用；发布包改为其自身 node_modules） */
-export function pluginDirs({ repo = repoRoot() } = {}) {
-  const candidates = {
-    '@whyshu/argent-presets': join(repo, 'plugins', 'argent-presets'),
-  };
-  const out = {};
-  for (const [name, dir] of Object.entries(candidates)) {
-    if (existsSync(join(dir, 'package.json'))) out[name] = dir;
-  }
-  return out;
-}
-
-/** 已发布插件的版本（发布模式装配 profile 用；与 npm 上实际可见版本对齐） */
-export const PUBLISHED_BUNDLE_VERSIONS = {
-  // ⚠️ 每个包**只允许出现一次**（2026-11-02 修：argent-desktop 曾同时写 0.2.2/0.2.3，
-  //    后者静默覆盖前者 ⇒ 改上面那行的人会以为生效了）
-  '@whyshu/argent-presets': '0.1.2',
-  '@whyshu/argent-core': '0.1.6',
-  '@whyshu/argent-dsh': '0.1.10',
-  '@whyshu/argent-skin': '0.1.14',
-  '@whyshu/argent-gateway': '0.2.3',
-  '@whyshu/argent-flow': '0.1.1',
-  '@whyshu/argent-ml': '0.1.1',
-  '@michengai/dsh-im-connect': '1.0.2',
-  '@linxin666/dsh-client-ui-task-board': '0.4.7',
-  '@whyshu/argent-desktop': '0.2.4',
-};
-
-
-/**
- * 发布模式随启动器安装的 runtime（@whyshu/argent-engine）根目录；本地联调回退 dist。
- *
- * ⚠️ 2026-10-30 事故（客户机 0.1.18）：npm 11 **没有把引擎提升到顶层**，而是嵌套在
- * `<prefix>/node_modules/@whyshu/argent/node_modules/@whyshu/argent-engine/`。
- * 旧实现只探测"提升后"的 4 个固定路径 ⇒ `argent runtime install` 直接 exit 2，
- * 客户机升级链路第一步就断（rc.5 的日报定时器脚本落不了地）。
- *
- * 修法：**先用模块解析**（`require.resolve`，提升/嵌套/符号链接/pnpm 布局都天然命中），
- * 再保留显式候选（含"嵌套在启动器自己的 node_modules"）作为兜底。
- * 两者都按同一判据校验（`engine/scripts` + `engine/VERSION`），⛔ 不靠"目录看起来像"。
- */
-export function engineRoot({ env = process.env, launcherLib = dirname(fileURLToPath(import.meta.url)) } = {}) {
-  const candidates = [];
-  if (env.ARGENT_ENGINE_ROOT) candidates.push(resolve(env.ARGENT_ENGINE_ROOT));
-  // ① 模块解析（最可靠）：以 launcher/lib 为锚，让 Node 自己按 npm 布局找包
-  try {
-    const req = createRequire(join(launcherLib, 'index.mjs'));
-    const pkgJson = req.resolve('@whyshu/argent-engine/package.json');
-    candidates.push(join(dirname(pkgJson), 'engine'));
-  } catch { /* 引擎未装/不可解析 ⇒ 继续用显式候选 */ }
-  // ② 显式候选（提升布局 / 嵌套在启动器自己 node_modules / 本地联调 dist）
-  candidates.push(resolve(launcherLib, '..', '..', '..', '@whyshu', 'argent-engine', 'engine'));
-  candidates.push(resolve(launcherLib, '..', 'node_modules', '@whyshu', 'argent-engine', 'engine'));
-  candidates.push(resolve(launcherLib, '..', '..', 'node_modules', '@whyshu', 'argent-engine', 'engine'));
-  candidates.push(resolve(launcherLib, '..', '..', 'dist', 'argent-engine', 'engine'));
-  for (const c of candidates) {
-    if (existsSync(join(c, 'scripts')) && existsSync(join(c, 'VERSION'))) return c;
-  }
-  // 找不到时给出可执行的诊断（别再让客户只看到一句"请用新版启动器"）
-  if (env.ARGENT_ENGINE_ROOT) {
-    console.error(`[engineRoot] ARGENT_ENGINE_ROOT=${env.ARGENT_ENGINE_ROOT} 不是有效的引擎根（需含 scripts/ 与 VERSION）`)
-  }
-  console.error(`[engineRoot] 已尝试 ${candidates.length} 个位置（模块解析 + 显式路径）均未命中；`
-    + '可执行 `npm ls -g @whyshu/argent-engine --all` 看真实布局，或用 ARGENT_ENGINE_ROOT 显式指定')
-  return '';
-}
-
-/**
- * 引擎定位（方案 C 契约的**写入侧**）。
- *
- * 判据与 engineRoot 一致但不猜：`<dir>/VERSION` + `<dir>/core/lib/argent-datadir.mjs`。
- * 优先级：本地仓库（开发联调）→ npm 包 `engine/` → 已物化 runtime（~/.argent-dsh）。
- * 找不到就返回 ok:false —— 由调用方决定写空值还是报错，⛔ 不要在这里编一个路径。
- */
-export function engineInfo({ repo = repoRoot(), target = process.env.ARGENT_RUNTIME_TARGET, env = process.env } = {}) {
-  const valid = (d) => Boolean(d) && existsSync(join(d, 'VERSION')) && existsSync(join(d, 'core', 'lib', 'argent-datadir.mjs'));
-  const cands = [];
-  // ① 显式 runtime 目标（update run --target）：客户机上**唯一稳定**的引擎位置
-  if (valid(target)) cands.push({ dir: target, source: 'target' });
-  // ② 本地仓库（开发联调）：必须真的是 git 检出，⛔ 不要把 npx 缓存里的包当"仓库"
-  if (valid(repo) && existsSync(join(repo, '.git'))) cands.push({ dir: repo, source: 'repo' });
-  // ③ 已物化 runtime（默认 ~/.argent-dsh）
-  const runtime = join(homedir(), '.argent-dsh');
-  if (valid(runtime)) cands.push({ dir: runtime, source: 'runtime' });
-  // ④ 最后才是 npm 包（npx 缓存路径，随时会被清 —— 只作兜底）
-  const pkg = engineRoot({ env });
-  if (valid(pkg)) cands.push({ dir: pkg, source: 'package' });
-  for (const c of cands) {
-    let version = '';
-    try { version = readFileSync(join(c.dir, 'VERSION'), 'utf8').trim(); } catch { /* 保留空串 */ }
-    return { ok: true, dir: c.dir, source: c.source, version };
-  }
-  return { ok: false, dir: '', source: 'none', version: '' };
-}
-
-/** 读引擎契约版本（唯一真源 = `<engine>/core/lib/contract.mjs`；读不到返回 null，⛔ 不猜） */
-export function engineContract(dir) {
-  try {
-    const m = readFileSync(join(dir, 'core', 'lib', 'contract.mjs'), 'utf8').match(/export const CONTRACT\s*=\s*(\d+)/);
-    return m ? Number(m[1]) : null;
-  } catch { return null; }
-}
-
-/** 写 `<profile>/argent.json`：宿主壳只读这个文件，不再猜引擎在哪（方案 C · P1） */
-export function writeEngineContract(dir, { repo = repoRoot(), target = process.env.ARGENT_RUNTIME_TARGET, env = process.env } = {}) {
-  const info = engineInfo({ repo, target, env });
-  const payload = {
-    engineDir: info.ok ? info.dir : '',
-    engineVersion: info.ok ? info.version : '',
-    contract: info.ok ? engineContract(info.dir) : null,
-    source: info.source,
-    writtenBy: LAUNCHER_VERSION ? `@whyshu/argent@${LAUNCHER_VERSION}` : '@whyshu/argent',
-    writtenAt: new Date().toISOString(),
-  };
-  writeFileSync(join(dir, 'argent.json'), JSON.stringify(payload, null, 2) + '\n');
-  return payload;
-}
-
-function walkFiles(dir, base = dir) {
-  const out = [];
-  for (const e of readdirSync(dir)) {
-    const p = join(dir, e);
-    const rel = p.slice(base.length + 1).split('\\').join('/');
-    const st = statSync(p);
-    if (st.isDirectory()) out.push(...walkFiles(p, base));
-    else out.push(rel);
-  }
-  return out;
-}
-
-/**
- * 把 npm runtime 包物化到客户机既有资产目录（默认 ~/.argent-dsh）。
- * 只覆盖 engine 包内的文件；客户配置/凭据/.git 不动；被覆盖文件先备份。
- */
-export function materializeRuntime({ target = join(homedir(), '.argent-dsh'), engine = engineRoot(), skillsTarget = '', now = new Date() } = {}) {
-  if (!engine) return { ok: false, code: 'engine_missing', message: '未找到 @whyshu/argent-engine（启动器依赖未安装）' };
-  if (!existsSync(target)) mkdirSync(target, { recursive: true });
-  const version = readFileSync(join(engine, 'VERSION'), 'utf8').trim();
-  const stamp = now.toISOString().replace(/[:.]/g, '-');
-  const backupDir = join(target, '.runtime-backup', stamp);
-  const files = walkFiles(engine);
-  let copied = 0;
-  const copyFile = (src, dst, rel) => {
-    if (existsSync(dst)) {
-      const b = join(backupDir, rel);
-      mkdirSync(dirname(b), { recursive: true });
-      cpSync(dst, b);
-    }
-    mkdirSync(dirname(dst), { recursive: true });
-    cpSync(src, dst);
-    // 2026-10-30：引擎 tgz 里 .sh 曾是 0644（打包器丢了执行位）⇒ 落地后不可执行。
-    // 包侧已修；这里再做一次落地归一，保证**旧包**装出来的 runtime 也能跑（幂等，不改内容）。
-    if (rel.endsWith('.sh')) { try { chmodSync(dst, (statSync(dst).mode & 0o777) | 0o111) } catch { /* noop */ } }
-    copied += 1;
-  };
-  for (const rel of files) copyFile(join(engine, rel), join(target, rel), rel);
-  let skillsFiles = 0;
-  if (skillsTarget) {
-    const skillsSrc = join(engine, 'skills');
-    if (existsSync(skillsSrc)) {
-      for (const rel of walkFiles(skillsSrc)) copyFile(join(skillsSrc, rel), join(skillsTarget, rel), `skills/${rel}`);
-      skillsFiles = walkFiles(skillsSrc).length;
-    }
-  }
-  mkdirSync(join(target, '.runtime-backup'), { recursive: true });
-  writeFileSync(join(target, 'RUNTIME_VERSION.json'), JSON.stringify({ package: '@whyshu/argent-engine', version, installedAt: now.toISOString(), files: copied, skillsFiles, skillsTarget: skillsTarget || null, backupDir }, null, 2) + '\n');
-  return { ok: true, version, files: copied, skillsFiles, target, skillsTarget, backupDir };
-}
-
-export function profileDir(dshHome, profile = PROFILE_NAME) {
-  return join(dshHome, 'profiles', profile);
-}
-
-/** 生成/更新 profile（幂等）：package.json（file: 依赖 + bundles）+ cordis.patch.yml（用户层） */
-export function buildProfile({ dshHome = dshHomeOf(), profile = PROFILE_NAME, repo = repoRoot(), extraBundles = [] } = {}) {
-  const dir = profileDir(dshHome, profile);
-  mkdirSync(dir, { recursive: true });
-  const plugins = pluginDirs({ repo });
-  const npmVersions = PUBLISHED_BUNDLE_VERSIONS;
-  const bundles = [...BASE_BUNDLES, ...(extraBundles || [])];
-  const deps = {};
-  const missing = [];
-  for (const name of bundles.filter((b) => !b.startsWith('@deepseek-ai/'))) {
-    if (plugins[name]) deps[name] = `file:${plugins[name]}`;
-    else if (npmVersions[name]) deps[name] = npmVersions[name];
-    else missing.push(name);
-  }
-  if (missing.length > 0) {
-    return { ok: false, code: 'plugins_missing', message: `找不到插件：${missing.join('、')}（本地无 plugins/ 且启动器 package.json 未声明依赖）`, dir };
-  }
-  // 非 @whyshu 的 bundle（dsh 官方）由宿主管，不进 profile dependencies
-  const pkg = {
-    name: `dsh-profile-${profile}`,
-    private: true,
-    dependencies: deps,
-    dsh: { profile: { bundles } },
-  };
-  writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
-  // 方案 C · P1：把"引擎在哪、什么版本、契约几"写成机器可读的契约文件（宿主壳只读它）
-  const engine = writeEngineContract(dir, { repo });
-  const patchLines = [
-    '# @whyshu/argent 生成（幂等；手工改动会在此文件重生成时被覆盖）',
-    '- id: agent-preset-registry',
-    '  config:',
-    `    default: ${DEFAULT_PRESET}`,
-  ];
-  if (bundles.includes('@linxin666/dsh-client-ui-task-board')) {
-    patchLines.push('- insert:', '    - id: ui-task-board', "      name: '@linxin666/dsh-client-ui-task-board'");
-  }
-  const patch = patchLines.join('\n') + '\n';
-  writeFileSync(join(dir, 'cordis.patch.yml'), patch);
-  // pnpm 配置必须与现有 web profile 同口径：否则 pnpm 会尝试从 registry 自动装 peer（含未发布版本）⇒ 安装失败
-  writeFileSync(join(dir, 'pnpm-workspace.yaml'), 'packages:\n  - .\nnodeLinker: hoisted\nautoInstallPeers: false\nallowBuilds:\n  protobufjs: true\n');
-  return { ok: true, dir, plugins: Object.keys(plugins), bundles: [...bundles], preset: DEFAULT_PRESET, engine };
-}
-
-export function depsInstalled(dshHome = dshHomeOf(), profile = PROFILE_NAME) {
-  return existsSync(join(profileDir(dshHome, profile), 'node_modules'));
-}
-
-/** 装配 profile 依赖：`dsh plugin --profile <p> install`（pnpm 在 profile 目录内执行） */
-export function installDeps({ dshHome = dshHomeOf(), profile = PROFILE_NAME, dshBin = 'dsh', spawn = spawnSync } = {}) {
-  const r = spawn(dshBin, ['plugin', '--profile', profile, 'install'], {
-    cwd: profileDir(dshHome, profile), env: { ...process.env, DSH_HOME: dshHome }, encoding: 'utf8', timeout: 300000,
-  });
-  const out = `${r.stdout || ''}${r.stderr || ''}`.trim();
-  if (r.error || r.status !== 0) return { ok: false, status: r.status, message: out.slice(-500) || r.error?.message || 'install failed' };
-  return { ok: true, status: 0, tail: out.slice(-300) };
-}
-
-export function authPath(dshHome = dshHomeOf()) {
-  return join(dshHome, 'argent', 'auth.json');
-}
-
-/** 读取已登录账号 token（600 文件；不存在/损坏返回 null） */
-export function readAuthToken(dshHome = dshHomeOf()) {
-  try {
-    const doc = JSON.parse(readFileSync(authPath(dshHome), 'utf8'));
-    return doc?.token ? doc : null;
-  } catch { return null; }
-}
-
-/** 发送短信验证码（首跑引导；开发环境服务端会返回 devCode） */
-export async function sendLoginCode({ serverUrl, phone, fetchImpl = globalThis.fetch }) {
-  const base = String(serverUrl || '').replace(/\/+$/, '');
-  const res = await fetchImpl(`${base}/api/user/sms/send`, {
-    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ phone }),
-  });
-  const text = await res.text(); let data = null; try { data = JSON.parse(text); } catch { data = null; }
-  if (!res.ok) return { ok: false, code: 'send_failed', message: data?.error || `HTTP ${res.status}`, cooldown: data?.cooldown };
-  return { ok: true, cooldown: data?.cooldown, devCode: data?.devCode || data?.code || '' };
-}
-
-/** 手机号+验证码登录（保存 token 到 600 auth.json，供 pair 使用） */
-export async function loginWithPhone({ serverUrl, phone, code, dshHome = dshHomeOf(), fetchImpl = globalThis.fetch }) {
-  const base = String(serverUrl || '').replace(/\/+$/, '');
-  const res = await fetchImpl(`${base}/api/user/login/phone`, {
-    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ phone, code }),
-  });
-  const text = await res.text(); let data = null; try { data = JSON.parse(text); } catch { data = null; }
-  const token = data?.token || data?.data?.token || '';
-  if (!res.ok || !token) return { ok: false, code: 'login_failed', message: data?.error || `HTTP ${res.status}` };
-  const path = authPath(dshHome);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify({ serverUrl: base, phone, token, savedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
-  return { ok: true, path, phone, serverUrl: base, tokenTail: token.slice(-6) };
-}
-
-export function runnerConfigPath(dshHome = dshHomeOf()) {
-  return join(dshHome, 'argent', 'runner.json');
-}
-
-export function runnerScriptPath({ repo = repoRoot() } = {}) {
-  // 发布包内置 runner（0.1.3 起）；本地仓库联调回退 scripts/argent-runner.mjs
-  const bundled = join(dirname(fileURLToPath(import.meta.url)), '..', 'runner', 'argent-runner.mjs');
-  if (existsSync(bundled)) return bundled;
-  const candidate = join(repo, 'scripts', 'argent-runner.mjs');
-  return existsSync(candidate) ? candidate : '';
-}
-
-/** P4 runner 的 launchd plist（macOS）；Linux 可换 systemd unit（TODO 发布前补） */
-export function buildLaunchdPlist({ dshHome = dshHomeOf(), repo = repoRoot(), nodeBin = process.execPath, runnerPath = '' } = {}) {
-  const script = runnerPath || runnerScriptPath({ repo });
-  const logDir = join(dshHome, 'argent', 'runner', 'logs');
-  return {
-    file: `${RUNNER_LABEL}.plist`,
-    content: `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>${RUNNER_LABEL}</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${nodeBin}</string>
-    <string>${script || '<argent-runner.mjs>'}</string>
-    <string>--config</string>
-    <string>${runnerConfigPath(dshHome)}</string>
-  </array>
-  <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
-  <key>StandardOutPath</key><string>${join(logDir, 'launchd.out.log')}</string>
-  <key>StandardErrorPath</key><string>${join(logDir, 'launchd.err.log')}</string>
-</dict>
-</plist>
-`,
-    label: RUNNER_LABEL,
-    script,
-  };
-}
-
-/** 状态自检（不启动任何东西；JSON 友好） */
-/**
- * 两构件对齐检查（方案 C · P3）：`<profile>/argent.json` ⇄ 实际引擎 ⇄ 插件声明。
- * ⛔ 只报告，不修；`problems` 为空才算对齐。
- */
-export function contractStatus({ dshHome = dshHomeOf(), profile = PROFILE_NAME, repo = repoRoot() } = {}) {
-  const dir = profileDir(dshHome, profile);
-  const file = join(dir, 'argent.json');
-  let contract = null;
-  try { contract = JSON.parse(readFileSync(file, 'utf8')); } catch { /* 缺文件/坏 JSON 都算未建立 */ }
-  const info = engineInfo({ repo });
-  const expected = info.ok ? engineContract(info.dir) : null;
-  let plugin = null;
-  try {
-    const pkg = JSON.parse(readFileSync(join(dir, 'node_modules', '@whyshu', 'argent-desktop', 'package.json'), 'utf8'));
-    plugin = { version: pkg.version || '', requires: pkg.argentEngine || '', contract: pkg.argentContract ?? null };
-  } catch { /* 未装插件（web profile）属正常 */ }
-  const problems = [];
-  if (!contract) problems.push(`缺少 ${file}（运行 argent setup 生成）`);
-  else {
-    if (contract.contract == null) problems.push('argent.json 缺 contract');
-    else if (expected !== null && contract.contract !== expected) problems.push(`契约不符：argent.json=${contract.contract}，引擎=${expected}`);
-    if (!contract.engineDir) problems.push('argent.json 未指向 engineDir');
-    else if (info.ok && contract.engineVersion !== info.version) problems.push(`引擎版本漂移：argent.json=${contract.engineVersion}，实际=${info.version}`);
-  }
-  if (plugin && plugin.contract != null && expected !== null && plugin.contract !== expected) {
-    problems.push(`插件要求契约 ${plugin.contract}，引擎提供 ${expected}`);
-  }
-  return { ok: problems.length === 0, file, contract, engine: info, plugin, expectedContract: expected, problems };
-}
-
-export function health({ dshHome = dshHomeOf(), profile = PROFILE_NAME, repo = repoRoot(), dshBin = 'dsh', port = 3080 } = {}) {
-  const version = probeDshVersion({ dshBin });
-  const dir = profileDir(dshHome, profile);
-  const profilePackage = join(dir, 'package.json');
-  const profilePatch = join(dir, 'cordis.patch.yml');
-  const runnerCfg = runnerConfigPath(dshHome);
-  const runnerCfgMode = existsSync(runnerCfg) ? (statSync(runnerCfg).mode & 0o777).toString(8) : '';
-  return {
-    ok: version.ok && versionMatches(version.version) && existsSync(profilePackage) && existsSync(profilePatch),
-    expectedDsh: DSH_EXACT_VERSION,
-    dsh: { ok: version.ok, version: version.ok ? version.version : '', matchesExact: version.ok && versionMatches(version.version), error: version.error },
-    profile: { dir, packageJson: existsSync(profilePackage), patch: existsSync(profilePatch) },
-    runner: { configPath: runnerCfg, configPresent: existsSync(runnerCfg), mode: runnerCfgMode },
-    webUrl: `http://127.0.0.1:${port}`,
-    contract: contractStatus({ dshHome, profile, repo }),
-    repo,
-  };
-}
-
-/**
- * 首跑配对：把 runner 配置写到 `$DSH_HOME/argent/runner.json`（600）。
- * 两种来源：
- *   · adminToken：调服务端 `POST /tenants/:appId/runner-tokens` 现场签发（90 天、绑定 appId）；
- *   · runnerToken：直接使用已签发的 token（由管理员线下交付）。
- * ⛔ 返回值/日志不回显 token；写盘前校验端口与响应。
- */
-export async function pairRunner({
-  serverUrl, tenantAppId, adminToken = '', runnerToken = '',
-  runnerId = '', label = '', dshHome = dshHomeOf(), fetchImpl = globalThis.fetch,
-}) {
-  const base = String(serverUrl || '').replace(/\/+$/, '');
-  const appId = String(tenantAppId || '').trim();
-  if (!base || !appId) return { ok: false, code: 'validation', message: 'serverUrl / tenantAppId 必填' };
-  if (!adminToken && !runnerToken) return { ok: false, code: 'validation', message: '需要 --admin-token 或 --runner-token 之一' };
-  let token = String(runnerToken || '').trim();
-  if (!token) {
-    const res = await fetchImpl(`${base}/api/argent/v1/tenants/${encodeURIComponent(appId)}/runner-tokens`, {
-      method: 'POST',
-      headers: { authorization: `Bearer ${String(adminToken).trim()}`, 'content-type': 'application/json' },
-      body: JSON.stringify({ label: String(label || 'argent-launcher') }),
-    });
-    const text = await res.text();
-    let data = null;
-    try { data = JSON.parse(text); } catch { data = null; }
-    if (!res.ok || !data?.data?.token) {
-      return { ok: false, code: 'issue_failed', message: `签发 runner token 失败：HTTP ${res.status} ${data?.error?.code || ''} ${data?.error?.message || ''}`.trim() };
-    }
-    token = data.data.token;
-  }
-  if (token.split('.').length !== 3) return { ok: false, code: 'token_shape', message: 'runner token 形态不正确（应为 JWT）' };
-  const cfgPath = runnerConfigPath(dshHome);
-  mkdirSync(dirname(cfgPath), { recursive: true });
-  const config = {
-    serverUrl: base, tenantAppId: appId, runnerToken: token,
-    runnerId: runnerId || `runner-${osHostname()}`,
-    leaseSec: 90, pollWaitMs: 20000, execTimeoutSec: 900,
-  };
-  writeFileSync(cfgPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
-  return { ok: true, configPath: cfgPath, serverUrl: base, tenantAppId: appId, runnerId: config.runnerId, tokenTail: token.slice(-6) };
-}
-
-
-// ── 客户机 outbound 更新（npm 唯一制品源；2026-10-22）────────────────
-/** 启动器包名与默认 registry。客户机只做出站 HTTPS；不依赖 /dl、SSH、组网。 */
-export const LAUNCHER_PACKAGE = '@whyshu/argent'
-export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
-
-/** 读取启动器自身版本（发布包 / 本地仓库均适用）。 */
-export function launcherVersion(launcherLib = dirname(fileURLToPath(import.meta.url))) {
-  try {
-    const pkg = JSON.parse(readFileSync(join(launcherLib, '..', 'package.json'), 'utf8'))
-    return String(pkg.version || '')
-  } catch { return '' }
-}
-
-/** 比较 x.y.z（支持 prerelease 简单后缀；返回 -1/0/1）。 */
-export function compareVersions(a, b) {
-  const parse = (v) => String(v || '').trim().replace(/^v/, '').split('-')[0].split('.').map((x) => Number(x) || 0)
-  const pa = parse(a); const pb = parse(b)
-  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
-    const d = (pa[i] || 0) - (pb[i] || 0)
-    if (d) return d > 0 ? 1 : -1
-  }
-  return 0
-}
-
-/** 从 npm registry 读取 @whyshu/argent 的 latest 版本（公开包，无需 token）。 */
-export async function latestLauncherVersion({
-  registry = process.env.ARGENT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY,
-  packageName = LAUNCHER_PACKAGE,
-  fetchImpl = globalThis.fetch,
-} = {}) {
-  const base = String(registry || DEFAULT_NPM_REGISTRY).replace(/\/+$/, '')
-  const encoded = String(packageName).replace('/', '%2F')
-  const url = `${base}/${encoded}/latest`
-  try {
-    const res = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15000) })
-    const text = await res.text()
-    let data = null
-    try { data = JSON.parse(text) } catch { data = null }
-    if (!res.ok) return { ok: false, code: 'registry_http', message: `registry HTTP ${res.status}`, url }
-    const version = String(data?.version || data?.['dist-tags']?.latest || '').trim()
-    if (!version) return { ok: false, code: 'registry_shape', message: 'registry 未返回 version', url }
-    return { ok: true, version, integrity: String(data?.dist?.integrity || ''), tarball: String(data?.dist?.tarball || ''), registry: base, url }
-  } catch (e) {
-    return { ok: false, code: 'registry_fetch', message: e?.message || String(e), url }
-  }
-}
-
-/** 读取已物化 runtime 的版本（没有则空串）。 */
-export function readRuntimeVersion(target = join(homedir(), '.argent-dsh')) {
-  try {
-    const d = JSON.parse(readFileSync(join(target, 'RUNTIME_VERSION.json'), 'utf8'))
-    return String(d?.version || '')
-  } catch { return '' }
-}
-
-/** 读 profile 当前插件版本（用于判断“runtime 已是最新、但插件还是旧版”）。 */
-export function readProfilePluginVersions({ dshHome = dshHomeOf(), profile = PROFILE_NAME } = {}) {
-  try {
-    const pkg = JSON.parse(readFileSync(join(profileDir(dshHome, profile), 'package.json'), 'utf8'))
-    const deps = pkg && typeof pkg.dependencies === 'object' ? pkg.dependencies : {}
-    const out = {}
-    for (const [name, ver] of Object.entries(deps)) {
-      if (!name.startsWith('@whyshu/argent-')) continue
-      const v = String(ver || '')
-      out[name] = v.startsWith('file:') ? '' : v
-    }
-    return out
-  } catch { return {} }
-}
-
-/** 检查更新（只读；不下载、不安装）。 */
-export async function checkForUpdate({
-  launcherLib, dshHome = dshHomeOf(), profile = PROFILE_NAME,
-  target = join(homedir(), '.argent-dsh'), registry = process.env.ARGENT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY,
-  fetchImpl = globalThis.fetch,
-} = {}) {
-  const current = launcherVersion(launcherLib)
-  const remote = await latestLauncherVersion({ registry, fetchImpl })
-  const runtime = readRuntimeVersion(target)
-  const installedPlugins = readProfilePluginVersions({ dshHome, profile })
-  if (!remote.ok) return { ok: false, code: remote.code, message: remote.message, current, runtime, installedPlugins, registry }
-  const pluginUpdates = []
-  for (const [name, want] of Object.entries(PUBLISHED_BUNDLE_VERSIONS)) {
-    const have = installedPlugins[name]
-    // 本地 file: 装配（开发机）不算可更新客户机；只比较明确版本号。
-    if (!have || !want) continue
-    if (compareVersions(want, have) > 0) pluginUpdates.push({ name, current: have, latest: want })
-  }
-  const launcherUpdate = current ? compareVersions(remote.version, current) > 0 : true
-  return {
-    ok: true, current, latest: remote.version,
-    updateAvailable: Boolean(launcherUpdate || pluginUpdates.length),
-    launcherUpdate, pluginUpdates, installedPlugins,
-    registry: remote.registry, integrity: remote.integrity, tarball: remote.tarball,
-    runtime, runtimeTarget: target,
-  }
-}
-
-
-/** 解析客户机**真实的** dsh（npx 启动器的依赖里也带一个 dsh，PATH 会被 npx 改写，不能直接用裸 `dsh`）。 */
-export function resolveDshBin({ env = process.env, home = homedir() } = {}) {
-  const explicit = String(env.ARGENT_DSH_BIN || env.DSH_BIN || '').trim()
-  if (explicit && existsSync(explicit)) return explicit
-  const pathEntries = String(env.PATH || '').split(':').filter(Boolean)
-    .filter((p) => !p.includes('_npx') && !p.replace(/\/+$/, '').endsWith('node_modules/.bin'))
-  for (const dir of pathEntries) {
-    const p = join(dir, process.platform === 'win32' ? 'dsh.cmd' : 'dsh')
-    if (existsSync(p)) return p
-  }
-  for (const p of [
-    join(home, '.local', 'node', 'bin', 'dsh'),
-    '/opt/homebrew/bin/dsh',
-    '/usr/local/bin/dsh',
-  ]) if (existsSync(p)) return p
-  return 'dsh'
-}
-
-/** 更新 profile 里已存在的插件版本；不重建 profile、不丢 bundles/依赖结构。 */
-export function updateProfilePluginVersions({
-  dshHome = dshHomeOf(), profile = PROFILE_NAME, versions = PUBLISHED_BUNDLE_VERSIONS,
-} = {}) {
-  const file = join(profileDir(dshHome, profile), 'package.json')
-  let pkg = null
-  try { pkg = JSON.parse(readFileSync(file, 'utf8')) } catch { return { ok: false, code: 'profile_missing', message: `profile 不存在：${file}` } }
-  if (!pkg.dependencies || typeof pkg.dependencies !== 'object') return { ok: false, code: 'profile_shape', message: 'profile package.json 缺 dependencies' }
-  const changed = []
-  for (const [name, want] of Object.entries(versions || {})) {
-    const have = String(pkg.dependencies[name] || '')
-    if (!have || have.startsWith('file:') || have === want) continue
-    pkg.dependencies[name] = want
-    changed.push({ name, from: have, to: want })
-  }
-  if (changed.length) writeFileSync(file, JSON.stringify(pkg, null, 2) + '\n')
-  return { ok: true, file, changed }
-}