From 773134d0dd303a1d568a6b997c485331763a40e6 Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 11:45:54 +0800
Subject: [PATCH 1/6] =?UTF-8?q?fix(launchd):=20=E6=B2=99=E7=AE=B1=20uninst?=
 =?UTF-8?q?all/status=20=E4=B8=8D=E5=86=8D=E6=93=8D=E4=BD=9C=E7=9C=9F?=
 =?UTF-8?q?=E5=AE=9E=E8=87=AA=E5=90=AF=E4=BD=9C=E4=B8=9A=EF=BC=88=E6=9C=AC?=
 =?UTF-8?q?=E6=9C=BA=20npm=20test=20=E4=BC=9A=E6=89=93=E6=AD=BB=E5=A4=96?=
 =?UTF-8?q?=E6=8C=82=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

真机故障：动不动就「无法连接本机 controller（外挂未运行？）：Failed to fetch」。

根因是 launchd.cjs 的 uninstall()：LABEL 是模块常量，plistPath(o.dir) 尊重 dir 覆盖，
但 bootout 硬编码 `gui/<uid>/local.zcode.advisor`，完全忽略 dir。于是
test/launchd.test.js:180/186 传沙箱 dir 调用 uninstall 时，bootout 打的是用户**真实**
的自启作业。launchctl bootout 会终止该作业的进程并把它从 launchd 卸载，KeepAlive
监督随作业一起消失 —— 进程被杀且**永远不会自动重启**，直到用户重开一次 App。

所以本机每跑一次 `npm test`，外挂就被确定性打死一次（不是「动不动」，是必死）；
用户重开 App 后又能用，下次测试再打死，表现为间歇性。CI 结构性看不见：
test job 跑在 ubuntu-latest，/bin/launchctl 不存在 → ENOENT 被 `catch (_)` 吞掉。

修复：
- 新增 realPlistPath()/managesRealAgent(p)：以**路径**判定目标是否为用户真实那份
  （而非「有没有传 dir」，这样显式指向真实目录或经 ZCODE_ADVISOR_LAUNCHD_DIR
  重定向都能正确识别）。
- 新增 canTouchLaunchd(p)：仅 darwin + 有 uid + 目标为真实 plist 时才碰 launchd 域。
  显式判断取代「抛 ENOENT 再静默吞掉」——后者正是本 bug 在 CI 无法暴露的原因。
- uninstall()/status()/ensureLoaded() 三处同类缺陷一并收口；status() 增加 queried
  字段，区分「没查过」与「查过、没加载」，不再把真实作业的态冒充沙箱 plist 的态
  （装了 agent 的开发机上「已写入但未加载」断言必红）。

顺带修复生产日志污染：controller.cjs:135 在 require 期固化 LOG_FILE，6 个测试
require controller 却未隔离该 env，导致测试噪音（startApi 的「本机 API 就绪」、
saveUserConfig 的 0.2.17 迁移行）写进用户真实日志，把真实故障淹没、并让「外挂从未
启动」被误读成「外挂反复启动」。

回归防线：
- test/launchd.test.js 用子进程打桩 launchctl，断言沙箱 uninstall 调用**零次**
  launchctl（已实测：对修复前代码该用例失败，对修复后通过）。
- 反向断言真实路径仍会 bootout（防止把卸载功能修坏）。
- test/static-guards.test.js 新增守卫：require controller 的测试必须隔离
  ZCODE_ADVISOR_COMPANION_LOG。

验证：npm test 531 项全绿（530 pass / 1 既有 macOS-only skip）；在真实 agent
运行时跑完整套件，进程 pid 前后不变；生产日志增量为 0。
---
 .../zcode-advisor/tools/companion/launchd.cjs | 55 +++++++++++++-
 test/companion-lock.test.js                   |  6 ++
 test/companion-zcode.test.js                  |  4 +
 test/health.test.js                           |  9 +++
 test/inject.test.js                           |  3 +
 test/launchd.test.js                          | 73 +++++++++++++++++++
 test/session-toggle.test.js                   |  4 +
 test/static-guards.test.js                    | 21 ++++++
 tools/companion/launchd.cjs                   | 55 +++++++++++++-
 9 files changed, 224 insertions(+), 6 deletions(-)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index e832741..ab18047 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -115,6 +115,40 @@ function launchctl(args) {
   return execFileSync('/bin/launchctl', args, { stdio: 'pipe', timeout: 20000, encoding: 'utf8' });
 }
 
