@forsion/tangu-computer-use 0.5.8

package/scripts/helper-signal.check.mjs

@@ -0,0 +1,59 @@
+// Probe actual packaged bits, not Swift source or an injected foreground.json.
+// Optional first argument checks a different installed/packaged executable.
+import assert from 'node:assert/strict';
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { appName, installMacosApp } from './macos-bundle.mjs';
+
+if (process.platform !== 'darwin') { console.log('SKIP macOS native helper'); process.exit(0); }
+const root = path.resolve(import.meta.dirname, '..');
+const temp = mkdtempSync(path.join(os.tmpdir(), 'cu-signal-')), socket = path.join(temp, 'bridge.sock');
+const app = process.argv[2] ? undefined : path.join(temp, appName);
+const executable = process.argv[2] || path.join(app, 'Contents/MacOS/bridge');
+const pause = ms => new Promise(r => setTimeout(r, ms));
+function request(cmd) {
+  return new Promise((resolve, reject) => {
+    const s = net.createConnection(socket); let data = '';
+    const finish = (error, result) => { clearTimeout(timer); s.destroy(); error ? reject(error) : resolve(result); };
+    const timer = setTimeout(() => finish(new Error('helper timeout')), 2000);
+    s.on('connect', () => s.write(JSON.stringify({ id: 'signal-probe', cmd }) + '\n'));
+    s.on('error', error => finish(error));
+    s.on('data', chunk => { data += chunk; if (data.includes('\n')) { try { finish(null, JSON.parse(data.split('\n')[0])); } catch(error) { finish(error); } } });
+  });
+}
+let child, spawnError;
+try {
+  if (app) await installMacosApp(root, app, { register: false });
+  assert.ok(existsSync(executable), 'bundle must ship a macOS helper');
+  child = app
+    ? spawn('/usr/bin/open', ['-n', '-g', app, '--args', 'serve', '--socket', socket], { stdio: 'ignore' })
+    : spawn(executable, ['serve', '--socket', socket], { stdio: 'ignore' });
+  child.on('error', error => { spawnError = error; });
+  let diagnostics;
+  for (let i = 0; i < 50; i++) {
+    if (spawnError) throw spawnError;
+    try { diagnostics = await request('diagnostics'); break; } catch { await pause(100); }
+  }
+  assert.equal(diagnostics?.ok, true, 'native helper must start');
+  const status = await request('permissionStatus');
+  assert.equal(status.ok, true);
+  if (app) {
+    assert.equal(status.result.source.attribution, 'helper-app', 'LaunchServices must attribute permissions to the installed helper app');
+    assert.equal(realpathSync(status.result.source.executablePath), realpathSync(executable));
+  }
+  const signal = JSON.parse(readFileSync(path.join(temp, 'foreground.json'), 'utf8'));
+  assert.equal(signal.v, 1); assert.equal(signal.active, false); assert.equal(signal.helperPid, status.result.source.pid);
+  assert.ok(Math.abs(Date.now() - signal.updatedAt) < 10000, 'signal belongs to this startup');
+  assert.ok(signal.expiresAt <= Date.now(), 'idle startup cannot open Mini');
+  console.log(`PASS native helper publishes an idle Mini signal (protocol ${diagnostics.result.protocolVersion})`);
+} finally {
+  await request('shutdown').catch(() => {}); await pause(300);
+  if (child && child.exitCode === null) child.kill('SIGTERM'); // Only our isolated probe/launcher, never a user daemon.
+  if (app) {
+    try { execFileSync('/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister', ['-u', app], { stdio: 'ignore' }); } catch {}
+  }
+  rmSync(temp, { recursive: true, force: true });
+}

package/scripts/highlight.check.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// 边缘光效的几何单测(照上游 INV-17 跑 agent_cursor_tests 的做法:临时编一个 @main 可执行文件跑一遍)。
+// 非 macOS 直接跳过 —— 光效本来就只有 mac 有。
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+if (process.platform !== 'darwin') {
+  console.log('highlight check skipped (not macOS)');
+  process.exit(0);
+}
+
+const triple = process.arch === 'x64' ? 'x86_64-apple-macosx14.0' : 'arm64-apple-macosx14.0';
+const binary = path.join(os.tmpdir(), `tangu-cu-highlight-tests-${process.pid}`);
+try {
+  execFileSync('xcrun', [
+    'swiftc', '-target', triple, '-parse-as-library',
+    '-module-cache-path', path.join(os.tmpdir(), `tangu-cu-highlight-test-cache-${process.arch}`),
+    '-framework', 'AppKit',
+    '-framework', 'SwiftUI',
+    'native/macos/agent_highlight.swift',
+    'native/macos/agent_highlight_tests.swift',
+    '-o', binary,
+  ], { cwd: root, stdio: 'inherit' });
+  execFileSync(binary, [], { cwd: root, stdio: 'inherit' });
+} finally {
+  fs.rmSync(binary, { force: true });
+}

