diff --git a/plugins/zcode-advisor/tools/companion/launchd.cjs b/plugins/zcode-advisor/tools/companion/launchd.cjs
index e832741..0be261d 100644
--- a/plugins/zcode-advisor/tools/companion/launchd.cjs
+++ b/plugins/zcode-advisor/tools/companion/launchd.cjs
@@ -111,10 +111,75 @@ 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' });
 }
 
+// 用户真实自启作业的 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 域）。
+//
+// realpathSync 可能因目录在两次调用之间被删而抛（TOCTOU）。这里不回退重试而是直接
+// 落到 path.resolve：**兜底方向是安全的**——沙箱目录消失时判定结果仍是「不是真实作业」，
+// 于是不碰 launchd 域（宁可不操作，也不能误打用户真实作业）。反之若真实目录消失，
+// 两条路径都退化成 path.resolve，仍然相等，卸载照常生效。
+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 不是这一份，任何
+// `launchctl print/bootout gui/<uid>/<LABEL>` 都打在用户**真实**的自启作业上：
+//   - bootout 会终止真实作业的进程并把它从 launchd 卸载。KeepAlive 监督随作业
+//     一起消失 → 进程被杀且**永远不会自动重启**，直到用户重开一次 App
+//     （真机故障：在本机跑一次 `npm test`，外挂就被打死，表现为「动不动就连不上
+//     controller」，而 CI 跑在 Linux 上、launchctl 不存在，ENOENT 被 catch 吞掉，
+//     所以结构性看不见）。
+//   - print 会把真实作业的运行态误报成沙箱的态（装了 agent 的开发机上，
+//     「已写入但未加载」这条断言必然变红）。
+// 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
+// 重定向的情形都能被正确识别。
+// 显式判断 platform/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 +206,24 @@ function isLoaded(label) {
 // 幂等加载：已加载且 plist 未变 → 什么都不做（**不能无条件 bootout+bootstrap**，
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
+//
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 canTouchLaunchd）：
+// 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
+//
+// 返回契约（三种形状，靠 skipped / warn 区分「跳过」与「失败」）：
+//   { 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，跳过加载' };
+  if (uid() === null) return { loaded: false, skipped: true, 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 {
@@ -155,6 +235,13 @@ 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=true 时 warn 说明跳过的原因（两者会同时出现）；loaded=true 时才代表真的
+// 交给了 launchd。调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath
@@ -182,43 +269,65 @@ 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：否则会打掉用户真实的自启作业
+  // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // 返回 { ok, path, removed, bootedOut, skipped }：skipped=true 表示**没去碰** launchd
+  // 域（沙箱/非 darwin/无 uid），此时 bootedOut 恒为 false，且与「bootout 试过但作业
+  // 本就没加载」区分开。
   let bootedOut = false;
-  if (uid() !== null) {
+  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);
   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) {
@@ -231,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/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..293da01 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,138 @@ 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());
+}
+
+// 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 仍应正常落盘');
+});
+
+// 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 是否存在。
+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);
+});
+
+// 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) {
+  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' });
@@ -188,6 +325,40 @@ 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.strictEqual(probe.r.skipped, true,
+    'skipped=true 表示「没去碰」launchd 域，与「碰了但作业未加载」可区分');
+  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 +372,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..0be261d 100644
--- a/tools/companion/launchd.cjs
+++ b/tools/companion/launchd.cjs
@@ -111,10 +111,75 @@ 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' });
 }
 
+// 用户真实自启作业的 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 域）。
+//
+// realpathSync 可能因目录在两次调用之间被删而抛（TOCTOU）。这里不回退重试而是直接
+// 落到 path.resolve：**兜底方向是安全的**——沙箱目录消失时判定结果仍是「不是真实作业」，
+// 于是不碰 launchd 域（宁可不操作，也不能误打用户真实作业）。反之若真实目录消失，
+// 两条路径都退化成 path.resolve，仍然相等，卸载照常生效。
+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 不是这一份，任何
+// `launchctl print/bootout gui/<uid>/<LABEL>` 都打在用户**真实**的自启作业上：
+//   - bootout 会终止真实作业的进程并把它从 launchd 卸载。KeepAlive 监督随作业
+//     一起消失 → 进程被杀且**永远不会自动重启**，直到用户重开一次 App
+//     （真机故障：在本机跑一次 `npm test`，外挂就被打死，表现为「动不动就连不上
+//     controller」，而 CI 跑在 Linux 上、launchctl 不存在，ENOENT 被 catch 吞掉，
+//     所以结构性看不见）。
+//   - print 会把真实作业的运行态误报成沙箱的态（装了 agent 的开发机上，
+//     「已写入但未加载」这条断言必然变红）。
+// 用路径判定而不是「有没有传 dir」：这样显式把 dir 指向真实目录、或经环境变量
+// 重定向的情形都能被正确识别。
+// 显式判断 platform/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 +206,24 @@ function isLoaded(label) {
 // 幂等加载：已加载且 plist 未变 → 什么都不做（**不能无条件 bootout+bootstrap**，
 // 那会把正在跑的实例杀掉再拉起，用户每次点图标都会闪断一次）。
 // plist 变了 → 必须重载，否则 launchd 仍按旧配置跑（升级后不生效）。
+//
+// 注意 plistFile 指向沙箱时**绝不能**走 launchd 域（见 canTouchLaunchd）：
+// 那里的 bootout 打的是真实 LABEL，会把用户真实的 agent 打死并卸载。
+//
+// 返回契约（三种形状，靠 skipped / warn 区分「跳过」与「失败」）：
+//   { 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，跳过加载' };
+  if (uid() === null) return { loaded: false, skipped: true, 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 {
@@ -155,6 +235,13 @@ 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=true 时 warn 说明跳过的原因（两者会同时出现）；loaded=true 时才代表真的
+// 交给了 launchd。调用方据此决定是否自行拉起进程。
 function install(opts) {
   const o = opts || {};
   const rt = o.nodeBin && o.controllerPath
@@ -182,43 +269,65 @@ 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：否则会打掉用户真实的自启作业
+  // （见 canTouchLaunchd）。重定向调用方（测试）只清理自己沙箱里的 plist 文件。
+  // 返回 { ok, path, removed, bootedOut, skipped }：skipped=true 表示**没去碰** launchd
+  // 域（沙箱/非 darwin/无 uid），此时 bootedOut 恒为 false，且与「bootout 试过但作业
+  // 本就没加载」区分开。
   let bootedOut = false;
-  if (uid() !== null) {
+  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);
   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) {
@@ -231,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;
 }