+// 用户真实自启作业的 plist 路径——**绕过一切覆盖**（dir 参数 / ZCODE_ADVISOR_LAUNCHD_DIR）。
+//
+// 关键不变量：LABEL 是固定常量，重定向只能改 plist 的**路径**，改不掉 launchd
+// 域里的作业名。所以一旦目标 plist 不是这一份，任何
+// `launchctl print/bootout gui/<uid>/<LABEL>` 都打在用户**真实**的自启作业上：
+//   - bootout 会终止真实作业的进程并把它从 launchd 卸载。KeepAlive 监督随作业
+//     一起消失 → 进程被杀且**永远不会自动重启**，直到用户重开一次 App
+//     （真机故障：在本机跑一次 `npm test`，外挂就被打死，表现为「动不动就连不上
+//     controller」，而 CI 跑在 Linux 上、launchctl 不存在，ENOENT 被 catch 吞掉，
+//     所以结构性看不见）。
+//   - print 会把真实作业的运行态误报成沙箱的态（装了 agent 的开发机上，
+//     「已写入但未加载」这条断言必然变红）。
+// 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
+// 重定向的情形都能被正确识别。
+function realPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
+function managesRealAgent(p) {
+  try {
+    return path.resolve(p) === path.resolve(realPlistPath());
+  } catch (_) {
+    return false;
+  }
+}
+
+// launchd 域操作仅在 macOS 且拿得到 uid 时才有意义。
+// 显式判断而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」正是本 bug
+// 在 CI 上无法暴露的原因。
+function canTouchLaunchd(p) {
+  return process.platform === 'darwin' && uid() !== null && managesRealAgent(p);
+}
+
 // 写 plist（幂等：内容相同则不重写，保持 mtime 稳定，避免触发无谓的重载）。
 function writePlist(content, dir) {
   const p = plistPath(dir);
@@ -141,9 +175,16 @@ function isLoaded(label) {
 // 幂等加载：已加载且 plist 未变 → 什么都不做（**不能无条件 bootout+bootstrap**，
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
+//
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 managesRealAgent）：
+// 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
+  if (!canTouchLaunchd(plistFile)) {
+    // 只落盘，由调用方决定是否需要别的加载方式；不谎报「已加载」。
+    return { loaded: false, skipped: true, warn: '目标不是用户真实 LaunchAgent，跳过 launchd 加载（避免影响真实自启作业）' };
+  }
   const loaded = isLoaded(l);
   if (loaded && !changed) return { loaded: true, reloaded: false };
   try {
@@ -196,8 +237,10 @@ function install(opts) {
 function uninstall(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
+  // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
+  // （见 managesRealAgent）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
   let bootedOut = false;
-  if (uid() !== null) {
+  if (canTouchLaunchd(p)) {
     try { launchctl(['bootout', `gui/${uid()}/${LABEL}`]); bootedOut = true; } catch (_) { /* 未加载：忽略 */ }
   }
   let removed = false;
@@ -209,16 +252,22 @@ function status(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
   const exists = fs.existsSync(p);
+  // 目标不是真实那份时不去查 launchd 域：作业名仍是真实 LABEL，查出来的是用户真实
+  // agent 的态，当成沙箱 plist 的态返回会让调用方拿到自相矛盾的结果（沙箱里文件不存在，
+  // 却报 loaded=true）——装了 agent 的开发机上这条断言必红。
+  // 返回 loaded=false + queried=false，让「没查过」与「查过、没加载」可区分。
   let loaded = false;
+  let queried = false;
   let detail = '';
-  if (uid() !== null) {
+  if (canTouchLaunchd(p)) {
+    queried = true;
     try {
       detail = launchctl(['print', `gui/${uid()}/${LABEL}`]);
       loaded = true;
     } catch (_) { /* 未加载 */ }
   }
   const state = /state = (\w+)/.exec(detail);
-  return { path: p, exists, loaded, state: state ? state[1] : '' };
+  return { path: p, exists, loaded, queried, state: state ? state[1] : '' };
 }
 
 function main(argv) {
diff --git a/test/companion-lock.test.js b/test/companion-lock.test.js
index f35e974..aeacb82 100644
--- a/test/companion-lock.test.js
+++ b/test/companion-lock.test.js
@@ -19,6 +19,12 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// 隔离生产日志：controller.cjs:135 在 require 期固化 LOG_FILE。本文件目前不写日志，
+// 但「require controller 就必须隔离日志路径」是这里的统一约束——否则将来新增用例
+// 一旦走到 startApi/saveUserConfig，噪音会直接落进用户真实日志。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'zca-lock-log-')), 'companion.log');
+
 const { _internal: I } = require('../tools/companion/controller.cjs');
 const LOCK = I.LOCK_FILE;
 
diff --git a/test/companion-zcode.test.js b/test/companion-zcode.test.js
index 6d14bd3..4195cc7 100644
--- a/test/companion-zcode.test.js
+++ b/test/companion-zcode.test.js
@@ -17,6 +17,10 @@ process.env.ZCODE_ADVISOR_USER_CONFIG = USER_CFG;
 process.env.ZCODE_ADVISOR_ZCODE_CONFIG = V2_CFG;
 // 隔离第二个数据源（provider_config.json）：否则会读到开发机真实配置，断言随环境漂移。
 process.env.ZCODE_ADVISOR_ZCODE_PROVIDER_CONFIG = path.join(dir, 'no-such-provider-config.json');
+// 隔离生产日志：controller.cjs:135 在 require 期固化 LOG_FILE。本文件的 saveUserConfig
+// 用例会触发 0.2.17 迁移日志（controller.cjs:733），不隔离就会写进用户真实日志
+// （配置隔离与日志隔离是两条独立的轴）。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(dir, 'companion.log');
 fs.writeFileSync(V2_CFG, JSON.stringify({
   provider: {
     p1: {
diff --git a/test/health.test.js b/test/health.test.js
index ef66d12..fe73074 100644
--- a/test/health.test.js
+++ b/test/health.test.js
@@ -14,6 +14,15 @@ const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
+// 隔离生产日志：controller.cjs:135 在模块加载期解析
+// LOG_FILE = process.env.ZCODE_ADVISOR_COMPANION_LOG || ~/.zcode/advisor-companion.log，
+// 而 startApi() 在 listen 时写「本机 API 就绪」（controller.cjs:1391）。
+// 下面两个用例会起真实 HTTP server（C.startApi(1, 0, tok)），不隔离就会把测试噪音
+// 写进用户真实日志，把真实故障淹没掉。runInChild 不传 env，子进程继承本进程 env，
+// 所以这里设一次即可覆盖全部子进程。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'zca-health-log-')), 'companion.log');
+
 const HEALTH = require('../hooks/lib/health');
 
 function tmpDir(prefix) {
diff --git a/test/inject.test.js b/test/inject.test.js
index 903f02b..4995757 100644
--- a/test/inject.test.js
+++ b/test/inject.test.js
@@ -20,6 +20,9 @@ const path = require('path');
 // 读到开发者本机真实的 ~/.zcode/v2/config.json（断言漂移 + 明文 key 进测试输出）。
 process.env.ZCODE_ADVISOR_ZCODE_CONFIG = path.join(os.tmpdir(), `zcadv-inject-no-zcode-${Date.now()}.json`);
 process.env.ZCODE_ADVISOR_USER_CONFIG = path.join(os.tmpdir(), `zcadv-inject-no-user-${Date.now()}.json`);
+// 本文件在端点归一化用例里 require controller.cjs，而 controller.cjs:135 在 require 期
+// 固化 LOG_FILE → 一并隔离，避免任何写日志路径落到用户真实的 advisor-companion.log。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(os.tmpdir(), `zcadv-inject-log-${Date.now()}.log`);
 
 const INJECT_SRC = fs.readFileSync(
   path.join(__dirname, '..', 'tools', 'companion', 'inject.js'),
diff --git a/test/launchd.test.js b/test/launchd.test.js
index 5a135bf..80f657f 100644
--- a/test/launchd.test.js
+++ b/test/launchd.test.js
@@ -21,6 +21,11 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// 先隔离所有「用户真实路径」再 require controller：controller 在模块加载期就解析
+// LOG_FILE（controller.cjs:135 `process.env.ZCODE_ADVISOR_COMPANION_LOG || ~/.zcode/...`），
+// 不设就会把测试日志写进用户真实的生产日志，把真实故障淹没在噪音里。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'zca-log-')), 'companion.log');
+
 const L = require('../tools/companion/launchd.cjs');
 const { _internal: I } = require('../tools/companion/controller.cjs');
 
@@ -173,6 +178,33 @@ test('install：默认不加载（避免已有实例在跑时制造反复重启
   assert.strictEqual(r.loaded, false, '不带 --now 时只落盘，由下次登录加载');
 });
 
+// 在子进程里跑 launchd 的域操作，并把 launchctl / fs.unlinkSync 打桩。
+//
+// 必须在 require(launchd.cjs) **之前**打桩：launchd.cjs:26 用的是
+// `const { execFileSync } = require('child_process')`，解构在 require 期取值，
+// 之后补丁无效。子进程隔离还能避免污染本进程的 require 缓存。
+// 真机故障回归防线：沙箱 dir 绝不能触发 `bootout gui/<uid>/local.zcode.advisor`。
+function probeUninstall(opts, extraEnv) {
+  const runner = `
+    const cp = require('child_process');
+    const calls = [];
+    // execFileSync 必须在 require 前打桩：launchd.cjs:26 解构取值，之后再补丁无效。
+    cp.execFileSync = (f, a) => { calls.push([f, a]); return ''; };
+    const L = require(${JSON.stringify(path.join(__dirname, '../tools/companion/launchd.cjs'))});
+    // unlinkSync 是在调用期通过 fs 模块对象取的，require 之后再打桩即可。
+    const fs = require('fs');
+    const unlinked = [];
+    fs.unlinkSync = (p) => { unlinked.push(p); return undefined; };
+    const r = L.uninstall(${JSON.stringify(opts)});
+    process.stdout.write(JSON.stringify({ r, calls, unlinked }));
+  `;
+  const out = require('child_process').execFileSync(process.execPath, ['-e', runner], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, extraEnv || {})
+  });
+  return JSON.parse(out.trim());
+}
+
 test('uninstall：移除 plist 文件（可逆）', () => {
   const dir = tmpDir();
   L.install({ dir, nodeBin: '/x/node', controllerPath: '/x/controller.cjs' });
@@ -188,6 +220,38 @@ test('uninstall：plist 不存在时不报错（幂等）', () => {
   assert.strictEqual(r.removed, false);
 });
 
+// 真机故障回归（本 bug 的原始形态）：npm test → test/launchd.test.js → uninstall({dir})
+// → 旧实现无条件 `launchctl bootout gui/<uid>/local.zcode.advisor`。LABEL 是常量，
+// bootout 打的是用户**真实**的自启作业：进程被杀 + 作业被卸载 + KeepAlive 监督消失
+// → 外挂永远不再自启，表现为「动不动就连不上本机 controller（外挂未运行？）：Failed to fetch」。
+// 沙箱 dir 的 uninstall 必须完全不碰 launchd 域。
+test('uninstall：dir 覆盖时绝不 bootout 真实 LABEL（本机 npm test 会打死外挂的回归）', () => {
+  const dir = tmpDir();
+  const probe = probeUninstall({ dir });
+  assert.deepStrictEqual(probe.calls, [],
+    '沙箱 uninstall 不得调用任何 launchctl（bootout 会终止并卸载用户真实自启作业）');
+  assert.strictEqual(probe.r.bootedOut, false);
+  assert.deepStrictEqual(probe.unlinked, [L.plistPath(dir)],
+    '只应删除沙箱自己的 plist');
+});
+
+test('uninstall：ZCODE_ADVISOR_LAUNCHD_DIR 重定向时同样不碰真实 LABEL', () => {
+  const dir = tmpDir();
+  const probe = probeUninstall({}, { ZCODE_ADVISOR_LAUNCHD_DIR: dir });
+  assert.deepStrictEqual(probe.calls, [], '经环境变量重定向也必须与真实作业隔离');
+  assert.strictEqual(probe.r.bootedOut, false);
+  assert.strictEqual(probe.r.path, path.join(dir, 'local.zcode.advisor.plist'));
+});
+
+// 反向防线：真实路径**必须**继续 bootout，否则「卸载」这个功能本身就废了。
+// 打桩后真实 plist 不会被删、launchd 也不会被动到。
+// 仅在 macOS 有意义：非 darwin 上 canTouchLaunchd 恒为 false（本就不该有 launchctl）。
+test('uninstall：无 dir 时仍 bootout 真实 LABEL（卸载功能未被修坏）', { skip: process.platform !== 'darwin' && '仅在 macOS 有 launchd 域' }, () => {
+  const probe = probeUninstall({});
+  assert.deepStrictEqual(probe.calls, [['/bin/launchctl', ['bootout', `gui/${process.getuid()}/local.zcode.advisor`]]]);
+  assert.strictEqual(probe.r.bootedOut, true);
+});
+
 test('status：未安装时 exists=false（启动器据此走回退路径）', () => {
   const s = L.status({ dir: tmpDir() });
   assert.strictEqual(s.exists, false);
@@ -201,6 +265,15 @@ test('status：已写入但未加载时 exists=true、loaded=false', () => {
   assert.strictEqual(s.loaded, false, '仅落盘不算加载（启动器据此决定是否自行拉起）');
 });
 
+// status 与 uninstall 同类缺陷：旧实现用 `launchctl print gui/<uid>/LABEL` 查真实作业，
+// 却把结果当成沙箱 plist 的态。装了 agent 的开发机上沙箱里明明没有 plist，
+// 也会报 loaded=true（这条断言在真机上必红）。
+test('status：dir 覆盖时不去查询真实作业，queried=false（不得把真实态冒充沙箱态）', () => {
+  const s = L.status({ dir: tmpDir() });
+  assert.strictEqual(s.queried, false, '重定向时不应查询 launchd 域');
+  assert.strictEqual(s.loaded, false);
+});
+
 test('LABEL：使用反向域名的固定标识（升级/卸载要能定位同一 agent）', () => {
   assert.strictEqual(L.LABEL, 'local.zcode.advisor');
 });
diff --git a/test/session-toggle.test.js b/test/session-toggle.test.js
index 07ad164..2452893 100644
--- a/test/session-toggle.test.js
+++ b/test/session-toggle.test.js
@@ -13,6 +13,10 @@ const path = require('path');
 const healthDir = fs.mkdtempSync(path.join(os.tmpdir(), 'zcadv-health-'));
 const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'zcadv-state-'));
 process.env.ZCODE_ADVISOR_HEALTH_DIR = healthDir;
+// 同理隔离生产日志（controller.cjs:135 在 require 期固化 LOG_FILE）：
+// 本文件目前不写日志，但 require controller 就一并隔离，避免后续新增用例污染用户真实日志。
+process.env.ZCODE_ADVISOR_COMPANION_LOG = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'zca-sess-log-')), 'companion.log');
 const controller = require('../tools/companion/controller.cjs');
 
 const SESSION_ID = 'sess_test0001';
diff --git a/test/static-guards.test.js b/test/static-guards.test.js
index a88a06d..c812f13 100644
--- a/test/static-guards.test.js
+++ b/test/static-guards.test.js
@@ -242,3 +242,24 @@ test('测试文件：无遗留的调试输出', () => {
     assert.ok(!/\[dbg\]/.test(src), `test/${f} 残留调试输出`);
   }
 });
+
+// 生产日志隔离守卫。
+//
+// 真机故障：controller.cjs:135 在模块加载期固化
+//   LOG_FILE = process.env.ZCODE_ADVISOR_COMPANION_LOG || ~/.zcode/advisor-companion.log
+// 只要测试 require 了 controller 却忘了设该 env，测试产生的日志（startApi 的
+// 「本机 API 就绪」、saveUserConfig 的 0.2.17 迁移行）就会写进用户**真实**日志，
+// 把真实故障淹没在测试噪音里，且「外挂从未启动」会被误读成「外挂反复启动」。
+// 这条守卫让「新增一个 require controller 的测试却忘记隔离」在 npm test 阶段就暴露。
+test('测试文件：require controller.cjs 必须同时隔离 ZCODE_ADVISOR_COMPANION_LOG', () => {
+  const offenders = [];
+  for (const f of fs.readdirSync(path.join(ROOT, 'test'))) {
+    if (!/\.test\.(js|cjs)$/.test(f)) continue;
+    const src = read(path.join('test', f));
+    // 只看真正 require() 控制器模块的文件；纯读文本的静态断言不算。
+    if (!/require\(['"][^'"]*companion\/controller/.test(src)) continue;
+    if (!/ZCODE_ADVISOR_COMPANION_LOG/.test(src)) offenders.push(`test/${f}`);
+  }
+  assert.deepStrictEqual(offenders, [],
+    `以下测试 require 了 controller.cjs 但未隔离 ZCODE_ADVISOR_COMPANION_LOG，会污染用户真实日志：${offenders.join(', ')}`);
+});
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index e832741..ab18047 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -115,6 +115,40 @@ function launchctl(args) {
   return execFileSync('/bin/launchctl', args, { stdio: 'pipe', timeout: 20000, encoding: 'utf8' });
 }
 
+// 用户真实自启作业的 plist 路径——**绕过一切覆盖**（dir 参数 / ZCODE_ADVISOR_LAUNCHD_DIR）。
+//
+// 关键不变量：LABEL 是固定常量，重定向只能改 plist 的**路径**，改不掉 launchd
+// 域里的作业名。所以一旦目标 plist 不是这一份，任何
+// `launchctl print/bootout gui/<uid>/<LABEL>` 都打在用户**真实**的自启作业上：
+//   - bootout 会终止真实作业的进程并把它从 launchd 卸载。KeepAlive 监督随作业
+//     一起消失 → 进程被杀且**永远不会自动重启**，直到用户重开一次 App
+//     （真机故障：在本机跑一次 `npm test`，外挂就被打死，表现为「动不动就连不上
+//     controller」，而 CI 跑在 Linux 上、launchctl 不存在，ENOENT 被 catch 吞掉，
+//     所以结构性看不见）。
+//   - print 会把真实作业的运行态误报成沙箱的态（装了 agent 的开发机上，
+//     「已写入但未加载」这条断言必然变红）。
+// 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
+// 重定向的情形都能被正确识别。
+function realPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
+function managesRealAgent(p) {
+  try {
+    return path.resolve(p) === path.resolve(realPlistPath());
+  } catch (_) {
+    return false;
+  }
+}
+
+// launchd 域操作仅在 macOS 且拿得到 uid 时才有意义。
+// 显式判断而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」正是本 bug
+// 在 CI 上无法暴露的原因。
+function canTouchLaunchd(p) {
+  return process.platform === 'darwin' && uid() !== null && managesRealAgent(p);
+}
+
 // 写 plist（幂等：内容相同则不重写，保持 mtime 稳定，避免触发无谓的重载）。
 function writePlist(content, dir) {
   const p = plistPath(dir);
@@ -141,9 +175,16 @@ function isLoaded(label) {
 // 幂等加载：已加载且 plist 未变 → 什么都不做（**不能无条件 bootout+bootstrap**，
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
+//
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 managesRealAgent）：
+// 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
+  if (!canTouchLaunchd(plistFile)) {
+    // 只落盘，由调用方决定是否需要别的加载方式；不谎报「已加载」。
+    return { loaded: false, skipped: true, warn: '目标不是用户真实 LaunchAgent，跳过 launchd 加载（避免影响真实自启作业）' };
+  }
   const loaded = isLoaded(l);
   if (loaded && !changed) return { loaded: true, reloaded: false };
   try {
@@ -196,8 +237,10 @@ function install(opts) {
 function uninstall(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
+  // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
+  // （见 managesRealAgent）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
   let bootedOut = false;
-  if (uid() !== null) {
+  if (canTouchLaunchd(p)) {
     try { launchctl(['bootout', `gui/${uid()}/${LABEL}`]); bootedOut = true; } catch (_) { /* 未加载：忽略 */ }
   }
   let removed = false;
@@ -209,16 +252,22 @@ function status(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
   const exists = fs.existsSync(p);
+  // 目标不是真实那份时不去查 launchd 域：作业名仍是真实 LABEL，查出来的是用户真实
+  // agent 的态，当成沙箱 plist 的态返回会让调用方拿到自相矛盾的结果（沙箱里文件不存在，
+  // 却报 loaded=true）——装了 agent 的开发机上这条断言必红。
+  // 返回 loaded=false + queried=false，让「没查过」与「查过、没加载」可区分。
   let loaded = false;
+  let queried = false;
   let detail = '';
-  if (uid() !== null) {
+  if (canTouchLaunchd(p)) {
+    queried = true;
     try {
       detail = launchctl(['print', `gui/${uid()}/${LABEL}`]);
       loaded = true;
     } catch (_) { /* 未加载 */ }
   }
   const state = /state = (\w+)/.exec(detail);
-  return { path: p, exists, loaded, state: state ? state[1] : '' };
+  return { path: p, exists, loaded, queried, state: state ? state[1] : '' };
 }
 
 function main(argv) {

From 6dc5268943ad9366164e8ffcc9d65ecf86ce25ec Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 12:18:35 +0800
Subject: [PATCH 2/6] =?UTF-8?q?fix(launchd):=20=E8=B7=AF=E5=BE=84=E5=88=A4?=
 =?UTF-8?q?=E5=AE=9A=E6=94=B9=E7=94=A8=20realpath=EF=BC=8C=E9=81=BF?=
 =?UTF-8?q?=E5=85=8D=E7=AC=A6=E5=8F=B7=E9=93=BE=E6=8E=A5=E4=B8=8B=E9=9D=99?=
 =?UTF-8?q?=E9=BB=98=E8=B7=B3=E8=BF=87=E7=9C=9F=E5=AE=9E=E4=BD=9C=E4=B8=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ocr 复审意见的修复（上一提交 773134d 的后续）：

1. [high/bug] managesRealAgent 只做 path.resolve，不解析符号链接。
   macOS 上 /var → /private/var、/tmp → /private/tmp 都是链接：经这些路径
   传进来的「真实 plist」会被判成沙箱，于是 install/uninstall/status 静默
   跳过 launchd 域操作——卸载与自启安装这两个功能本身失效。
   改为 canonicalPath()：优先 realpath 父目录（plist 可能尚未落盘，父目录
   一定存在），退回 realpath 自身，最后退回 path.resolve。
   两个方向都不再误判：指向真实目录的链接被认成真实（该 bootout），
   沙箱仍被认成沙箱（不碰 launchd 域）。

2. [high/bug] 原 catch (_) 连 os.homedir() 的异常一起吞掉，返回「不是真实
   作业」。那会让 install 照旧把 plist 落盘却永远不 bootstrap——正是本 bug
   的另一种形态（文件在、作业不在、用户以为装好了）。现在只捕获路径定位
   失败，并明确写 stderr。

3. [high/test] ensureLoaded 的「跳过」分支是 install 侧的主修复点，原先没有
   回归测试。新增 probeInstallNow + 断言：沙箱 install --now 不调用任何
   launchctl、loaded=false、skipped=true、warn 匹配、plist 仍落盘。

4. [medium] 补齐信号语义：ensureLoaded 的三态返回契约写进注释；install 透传
   skipped；uninstall 增加 skipped（与「bootout 试过但作业未加载」区分）；
   status 的 loaded/queried 含义写进注释。

5. 新增符号链接回归测试：指向真实目录的链接必须判为真实作业；沙箱目录
   （即便经 /var 链接）必须判为沙箱。

验证：npm test 540 项 0 失败；跑测试前后 ~/.zcode/advisor-companion.log 零增长；
真实 LaunchAgent 在整轮测试后仍 running（pid 不变）。
---
 .../zcode-advisor/tools/companion/launchd.cjs | 81 ++++++++++++++-----
 test/launchd.test.js                          | 69 ++++++++++++++++
 tools/companion/launchd.cjs                   | 81 ++++++++++++++-----
 3 files changed, 189 insertions(+), 42 deletions(-)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index ab18047..9f71784 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -116,6 +116,43 @@ function launchctl(args) {
 }
 
 // 用户真实自启作业的 plist 路径——**绕过一切覆盖**（dir 参数 / ZCODE_ADVISOR_LAUNCHD_DIR）。
+// 完整安全不变量见 canTouchLaunchd 上方注释；这里只负责算出路径。
+function realPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+// 路径规范化：优先 realpath 父目录（plist 可能还没落盘，但父目录一定存在），
+// 再退回 realpath 自身，最后退回 path.resolve。
+//
+// 只做 path.resolve 会把「指向真实目录的符号链接」判成另一个位置：macOS 上
+// /var → /private/var、/tmp → /private/tmp 都是这种链接。后果是真实卸载被误判成
+// 「不是真实作业」而静默跳过——卸载功能本身失效。realpath 之后两个方向都不会误判：
+// 指向真实目录的链接被认成真实（该 bootout），沙箱仍被认成沙箱（不碰 launchd 域）。
+function canonicalPath(p) {
+  const dir = path.dirname(p);
+  const base = path.basename(p);
+  try { return path.join(fs.realpathSync(dir), base); } catch (_) { /* 父目录不存在 */ }
+  try { return fs.realpathSync(p); } catch (_) { /* 文件也不存在 */ }
+  return path.resolve(p);
+}
+
+// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
+//
+// 注意：os.homedir() 在个别环境下会抛（用户记录查不到）。这里**不静默吞掉**：
+// 吞掉会让 install 照旧把 plist 落盘、却永远不 bootstrap——正好是本 bug 的另一种形态
+// （文件在、作业不在、用户以为装好了）。出错时明确写 stderr 再返回 false。
+function managesRealAgent(p) {
+  let real;
+  try {
+    real = realPlistPath();
+  } catch (err) {
+    process.stderr.write(`[launchd] 无法定位用户 LaunchAgents 目录，跳过 launchd 域操作：${(err && err.message) || err}\n`);
+    return false;
+  }
+  return canonicalPath(p) === canonicalPath(real);
+}
+
+// launchd 域操作仅在 macOS、拿得到 uid、且**目标就是用户真实那份 plist** 时才允许。
 //
 // 关键不变量：LABEL 是固定常量，重定向只能改 plist 的**路径**，改不掉 launchd
 // 域里的作业名。所以一旦目标 plist 不是这一份，任何
@@ -129,22 +166,8 @@ function launchctl(args) {
 //     「已写入但未加载」这条断言必然变红）。
 // 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
 // 重定向的情形都能被正确识别。
-function realPlistPath() {
-  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
-}
-
-// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
-function managesRealAgent(p) {
-  try {
-    return path.resolve(p) === path.resolve(realPlistPath());
-  } catch (_) {
-    return false;
-  }
-}
-
-// launchd 域操作仅在 macOS 且拿得到 uid 时才有意义。
-// 显式判断而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」正是本 bug
-// 在 CI 上无法暴露的原因。
+// 显式判断 platform/uid 而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」
+// 正是本 bug 在 CI 上无法暴露的原因。
 function canTouchLaunchd(p) {
   return process.platform === 'darwin' && uid() !== null && managesRealAgent(p);
 }
@@ -176,8 +199,13 @@ function isLoaded(label) {
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
 //
-// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 managesRealAgent）：
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 canTouchLaunchd）：
 // 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
+//
+// 返回契约（三种形状，靠 skipped / warn 区分「跳过」与「失败」）：
+//   { loaded:true,  reloaded:boolean }            —— 已加载（reloaded 表示是否重载过）
+//   { loaded:false, skipped:true, warn }          —— 故意跳过域操作（沙箱/非 darwin/无 uid）
+//   { loaded:false, warn }                        —— 真失败（bootstrap 抛错）
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
@@ -223,31 +251,42 @@ function install(opts) {
   // --now 才立即 bootstrap（launchctl bootstrap 会因 RunAtLoad 立刻拉起 controller）。
   let loaded = false;
   let warn = '';
+  let skipped = false;
   if (o.now) {
     const r = ensureLoaded(written.path, written.changed);
     loaded = r.loaded;
     warn = r.warn || '';
+    skipped = r.skipped === true;
     if (!r.loaded && warn) {
-      return { ok: true, path: written.path, changed: written.changed, loaded: false, warn };
+      return { ok: true, path: written.path, changed: written.changed, loaded: false, skipped, warn };
     }
   }
-  return { ok: true, path: written.path, changed: written.changed, loaded };
+  return { ok: true, path: written.path, changed: written.changed, loaded, skipped };
 }
 
 function uninstall(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
   // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
-  // （见 managesRealAgent）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
   let bootedOut = false;
+  let skipped = false;
   if (canTouchLaunchd(p)) {
     try { launchctl(['bootout', `gui/${uid()}/${LABEL}`]); bootedOut = true; } catch (_) { /* 未加载：忽略 */ }
+  } else {
+    // 非 darwin / 拿不到 uid / 目标是沙箱：bootedOut=false 是**故意**的，
+    // 用 skipped 与「bootout 试过但作业本就没加载」区分开。
+    skipped = true;
   }
   let removed = false;
   try { fs.unlinkSync(p); removed = true; } catch (_) { /* 不存在：忽略 */ }
-  return { ok: true, path: p, removed, bootedOut };
+  return { ok: true, path: p, removed, bootedOut, skipped };
 }
 
+// 返回：{ path, exists, loaded, queried, state }。
+// loaded 的含义**始终**是「launchd 报告该作业已加载」；重定向（沙箱）时不去查询，
+// 于是 loaded 恒为 false，靠 queried=false 表示「没查过」而不是「查过、没加载」。
+// 调用方若要区分这两种情况，看 queried。
 function status(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
diff --git a/test/launchd.test.js b/test/launchd.test.js
index 80f657f..273170c 100644
--- a/test/launchd.test.js
+++ b/test/launchd.test.js
@@ -205,6 +205,75 @@ function probeUninstall(opts, extraEnv) {
   return JSON.parse(out.trim());
 }
 
+// install --now 走的是 ensureLoaded 的「跳过」分支，这是 install 侧的主修复点。
+// 必须在子进程里打桩：真机上不拦的话，`install --now` 会把沙箱 plist bootstrap 进
+// 用户真实的 gui 域，等于凭空多出一个自启作业。
+function probeInstallNow(opts, extraEnv) {
+  const runner = `
+    const cp = require('child_process');
+    const calls = [];
+    cp.execFileSync = (f, a) => { calls.push([f, a]); return ''; };
+    const L = require(${JSON.stringify(path.join(__dirname, '../tools/companion/launchd.cjs'))});
+    const r = L.install(${JSON.stringify(opts)});
+    process.stdout.write(JSON.stringify({ r, calls }));
+  `;
+  const out = require('child_process').execFileSync(process.execPath, ['-e', runner], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, extraEnv || {})
+  });
+  return JSON.parse(out.trim());
+}
+
+test('install --now：沙箱 dir 只落盘，绝不 bootstrap 进真实 gui 域', () => {
+  const dir = tmpDir();
+  const probe = probeInstallNow({ dir, now: true, nodeBin: '/x/node', controllerPath: '/x/controller.cjs' });
+  assert.deepStrictEqual(probe.calls, [],
+    '沙箱 install --now 不得调用任何 launchctl（bootstrap 会往用户真实 gui 域塞作业）');
+  assert.strictEqual(probe.r.loaded, false);
+  assert.strictEqual(probe.r.skipped, true, '必须把「跳过加载」明确报给调用方');
+  assert.match(probe.r.warn, /跳过 launchd 加载/);
+  assert.ok(fs.existsSync(L.plistPath(dir)), 'plist 仍应正常落盘');
+});
+
+// 符号链接规范化：只做 path.resolve 时，「指向真实 LaunchAgents 目录的链接」会被判成
+// 另一个位置 → 真实卸载被静默跳过（卸载功能失效）。macOS 上 /var → /private/var 就是
+// 这类链接。这里用自建链接锁死语义，不依赖平台上的 /var 是否存在。
+test('路径判定：指向真实目录的符号链接仍算真实作业（否则卸载被静默跳过）', { skip: process.platform !== 'darwin' && '仅在 macOS 有 launchd 域' }, () => {
+  const linkParent = tmpDir();
+  const link = path.join(linkParent, 'LaunchAgents-link');
+  const realDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+  if (!fs.existsSync(realDir)) return;
+  fs.symlinkSync(realDir, link, 'dir');
+  // 打桩后 status 不会真的查 launchd；queried 表示「判定为真实作业、允许操作域」。
+  const probe = probeStatus({ dir: link });
+  assert.strictEqual(probe.r.queried, true,
+    '链接指向真实目录时必须认定为真实作业（path.resolve 版本会误判为沙箱）');
+});
+
+test('路径判定：沙箱目录即使经 /var 符号链接也不得认定为真实作业', () => {
+  const dir = tmpDir();
+  const probe = probeStatus({ dir });
+  assert.strictEqual(probe.r.queried, false);
+});
+
+// status 的域查询同样要打桩：真机上不拦的话，`status` 会去 print 用户真实作业，
+// 把真实运行态当成沙箱 plist 的态返回（装了 agent 的开发机上断言必红）。
+function probeStatus(opts, extraEnv) {
+  const runner = `
+    const cp = require('child_process');
+    const calls = [];
+    cp.execFileSync = (f, a) => { calls.push([f, a]); return ''; };
+    const L = require(${JSON.stringify(path.join(__dirname, '../tools/companion/launchd.cjs'))});
+    const r = L.status(${JSON.stringify(opts)});
+    process.stdout.write(JSON.stringify({ r, calls }));
+  `;
+  const out = require('child_process').execFileSync(process.execPath, ['-e', runner], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, extraEnv || {})
+  });
+  return JSON.parse(out.trim());
+}
+
 test('uninstall：移除 plist 文件（可逆）', () => {
   const dir = tmpDir();
   L.install({ dir, nodeBin: '/x/node', controllerPath: '/x/controller.cjs' });
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index ab18047..9f71784 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -116,6 +116,43 @@ function launchctl(args) {
 }
 
 // 用户真实自启作业的 plist 路径——**绕过一切覆盖**（dir 参数 / ZCODE_ADVISOR_LAUNCHD_DIR）。
+// 完整安全不变量见 canTouchLaunchd 上方注释；这里只负责算出路径。
+function realPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+// 路径规范化：优先 realpath 父目录（plist 可能还没落盘，但父目录一定存在），
+// 再退回 realpath 自身，最后退回 path.resolve。
+//
+// 只做 path.resolve 会把「指向真实目录的符号链接」判成另一个位置：macOS 上
+// /var → /private/var、/tmp → /private/tmp 都是这种链接。后果是真实卸载被误判成
+// 「不是真实作业」而静默跳过——卸载功能本身失效。realpath 之后两个方向都不会误判：
+// 指向真实目录的链接被认成真实（该 bootout），沙箱仍被认成沙箱（不碰 launchd 域）。
+function canonicalPath(p) {
+  const dir = path.dirname(p);
+  const base = path.basename(p);
+  try { return path.join(fs.realpathSync(dir), base); } catch (_) { /* 父目录不存在 */ }
+  try { return fs.realpathSync(p); } catch (_) { /* 文件也不存在 */ }
+  return path.resolve(p);
+}
+
+// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
+//
+// 注意：os.homedir() 在个别环境下会抛（用户记录查不到）。这里**不静默吞掉**：
+// 吞掉会让 install 照旧把 plist 落盘、却永远不 bootstrap——正好是本 bug 的另一种形态
+// （文件在、作业不在、用户以为装好了）。出错时明确写 stderr 再返回 false。
+function managesRealAgent(p) {
+  let real;
+  try {
+    real = realPlistPath();
+  } catch (err) {
+    process.stderr.write(`[launchd] 无法定位用户 LaunchAgents 目录，跳过 launchd 域操作：${(err && err.message) || err}\n`);
+    return false;
+  }
+  return canonicalPath(p) === canonicalPath(real);
+}
+
+// launchd 域操作仅在 macOS、拿得到 uid、且**目标就是用户真实那份 plist** 时才允许。
 //
 // 关键不变量：LABEL 是固定常量，重定向只能改 plist 的**路径**，改不掉 launchd
 // 域里的作业名。所以一旦目标 plist 不是这一份，任何
@@ -129,22 +166,8 @@ function launchctl(args) {
 //     「已写入但未加载」这条断言必然变红）。
 // 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
 // 重定向的情形都能被正确识别。
-function realPlistPath() {
-  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
-}
-
-// 目标 plist 是否就是用户真实那份（只有这份才允许操作 launchd 域）。
-function managesRealAgent(p) {
-  try {
-    return path.resolve(p) === path.resolve(realPlistPath());
-  } catch (_) {
-    return false;
-  }
-}
-
-// launchd 域操作仅在 macOS 且拿得到 uid 时才有意义。
-// 显式判断而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」正是本 bug
-// 在 CI 上无法暴露的原因。
+// 显式判断 platform/uid 而不是靠 execFileSync 抛 ENOENT 再吞掉——「静默吞掉」
+// 正是本 bug 在 CI 上无法暴露的原因。
 function canTouchLaunchd(p) {
   return process.platform === 'darwin' && uid() !== null && managesRealAgent(p);
 }
@@ -176,8 +199,13 @@ function isLoaded(label) {
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
 //
-// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 managesRealAgent）：
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 canTouchLaunchd）：
 // 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
+//
+// 返回契约（三种形状，靠 skipped / warn 区分「跳过」与「失败」）：
+//   { loaded:true,  reloaded:boolean }            —— 已加载（reloaded 表示是否重载过）
+//   { loaded:false, skipped:true, warn }          —— 故意跳过域操作（沙箱/非 darwin/无 uid）
+//   { loaded:false, warn }                        —— 真失败（bootstrap 抛错）
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
@@ -223,31 +251,42 @@ function install(opts) {
   // --now 才立即 bootstrap（launchctl bootstrap 会因 RunAtLoad 立刻拉起 controller）。
   let loaded = false;
   let warn = '';
+  let skipped = false;
   if (o.now) {
     const r = ensureLoaded(written.path, written.changed);
     loaded = r.loaded;
     warn = r.warn || '';
+    skipped = r.skipped === true;
     if (!r.loaded && warn) {
-      return { ok: true, path: written.path, changed: written.changed, loaded: false, warn };
+      return { ok: true, path: written.path, changed: written.changed, loaded: false, skipped, warn };
     }
   }
-  return { ok: true, path: written.path, changed: written.changed, loaded };
+  return { ok: true, path: written.path, changed: written.changed, loaded, skipped };
 }
 
 function uninstall(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);
   // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
-  // （见 managesRealAgent）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
   let bootedOut = false;
+  let skipped = false;
   if (canTouchLaunchd(p)) {
     try { launchctl(['bootout', `gui/${uid()}/${LABEL}`]); bootedOut = true; } catch (_) { /* 未加载：忽略 */ }
+  } else {
+    // 非 darwin / 拿不到 uid / 目标是沙箱：bootedOut=false 是**故意**的，
+    // 用 skipped 与「bootout 试过但作业本就没加载」区分开。
+    skipped = true;
   }
   let removed = false;
   try { fs.unlinkSync(p); removed = true; } catch (_) { /* 不存在：忽略 */ }
-  return { ok: true, path: p, removed, bootedOut };
+  return { ok: true, path: p, removed, bootedOut, skipped };
 }
 
+// 返回：{ path, exists, loaded, queried, state }。
+// loaded 的含义**始终**是「launchd 报告该作业已加载」；重定向（沙箱）时不去查询，
+// 于是 loaded 恒为 false，靠 queried=false 表示「没查过」而不是「查过、没加载」。
+// 调用方若要区分这两种情况，看 queried。
 function status(opts) {
   const o = opts || {};
   const p = plistPath(o.dir);

From d80fae83b1bfd7f0e6ebb342409ce484bc41dcd7 Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 12:27:29 +0800
Subject: [PATCH 3/6] =?UTF-8?q?fix(launchd):=20=E8=A1=A5=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=E4=B8=8E=20realpath=20TOCTOU=20=E5=85=9C?=
 =?UTF-8?q?=E5=BA=95=E6=96=B9=E5=90=91=E7=9A=84=E5=9B=9E=E5=BD=92=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OCR 复审（PR #10）逐条核对后的处置：
- ensureLoaded/install/uninstall 补 skipped 契约说明：skipped 只表示
  「没去碰 launchd 域」，与「碰了但作业未加载」是两回事，调用方据此
  决定是否自行拉起进程。
- canonicalPath 补注 realpathSync 的 TOCTOU 兜底方向：目录消失时退回
  path.resolve，沙箱仍判为非真实作业（宁可不操作，也不误打真实作业）。
- 新增回归测试锁死该兜底方向，并在沙箱 uninstall 断言 skipped=true。

其余 OCR 意见经实测判为误报或不适用，未采纳：
- status() 缺 queried 文档：HEAD 已有该注释块（launchd.cjs:286-289）。
- uid() 未防 process.getuid 缺失：已有 typeof 检查 + try/catch。
- ensureLoaded 的 bootout 未捕获异常：已包 try/catch。
- 要求加 console.debug/console.warn：全项目零处使用 console.debug，
  且 tools/companion 的日志走 LOG_FILE 而非 stderr，属风格性建议。
- 要求异步 realpath + 重试：判定是同步短路径，重试反而扩大 TOCTOU 窗口。
- 要求校验 macOS 模拟器/真实硬件：无此可编程信号，非 darwin 已短路。
- 要求 homedir 错误信息更详细：现有信息不含路径，改详细反而更易泄露。
---
 plugins/zcode-advisor/tools/companion/launchd.cjs | 11 +++++++++++
 test/launchd.test.js                              | 12 ++++++++++++
 tools/companion/launchd.cjs                       | 11 +++++++++++
 3 files changed, 34 insertions(+)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index 9f71784..ed93e7d 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -128,6 +128,11 @@ function realPlistPath() {
 // /var → /private/var、/tmp → /private/tmp 都是这种链接。后果是真实卸载被误判成
 // 「不是真实作业」而静默跳过——卸载功能本身失效。realpath 之后两个方向都不会误判：
 // 指向真实目录的链接被认成真实（该 bootout），沙箱仍被认成沙箱（不碰 launchd 域）。
+//
+// realpathSync 可能因目录在两次调用之间被删而抛（TOCTOU）。这里不回退重试而是直接
+// 落到 path.resolve：**兜底方向是安全的**——沙箱目录消失时判定结果仍是「不是真实作业」，
+// 于是不碰 launchd 域（宁可不操作，也不能误打用户真实作业）。反之若真实目录消失，
+// 两条路径都退化成 path.resolve，仍然相等，卸载照常生效。
 function canonicalPath(p) {
   const dir = path.dirname(p);
   const base = path.basename(p);
@@ -206,6 +211,9 @@ function isLoaded(label) {
 //   { loaded:true,  reloaded:boolean }            —— 已加载（reloaded 表示是否重载过）
 //   { loaded:false, skipped:true, warn }          —— 故意跳过域操作（沙箱/非 darwin/无 uid）
 //   { loaded:false, warn }                        —— 真失败（bootstrap 抛错）
+//
+// 注意 skipped 只表示「**没去碰** launchd 域」，与「碰了但作业没加载」是两回事；
+// install/uninstall 的返回值沿用同一含义，调用方据此决定是否自行拉起进程。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
@@ -269,6 +277,9 @@ function uninstall(opts) {
   const p = plistPath(o.dir);
   // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
   // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // 返回 { ok, path, removed, bootedOut, skipped }：skipped=true 表示**没去碰** launchd
+  // 域（沙箱/非 darwin/无 uid），此时 bootedOut 恒为 false，且与「bootout 试过但作业
+  // 本就没加载」区分开。
   let bootedOut = false;
   let skipped = false;
   if (canTouchLaunchd(p)) {
diff --git a/test/launchd.test.js b/test/launchd.test.js
index 273170c..13607d7 100644
--- a/test/launchd.test.js
+++ b/test/launchd.test.js
@@ -256,6 +256,16 @@ test('路径判定：沙箱目录即使经 /var 符号链接也不得认定为
   assert.strictEqual(probe.r.queried, false);
 });
 
+// realpathSync 的 TOCTOU 兜底方向必须是安全的：沙箱目录在判定途中消失时，
+// canonicalPath 退化成 path.resolve，仍不得被认成真实作业（宁可跳过，也不能误打真实作业）。
+test('路径判定：沙箱目录不存在时兜底为「非真实作业」（realpath 失败方向必须安全）', () => {
+  const gone = path.join(os.tmpdir(), `zca-vanished-${process.pid}-${Date.now()}`);
+  assert.ok(!fs.existsSync(gone), '前置条件：该目录确实不存在');
+  const s = L.status({ dir: gone });
+  assert.strictEqual(s.queried, false, '路径不可 realpath 时不得认定为真实作业（否则会误 bootout 用户真实作业）');
+  assert.strictEqual(s.loaded, false);
+});
+
 // status 的域查询同样要打桩：真机上不拦的话，`status` 会去 print 用户真实作业，
 // 把真实运行态当成沙箱 plist 的态返回（装了 agent 的开发机上断言必红）。
 function probeStatus(opts, extraEnv) {
@@ -300,6 +310,8 @@ test('uninstall：dir 覆盖时绝不 bootout 真实 LABEL（本机 npm test 会
   assert.deepStrictEqual(probe.calls, [],
     '沙箱 uninstall 不得调用任何 launchctl（bootout 会终止并卸载用户真实自启作业）');
   assert.strictEqual(probe.r.bootedOut, false);
+  assert.strictEqual(probe.r.skipped, true,
+    'skipped=true 表示「没去碰」launchd 域，与「碰了但作业未加载」可区分');
   assert.deepStrictEqual(probe.unlinked, [L.plistPath(dir)],
     '只应删除沙箱自己的 plist');
 });
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index 9f71784..ed93e7d 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -128,6 +128,11 @@ function realPlistPath() {
 // /var → /private/var、/tmp → /private/tmp 都是这种链接。后果是真实卸载被误判成
 // 「不是真实作业」而静默跳过——卸载功能本身失效。realpath 之后两个方向都不会误判：
 // 指向真实目录的链接被认成真实（该 bootout），沙箱仍被认成沙箱（不碰 launchd 域）。
+//
+// realpathSync 可能因目录在两次调用之间被删而抛（TOCTOU）。这里不回退重试而是直接
+// 落到 path.resolve：**兜底方向是安全的**——沙箱目录消失时判定结果仍是「不是真实作业」，
+// 于是不碰 launchd 域（宁可不操作，也不能误打用户真实作业）。反之若真实目录消失，
+// 两条路径都退化成 path.resolve，仍然相等，卸载照常生效。
 function canonicalPath(p) {
   const dir = path.dirname(p);
   const base = path.basename(p);
@@ -206,6 +211,9 @@ function isLoaded(label) {
 //   { loaded:true,  reloaded:boolean }            —— 已加载（reloaded 表示是否重载过）
 //   { loaded:false, skipped:true, warn }          —— 故意跳过域操作（沙箱/非 darwin/无 uid）
 //   { loaded:false, warn }                        —— 真失败（bootstrap 抛错）
+//
+// 注意 skipped 只表示「**没去碰** launchd 域」，与「碰了但作业没加载」是两回事；
+// install/uninstall 的返回值沿用同一含义，调用方据此决定是否自行拉起进程。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
   if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
@@ -269,6 +277,9 @@ function uninstall(opts) {
   const p = plistPath(o.dir);
   // 只在「目标就是用户真实那份 + macOS」时才 bootout：否则会打掉用户真实的自启作业
   // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // 返回 { ok, path, removed, bootedOut, skipped }：skipped=true 表示**没去碰** launchd
+  // 域（沙箱/非 darwin/无 uid），此时 bootedOut 恒为 false，且与「bootout 试过但作业
+  // 本就没加载」区分开。
   let bootedOut = false;
   let skipped = false;
   if (canTouchLaunchd(p)) {

From 4da8eb2c288c8a2318df3a1b95904616c8f42087 Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 12:30:38 +0800
Subject: [PATCH 4/6] =?UTF-8?q?docs(launchd):=20=E8=A1=A5=20install=20?=
 =?UTF-8?q?=E8=BF=94=E5=9B=9E=E5=A5=91=E7=BA=A6=E4=B8=8E=20/bin/launchctl?=
 =?UTF-8?q?=20=E5=9B=BA=E5=AE=9A=E8=B7=AF=E5=BE=84=E7=9A=84=E7=90=86?=
 =?UTF-8?q?=E7=94=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OCR 第三轮复审（PR #10，run 37413811219）后补充的文档：
- install() 补完整返回契约（ok/reason、skipped 与 warn 互斥地表达
  「故意跳过」与「尝试后失败」、loaded/changed 的含义）。
- launchctl() 说明为何固定 /bin/launchctl：系统自带、不随版本漂移，
  且刻意不走 PATH——PATH 上的同名文件可能被劫持，而该调用会 bootout
  用户真实的自启作业。

第三轮其余意见与第二轮重复，仍判为误报或不适用：
- status() 缺 queried 文档 / ensureLoaded 缺 reloaded 文档：注释块已存在
  （launchd.cjs:211 与 :297-300）。
- realpath catch 是空块：两个 catch 均带行内原因注释，且已补 TOCTOU
  兜底方向说明；不加 console.warn 是因为全项目零处使用 console.* 写日志。
- 要求加文件锁/重试缓解 TOCTOU：判定是同步短路径，重试反而扩大窗口。
- 要求重命名 queried 为 isRealAgentQueried：会破坏已发布的返回契约，
  且 queried 已在调用方注释中定义。
- 要求动态查找 launchctl 路径：见上，固定绝对路径才是安全方向。
---
 plugins/zcode-advisor/tools/companion/launchd.cjs | 9 +++++++++
 tools/companion/launchd.cjs                       | 9 +++++++++
 2 files changed, 18 insertions(+)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index ed93e7d..2ce6b7b 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -111,6 +111,9 @@ function uid() {
   try { return typeof process.getuid === 'function' ? process.getuid() : null; } catch (_) { return null; }
 }
 
+// launchctl 固定在 /bin/launchctl：这是 macOS 系统自带、不随版本漂移的绝对路径，
+// 刻意不走 PATH 查找——PATH 上的同名文件可能被用户环境劫持，而这里的调用会
+// bootout 用户真实的自启作业。
 function launchctl(args) {
   return execFileSync('/bin/launchctl', args, { stdio: 'pipe', timeout: 20000, encoding: 'utf8' });
 }
@@ -232,6 +235,12 @@ function ensureLoaded(plistFile, changed, label) {
   }
 }
 
+// 返回契约：{ ok, path, changed, loaded, skipped, warn?, reason? }
+//   ok:false + reason        —— 未安装（找不到 controller / 工作树布局 / 写盘失败）
+//   ok:true  + skipped:true  —— 只落盘、**没去碰** launchd 域（沙箱/非 darwin/无 uid）
+//   ok:true  + loaded:true   —— 已交给 launchd 加载（changed 表示这次是否重写了 plist）
+//   ok:true  + loaded:false + warn —— 碰了域但 bootstrap 失败
+// skipped 与 warn 互斥地表达「故意跳过」与「尝试后失败」，调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index ed93e7d..2ce6b7b 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -111,6 +111,9 @@ function uid() {
   try { return typeof process.getuid === 'function' ? process.getuid() : null; } catch (_) { return null; }
 }
 
+// launchctl 固定在 /bin/launchctl：这是 macOS 系统自带、不随版本漂移的绝对路径，
+// 刻意不走 PATH 查找——PATH 上的同名文件可能被用户环境劫持，而这里的调用会
+// bootout 用户真实的自启作业。
 function launchctl(args) {
   return execFileSync('/bin/launchctl', args, { stdio: 'pipe', timeout: 20000, encoding: 'utf8' });
 }
@@ -232,6 +235,12 @@ function ensureLoaded(plistFile, changed, label) {
   }
 }
 
+// 返回契约：{ ok, path, changed, loaded, skipped, warn?, reason? }
+//   ok:false + reason        —— 未安装（找不到 controller / 工作树布局 / 写盘失败）
+//   ok:true  + skipped:true  —— 只落盘、**没去碰** launchd 域（沙箱/非 darwin/无 uid）
+//   ok:true  + loaded:true   —— 已交给 launchd 加载（changed 表示这次是否重写了 plist）
+//   ok:true  + loaded:false + warn —— 碰了域但 bootstrap 失败
+// skipped 与 warn 互斥地表达「故意跳过」与「尝试后失败」，调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath

From f951da191ec82080d9914fd44ab592b0995a9d9a Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 12:40:02 +0800
Subject: [PATCH 5/6] =?UTF-8?q?fix(launchd):=20uid=20=E5=8F=96=E4=B8=8D?=
 =?UTF-8?q?=E5=88=B0=E6=97=B6=20ensureLoaded=20=E4=B9=9F=E5=BF=85=E9=A1=BB?=
 =?UTF-8?q?=E6=8A=A5=20skipped?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OCR 第四轮复审（PR #10）里唯一成立的一条：ensureLoaded 在 uid()===null
时返回 {loaded:false, warn} 而**没有** skipped:true，与沙箱分支的契约
不一致。调用方按 skipped 判断「是故意跳过还是尝试后失败」，缺这个字段
会把「拿不到 uid、根本没去加载」误当成「加载失败」，进而重复重试。

同时修正上一轮我自己写错的文档：install() 契约里写「skipped 与 warn 互斥」，
实测沙箱分支两个字段同时出现（skipped=true 且 warn 有值）。改为
「skipped=true 时 warn 说明跳过原因，两者会同时出现」。

新增回归测试：删掉 process.getuid 后 install --now 必须
skipped=true、warn 含 uid、且一次 launchctl 都不调。已验证该测试在
修复前的源码上会红（fail 1），修复后转绿。

第四轮其余意见仍判为误报（逐条实测）：
- canonicalPath 回退 path.resolve「未做安全校验」：兜底方向本就是安全的，
  沙箱目录消失时判为「非真实作业」→ 不碰 launchd 域，已在注释中写明。
- managesRealAgent 里 homedir 抛错后「未阻止后续比较」：catch 内已
  return false（launchd.cjs:154-158）。
- ensureLoaded 的 skipped「未阻止 launchctl」：该分支在任何 launchctl
  调用之前直接 return（launchd.cjs:223-227）。
- skipped/queried/bootedOut「未在函数开头声明」：均已声明
  （launchd.cjs:269-271、:292-293、:318-319）。
- 变量命名 o/plistFile/p：const o = opts || {} 是仓库既有约定（10 处）。
- status 缺 queried 文档：注释块已存在（launchd.cjs:314-319）。
- logPath 的 homedir 未处理：属未改动的既有代码，不在本次改动范围。
- launchctl 错误处理不一致：uninstall/status 的静默是设计意图（清理动作
  失败不应阻断卸载/查询），ensureLoaded 才需要把失败报给调用方。
---
 .../zcode-advisor/tools/companion/launchd.cjs |  5 ++--
 test/launchd.test.js                          | 26 +++++++++++++++++++
 tools/companion/launchd.cjs                   |  5 ++--
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index 2ce6b7b..c8748e0 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -219,7 +219,7 @@ function isLoaded(label) {
 // install/uninstall 的返回值沿用同一含义，调用方据此决定是否自行拉起进程。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
-  if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
+  if (uid() === null) return { loaded: false, skipped: true, warn: '无法获取 uid，跳过加载' };
   if (!canTouchLaunchd(plistFile)) {
     // 只落盘，由调用方决定是否需要别的加载方式；不谎报「已加载」。
     return { loaded: false, skipped: true, warn: '目标不是用户真实 LaunchAgent，跳过 launchd 加载（避免影响真实自启作业）' };
@@ -240,7 +240,8 @@ function ensureLoaded(plistFile, changed, label) {
 //   ok:true  + skipped:true  —— 只落盘、**没去碰** launchd 域（沙箱/非 darwin/无 uid）
 //   ok:true  + loaded:true   —— 已交给 launchd 加载（changed 表示这次是否重写了 plist）
 //   ok:true  + loaded:false + warn —— 碰了域但 bootstrap 失败
-// skipped 与 warn 互斥地表达「故意跳过」与「尝试后失败」，调用方据此决定是否自行拉起进程。
+// skipped=true 时 warn 说明跳过的原因（两者会同时出现）；loaded=true 时才代表真的
+// 交给了 launchd。调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath
diff --git a/test/launchd.test.js b/test/launchd.test.js
index 13607d7..293da01 100644
--- a/test/launchd.test.js
+++ b/test/launchd.test.js
@@ -235,6 +235,32 @@ test('install --now：沙箱 dir 只落盘，绝不 bootstrap 进真实 gui 域'
   assert.ok(fs.existsSync(L.plistPath(dir)), 'plist 仍应正常落盘');
 });
 
+// uid() 取不到时也必须走「跳过」分支：此时 canTouchLaunchd 为 false，绝不能落到
+// launchctl bootstrap（拿不到 uid 还去 bootstrap 只会失败或打错域）。返回值必须和
+// 沙箱路径一样明确报 skipped=true，否则调用方会把「没加载」当成「加载失败」。
+// 用删除 process.getuid 来模拟（uid() 在调用时按 typeof 判断，故 require 前删即可）。
+test('install --now：拿不到 uid 时同样报 skipped=true 且不调 launchctl', () => {
+  const dir = tmpDir();
+  const runner = `
+    delete process.getuid;
+    const cp = require('child_process');
+    const calls = [];
+    cp.execFileSync = (f, a) => { calls.push([f, a]); return ''; };
+    const L = require(${JSON.stringify(path.join(__dirname, '../tools/companion/launchd.cjs'))});
+    const r = L.install(${JSON.stringify({ dir, now: true, nodeBin: '/x/node', controllerPath: '/x/controller.cjs' })});
+    process.stdout.write(JSON.stringify({ r, calls }));
+  `;
+  const out = require('child_process').execFileSync(process.execPath, ['-e', runner], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env)
+  });
+  const probe = JSON.parse(out.trim());
+  assert.deepStrictEqual(probe.calls, [], '拿不到 uid 时不得调用任何 launchctl');
+  assert.strictEqual(probe.r.loaded, false);
+  assert.strictEqual(probe.r.skipped, true, '拿不到 uid 也要明确报「跳过」而不是「失败」');
+  assert.match(probe.r.warn, /uid/);
+});
+
 // 符号链接规范化：只做 path.resolve 时，「指向真实 LaunchAgents 目录的链接」会被判成
 // 另一个位置 → 真实卸载被静默跳过（卸载功能失效）。macOS 上 /var → /private/var 就是
 // 这类链接。这里用自建链接锁死语义，不依赖平台上的 /var 是否存在。
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index 2ce6b7b..c8748e0 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -219,7 +219,7 @@ function isLoaded(label) {
 // install/uninstall 的返回值沿用同一含义，调用方据此决定是否自行拉起进程。
 function ensureLoaded(plistFile, changed, label) {
   const l = label || LABEL;
-  if (uid() === null) return { loaded: false, warn: '无法获取 uid，跳过加载' };
+  if (uid() === null) return { loaded: false, skipped: true, warn: '无法获取 uid，跳过加载' };
   if (!canTouchLaunchd(plistFile)) {
     // 只落盘，由调用方决定是否需要别的加载方式；不谎报「已加载」。
     return { loaded: false, skipped: true, warn: '目标不是用户真实 LaunchAgent，跳过 launchd 加载（避免影响真实自启作业）' };
@@ -240,7 +240,8 @@ function ensureLoaded(plistFile, changed, label) {
 //   ok:true  + skipped:true  —— 只落盘、**没去碰** launchd 域（沙箱/非 darwin/无 uid）
 //   ok:true  + loaded:true   —— 已交给 launchd 加载（changed 表示这次是否重写了 plist）
 //   ok:true  + loaded:false + warn —— 碰了域但 bootstrap 失败
-// skipped 与 warn 互斥地表达「故意跳过」与「尝试后失败」，调用方据此决定是否自行拉起进程。
+// skipped=true 时 warn 说明跳过的原因（两者会同时出现）；loaded=true 时才代表真的
+// 交给了 launchd。调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath

From 91c834ac1d7abb7cd086562f2ee71bd8f2786640 Mon Sep 17 00:00:00 2001
From: Seller-1990 <sjt15866355912@gmail.com>
Date: Tue, 6 Oct 2026 12:52:29 +0800
Subject: [PATCH 6/6] =?UTF-8?q?fix(launchd):=20CLI=20=E6=98=8E=E7=A1=AE?=
 =?UTF-8?q?=E8=BE=93=E5=87=BA=20skipped/queried=EF=BC=8C=E9=81=BF=E5=85=8D?=
 =?UTF-8?q?=E8=AF=AF=E8=AF=BB=E4=B8=BA=E3=80=8C=E4=BD=9C=E4=B8=9A=E6=B2=A1?=
 =?UTF-8?q?=E5=9C=A8=E8=B7=91=E3=80=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OCR 第五轮复审（PR #10）里唯一有实质的一条：新增的 skipped/queried
返回字段没有任何调用方消费。CLI 是唯一的人类可读出口，补上：
- uninstall 在 skipped=true 时打印「（未操作 launchd 域）」——否则
  「已移除/文件不存在」只描述 plist 文件，容易被当成真实作业也被卸载了。
- status 在 queried=false 时打印 queried=否——否则只打 loaded=否 会让
  packagers.cjs:213 / install-templates.cjs:184 的
  把「没查过」误读成「作业没在跑」。

刻意不改  这个 grep 契约：它只在真实 plist 路径上被调用
（无 dir 参数），此时 queried 恒为 true，行为与改动前一致；已实测
真机 status 输出不含 queried=否、且 grep 仍命中。

第五轮其余意见判为误报或不适用：
- 「bootout 是拼音、建议国际化」：bootout 是 launchctl 的真实子命令名，
  改名会让命令失效。
- 「按操作类型调超时」：print/bootout/bootstrap 共用 20s 是既有设计，
  本次未改动该行。
- 「函数开头补更详细文档」：四个函数的返回契约注释块均已存在。
- 「launchctl 固定路径/变量命名」：与第四轮重复，已逐条答复。
---
 plugins/zcode-advisor/tools/companion/launchd.cjs | 12 ++++++++++--
 tools/companion/launchd.cjs                       | 12 ++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index c8748e0..0be261d 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -340,11 +340,19 @@ function main(argv) {
   }
   if (cmd === 'uninstall') {
     const r = uninstall();
-    console.log(`[launchd] uninstall: ${r.removed ? '已移除' : '文件不存在'} ${r.path}`);
+    // skipped=true 时说明**没去碰** launchd 域（沙箱/非 darwin/无 uid），此时
+    // 「已移除/文件不存在」只描述 plist 文件，不代表真实作业被卸载——打印出来，
+    // 免得看日志的人把「文件删了」当成「作业也停了」。
+    const skip = r.skipped ? '（未操作 launchd 域）' : '';
+    console.log(`[launchd] uninstall: ${r.removed ? '已移除' : '文件不存在'}${skip} ${r.path}`);
     return 0;
   }
   const s = status();
-  console.log(`[launchd] status: plist=${s.exists ? '存在' : '不存在'} loaded=${s.loaded ? '是' : '否'}${s.state ? ` state=${s.state}` : ''} path=${s.path}`);
+  // queried=false 表示**没查** launchd 域（沙箱/非 darwin/无 uid），与「查过、没加载」
+  // 是两回事。只打 loaded=否 会让调用方（packagers/install-templates 里的
+  // `grep -q 'loaded=是'`）把「没查过」误读成「作业没在跑」。
+  const q = s.queried === false ? ' queried=否' : '';
+  console.log(`[launchd] status: plist=${s.exists ? '存在' : '不存在'} loaded=${s.loaded ? '是' : '否'}${q}${s.state ? ` state=${s.state}` : ''} path=${s.path}`);
   return 0;
 }
 
diff --git a/tools/companion/launchd.cjs b/tools/companion/launchd.cjs
index c8748e0..0be261d 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -340,11 +340,19 @@ function main(argv) {
   }
   if (cmd === 'uninstall') {
     const r = uninstall();
-    console.log(`[launchd] uninstall: ${r.removed ? '已移除' : '文件不存在'} ${r.path}`);
+    // skipped=true 时说明**没去碰** launchd 域（沙箱/非 darwin/无 uid），此时
+    // 「已移除/文件不存在」只描述 plist 文件，不代表真实作业被卸载——打印出来，
+    // 免得看日志的人把「文件删了」当成「作业也停了」。
+    const skip = r.skipped ? '（未操作 launchd 域）' : '';
+    console.log(`[launchd] uninstall: ${r.removed ? '已移除' : '文件不存在'}${skip} ${r.path}`);
     return 0;
   }
   const s = status();
-  console.log(`[launchd] status: plist=${s.exists ? '存在' : '不存在'} loaded=${s.loaded ? '是' : '否'}${s.state ? ` state=${s.state}` : ''} path=${s.path}`);
+  // queried=false 表示**没查** launchd 域（沙箱/非 darwin/无 uid），与「查过、没加载」
+  // 是两回事。只打 loaded=否 会让调用方（packagers/install-templates 里的
+  // `grep -q 'loaded=是'`）把「没查过」误读成「作业没在跑」。
+  const q = s.queried === false ? ' queried=否' : '';
+  console.log(`[launchd] status: plist=${s.exists ? '存在' : '不存在'} loaded=${s.loaded ? '是' : '否'}${q}${s.state ? ` state=${s.state}` : ''} path=${s.path}`);
   return 0;
 }