package/scripts/keychain-free-install.check.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Real install/repair checks in disposable directories. A Node preload traps all
+// process launches, including absolute paths, before production modules load.
+// No keychain access, LS registration, system permission prompt or user app.
+import assert from 'node:assert/strict';
+import { spawnSync, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { bundledMacosApp, sha256, macosHelperIsCurrent, appName } from './macos-bundle.mjs';
+
+if (process.platform !== 'darwin') {
+  console.log('SKIP real macOS installer checks');
+  process.exit(0);
+}
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'cu-keychain-free-'));
+try {
+  const trace = path.join(temp, 'commands.jsonl'), guard = path.join(temp, 'guard.mjs');
+  await fs.writeFile(guard, `import cp from 'node:child_process';
+    import fs from 'node:fs/promises';
+    import {appendFileSync} from 'node:fs';
+    import {syncBuiltinESMExports} from 'node:module';
+    import path from 'node:path';
+    for (const method of ['spawn','spawnSync','exec','execSync','execFile','execFileSync']) {
+      const original = cp[method];
+      cp[method] = function(command, args, ...rest) {
+        const name = path.basename(command);
+        appendFileSync(process.env.CU_TEST_TRACE, JSON.stringify({method,command,args})+'\\n');
+        if (['security','openssl','xcrun'].includes(name) || method === 'exec' || method === 'execSync'
+          || (name === 'codesign' && (!Array.isArray(args) || args[0] !== '--verify'))) {
+          throw Error('Forbidden runtime signing/keychain command: '+command);
+        }
+        if (name === 'lsregister') return Buffer.alloc(0);
+        return original.call(this, command, args, ...rest);
+      };
+    }
+    syncBuiltinESMExports();
+    if (process.env.CU_TEST_RENAME_FAIL === '1') {
+      const rename = fs.rename;
+      fs.rename = async (from, to) => {
+        if (path.basename(from) === 'tangu-computer-use.app' && to === process.env.PI_COMPUTER_USE_HELPER_APP_PATH) {
+          throw Object.assign(Error('fixture replacement failure'), {code:'EACCES'});
+        }
+        return rename(from, to);
+      };
+    }
+  `);
+  const installed = path.join(temp, 'Applications', appName);
+  const env = { ...process.env, CU_TEST_TRACE: trace, PI_COMPUTER_USE_HELPER_APP_PATH: installed,
+    // These old knobs must not opt runtime back into signing or key discovery.
+    PI_COMPUTER_USE_CODESIGN_IDENTITY: 'must-never-use-user-key', PI_COMPUTER_USE_NO_SIGN: '0',
+    PI_COMPUTER_USE_ALLOW_BUILD: '1' };
+  function run(flags = [], source = root, extraEnv = {}) {
+    const result = spawnSync(process.execPath, ['--import', pathToFileURL(guard).href, path.join(source, 'scripts/setup-helper.mjs'), ...flags],
+      { env: { ...env, ...extraEnv }, encoding: 'utf8', timeout: 45_000 });
+    assert.ifError(result.error);
+    return result;
+  }
+  const install = () => { const result = run(['--runtime']); assert.equal(result.status, 0, result.stderr); };
+  const check = status => { const result = run(['--check']); assert.equal(result.status, status, result.stderr); };
+  const image = () => fs.readFile(path.join(installed, 'Contents/MacOS/bridge')).then(sha256);
+
+  for (const arch of ['arm64', 'x64']) {
+    const bundle = bundledMacosApp(root, arch);
+    assert.equal(sha256(await fs.readFile(bundle.archive)), bundle.metadata.archiveSha256);
+  }
+  check(10);
+  install();
+  check(0);
+  assert.ok(macosHelperIsCurrent(root, installed));
+  const inode = (await fs.stat(installed)).ino, expected = await image();
+  install();
+  assert.equal((await fs.stat(installed)).ino, inode, 'current app must not be replaced');
+  console.log('PASS first install / idempotent reinstall / current check');
+
+  await fs.rm(path.join(installed, 'Contents/_CodeSignature'), { recursive: true });
+  await fs.writeFile(path.join(installed, 'Contents/MacOS/bridge.cstemp'), 'interrupted old codesign');
+  check(10); install(); check(0);
+  assert.equal(await fs.access(path.join(installed, 'Contents/MacOS/bridge.cstemp')).then(() => true, () => false), false);
+  assert.equal(await image(), expected);
+  console.log('PASS rejected-keychain partial app repaired, including signature/temp residue');
+
+  const info = path.join(installed, 'Contents/Info.plist');
+  const packageVersion = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8')).version;
+  await fs.writeFile(info, (await fs.readFile(info, 'utf8')).replaceAll(packageVersion, '0.0.0'));
+  check(10); install(); check(0);
+  console.log('PASS same-protocol old app upgraded');
+
+  await fs.appendFile(info, '<!-- old installation -->');
+  const previousInfo = await fs.readFile(info, 'utf8');
+  const failedReplacement = run(['--runtime'], root, { CU_TEST_RENAME_FAIL: '1' });
+  assert.notEqual(failedReplacement.status, 0);
+  assert.match(failedReplacement.stderr, /fixture replacement failure/);
+  assert.equal(await fs.readFile(info, 'utf8'), previousInfo, 'replacement failure must restore previous app');
+  install(); check(0);
+  console.log('PASS atomic replacement rollback preserves previous app');
+
+  // Bad/missing bundled assets must fail without changing an existing app and
+  // without falling back to loose-binary signing, keychain discovery or downloads.
+  const bad = path.join(temp, 'bad-package');
+  await fs.mkdir(bad);
+  for (const rel of ['scripts', 'src/vendor/platform/macos', 'prebuilt/macos', 'package.json']) {
+    await fs.cp(path.join(root, rel), path.join(bad, rel), { recursive: true });
+  }
+  const badBundle = bundledMacosApp(bad);
+  await fs.appendFile(badBundle.archive, 'corruption');
+  const corrupted = run(['--runtime'], bad);
+  assert.notEqual(corrupted.status, 0); assert.match(corrupted.stderr, /archive is damaged/);
+  assert.equal(await image(), expected); check(0);
+  await fs.rm(path.join(bad, 'prebuilt/macos'), { recursive: true });
+  await fs.mkdir(path.join(bad, 'prebuilt/macos', process.arch), { recursive: true });
+  await fs.copyFile(path.join(root, 'prebuilt/macos', process.arch, 'bridge'), path.join(bad, 'prebuilt/macos', process.arch, 'bridge'));
+  const missing = run(['--runtime'], bad);
+  assert.notEqual(missing.status, 0); assert.match(missing.stderr, /pre-signed.*missing/);
+  assert.equal(await image(), expected); check(0);
+  console.log('PASS corrupt/missing archives fail closed and preserve existing app');
+
+  await fs.rm(path.join(installed, 'Contents/_CodeSignature'), { recursive: true });
+  const staleLock = `${installed}.install-lock`;
+  await fs.mkdir(staleLock);
+  await fs.writeFile(path.join(staleLock, 'pid'), '0');
+  await fs.utimes(staleLock, new Date(Date.now() - 60_000), new Date(Date.now() - 60_000));
+  const concurrent = () => new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['--import', pathToFileURL(guard).href, path.join(root, 'scripts/setup-helper.mjs'), '--runtime'], { env, stdio: ['ignore','pipe','pipe'] });
+    let stderr = ''; child.stderr.on('data', data => { stderr += data; });
+    child.on('error', reject); child.on('close', code => code === 0 ? resolve() : reject(new Error(stderr)));
+  });
+  await Promise.all([concurrent(), concurrent()]);
+  check(0);
+  assert.deepEqual(await fs.readdir(path.dirname(installed)), [appName], 'no staging or lock residue');
+  const commands = (await fs.readFile(trace, 'utf8')).trim().split('\n').map(line => JSON.parse(line));
+  assert.ok(commands.some(cmd => path.basename(cmd.command) === 'codesign'));
+  assert.ok(commands.every(cmd => !['security','openssl','xcrun'].includes(path.basename(cmd.command))
+    && (path.basename(cmd.command) !== 'codesign' || cmd.args[0] === '--verify')));
+  console.log('PASS concurrent repair / stale-lock recovery / no runtime signing or keychain commands');
+} finally {
+  await fs.rm(temp, { recursive: true, force: true });
+}

