@forsion/tangu-computer-use 0.5.8

package/scripts/build-native.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageMacosApp } from "./package-macos-app.mjs";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const macosSourcePaths = [
+	"foreground_activity.swift",
+	"agent_cursor.swift",
+	"agent_cursor_motion.swift",
+	"agent_highlight.swift",
+	"live_stream.swift",
+	"bridge.swift",
+].map((file) => path.join(rootDir, "native", "macos", file));
+const windowsCrateDir = path.join(rootDir, "native", "windows", "bridge-rs");
+const linuxCrateDir = path.join(rootDir, "native", "linux", "bridge-rs");
+const linuxTargets = { x64: "x86_64-unknown-linux-gnu", arm64: "aarch64-unknown-linux-gnu" };
+const archTriples = {
+	arm64: "arm64-apple-macosx",
+	x64: "x86_64-apple-macosx",
+};
+const deploymentTarget = "14.0";
+const frameworks = ["ApplicationServices", "AppKit", "ScreenCaptureKit", "Foundation", "SwiftUI"];
+const defaultCodeSignIdentifier = "com.forsion.tangu-computer-use";
+
+async function exists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function getArg(name) {
+	const index = process.argv.indexOf(name);
+	if (index >= 0 && index + 1 < process.argv.length) {
+		return process.argv[index + 1];
+	}
+	return undefined;
+}
+
+function hasArg(name) {
+	return process.argv.includes(name);
+}
+
+function normalizeArch(arch) {
+	if (arch === "universal" || arch === "all") return arch;
+	if (arch === "arm64" || arch === "x64") return arch;
+	throw new Error(`Unsupported architecture '${arch}'. Supported: arm64, x64, universal, all.`);
+}
+
+async function run(command, args) {
+	await new Promise((resolve, reject) => {
+		const child = spawn(command, args, { stdio: "inherit" });
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(new Error(`Command failed (${code}): ${command} ${args.join(" ")}`));
+		});
+	});
+}
+
+function defaultOutputPath(arch) {
+	return path.join(rootDir, "prebuilt", "macos", arch, "bridge");
+}
+
+function moduleCachePath(arch) {
+	return path.join(os.tmpdir(), `tangu-computer-use-swift-module-cache-${arch}`);
+}
+
+function swiftArgsForArch(arch, outputPath) {
+	const args = [
+		"swiftc",
+		"-target",
+		`${archTriples[arch]}${deploymentTarget}`,
+		"-module-cache-path",
+		moduleCachePath(arch),
+		"-O",
+	];
+	for (const framework of frameworks) args.push("-framework", framework);
+	args.push(...macosSourcePaths, "-o", outputPath);
+	return args;
+}
+
+function signingArgs() {
+	const identity = getArg("--sign-identity") ?? process.env.PI_COMPUTER_USE_CODESIGN_IDENTITY ?? "-";
+	const identifier = getArg("--sign-identifier") ?? process.env.PI_COMPUTER_USE_CODESIGN_IDENTIFIER ?? defaultCodeSignIdentifier;
+	const args = ["--force", "-i", identifier];
+	if (hasArg("--hardened-runtime")) {
+		args.push("--options", "runtime");
+	}
+	if (hasArg("--timestamp")) {
+		args.push("--timestamp");
+	} else {
+		args.push("--timestamp=none");
+	}
+	args.push("--sign", identity);
+	return args;
+}
+
+async function signBinary(outputPath) {
+	if (hasArg("--no-sign") || process.env.PI_COMPUTER_USE_NO_SIGN === "1") return;
+	await run("/usr/bin/codesign", [...signingArgs(), outputPath]);
+}
+
+async function packageApp(binary, arch) {
+	const version = JSON.parse(await fs.readFile(path.join(rootDir, 'package.json'), 'utf8')).version;
+	// Even unsigned dev binaries need a sealed app for installation. This
+	// build-time ad-hoc fallback never discovers or creates a private key.
+	const sign = hasArg('--no-sign') || process.env.PI_COMPUTER_USE_NO_SIGN === '1'
+		? ['--force', '-i', defaultCodeSignIdentifier, '--timestamp=none', '--sign', '-'] : signingArgs();
+	await packageMacosApp(binary, path.join(rootDir, 'prebuilt/macos', arch), version, sign);
+}
+
+async function buildForArch(arch, outputPath) {
+	await fs.mkdir(path.dirname(outputPath), { recursive: true });
+	console.log(`Building native helper for ${arch}...`);
+	await run("xcrun", swiftArgsForArch(arch, outputPath));
+	await fs.chmod(outputPath, 0o755);
+	await signBinary(outputPath);
+	console.log(`Built helper at ${outputPath}`);
+}
+
+async function buildUniversal(outputPath) {
+	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "tangu-computer-use-build-"));
+	const x64Output = path.join(tempDir, "bridge-x64");
+	const arm64Output = path.join(tempDir, "bridge-arm64");
+	await buildForArch("x64", x64Output);
+	await buildForArch("arm64", arm64Output);
+	await fs.mkdir(path.dirname(outputPath), { recursive: true });
+	await run("lipo", ["-create", "-output", outputPath, x64Output, arm64Output]);
+	await fs.chmod(outputPath, 0o755);
+	await signBinary(outputPath);
+	console.log(`Built universal helper at ${outputPath}`);
+	await fs.rm(tempDir, { recursive: true, force: true });
+}
+
+/**
+ * Return the actual cargo binary path, handling platform suffix differences.
+ * On Windows, the binary is named "windows-bridge.exe"; on other platforms it's "windows-bridge".
+ */
+function windowsBinaryPath(crateDir, target) {
+	const releaseDir = target
+		? path.join(crateDir, "target", target, "release")
+		: path.join(crateDir, "target", "release");
+	return path.join(releaseDir, "windows-bridge.exe");
+}
+
+async function buildWindowsHelper(prebuiltOutput) {
+	const target = getArg("--target");
+	if (process.platform !== "win32" && !target?.includes("windows")) {
+		throw new Error("Refusing to label a host binary as Windows. Build on Windows or pass an explicit Windows --target triple.");
+	}
+	const prebuiltDir = prebuiltOutput
+		? path.resolve(process.cwd(), prebuiltOutput, "..")
+		: path.join(rootDir, "prebuilt", "windows");
+	const manifestPath = path.join(windowsCrateDir, "Cargo.toml");
+
+	console.log("Building Windows helper with cargo...");
+	// Tangu: link the MSVC runtime statically. The default dynamic link imports VCRUNTIME140.dll, which Windows does
+	// not ship, so the helper would not start on a clean machine; verify-package.mjs rejects such a helper. RUSTFLAGS,
+	// not the crate's .cargo/config.toml: cargo reads config from the caller's cwd. A duplicate flag (Genesis CI sets
+	// it too) is harmless.
+	// ponytail: a set RUSTFLAGS makes cargo ignore config rustflags (build.rustflags, target.<triple>.rustflags,
+	// CARGO_TARGET_*_RUSTFLAGS), so a cross-build's extra flags (xwin's -Lnative) must come in RUSTFLAGS. If that
+	// bites, pass `--config target.'cfg(target_env = "msvc")'.rustflags=[...]` whenever RUSTFLAGS is unset.
+	process.env.RUSTFLAGS = `${process.env.RUSTFLAGS ?? ""} -C target-feature=+crt-static`.trim();
+	const cargoArgs = [
+		"build",
+		"--release",
+		"--manifest-path",
+		manifestPath,
+	];
+	if (target) cargoArgs.push("--target", target);
+	await run("cargo", cargoArgs);
+
+	await fs.mkdir(prebuiltDir, { recursive: true });
+
+	const cargoOutput = windowsBinaryPath(windowsCrateDir, target);
+	const handle = await fs.open(cargoOutput, "r");
+	try {
+		const signature = Buffer.alloc(2);
+		await handle.read(signature, 0, 2, 0);
+		if (signature.toString("ascii") !== "MZ") {
+			throw new Error(`Cargo output is not a Windows PE executable: ${cargoOutput}`);
+		}
+	} finally {
+		await handle.close();
+	}
+	const prebuiltDest = path.join(prebuiltDir, "windows-bridge.exe");
+	await fs.copyFile(cargoOutput, prebuiltDest);
+	await fs.chmod(prebuiltDest, 0o755);
+	console.log(`Built Windows helper at ${prebuiltDest}`);
+}
+
+function linuxBinaryPath(crateDir, target) {
+	const targetDir = target ? path.join("target", target) : "target";
+	return path.join(crateDir, targetDir, "release", "linux-bridge");
+}
+
+function defaultLinuxOutputPath(arch) {
+	return path.join(rootDir, "prebuilt", "linux", arch, "linux-bridge");
+}
+
+async function buildLinuxForArch(arch, outputPath) {
+	const explicitTarget = getArg("--target");
+	if (explicitTarget && !explicitTarget.includes("linux")) throw new Error(`Linux builds require a Linux --target triple, got ${explicitTarget}.`);
+	const target = explicitTarget ?? (process.platform === "linux" && process.arch === arch ? undefined : linuxTargets[arch]);
+	console.log(`Building Linux helper for ${arch} with cargo...`);
+	const cargoArgs = ["build", "--release", "--manifest-path", path.join(linuxCrateDir, "Cargo.toml")];
+	if (target) cargoArgs.push("--target", target);
+	await run("cargo", cargoArgs);
+	const cargoOutput = linuxBinaryPath(linuxCrateDir, target);
+	const header = await fs.readFile(cargoOutput).then((data) => data.subarray(0, 20));
+	if (header.length < 20 || !header.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))) throw new Error(`Cargo output is not a Linux ELF executable: ${cargoOutput}`);
+	const machine = header.readUInt16LE(18);
+	const expectedMachine = arch === "x64" ? 0x3e : 0xb7;
+	if (machine !== expectedMachine) throw new Error(`Cargo output architecture does not match ${arch}: ${cargoOutput}`);
+	await fs.mkdir(path.dirname(outputPath), { recursive: true });
+	await fs.copyFile(cargoOutput, outputPath);
+	await fs.chmod(outputPath, 0o755);
+	console.log(`Built Linux helper at ${outputPath}`);
+}
+
+async function buildLinuxHelper() {
+	const arch = normalizeArch(getArg("--arch") ?? process.arch);
+	if (arch === "universal") throw new Error("Linux does not support --arch universal. Use x64, arm64, or all.");
+	const outputArg = getArg("--output");
+	if (arch === "all") {
+		if (outputArg) throw new Error("--output is not supported with --arch all. Use a single architecture for one output.");
+		for (const nextArch of ["x64", "arm64"]) await buildLinuxForArch(nextArch, defaultLinuxOutputPath(nextArch));
+		return;
+	}
+	await buildLinuxForArch(arch, outputArg ? path.resolve(process.cwd(), outputArg) : defaultLinuxOutputPath(arch));
+}
+
+async function main() {
+	const explicitPlatform = getArg("--platform");
+
+	if (explicitPlatform === "windows") {
+		await buildWindowsHelper(getArg("--output"));
+		return;
+	}
+
+	if (explicitPlatform === "linux") {
+		await buildLinuxHelper();
+		return;
+	}
+
+	if (explicitPlatform === "darwin") {
+		// Fall through to macOS build logic below.
+	} else if (process.platform === "win32") {
+		await buildWindowsHelper(getArg("--output"));
+		return;
+	} else if (process.platform === "linux") {
+		await buildLinuxHelper();
+		return;
+	} else if (process.platform !== "darwin") {
+		console.log(
+			`Skipping native build: unsupported platform "${process.platform}". ` +
+				"Use --platform windows or --platform linux to build a helper, or run on macOS for the macOS helper.",
+		);
+		return;
+	}
+
+	const arch = normalizeArch(getArg("--arch") ?? process.arch);
+	const outputArg = getArg("--output");
+
+	if (arch === "all") {
+		if (outputArg) {
+			throw new Error("--output is not supported with --arch all. Use a single architecture for one output.");
+		}
+		for (const nextArch of ["x64", "arm64"]) {
+			await buildForArch(nextArch, defaultOutputPath(nextArch));
+			await packageApp(defaultOutputPath(nextArch), nextArch);
+		}
+		return;
+	}
+
+	const outputPath = outputArg ? path.resolve(process.cwd(), outputArg) : defaultOutputPath(arch);
+	if (arch === "universal") {
+		await buildUniversal(outputPath);
+		if (!outputArg) await packageApp(outputPath, arch);
+		return;
+	}
+
+	await buildForArch(arch, outputPath);
+	if (!outputArg) await packageApp(outputPath, arch);
+}
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+});