package/scripts/live-view.check.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * 「实时画面」的真机仪器 —— 证明 liveView 走的是**常驻取景流**而不是每帧现截,而且画面真的在动。
+ *
+ * 症状是"不是 share screen 的实时画面,是掉帧的"。掉帧有两种完全不同的成因,这个脚本分开钉:
+ *   ① **取一帧要多久**(source=snapshot 时每帧都要重新协商采集会话,几十到几百毫秒不等)
+ *   ② **帧到底新不新**(流没起来 / 只推 .idle 空帧的话,拿到的会是同一张,再快也是静止画)
+ * 所以既量延迟也量**相邻帧的字节差异** —— 只量其一都能被另一种失败蒙混过去。
+ *
+ * 跑法:node scripts/live-view.check.mjs
+ * 需要:macOS、helper 已装并授权(辅助功能 + 屏幕录制)。会短暂打开「计算器」,跑完关掉。
+ */
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { connect } from 'node:net'
+import { homedir } from 'node:os'
+import { ensureDaemon, freshCalculator, killCalculator } from './calc-fixture.mjs'
+
+const SOCK = `${homedir()}/Library/Caches/tangu-computer-use/bridge.sock`
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const FRAMES = 24
+const TICK_MS = 120 // 与 main.js 的轮询节奏一致
+
+let seq = 0
+function ask(payload) {
+  return new Promise((resolve, reject) => {
+    const sock = connect(SOCK)
+    let buf = ''
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error(`timeout: ${payload.cmd}`)) }, 20_000)
+    sock.on('error', (e) => { clearTimeout(timer); reject(e) })
+    sock.on('data', (d) => {
+      buf += d
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      clearTimeout(timer)
+      sock.end()
+      const msg = JSON.parse(buf.slice(0, nl))
+      if (!msg.ok) return reject(Object.assign(new Error(msg.error?.message || 'helper error'), { code: msg.error?.code }))
+      resolve(msg.result)
+    })
+    sock.write(`${JSON.stringify({ id: `lv_${++seq}`, ...payload })}\n`)
+  })
+}
+
+const findNode = (node, pred) => {
+  if (!node) return null
+  if (pred(node)) return node
+  for (const c of node.children || []) { const hit = findNode(c, pred); if (hit) return hit }
+  return null
+}
+const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)]
+
+const diag = await ensureDaemon(ask)
+assert.equal(diag.protocolVersion, 11, `helper 协议应为 11,实测 ${diag.protocolVersion}`)
+assert.ok(diag.screenRecording, '需要「屏幕录制」权限,否则拿不到任何画面')
+
+try {
+  const { calc, win } = await freshCalculator(ask)
+  const look = await ask({ cmd: 'look', pid: calc.pid, windowId: win.windowId, includeImage: true })
+  const keyOf = (d) => {
+    const n = findNode(look.outline, (x) => x.role === 'AXButton' && (x.description === d || x.title === d))
+    assert.ok(n, `没找到数字键 ${d}`)
+    return { x: n.rect.x + n.rect.w / 2, y: n.rect.y + n.rect.h / 2 }
+  }
+  // ⚠️policy 必须是 background:这里只是要把窗口内容点变以便验证帧在更新,
+  // 用 foreground/hid 的话仪器每跑一次就抢 12 次用户焦点、还把实物鼠标拽走 ——
+  // 测「不抢前台」的项目自己抢前台,荒唐。后台 AX 按压点得中数字键(check:blindclick 已证明)。
+  const click = (d) => ask({
+    cmd: 'act', lookId: look.lookId, pid: calc.pid, policy: 'background',
+    cursorOverlay: true, action: 'click', target: keyOf(d), params: { button: 'left', clickCount: 1 },
+  })
+
+  // liveView 只认"最近被操控过的窗口" —— 先动一下,它才有东西可播
+  await click('1')
+  await sleep(300)
+
+  const frames = []
+  for (let i = 0; i < FRAMES; i++) {
+    // 每帧之间改一下计算器的读数,窗口内容才会**真的**变 —— 否则静止窗口本来就该是同一张,
+    // "帧不变"证明不了流没工作。
+    if (i % 2 === 0) await click(String((i / 2) % 10))
+    const t0 = process.hrtime.bigint()
+    const f = await ask({ cmd: 'liveView', maxDimension: 800, quality: 0.55, activeWithinMs: 120_000 })
+    const ms = Number(process.hrtime.bigint() - t0) / 1e6
+    frames.push({
+      ms,
+      source: f.source,
+      active: f.active,
+      error: f.error,
+      hash: f.jpegBase64 ? createHash('sha1').update(f.jpegBase64).digest('hex').slice(0, 8) : null,
+      size: f.jpegBase64 ? f.jpegBase64.length : 0,
+      dims: f.width ? `${f.width}x${f.height}` : null,
+    })
+    await sleep(TICK_MS)
+  }
+
+  const withImage = frames.filter((f) => f.hash)
+  const streamed = frames.filter((f) => f.source === 'stream')
+  const distinct = new Set(withImage.map((f) => f.hash)).size
+  const lat = median(withImage.map((f) => f.ms))
+
+  console.log(`  取到画面 ${withImage.length}/${FRAMES} 帧 ｜ 走取景流 ${streamed.length} 帧 ｜ 不重复画面 ${distinct} 种`)
+  console.log(`  单帧耗时中位数 ${lat.toFixed(1)}ms ｜ 尺寸 ${withImage[0]?.dims} ｜ 约 ${(withImage[0]?.size / 1024).toFixed(0)}KB/帧`)
+  const mark = (f) => ({ stream: 'S', snapshot: 'n', legacy: 'L' }[f.source] || (f.error ? '!' : '·'))
+  console.log(`  source 序列: ${frames.map(mark).join('')}   (S=常驻流, n=单帧兜底, L=上游老路)`)
+
+  assert.ok(withImage.length >= FRAMES - 2, `应该几乎每次都拿到画面,实得 ${withImage.length}/${FRAMES}`)
+  assert.ok(streamed.length >= FRAMES - 3, `除头几帧外都应走常驻取景流,实得 ${streamed.length}/${FRAMES} —— 全是 snapshot 说明流没起来`)
+  // 命门:延迟低但画面永远是同一张 = 静止画,照样是用户说的"掉帧"
+  assert.ok(distinct >= FRAMES / 3, `画面必须真的在更新,${withImage.length} 帧里只有 ${distinct} 种`)
+  assert.ok(lat < 100, `单帧耗时中位数应远低于轮询间隔(${TICK_MS}ms),实测 ${lat.toFixed(1)}ms —— 追不上就是掉帧`)
+  // ⚠️"占不满有留白"的回归线:上游 captureWindow 不设宽高,ScreenCaptureKit 会按整块屏幕出图、
+  // 把窗口摆在左上角、其余留白 —— 留白是**烤进 JPEG** 的,CSS 那头救不回来。
+  // 所以每一帧的宽高比都必须等于窗口自己的宽高比。
+  const wantAr = win.framePoints.w / win.framePoints.h
+  for (const f of withImage) {
+    const [w, h] = f.dims.split('x').map(Number)
+    assert.ok(Math.abs(w / h - wantAr) < 0.02, `画面宽高比必须等于窗口(窗口 ${win.framePoints.w}x${win.framePoints.h} → ${wantAr.toFixed(3)}),实得 ${f.dims} → ${(w / h).toFixed(3)}(source=${f.source})`)
+  }
+  assert.ok(!frames.some((f) => f.source === 'legacy'), '不该退到上游那条会留白的老路')
+  console.log(`✅ 实时画面:走常驻取景流、单帧亚百毫秒、画面确实在动、且每帧都是窗口原比例(无留白)`)
+} finally {
+  await killCalculator(ask).catch(() => {})
+}