package/scripts/build.mjs

@@ -0,0 +1,84 @@
+// esbuild bundle:src/index.ts → tangu-plugins/computer-use/dist/index.js(单文件 ESM,运行时零 node_modules)。
+// pi 依赖靠 alias 指到 pi-compat;node 内置 external;banner 注入 __dirname/__filename/require(vendor 可能用)。
+//
+// 产物为什么放这么深:本仓已升级为 **Forsion 捆绑包** —— 仓根就是 bundle 根(manifest.json + main.js +
+// skills/),引擎侧内容按 bundles.ts 的约定住在 tangu-plugins/<pid>/。
+import { build } from 'esbuild';
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = path.join(root, 'tangu-plugins/computer-use/dist');
+
+// vendor 三个 helper(macos/windows/linux)用 import.meta.url 往上 3 级找包根,再拼 scripts/setup-helper.mjs
+// 去装 native helper。源码树里 src/vendor/platform/<os>/ → 包根,对;打成单文件后就看产物放哪:
+//   放 <root>/dist/index.js       → 上跳 3 级冲出仓外,spawn 必失败(曾是 P0,靠构建期改写补救)
+//   放 <root>/tangu-plugins/computer-use/dist/index.js → 上跳 3 级正好是 <root> ✔
+// 所以捆绑包化之后**不再需要改写 vendor**,只需守住这个不变量。两道守卫:
+//   ① 每个平台文件里那行还在(上游改写法就炸,别静默失配)
+//   ② 构建完按产物位置实算一遍,3 级上跳必须落在含 scripts/setup-helper.mjs 的目录
+const PLATFORMS = ['macos', 'windows', 'linux'];
+const PKG_ROOT_NEEDLE = 'path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..")';
+const seen = new Set();
+const checkPackageRoot = {
+  name: 'check-vendor-package-root',
+  setup(b) {
+    b.onLoad({ filter: new RegExp(`vendor[\\\\/]platform[\\\\/](${PLATFORMS.join('|')})[\\\\/]helper\\.ts$`) }, async (args) => {
+      const src = await readFile(args.path, 'utf8');
+      if (!src.includes(PKG_ROOT_NEEDLE)) {
+        throw new Error(`PACKAGE_ROOT pattern not found in ${args.path} — 上游改了写法,重新核对 build.mjs 里的产物层级`);
+      }
+      seen.add(path.basename(path.dirname(args.path)));
+      return { contents: src, loader: 'ts' };
+    });
+  },
+};
+
+await build({
+  entryPoints: [path.join(root, 'src/index.ts')],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node20',
+  outfile: path.join(outDir, 'index.js'),
+  external: ['node:*'],
+  alias: { '@earendil-works/pi-coding-agent': path.join(root, 'src/pi-compat.ts') },
+  plugins: [checkPackageRoot],
+  banner: {
+    js: [
+      "import { createRequire as __createRequire } from 'node:module';",
+      "import { fileURLToPath as __fileURLToPath } from 'node:url';",
+      "import { dirname as __pathDirname } from 'node:path';",
+      'const require = __createRequire(import.meta.url);',
+      'const __filename = __fileURLToPath(import.meta.url);',
+      'const __dirname = __pathDirname(__filename);',
+    ].join('\n'),
+  },
+  logLevel: 'info',
+});
+
+const missed = PLATFORMS.filter((p) => !seen.has(p));
+if (missed.length) {
+  throw new Error(`${missed.join('/')} 后端没进 bundle —— 上游改了目录布局,或 platform/index.ts 不再引它`);
+}
+
+const resolvedPackageRoot = path.resolve(outDir, '..', '..', '..');
+await access(path.join(resolvedPackageRoot, 'scripts', 'setup-helper.mjs')).catch(() => {
+  throw new Error(
+    `PACKAGE_ROOT 不变量破了:产物在 ${outDir},vendor 上跳 3 级得到 ${resolvedPackageRoot},那里没有 scripts/setup-helper.mjs。` +
+      '改产物位置就必须同步核对这条(装 native helper 全靠它)。',
+  );
+});
+
+// 纯前台透明化模块单独产一份,给 scripts/no-foreground.check.mjs 免依赖 import(node 跑不了 .ts)。
+await build({
+  entryPoints: [path.join(root, 'src/foregroundNote.ts')],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  target: 'node20',
+  outfile: path.join(outDir, 'foregroundNote.js'),
+});
+
+console.log('✓ built tangu-plugins/computer-use/dist/index.js');

package/scripts/calc-fixture.mjs

@@ -0,0 +1,78 @@
+/**
+ * 三个真机仪器共用的「干净的计算器」夹具。
+ *
+ * 为什么值得单独拿出来:每个仪器跑完都 `pkill -x Calculator`,下一个立刻 `open` —— 会撞上**正在退出**
+ * 的旧进程,拿到一个马上就要消失的 windowId。表现是取景流绑到死窗口、整轮回同一张图,于是
+ * check:liveview 在单跑时绿、串跑时随机红。薄脆的仪器比没有更坏:它会训练人忽略红灯。
+ * 所以开之前先确认旧的**真的没了**,再开、再等到窗口可观察为止。
+ */
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { resolveMacosHelperAppPath } from '../src/vendor/platform/macos/helper-path.mjs'
+
+const execFileP = promisify(execFile)
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const BUNDLE_ID = 'com.apple.calculator'
+
+export const SOCK = `${os.homedir()}/Library/Caches/tangu-computer-use/bridge.sock`
+export const HELPER_APP = resolveMacosHelperAppPath()
+export const HELPER_EXECUTABLE = path.join(HELPER_APP, 'Contents', 'MacOS', 'bridge')
+
+/**
+ * daemon 没在跑就拉起来。仪器要能从**冷机**跑起来 —— 刚重装完 helper、或刚 `computer-use stop` 过,
+ * 否则每次都得先手动铺场,而「先手动铺场」的仪器迟早没人跑。
+ *
+ * ⚠️必须走 `open -n -g <APP>`(与 vendor 的 launchDaemon 一致),**不能**直接 spawn
+ * Contents/MacOS/bridge:TCC 认的是 responsible process,直接 spawn 会把归因挂到调用者
+ * (终端/node)身上,于是 diagnostics 报「没有辅助功能权限」—— 看起来像授权丢了,其实是启动方式错了。
+ */
+export async function ensureDaemon(ask) {
+  for (let attempt = 0; attempt < 25; attempt++) {
+    try { return await ask({ cmd: 'diagnostics' }) } catch (e) {
+      if (attempt === 0 && (e.code === 'ECONNREFUSED' || e.code === 'ENOENT')) {
+        fs.rmSync(SOCK, { force: true })
+        await execFileP('open', ['-n', '-g', HELPER_APP, '--args', 'serve', '--socket', SOCK]).catch(() => {})
+      }
+      await sleep(300)
+    }
+  }
+  throw new Error(`helper daemon 起不来(${HELPER_APP})`)
+}
+
+async function listCalculator(ask) {
+  return (await ask({ cmd: 'listApps' })).find((a) => a.bundleId === BUNDLE_ID)
+}
+
+/** 结束掉当前的计算器,并等到 helper 也确认它不在了。 */
+export async function killCalculator(ask, timeoutMs = 8_000) {
+  await execFileP('pkill', ['-x', 'Calculator']).catch(() => {})
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (!(await listCalculator(ask))) return
+    await sleep(150)
+  }
+  // ⚠️静默放行等于把夹具要消灭的竞态原样放回来:下一步会立刻 open,撞上还没退干净的旧实例。
+  // 宁可红,也别让后面那些断言在一个不确定的场子里跑。
+  throw new Error('计算器在 ' + timeoutMs + 'ms 内没有退出 —— 场子不干净,拒绝继续')
+}
+
+/** 开一个全新的、后台的、已经有可观察窗口的计算器。 */
+export async function freshCalculator(ask, timeoutMs = 15_000) {
+  await killCalculator(ask)
+  await execFileP('open', ['-g', '-a', 'Calculator'])
+  const deadline = Date.now() + timeoutMs
+  let last = '还没看到计算器进程'
+  while (Date.now() < deadline) {
+    const calc = await listCalculator(ask)
+    if (calc) {
+      const win = (await ask({ cmd: 'listRoots', pid: calc.pid })).roots.find((r) => r.windowId)
+      if (win) return { calc, win }
+      last = '进程在但还没有可见窗口'
+    }
+    await sleep(300)
+  }
+  throw new Error(`等计算器就绪超时:${last}`)
+}