package/scripts/macos-bundle.d.mts

@@ -0,0 +1 @@
+export function macosHelperIsCurrent(root: string, app: string): boolean;

package/scripts/macos-bundle.mjs

@@ -0,0 +1,119 @@
+// A sealed helper travels as a ZIP: Electron's outer --deep signing must never
+// re-sign it. Runtime operations here only verify, copy and register the app.
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const appName = 'tangu-computer-use.app';
+export const bundleId = 'com.forsion.tangu-computer-use';
+// Release helpers are signed with one fixed self-signed certificate (SHA-1 below). macOS files the
+// Accessibility and Screen Recording grants under the designated requirement = bundle id + this
+// certificate's hash, so helper updates keep the grants for as long as neither changes. Never replace
+// the certificate or change the bundle id: every user would have to grant access again. The private key
+// lives only in the GitHub secrets CU_SIGNING_P12 / CU_SIGNING_P12_PASSWORD (backup kept by the owner);
+// the release workflow signs with it and scripts/verify-package.mjs refuses a helper signed by anything else.
+export const releaseCertSha1 = 'dab3a30e7568c7e2c021660b49398356a205a191';
+export const sealedFiles = ['Contents/MacOS/bridge', 'Contents/Info.plist', 'Contents/_CodeSignature/CodeResources'];
+export const sha256 = data => createHash('sha256').update(data).digest('hex');
+
+export function bundledMacosApp(root, arch = process.arch) {
+  for (const candidate of ['universal', arch]) {
+    const dir = path.join(root, 'prebuilt/macos', candidate);
+    const archive = path.join(dir, `${appName}.zip`);
+    if (!existsSync(archive)) continue;
+    const metadata = JSON.parse(readFileSync(path.join(dir, `${appName}.json`), 'utf8'));
+    const version = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+    if (metadata.bundleId !== bundleId || metadata.version !== version || !/^[a-f0-9]{64}$/.test(metadata.archiveSha256)
+      || sealedFiles.some(file => !/^[a-f0-9]{64}$/.test(metadata.files?.[file]))) {
+      throw new Error('The bundled Computer Use helper metadata is invalid. Reinstall or rebuild the plugin.');
+    }
+    return { archive, metadata };
+  }
+  throw new Error('The pre-signed Computer Use helper app is missing. Reinstall the plugin. For development, run npm run build:native on macOS.');
+}
+
+export function verifyMacosApp(app) {
+  // -R pins the helper identity; signature verification never needs a private key.
+  execFileSync('/usr/bin/codesign', ['--verify', '--strict', '-R', `=identifier "${bundleId}"`, app],
+    { stdio: 'pipe', timeout: 15_000 });
+}
+
+export function macosAppMatches(app, metadata) {
+  try {
+    if (sealedFiles.some(file => sha256(readFileSync(path.join(app, file))) !== metadata.files[file])) return false;
+    verifyMacosApp(app);
+    return true;
+  } catch { return false; }
+}
+
+export function macosHelperIsCurrent(root, app) {
+  return macosAppMatches(app, bundledMacosApp(root).metadata);
+}
+
+async function withInstallLock(app, work) {
+  const lock = `${app}.install-lock`;
+  async function abandoned() {
+    const owner = Number(await fs.readFile(path.join(lock, 'pid'), 'utf8').catch(() => ''));
+    const age = Date.now() - (await fs.stat(lock).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+    if (age <= 30_000) return false;
+    if (!owner) return true;
+    try { process.kill(owner, 0); return false; } catch (error) { return error.code === 'ESRCH'; }
+  }
+  const deadline = Date.now() + 30_000;
+  while (true) {
+    try { await fs.mkdir(lock); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      // A live owner, regardless of age, keeps its lock until replacement finishes.
+      if (await abandoned()) {
+        // Serialize stale-lock recovery and recheck inside it. Two recovering
+        // installers must not delete a lock that the first has just acquired.
+        const recovery = `${lock}.recovery`;
+        const ownsRecovery = await fs.mkdir(recovery).then(() => true, error => { if (error.code === 'EEXIST') return false; throw error; });
+        if (ownsRecovery) {
+          try { if (await abandoned()) await fs.rm(lock, { recursive: true, force: true }); }
+          finally { await fs.rm(recovery, { recursive: true, force: true }); }
+          continue;
+        }
+      }
+      if (Date.now() > deadline) throw new Error('Another Computer Use installation is still running. Retry when it finishes.');
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+  try { await fs.writeFile(path.join(lock, 'pid'), String(process.pid)); return await work(); }
+  finally { await fs.rm(lock, { recursive: true, force: true }); }
+}
+
+export async function installMacosApp(root, app, { register = true } = {}) {
+  if (!path.basename(app).endsWith('.app')) throw new Error('Helper destination must be an .app bundle.');
+  const parent = path.dirname(app);
+  await fs.mkdir(parent, { recursive: true });
+  return withInstallLock(app, async () => {
+    const { archive, metadata } = bundledMacosApp(root);
+    if (sha256(await fs.readFile(archive)) !== metadata.archiveSha256) throw new Error('The bundled Computer Use helper archive is damaged. Reinstall the plugin.');
+    let changed = false;
+    if (!macosAppMatches(app, metadata)) {
+      const staging = await fs.mkdtemp(path.join(parent, '.tangu-computer-use-install-'));
+      const next = path.join(staging, appName), old = path.join(staging, 'previous.app');
+      let movedOld = false;
+      try {
+        execFileSync('/usr/bin/ditto', ['-x', '-k', archive, staging], { stdio: 'pipe', timeout: 30_000 });
+        if (!macosAppMatches(next, metadata)) throw new Error('The bundled Computer Use helper signature or contents are invalid.');
+        if (existsSync(app)) { await fs.rename(app, old); movedOld = true; }
+        try { await fs.rename(next, app); }
+        catch (error) { if (movedOld) await fs.rename(old, app); throw error; }
+        changed = true;
+      } finally {
+        // If rollback itself failed, preserve the previous app for recovery.
+        if (!movedOld || existsSync(app)) await fs.rm(staging, { recursive: true, force: true });
+      }
+    }
+    if (register) {
+      const command = '/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister';
+      try { execFileSync(command, ['-f', app], { stdio: 'pipe', timeout: 10_000 }); } catch { /* open will register it as well */ }
+    }
+    return changed;
+  });
+}

package/scripts/make-signing-cert.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Create a stable self-signed code-signing certificate for release signing,
+# exported as a .p12 ready for the release workflow secrets.
+#
+# This certificate makes local signing repeatable, but macOS may still require
+# permission review after native code changes. Persistent update identity is a
+# property of Developer ID-signed release bundles, not a guarantee of this
+# self-signed development certificate.
+#
+# Keep the generated key.pem + cert.pem somewhere safe and permanent: losing
+# them means the next release signs under a new leaf and every user
+# re-grants once. If you later enroll in the Apple Developer Program, swap
+# the workflow secrets for a Developer ID cert (users re-grant that once).
+#
+# Usage: ./scripts/make-signing-cert.sh [output-dir]
+# Then, for the Release workflow:
+#   base64 -i <dir>/id.p12 | pbcopy      -> secret APPLICATION_CERT_BASE64
+#   secret CERT_PASSWORD  = the password you enter below
+#   secret SIGN_IDENTITY  = "tangu-computer-use Self Signed"
+set -euo pipefail
+
+OUT_DIR="${1:-./signing}"
+CN="tangu-computer-use Self Signed"
+mkdir -p "$OUT_DIR"
+cd "$OUT_DIR"
+
+read -r -s -p "Password for the exported .p12: " P12_PASS
+echo
+
+cat > cert.conf <<'EOF'
+[req]
+distinguished_name = dn
+x509_extensions = v3
+prompt = no
+[dn]
+CN = tangu-computer-use Self Signed
+[v3]
+keyUsage = critical, digitalSignature
+extendedKeyUsage = critical, codeSigning
+basicConstraints = critical, CA:false
+EOF
+
+# 10-year validity so the signing identity does not silently expire between
+# releases (an expired leaf would change grant behavior).
+openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
+  -days 3650 -nodes -config cert.conf
+
+# macOS `security`/Keychain cannot read OpenSSL 3's default PKCS12 MAC; the
+# legacy PBE + SHA1 MAC flags are required for `security import` to accept it.
+openssl pkcs12 -export -out id.p12 -inkey key.pem -in cert.pem \
+  -passout "pass:${P12_PASS}" -name "$CN" \
+  -legacy -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1
+
+rm -f cert.conf
+echo
+echo "Wrote $OUT_DIR/{key.pem,cert.pem,id.p12}. Back these up permanently."
+echo "SIGN_IDENTITY secret value: $CN"

package/scripts/mini-foreground.check.mjs

@@ -0,0 +1,11 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const root = path.resolve(import.meta.dirname, '..');
+const temp = mkdtempSync(path.join(os.tmpdir(), 'cu-mini-signal-'));
+try {
+  execFileSync('xcrun', ['swiftc', '-module-cache-path', path.join(temp, 'cache'), '-parse-as-library',
+    path.join(root, 'native/macos/foreground_activity.swift'), path.join(root, 'native/macos/foreground_activity_tests.swift'), '-o', path.join(temp, 'test')], { stdio: 'inherit' });
+  execFileSync(path.join(temp, 'test'), [], { stdio: 'inherit' });
+} finally { rmSync(temp, { recursive: true, force: true }); }

package/scripts/no-foreground.check.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * 前台行为的回归仪器。两部分:
+ *   1) 默认:foregroundNote 判据的纯单测(免 TCC/免真机,CI 可跑)。钉住「什么算夺取前台」的定义,
+ *      防上游同步或重构悄悄让透明化提示失效。需先 `npm run build`(读 dist/foregroundNote.js)。
+ *   2) --live:ensure_app 的「后台启动不抢前台」不变量——open -g 一个临时文件到 TextEdit,断言终端仍是
+ *      前台(TextEdit 没跳到前台)。需 macOS。这是我新增行为(ensure_app/透明化)的真机绿灯,不重复测 vendor。
+ *
+ * 用法: node scripts/no-foreground.check.mjs [--live]
+ */
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const execFileP = promisify(execFile);
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+async function unitTests() {
+  const { foregroundNote } = await import(path.join(here, '..', 'tangu-plugins', 'computer-use', 'dist', 'foregroundNote.js'));
+  const has = (s) => s.includes('[foreground]');
+
+  // 无信号 → 空串
+  assert.equal(foregroundNote(undefined), '', 'undefined → empty');
+  assert.equal(foregroundNote(null), '', 'null → empty');
+  assert.equal(foregroundNote({}), '', 'no signals → empty');
+  assert.equal(foregroundNote({ delivery: 'ax', deliveryPolicy: 'background' }), '', 'pure background → empty');
+  assert.equal(foregroundNote({ steps: [{ delivery: 'ax' }, { delivery: 'pid', deliveryPolicy: 'background' }] }), '', 'all-background steps → empty');
+
+  // 各前台信号 → 提示
+  assert.ok(has(foregroundNote({ escalatedToForeground: true })), 'escalated → note');
+  assert.ok(has(foregroundNote({ delivery: 'hid' })), 'hid delivery → note');
+  assert.ok(has(foregroundNote({ deliveryPolicy: 'foreground' })), 'foreground policy → note');
+
+  // ⚠️坐标点击在 TS 层恒被判 needsForeground → policy 恒为 foreground;helper 却可能用 AX 命中测试
+  // 在后台完成它。这时报「抢了前台」是**反的**,比不报更坏。
+  assert.equal(foregroundNote({ delivery: 'ax', deliveryPolicy: 'foreground' }), '', 'ax delivery under a foreground policy → no note');
+  assert.ok(has(foregroundNote({ delivery: 'ax', deliveryPolicy: 'foreground', escalatedToForeground: true })), 'ax + escalated → still a note');
+  assert.ok(has(foregroundNote({ steps: [{ delivery: 'ax', deliveryPolicy: 'foreground' }, { delivery: 'hid' }] })), 'any hid step → note');
+  assert.ok(has(foregroundNote({ steps: [{ delivery: 'ax' }, { escalatedToForeground: true }] })), 'any escalated step → note');
+
+  // 升级原因透传
+  const withReason = foregroundNote({ escalatedToForeground: true, escalationReason: 'foreground_required' });
+  assert.ok(withReason.includes('foreground_required'), 'reason surfaced');
+
+  console.log('✓ unit: foregroundNote 判据 9 项全过');
+}
+
+async function frontmostBundleId() {
+  const { stdout } = await execFileP('osascript', ['-e',
+    'tell application "System Events" to get bundle identifier of first application process whose frontmost is true']);
+  return stdout.trim();
+}
+
+async function liveTest() {
+  if (process.platform !== 'darwin') { console.log('· live: 跳过(非 macOS)'); return; }
+  const before = await frontmostBundleId();
+  const dir = mkdtempSync(path.join(tmpdir(), 'cu-nofg-'));
+  const file = path.join(dir, 'cu-no-foreground-probe.txt');
+  writeFileSync(file, 'probe\n');
+  try {
+    // -g:后台打开(TextEdit 承接 .txt),不应置前台。
+    await execFileP('open', ['-g', '-e', file], { timeout: 8_000 });
+    await new Promise((r) => setTimeout(r, 1500));
+    const after = await frontmostBundleId();
+    assert.equal(after, before, `frontmost changed: ${before} → ${after}(后台启动却抢了前台)`);
+    assert.notEqual(after, 'com.apple.TextEdit', 'TextEdit 跳到了前台');
+    console.log(`✓ live: 后台启动 TextEdit,前台仍是 ${after}(未被抢)`);
+  } finally {
+    await execFileP('osascript', ['-e', 'tell application "TextEdit" to close (every document whose path is "' + file + '")']).catch(() => {});
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const live = process.argv.includes('--live');
+await unitTests();
+if (live) await liveTest();
+console.log(`\n✅ no-foreground check 通过${live ? '(含 --live)' : ''}`);