package/scripts/cli-exit.check.mjs

@@ -0,0 +1,49 @@
+// `tangu computer-use setup|doctor` must let the process exit by itself. On Windows and Linux the helper is a
+// stdio child whose open pipes keep the event loop alive, and the host deliberately never force-exits after a
+// plugin command (long-running commands such as `tangu worker` live on their open handles). Runs the real cliMain
+// in its own process with a helper of that shape and asserts the process ends within the deadline, with the
+// command's exit code.
+import assert from 'node:assert/strict';
+import { build } from 'esbuild';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const temp = mkdtempSync(path.join(os.tmpdir(), 'cu-cli-exit-'));
+try {
+  await build({ entryPoints: [path.resolve('src/setup.ts')], outfile: path.join(temp, 'cli.mjs'), bundle: true, platform: 'node', format: 'esm',
+    plugins: [{ name: 'stdio-helper', setup(b) {
+      b.onResolve({ filter: /\/vendor\/bridge\.ts$|\/helperState\.ts$/ }, (args) => ({ path: args.path, namespace: 'fixture' }));
+      b.onLoad({ filter: /.*/, namespace: 'fixture' }, (args) => ({ contents: args.path.endsWith('helperState.ts')
+        ? `export const helperInstalled = () => !process.env.CU_FIXTURE_NO_HELPER; export const helperExecutablePath = () => 'fixture-helper';`
+        : `import { spawn } from 'node:child_process';
+           let child;
+           export async function ensureComputerUseSetup() {
+             child = spawn(process.execPath, ['-e', 'process.stdin.resume()'], { stdio: 'pipe' }); // same shape as the Windows/Linux helper
+             if (process.env.CU_FIXTURE_FAIL) throw new Error('fixture helper is not ready');
+           }
+           export async function shutdownComputerUseSession() {
+             if (!child) return;
+             child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); child.kill();
+             child = undefined;
+           }` }));
+    } }], logLevel: 'silent' });
+  const runner = path.join(temp, 'run.mjs');
+  // Mirrors the host: the returned code becomes the exit code, nothing forces the process to exit.
+  writeFileSync(runner, `import { cliMain } from './cli.mjs';\nprocess.exitCode = await cliMain(process.argv.slice(2));\n`);
+  for (const [name, args, env, code] of [
+    ['setup succeeds', ['setup'], {}, 0],
+    ['doctor succeeds', ['doctor'], {}, 0],
+    ['setup fails after starting the helper', ['setup'], { CU_FIXTURE_FAIL: '1' }, 1],
+    ['doctor fails after starting the helper', ['doctor'], { CU_FIXTURE_FAIL: '1' }, 1],
+    ['doctor without an installed helper', ['doctor'], { CU_FIXTURE_NO_HELPER: '1' }, 1],
+  ]) {
+    const r = spawnSync(process.execPath, [runner, ...args], { env: { ...process.env, ...env }, encoding: 'utf8', timeout: 10_000 });
+    assert.equal(r.error?.code, undefined, `${name}: the process did not exit on its own (${r.error?.code})`);
+    assert.equal(r.status, code, `${name}: exit code\n${r.stdout}${r.stderr}`);
+    console.log(`PASS ${name}`);
+  }
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}

package/scripts/helper-path.check.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// mac helper 安装位置的解析规则(照搬上游 check-macos-helper-path.mjs,路径改到 vendor)。
+// 为什么值得留:v0.5.0 起 helper 不再固定装 /Applications —— 已有的可写系统安装留在原地,其余一律
+// 装进 ~/Applications(标准用户无需管理员)。解析错 = 装到一处、运行时连另一处,doctor 全绿但真操作必失败。
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { resolveMacosHelperAppPath } from '../src/vendor/platform/macos/helper-path.mjs';
+
+const homeDir = path.join(path.sep, 'Users', 'standard-user');
+const systemHelperAppPath = path.join(path.sep, 'Applications', 'tangu-computer-use.app');
+const userHelperAppPath = path.join(homeDir, 'Applications', 'tangu-computer-use.app');
+
+assert.equal(
+  resolveMacosHelperAppPath({ env: { PI_COMPUTER_USE_HELPER_APP_PATH: '/tmp/custom-helper.app' }, homeDir }),
+  '/tmp/custom-helper.app',
+  '显式路径优先',
+);
+assert.equal(
+  resolveMacosHelperAppPath({ env: {}, homeDir, systemHelperAppPath, fileExists: () => false }),
+  userHelperAppPath,
+  '全新安装走 ~/Applications',
+);
+assert.equal(
+  resolveMacosHelperAppPath({ env: {}, homeDir, systemHelperAppPath, fileExists: () => true, directoryIsWritable: () => true }),
+  systemHelperAppPath,
+  '已有的可写系统安装留在原地(不迁移 = 不用重新授权 TCC)',
+);
+assert.equal(
+  resolveMacosHelperAppPath({ env: {}, homeDir, systemHelperAppPath, fileExists: () => true, directoryIsWritable: () => false }),
+  userHelperAppPath,
+  '标准用户从不可写的系统安装迁走',
+);
+
+// 品牌:app 名必须是 tangu-*,否则 native/setup-helper 与运行时对不上(P0 复发防线)。
+assert.ok(
+  resolveMacosHelperAppPath({ env: {}, homeDir, fileExists: () => false }).endsWith('tangu-computer-use.app'),
+  'helper app 名必须品牌化',
+);
+
+// ── 自装/自更新的前置条件(症状:「首次安装和更新都要去终端敲 setup」)────────────────
+// 自愈只有在 bundle **自带**安装脚本 + 随包二进制时才成立。这三样任缺其一,
+// onboarding.ts 的 ensureHelperCurrent 就只能退回「请开终端」—— 而那正是要消灭的体验。
+// 从**构建产物**的位置往上找,而不是从本脚本找:产物挪位过一次就是 P0(见 scripts/build.mjs)。
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const artifact = path.join(repoRoot, 'tangu-plugins', 'computer-use', 'dist', 'index.js');
+assert.ok(existsSync(artifact), `构建产物不在 ${artifact} —— 先 npm run build`);
+
+function bundleRootFrom(startFile) {
+  let dir = path.dirname(startFile);
+  for (let up = 0; up < 6; up++) {
+    if (existsSync(path.join(dir, 'manifest.json')) && existsSync(path.join(dir, 'scripts', 'setup-helper.mjs'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+assert.equal(bundleRootFrom(artifact), repoRoot, '从产物往上必须能找到 bundle 根(manifest.json + scripts/setup-helper.mjs)');
+
+const arch = process.arch === 'x64' ? 'x64' : 'arm64';
+assert.ok(
+  existsSync(path.join(repoRoot, 'prebuilt', 'macos', arch, 'bridge'))
+    || existsSync(path.join(repoRoot, 'prebuilt', 'macos', 'universal', 'tangu-computer-use.app')),
+  `bundle 里必须随包带 native helper(prebuilt/macos/${arch}/bridge 或 universal 的已签名 .app)—— 否则自装要联网,离线/内网必失败`,
+);
+
+// ⚠️自装绝不能杀安装子进程:它内部 codesign helper.app,被中断会留下 *.cstemp,下次 --deep 把它封进
+// CodeResources 再删掉 → 签名恒定校验失败 → TCC 认签名 → 用户看到「权限开关怎么点都没用」。
+// 这条错了**不会报错**,只会静默毁掉授权,所以用文本防线钉住(2026-07-28 真踩过)。
+import { readFileSync } from 'node:fs';
+const onboarding = readFileSync(path.join(repoRoot, 'src', 'onboarding.ts'), 'utf8');
+assert.ok(!/child\.kill\(/.test(onboarding), 'src/onboarding.ts 不得 kill 安装子进程 —— 中断 codesign 会永久毁掉签名与 TCC 授权');
+assert.ok(/ELECTRON_RUN_AS_NODE/.test(onboarding), '自装必须设 ELECTRON_RUN_AS_NODE,否则在 Electron 宿主里会去开窗口而不是跑脚本');
+assert.ok(/macosHelperIsCurrent/.test(onboarding), 'helperNeedsUpdate 与安装器共用完整 App 与签名校验');
+// 权限真值只能问 checkPermissions:diagnostics 的 screenRecording 只是 CGPreflight 缓存值
+// (bridge.swift 自己的注释:"Permission truth comes from checkPermissions")。
+assert.ok(/checkPermissions/.test(onboarding), '权限判定必须走 checkPermissions,不能用 diagnostics 的预检值');
+
+console.log('helper path checks passed');

package/scripts/helper-refresh.check.mjs

@@ -0,0 +1,62 @@
+// Exercise the production onboarding flow with isolated installer/daemon boundaries.
+import assert from 'node:assert/strict';
+import { build } from 'esbuild';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const temp = mkdtempSync(path.join(os.tmpdir(), 'cu-refresh-'));
+try {
+  for (const scenario of ['stale', 'missing', 'current', 'install-failure', 'restart-failure']) {
+    const root = path.join(temp, scenario), events = path.join(root, 'events');
+    const executable = path.join(root, 'installed/Contents/MacOS/bridge');
+    const stamp = path.join(root, 'installed/Contents/Resources/source.sha256');
+    const bundled = path.join(root, `prebuilt/macos/${process.arch}/tangu-computer-use.app.zip`);
+    const output = path.join(root, 'tangu-plugins/computer-use/dist/probe.mjs');
+    for (const file of [executable, stamp, bundled, output, path.join(root, 'scripts/setup-helper.mjs')]) mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(path.join(root, 'manifest.json'), '{}');
+    writeFileSync(path.join(root, 'package.json'), JSON.stringify({ version: '0.5.3' }));
+    writeFileSync(bundled, 'new helper image');
+    if (scenario !== 'missing') writeFileSync(executable, 'locally signed image');
+    writeFileSync(stamp, scenario === 'current' ? createHash('sha256').update(readFileSync(bundled)).digest('hex') : 'old image');
+    const sealed = ['Contents/MacOS/bridge', 'Contents/Info.plist', 'Contents/_CodeSignature/CodeResources'];
+    const files = {};
+    for (const file of sealed) {
+      const target = path.join(root, 'installed', file);
+      mkdirSync(path.dirname(target), { recursive: true });
+      files[file] = createHash('sha256').update('new helper image').digest('hex');
+      if (scenario !== 'missing') writeFileSync(target, scenario === 'current' ? 'new helper image' : 'old helper image');
+    }
+    writeFileSync(bundled.replace(/\.zip$/, '.json'), JSON.stringify({ version: '0.5.3', bundleId: 'com.forsion.tangu-computer-use', archiveSha256: files[sealed[0]], files }));
+    writeFileSync(path.join(root, 'scripts/setup-helper.mjs'), `import {appendFileSync} from 'node:fs';
+      appendFileSync(${JSON.stringify(events)}, 'install\\n');
+      ${scenario === 'install-failure' ? "console.error('fixture install failure'); process.exitCode = 1;" : ''}`);
+    await build({ entryPoints: [path.resolve('src/onboarding.ts')], outfile: output, bundle: true, platform: 'node', format: 'esm',
+      define: { 'process.platform': '"darwin"' },
+      plugins: [{ name: 'isolated-helper', setup(b) {
+        b.onResolve({ filter: /^node:child_process$/ }, args => args.namespace !== 'process-fixture' ? { path: args.path, namespace: 'process-fixture' } : undefined);
+        b.onLoad({ filter: /.*/, namespace: 'process-fixture' }, () => ({ contents: `export {spawn} from 'node:child_process'; export const execFileSync = () => Buffer.alloc(0);` }));
+        b.onResolve({ filter: /\/helperState\.ts$|\/vendor\/platform\/macos\/helper\.ts$/ }, (args) => ({ path: args.path, namespace: 'fixture' }));
+        b.onLoad({ filter: /.*/, namespace: 'fixture' }, (args) => ({ contents: args.path.endsWith('helperState.ts')
+          ? `import {existsSync} from 'node:fs'; export const helperInstalled = () => existsSync(${JSON.stringify(executable)}); export const helperExecutablePath = () => ${JSON.stringify(executable)}; export const isSupportedPlatform = () => true;`
+          : `import {appendFileSync,readFileSync} from 'node:fs'; export const macosHelper = {restart: async () => {
+              if(readFileSync(${JSON.stringify(events)}, 'utf8') !== 'install\\n') throw Error('restarted before installer finished');
+              appendFileSync(${JSON.stringify(events)}, 'restart\\n');
+              ${scenario === 'restart-failure' ? "throw Error('fixture restart failure');" : ''}
+            }};` }));
+      } }], logLevel: 'silent' });
+    const mod = await import(pathToFileURL(output).href);
+    const [note, duplicate] = await Promise.all([mod.ensureHelperCurrent(), mod.ensureHelperCurrent()]);
+    const lines = existsSync(events) ? readFileSync(events, 'utf8').trim().split('\n') : [];
+    assert.deepEqual(lines, scenario === 'current' ? [] : ['install', ...(['stale', 'restart-failure'].includes(scenario) ? ['restart'] : [])], scenario);
+    assert.equal(duplicate, undefined, 'concurrent callers share one installation and one notification');
+    assert.equal(mod.autoInstallFailed(), scenario.endsWith('failure'));
+    if (scenario.endsWith('failure')) assert.match(note, /Could not install.*fixture (install|restart) failure/);
+    else if (scenario === 'stale') assert.match(note, /^Updated/);
+    else if (scenario === 'missing') assert.match(note, /^Installed/);
+    else assert.equal(note, undefined);
+    console.log(`PASS ${scenario}`);
+  }
+} finally { rmSync(temp, { recursive: true, force: true }); }