@tomflow/chatloop-tools 0.4.5 → 0.4.7

package/README.md

@@ -1,16 +1,37 @@
 # @tomflow/chatloop-tools — Chat Loop 工具包
 
-**v0.4.5 · npm 安装包 · Node.js >=20 · 当前验证平台 macOS**
+**v0.4.7 · Node.js >=20 · 当前验证平台 macOS；实际发布版本以 npm Registry 为准**
 
-本包是**本地 CLI + 统一 stdio MCP Gateway**：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前代理 **Desktop Commander 0.2.44** 原有 26 个工具，新增 **Chat Loop Extension** 四个专用 Action CLI 工具（总计 30 个 MCP 工具），Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel、tunnel-client 或 Chrome 扩展，也不会替用户安装这些组件。
+本包是**本地 CLI + 统一 stdio MCP Gateway**（以下 API 合同适用于 v0.4.7，低版本以各自安装版说明为准）：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前代理 **Desktop Commander 0.2.44** 原有 26 个工具，新增 **Chat Loop Extension** 四个专用 Action CLI 工具（总计 30 个 MCP 工具），Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel 或 Chrome 扩展；但 v0.4.6 **随 npm 自动安装一份 Chat Loop 私有的对应平台 tunnel-client 二进制依赖**，不会使用 Local Dev/Homebrew 上的程序，也不包含任何用户凭据。
 
  > **给人类和 AI 的 API 合同**：此 README 随 npm 包分发，可独立阅读；对外的稳定使用入口是 `chatloop-tools` CLI（兼容别名 `chat-loop-local`）和 `chatloop-tools mcp` 提供的 MCP 协议。**无承诺的 JavaScript import/exports API**，不要依赖 `lib/` 内部模块。研发架构文档在仓库 `docs/17-local-tools-multi-tool-plan.md`，不随 npm 包发行。
 
+## Chat Loop 专属 tunnel-client：打包内置，不依赖 Local Dev
+
+v0.4.7 延续 v0.4.6 的独立 npm 平台二进制依赖分发 OpenAI 官方 [tunnel-client v0.0.19](https://github.com/openai/tunnel-client/releases/tag/v0.0.19) 的 macOS Intel(x64)/Apple Silicon(arm64) **完整发行二进制与 cloudflared 同伴程序**分别封装在同一 `@tomflow` scope 的 `@tomflow/chatloop-tunnel-darwin-{x64,arm64}@0.0.19` 平台子包，主包用 `optionalDependencies` 由 npm **自动只安装匹配当前 OS/CPU 的包**。这仍属于 Chat Loop Tools 的内部依赖，不安装到 PATH、Homebrew 或 Local Dev。两份官方 ZIP 均按上游 SHA256SUMS 验证；将许可证、NOTICE、第三方许可证、SPDX 和二进制 SHA256 溯源一并保留。启动只调用本包自身的绝对路径，不搜索 PATH、不依赖本机 Homebrew 或 Local Dev。
+
+**版本注意**：`@latest` 始终取 npm Registry 当前最新版本；如 Registry 尚未提供 v0.4.7，下列生命周期命令只能在本仓源码或独立 v0.4.7 tarball 环境中使用。
+
+```bash
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel doctor
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel --version
+# 用户完成专属 Tunnel 的账号授权、配置后，由统一 Supervisor 启动：
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools start tunnel
+# 兼容入口（等价于 start tunnel，不再另开未托管前台进程）：
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel run
+```
+
+`tunnel doctor` 校验当前架构的 tunnel-client/cloudflared 哈希，报告 `BUNDLED_READY` 不代表连接已认证。**v0.4.7** 注册唯一组件 ID `tunnel`，由同一个 Supervisor 执行 `start|stop|restart|status tunnel`；无参命令统一涵盖已启用的 Desktop Commander 与 Tunnel。启动时只读产品自己的 `~/.chat-loop/tunnel/profiles/chat-loop.yaml`，缺少配置以 `PROFILE_NOT_FOUND` 失败而不启动。启动的真实二进制路径固定为本包对应平台依赖，唯一管理器持有子进程句柄；重复启动不复制进程，失去所有权时保留 `owner.json` 证据并安全拒绝接管、发信号。仅能停止本管理器直接持有的子进程，绝不按进程名查杀其他 Tunnel。
+
+Supervisor 自己创建的独立 Unix 健康 Socket `<state-dir>/tools/tunnel/health.sock` 通过 `/readyz` 判断**本地启动就绪**；结果 `after=RUNNING / evidence=LOCAL_READYZ / connection=UNVERIFIED` **不代表** OpenAI 云端请求成功。最后仍必须经 ChatGPT 真实 tools/call 验证。统一 Tunnel 子进程不继承外部的 `OPENAI_ADMIN_KEY` 或 `CONTROL_PLANE_API_KEY`：若自己的 profile 使用 `env:CONTROL_PLANE_API_KEY`，用户须明确在启动该 CLI 时提供产品独立的 `CHAT_LOOP_TUNNEL_CONTROL_PLANE_API_KEY`，由适配器专门映射；也可让产品自己的 profile 指向用户自有受保护的 `file:` 密钥引用。不要把凭据放在 CLI 参数、聊天或仓库里。
+
+**限制**：当前内置二进制仅适用 macOS Intel/Apple Silicon；其他操作系统明确失败而不回退系统 PATH。官方 macOS 发布二进制未签名；当前 Mac 可运行，Gatekeeper 单独检查拒绝，**其他用户机器的安装/公证/首次执行尚未验收**，不能宣称所有 macOS 用户零配置成功。
+
 ## 1. 可用范围与安全前提
 
 - **已经验证**：仓库内 CLI 生命周期、真实 Desktop Commander MCP 握手和只读调用、26 项工具发现、单工具故障隔离、Gateway 断线重连；全部在本机测试或隔离状态目录内完成。
 - **已验证（2026-11-05）**：v0.4.0 本地 tarball 在仓库外 macOS 临时目录用 npm 安装（`--ignore-scripts`），安装后的 `doctor/status/start/stop` 正常；MCP initialize、26 工具列表与 `read_file` 调用读回临时文件均通过。未改现有 Local Dev/Tunnel。
-- **未验证 / 不能宣称可正式上线**：用户自有 Tunnel → ChatGPT 完整联通、新版 2026 MCP 客户端、Windows/Linux、长任务取消、用户目录/命令授权边界、无 `--ignore-scripts` 的完整安装差异、npm/Plugin 公共发布。
+- **已验收历史与当前缺口要区分**：旧 v0.4.3 通过用户独立 Tunnel → ChatGPT 的 26 工具发现和真实只读 tools/call；正式 npm v0.4.5 已发布、npx latest 本地 MCP 30 工具发现通过，但**当前专用 Tunnel 因安全工具阻断重连，处于 STOPPED**，v0.4.5 的远端 tools/call **仍未验收**；但真实 macOS Chrome 0.3.29 + Native Host + 本地 MCP tools/call 的 Text/DOM/PNG/Reload **已通过**，并在 Reload 后正式 Audit 复核版本/Owner 未变化。Windows/Linux、新版 MCP 2026 协议、长任务取消、最小权限及公开 Chat Loop 产品 Plugin 发布也未验收。
 - **高风险权限**：Desktop Commander 在独立 `HOME` 下运行，但仍继承**当前操作系统用户的文件、进程与命令权限**；这不是文件系统沙箱。只在获用户明确授权的机器上运行，勿以管理员权限启动，勿向不可信客户端暴露；生产级目录白名单/命令审批**尚未实现**。
 
 ## 2. 安装及入口
@@ -45,7 +66,7 @@ npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools mcp
 cd packages/local-tools
 npm pack
 # 在仓库外一个全新的目录：
-npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
+npm install /absolute/path/to/tomflow-chatloop-tools-0.4.7.tgz
 ./node_modules/.bin/chat-loop-local doctor
 ./node_modules/.bin/chat-loop-local status
 ```
@@ -54,7 +75,7 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
 
 ## 3. CLI API
 
-语法：`chatloop-tools <command> [tool-id]`。正式工具 ID 目前只有 **`desktop-commander`**（不是 MCP 工具名）；可选参数最多一个。**不带工具 ID：对所有 enabled=true 模块操作**，但 `status` 无参数显示全部登记模块（包括 disabled）；**带 ID：只作用于该模块**。绝不把无效 ID 回退为全体操作。
+语法：`chatloop-tools <command> [tool-id]`。正式可管理组件 ID 是 **`desktop-commander`** 和 **`tunnel`**（都不是 MCP 工具名）；可选参数最多一个。**不带工具 ID：对所有 enabled=true 模块操作**，但 `status` 无参数显示全部登记模块（包括 disabled）；**带 ID：只作用于该模块**。绝不把无效 ID 回退为全体操作。
 
 | 命令 | 参数 | 语义与副作用 |
 | --- | --- | --- |
@@ -62,7 +83,7 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
 | `capabilities` | 无 | 返回当前命令能力与边界 |
 | `status` | 可选工具 ID | **只读**；不因查询而启动 Supervisor |
 | `start` | 可选工具 ID | 启动指定或全部启用工具，运行中返回 `ALREADY_RUNNING` |
-| `stop` | 可选工具 ID | 停止指定或全部启用工具，仅限本包拥有的进程；不停止 Tunnel/其他项目 |
+| `stop` | 可选组件 ID | 只停止本 Supervisor 实际拥有的组件；无参全体先停止 Tunnel，后停止 Desktop Commander；绝不影响 Local Dev |
 | `restart` | 可选工具 ID | 对指定或全部启用工具执行 stop → start；原本停止的也会启动 |
 | `mcp` | 无 | 在前台运行 **stdio MCP Server**，由 MCP 客户端持续连接；**不会自行 start 工具** |
 
@@ -171,9 +192,9 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
 | `CHAT_LOOP_LOCAL_TOOLS_STATE_DIR` | 覆盖本包状态目录，默认 `~/.chat-loop/local-tools`；测试建议使用新建私有临时目录 |
 | `CHAT_LOOP_LOCAL_TOOLS_FIXTURES=1` | **仅测试**：禁用 DC、启用 `mock-alpha`、`mock-beta` |
 | `CHAT_LOOP_LOCAL_TOOLS_FIXTURES=both` | **仅测试**：真实 DC + 两个模拟工具共同启用 |
-| 未设置测试开关 | Supervisor 默认只管理 `desktop-commander`；MCP 另外公布四个无需 Supervisor 启动的 Extension Action |
+| 未设置测试开关 | Supervisor 管理 `desktop-commander` 与 `tunnel`；MCP 另外公布四个无需 Supervisor 启动的 Extension Action |
 
-`<state-dir>/manager.lock`、`control.sock`、`events.jsonl` 是本包进程所有权/IPC/唯一事件日志；`tools/desktop-commander/home` 是与其他项目隔离的 DC 配置目录。**Supervisor** 按需存在，持有 Registry、进程与串行队列；**Gateway** 只转发 MCP，不自己管理子进程；**Adapter** 处理具体工具的生命周期/协议。
+`<state-dir>/manager.lock`、`control.sock`、`events.jsonl` 是本包进程所有权/IPC/唯一事件日志；`tools/desktop-commander/home` 是隔离的 DC 配置目录。Tunnel 另用 `tools/tunnel/owner.json` 保存崩溃后需要核实的所有权证据，以及私有 `health.sock` 只读健康探针；它们不是第二套权威日志。若孤儿标记仍在，即使旧管理器已死，也不得凭 PID 猜测、强制杀或自动启动第二实例。**Supervisor** 按需存在，持有 Registry、进程与串行队列；**Gateway** 只转发 MCP，不自己管理子进程；**Adapter** 处理具体工具的生命周期/协议。
 
 - CLI、Gateway 和 Supervisor 必须使用**相同的状态目录/测试开关**；不同版本或 Registry 签名会拒绝管理。不要随意删除未知 `manager.lock`，也不要使用 PID 或进程名批量杀掉其他项目的工具。
 - `stop` 仅管理本包拥有的子进程。关闭 Gateway 不会自动停止正在运行的 Desktop Commander；工具停止后仍可列出 API，但调用返回 `TOOL_UNAVAILABLE`。
@@ -190,7 +211,7 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
 
 ## 7. 本机验证与发布闸门
 
-在 Chat Loop 仓库根目录：
+在 Chat Loop 仓库根目录（根 `npm test` 限制测试文件并发为 2，避免共享资源负载使真实 Desktop Commander 生命周期超时；仍保留全部 184 个测试用例）：
 
 ```bash
 npm run check

package/bin/cli.mjs

@@ -8,6 +8,7 @@ import {fileURLToPath} from 'node:url';
 import {CONTRACT,ACTIONS,registry,ensurePrivateDir,paths,
   safeFallback,recoverStaleLock,exitCode,talk} from '../lib/control.mjs';
 import {runGateway} from '../lib/gateway.mjs';
+import {tunnelDoctor,runTunnel} from '../lib/tunnel.mjs';
 
 const require=createRequire(import.meta.url);
 const command=process.argv[2]??'doctor';
@@ -58,34 +59,34 @@ async function connectOrLaunch(request){
   }
   throw Object.assign(new Error('Supervisor did not become ready'),{code:last?.code||'MANAGER_UNAVAILABLE'});
 }
-async function runControl(){
-  const requestId=randomUUID(), target=extra[0]||null;
-  if(extra.length>1 || (extra.length===1 && !/^[a-z][a-z0-9-]*$/.test(target))){
-    const reply=fail('INVALID_ARGUMENT',command,target,requestId);emit(reply);process.exitCode=2;return;
+async function runControl(action=command, params=extra){
+  const requestId=randomUUID(), target=params[0]||null;
+  if(params.length>1 || (params.length===1 && !/^[a-z][a-z0-9-]*$/.test(target))){
+    const reply=fail('INVALID_ARGUMENT',action,target,requestId);emit(reply);process.exitCode=2;return;
   }
   const tool=target?registry().find(t=>t.id===target):null;
   if(target && !tool){const reply=fail('UNKNOWN_TOOL',command,target,requestId);emit(reply);process.exitCode=2;return;}
-  if(command!=='status' && tool && !tool.enabled){const reply=fail('DISABLED_TOOL',command,target,requestId);emit(reply);process.exitCode=2;return;}
-  if(command!=='status' && !target && !registry().some(t=>t.enabled)){
-    const reply=fail('NO_ENABLED_TOOLS',command,target,requestId);emit(reply);process.exitCode=5;return;
+  if(action!=='status' && tool && !tool.enabled){const reply=fail('DISABLED_TOOL',action,target,requestId);emit(reply);process.exitCode=2;return;}
+  if(action!=='status' && !target && !registry().some(t=>t.enabled)){
+    const reply=fail('NO_ENABLED_TOOLS',action,target,requestId);emit(reply);process.exitCode=5;return;
   }
-  const req={contract:CONTRACT,requestId,action:command,scope:target?'tool':'all',deadlineMs:12000};
+  const req={contract:CONTRACT,requestId,action,scope:target?'tool':'all',deadlineMs:12000};
   if(target)req.toolId=target;
   let reply;
   try{
-    if(command==='start'||command==='restart')reply=await connectOrLaunch(req);
+    if(action==='start'||action==='restart')reply=await connectOrLaunch(req);
     else{
       try{reply=await talk(req);}
       catch(err){
         if(!['ENOENT','ECONNREFUSED','TIMEOUT','UNKNOWN_RESULT'].includes(err.code))throw err;
-        reply=safeFallback(command,target,requestId);
+        reply=safeFallback(action,target,requestId);
       }
     }
   }catch(err){
     const known=['INCOMPATIBLE_VERSION','MANAGER_UNAVAILABLE',
       'INSECURE_STATE_DIR','TIMEOUT','UNKNOWN_RESULT'];
     reply=fail(known.includes(err.code)?err.code:'MANAGER_UNAVAILABLE',
-      command,target,requestId);
+      action,target,requestId);
   }
   emit(reply);process.exitCode=exitCode(reply);
 }
@@ -96,10 +97,27 @@ if(command==='mcp'){
 else if(command==='doctor'){
   if(extra.length){emit(fail('INVALID_ARGUMENT'));process.exitCode=2;}
   else{const snapshot=inspect();emit({contract:'chat-loop.local-tools.v1',command,...snapshot});if(snapshot.status!=='LOCAL_READY')process.exitCode=1;}
+ }else if(command==='tunnel'){
+  if(extra.length===1&&extra[0]==='doctor'){
+    const result=tunnelDoctor();
+    emit({contract:'chat-loop.local-tools.v1',command,...result});
+    if(result.status!=='BUNDLED_READY')process.exitCode=1;
+  }else if(extra.length===1&&extra[0]==='run'){
+    // Compatibility alias: all tunnel execution now belongs to the Supervisor.
+    await runControl('start',['tunnel']);
+  }else if(extra.length===1&&extra[0]==='--version'){
+    try{await runTunnel(['--version']);}
+    catch(e){emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',
+      code:e.code||'TUNNEL_EXEC_FAILED'});process.exitCode=1;}
+  }else{
+    emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',
+      code:'INVALID_ARGUMENT',usage:'tunnel doctor | tunnel --version | tunnel run (managed)'});
+    process.exitCode=2;
+  }
 }else if(command==='capabilities'){
   if(extra.length){emit(fail('INVALID_ARGUMENT'));process.exitCode=2;}
   else emit({contract:'chat-loop.local-tools.v1',command,status:'OK',
-    implemented:['capabilities','doctor','mcp','start','stop','restart','status'],
+    implemented:['capabilities','doctor','mcp','start','stop','restart','status','tunnel'],
     lifecycle:'SUPERVISOR_MCP_GATEWAY',mcpTools:'Namespaced tool catalog',
-    tunnel:'SEPARATE_USER_RESOURCE'});
+    tunnel:'BUNDLED_SUPERVISOR_MANAGED'});
 }else{emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',code:'UNKNOWN_COMMAND'});process.exitCode=1;}

package/lib/adapters/index.mjs

@@ -1,9 +1,11 @@
 import {createFixtureAdapter} from './fixture.mjs';
 import {createMcpChildAdapter} from './mcp-child.mjs';
+import {createTunnelAdapter} from './tunnel.mjs';
 
 const factories=new Map([
   ['fixture',createFixtureAdapter],
-  ['mcp-child',createMcpChildAdapter]
+  ['mcp-child',createMcpChildAdapter],
+  ['tunnel',createTunnelAdapter]
 ]);
 // Register future tool kinds here; Supervisor does not know concrete tools.
 export function createAdapter(kind,ctx){

package/lib/adapters/tunnel.mjs

@@ -0,0 +1,160 @@
+// One Chat Loop-owned tunnel-client child, never Local Dev or a system executable.
+import {spawn} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {existsSync,lstatSync,mkdirSync,readFileSync,unlinkSync,writeFileSync} from 'node:fs';
+import {request as httpRequest} from 'node:http';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+import {paths} from '../control.mjs';
+import {bundledTunnel} from '../tunnel.mjs';
+
+const err=code=>({code});
+const result=(t,before,after,outcome,error=null,pid=null,evidence=null,connection='UNVERIFIED')=>
+  ({toolId:t.id,enabled:t.enabled,before,after,outcome,pid,evidence,error,connection});
+const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+function probe(socketPath,ms=350){
+  return new Promise(resolve=>{
+    const req=httpRequest({socketPath,path:'/readyz',method:'GET',timeout:ms},res=>{
+      res.resume();res.once('end',()=>resolve(res.statusCode===200));
+    });
+    req.once('error',()=>resolve(false));
+    req.once('timeout',()=>{req.destroy();resolve(false);});
+    req.end();
+  });
+}
+function safeUnlink(file){
+  try{unlinkSync(file);}catch(e){if(e.code!=='ENOENT')throw e;}
+}
+export function createTunnelAdapter({records,log},options={}){
+  const locate=options.locate||bundledTunnel;
+  const spawnChild=options.spawnChild||spawn;
+  const profileDir=options.profileDir||join(homedir(),'.chat-loop','tunnel','profiles');
+  const profile=join(profileDir,'chat-loop.yaml');
+  const dir=join(paths().dir,'tools','tunnel');
+  const marker=join(dir,'owner.json');
+  const socket=join(dir,'health.sock');
+  function isMarked(){
+    try{lstatSync(marker);return true;}
+    catch(e){if(e.code==='ENOENT')return false;throw e;}
+  }
+  function forget(rec){
+    let owned=false;
+    try{owned=JSON.parse(readFileSync(marker,'utf8')).nonce===rec.nonce;}
+    catch{}
+    // If owner evidence changed, never touch a socket potentially owned by another manager.
+    if(!owned)return;
+    try{
+      if(existsSync(socket)){
+        const stat=lstatSync(socket);
+        if(stat.isSocket()&&(!process.getuid||stat.uid===process.getuid()))safeUnlink(socket);
+      }
+    }catch{}
+    try{safeUnlink(marker);}catch{}
+  }
+  function validProfile(){
+    try{
+      const s=lstatSync(profile);
+      return s.isFile()&&!s.isSymbolicLink()&&(!process.getuid||s.uid===process.getuid());
+    }catch{return false;}
+  }
+  async function inspect(t){
+    const rec=records.get(t.id);
+    if(!rec){
+      if(isMarked())return result(t,'UNKNOWN','UNKNOWN','OBSERVED',err('OWNERSHIP_UNCERTAIN'),null,'ORPHAN_MARKER');
+      return result(t,'STOPPED','STOPPED','OBSERVED',null,null,'NO_OWNED_PROCESS');
+    }
+    if(rec.exited)return result(t,rec.state,rec.state,'OBSERVED',
+      rec.state==='FAILED'?err(rec.authRequired?'AUTH_REQUIRED':'CHILD_EXIT'):null,null,'CHILD_EXIT');
+    if(rec.state==='STOPPING'||rec.stopSignaled)
+      return result(t,rec.state,'UNKNOWN','OBSERVED',err('UNKNOWN_RESULT'),rec.pid,'STOP_UNCONFIRMED');
+    const before=rec.state,ready=await probe(socket);
+    if(!ready){rec.state='UNKNOWN';return result(t,before,'UNKNOWN','OBSERVED',err('READINESS_LOST'),rec.pid,'READYZ_NOT_200');}
+    rec.state='RUNNING';
+    return result(t,before,'RUNNING','OBSERVED',null,rec.pid,'LOCAL_READYZ');
+  }
+  async function launch(t,ctx){
+    const old=records.get(t.id),before=old?.state||'STOPPED';
+    if(old&&!old.exited){
+      const state=await inspect(t);
+      return state.after==='RUNNING'?result(t,before,'RUNNING','ALREADY_RUNNING',null,old.pid,'LOCAL_READYZ'):
+        result(t,before,'UNKNOWN','IDENTITY_UNCERTAIN',state.error||err('UNKNOWN_RESULT'),old.pid,state.evidence);
+    }
+    if(isMarked())return result(t,before,'UNKNOWN','OWNERSHIP_UNCERTAIN',err('OWNERSHIP_UNCERTAIN'),null,'ORPHAN_MARKER');
+    if(!validProfile())return result(t,before,'FAILED','START_FAILED',err('PROFILE_NOT_FOUND'),null,'NO_PROCESS_STARTED');
+    if(ctx.remaining()<500)return result(t,before,before,'DEADLINE_EXPIRED',err('TIMEOUT'),null,'NO_PROCESS_STARTED');
+    let binary;
+    try{binary=locate().binary;}
+    catch(e){return result(t,before,'FAILED','START_FAILED',err(e.code||'INVALID_BUNDLE'));}
+    mkdirSync(dir,{recursive:true,mode:0o700});
+    const ds=lstatSync(dir);
+    if(!ds.isDirectory()||ds.isSymbolicLink()||(ds.mode&0o077)||
+      (process.getuid&&ds.uid!==process.getuid()))
+      return result(t,before,'UNKNOWN','START_FAILED',err('INSECURE_STATE_DIR'));
+    if(existsSync(socket))return result(t,before,'UNKNOWN','OWNERSHIP_UNCERTAIN',err('OWNERSHIP_UNCERTAIN'),null,'STALE_HEALTH_SOCKET');
+    const nonce=randomUUID();
+    try{writeFileSync(marker,JSON.stringify({nonce,created:Date.now(),binary}),{flag:'wx',mode:0o600});}
+    catch{return result(t,before,'UNKNOWN','OWNERSHIP_UNCERTAIN',err('OWNERSHIP_UNCERTAIN'));}
+    // Never inherit Local Dev's CONTROL_PLANE_API_KEY or OPENAI_ADMIN_KEY.
+    const env={HOME:homedir(),PATH:process.env.PATH||'/usr/bin:/bin',
+      USER:process.env.USER||'',LANG:process.env.LANG||'en_US.UTF-8',
+      TMPDIR:process.env.TMPDIR||'/tmp'};
+    if(process.env.CHAT_LOOP_TUNNEL_CONTROL_PLANE_API_KEY)
+      env.CONTROL_PLANE_API_KEY=process.env.CHAT_LOOP_TUNNEL_CONTROL_PLANE_API_KEY;
+    let child;
+    try{child=spawnChild(binary,['run','--profile-dir',profileDir,'--profile','chat-loop',
+      '--health.unix-socket',socket],{env,stdio:['ignore','pipe','pipe'],windowsHide:true});}
+    catch(e){safeUnlink(marker);return result(t,before,'FAILED','START_FAILED',err(e.code||'SPAWN_FAILED'));}
+    const rec={child,pid:child.pid||null,nonce,exited:false,state:'STARTING'};
+    records.set(t.id,rec);
+    child.stdout?.on('data',data=>log('tunnel-output',{toolId:t.id,bytes:data.length}));
+    child.stderr?.on('data',data=>{
+      // Recognize missing authorization without storing credentials or raw stderr.
+      if(/CONTROL_PLANE_API_KEY|OPENAI_ADMIN_KEY|missing (?:the )?(?:api|runtime) key/i.test(data.toString()))
+        rec.authRequired=true;
+      log('tunnel-stderr',{toolId:t.id,bytes:data.length});
+    });
+    child.once('error',e=>log('tunnel-error',{toolId:t.id,code:e.code||'ERROR'}));
+    function onExit(code,signal){
+      if(rec.exited)return;
+      rec.exited=true;rec.state=rec.state==='STOPPING'?'STOPPED':'FAILED';
+      forget(rec);log('tunnel-exit',{toolId:t.id,pid:rec.pid,code,signal});
+    }
+    child.once('exit',onExit);
+    // spawn ENOENT emits error then close, potentially without an exit event.
+    child.once('close',(code,signal)=>onExit(code,signal));
+    const until=Date.now()+Math.min(8000,Math.max(0,ctx.remaining()-250));
+    while(Date.now()<until&&!rec.exited){
+      if(await probe(socket,250)){
+        rec.state='RUNNING';log('tool-start',{requestId:ctx.requestId,toolId:t.id,pid:rec.pid});
+        return result(t,before,'RUNNING','STARTED',null,rec.pid,'LOCAL_READYZ');
+      }
+      await pause(100);
+    }
+    if(rec.exited)return result(t,before,'FAILED','START_FAILED',err(rec.authRequired?'AUTH_REQUIRED':'CHILD_EXIT'),null,'CHILD_EXIT');
+    rec.state='UNKNOWN';
+    return result(t,before,'UNKNOWN','START_UNVERIFIED',err('UNKNOWN_RESULT'),rec.pid,'READYZ_NOT_200');
+  }
+  async function stop(t,ctx){
+    const rec=records.get(t.id),before=rec?.state||'STOPPED';
+    if(!rec||rec.exited){
+      if(isMarked())return result(t,before,'UNKNOWN','OWNERSHIP_UNCERTAIN',err('OWNERSHIP_UNCERTAIN'),null,'ORPHAN_MARKER');
+      return result(t,before,'STOPPED','ALREADY_STOPPED',null,null,'NO_LIVE_OWNED_CHILD');
+    }
+    if(ctx.remaining()<100)return result(t,before,before,'DEADLINE_EXPIRED',err('TIMEOUT'),rec.pid,'NO_SIGNAL_SENT');
+    rec.state='STOPPING';rec.stopSignaled=true;
+    if(!rec.child.kill('SIGTERM')){
+      rec.state='UNKNOWN';return result(t,before,'UNKNOWN','STOP_FAILED',err('UNKNOWN_RESULT'),rec.pid,'SIGNAL_UNCONFIRMED');
+    }
+    const exited=await new Promise(resolve=>{
+      if(rec.exited)return resolve(true);
+      const timer=setTimeout(()=>resolve(false),Math.min(2200,Math.max(1,ctx.remaining())));
+      rec.child.once('exit',()=>{clearTimeout(timer);resolve(true);});
+    });
+    if(!exited){
+      rec.state='UNKNOWN';return result(t,before,'UNKNOWN','STOP_TIMEOUT',err('UNKNOWN_RESULT'),rec.pid,'NO_EXIT_CONFIRMATION');
+    }
+    log('tool-stop',{requestId:ctx.requestId,toolId:t.id,pid:rec.pid});
+    return result(t,before,'STOPPED','STOPPED',null,null,'EXIT_CONFIRMED');
+  }
+  return {launch,stop,inspect};
+}

package/lib/control.mjs

@@ -4,12 +4,15 @@ import {homedir} from 'node:os';
 import {join} from 'node:path';
 
 export const CONTRACT = 'chat-loop.local-control.v1';
-export const VERSION = '0.4.5';
+export const VERSION = '0.4.7';
 export const ACTIONS = new Set(['start','stop','restart','status']);
 export const directory = () => process.env.CHAT_LOOP_LOCAL_TOOLS_STATE_DIR || join(homedir(), '.chat-loop', 'local-tools');
 export const paths = () => ({dir: directory(), socket: join(directory(), 'control.sock'), lock: join(directory(), 'manager.lock'), log: join(directory(), 'events.jsonl')});
 export function registry() {
   const tools = [{id: 'desktop-commander', enabled: process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES !== '1', kind: 'mcp-child'}];
+  if (!['1','both'].includes(process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES)) {
+    tools.push({id:'tunnel',enabled:true,kind:'tunnel'});
+  }
   if (['1','both'].includes(process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES)) {
     tools.push({id: 'mock-alpha', enabled: true, kind: 'fixture'});
     tools.push({id: 'mock-beta', enabled: true, kind: 'fixture'});
@@ -38,14 +41,22 @@ export function verifyOwner(hello) {
     throw Object.assign(new Error('Manager lock and IPC mismatch'),{code:'MANAGER_UNAVAILABLE'});
 }
 export function safeFallback(action, target, requestId) {
-  const found = registry().filter(t => target ? t.id === target : action === 'status' || t.enabled);
-  const unsure = lockPresent();
-  const results = found.map(t => ({toolId:t.id, enabled:t.enabled, before:t.enabled ? (unsure ? 'UNKNOWN' : 'STOPPED') : 'DISABLED',
-    after:t.enabled ? (unsure ? 'UNKNOWN' : 'STOPPED') : 'DISABLED',
-    outcome:unsure && t.enabled ? 'MANAGER_UNAVAILABLE' : action === 'stop' ? 'ALREADY_STOPPED' : 'OBSERVED',
-    pid:null, evidence:unsure ? 'STALE_MANAGER_LOCK' : 'NO_MANAGER_LOCK', error:unsure && t.enabled ? {code:'UNKNOWN_RESULT'} : null}));
-  return {contract:CONTRACT,requestId,action,scope:target?'tool':'all',target:target || null,
-    status:unsure ? 'UNKNOWN':'OK',results};
+  const found=registry().filter(t=>target?t.id===target:action==='status'||t.enabled);
+  const locked=lockPresent();
+  const orphan=()=>{
+    try{lstatSync(join(paths().dir,'tools','tunnel','owner.json'));return true;}
+    catch(e){return e.code!=='ENOENT';}
+  };
+  const results=found.map(t=>{
+    const uncertain=locked||(t.id==='tunnel'&&orphan());
+    return {toolId:t.id,enabled:t.enabled,before:t.enabled?(uncertain?'UNKNOWN':'STOPPED'):'DISABLED',
+      after:t.enabled?(uncertain?'UNKNOWN':'STOPPED'):'DISABLED',
+      outcome:uncertain&&t.enabled?'MANAGER_UNAVAILABLE':action==='stop'?'ALREADY_STOPPED':'OBSERVED',
+      pid:null,evidence:locked?'STALE_MANAGER_LOCK':uncertain?'ORPHAN_MARKER':'NO_MANAGER_LOCK',
+      error:uncertain&&t.enabled?{code:'UNKNOWN_RESULT'}:null};
+  });
+  return {contract:CONTRACT,requestId,action,scope:target?'tool':'all',target:target||null,
+    status:results.some(r=>r.after==='UNKNOWN')?'UNKNOWN':'OK',results};
 }
 export function send(request, timeout=3000) {
   return new Promise((resolve,reject)=>{

package/lib/gateway.mjs

@@ -46,7 +46,7 @@ export function runGateway(){
         return reject(m.id,-32602,'UNSUPPORTED_MCP_VERSION');
       connected=true;
       return reply(m.id,{protocolVersion:m.params.protocolVersion,
-        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:'0.4.5'}});
+        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:'0.4.7'}});
     }
     // A modern MCP client probes discovery before falling back to legacy initialize.
     // We only implement the legacy handshake era, so report unsupported method.

package/lib/supervisor.mjs

@@ -84,7 +84,9 @@ async function execute(req){
   const promise=(async()=>{
     const results=[];
     // Batch targets run in Registry order; each tool is separately serialized.
-    for(const t of found){
+    // Stop incoming Tunnel requests before stopping the MCP child.
+    const ordered=req.action==='stop'&&req.scope==='all'?[...found].reverse():found;
+    for(const t of ordered){
       const item=await serial(t.id,async()=>{
         if(req.action==='status'){
           if(!t.enabled)return {toolId:t.id,enabled:false,before:'DISABLED',after:'DISABLED',
@@ -97,7 +99,9 @@ async function execute(req){
         if(ended.error)return {...ended,outcome:'RESTART_FAILED'};
         const began=await adapterFor(t).launch(t,ctx);
         return {...began,before:ended.before,outcome:began.error?'RESTART_FAILED':'RESTARTED'};
-      });
+      }).catch(e=>({toolId:t.id,enabled:t.enabled,before:'UNKNOWN',after:'UNKNOWN',
+        outcome:'ADAPTER_FAILED',pid:null,evidence:'UNHANDLED_ADAPTER_ERROR',
+        error:error(e.code||'UNKNOWN_RESULT')}));
       results.push(item);
     }
     const failures=results.filter(r=>r.error);
@@ -155,8 +159,10 @@ async function main(){
   chmodSync(p.socket,0o600);
   log('manager-start',{pid:process.pid,version:VERSION});
   process.on('SIGTERM',async()=>{
-    for(const t of catalog.filter(t=>t.enabled))
-      await serial(t.id,()=>adapterFor(t).stop(t,{requestId:'manager-shutdown',remaining:()=>5000}));
+    for(const t of catalog.filter(t=>t.enabled).reverse()){
+      try{await serial(t.id,()=>adapterFor(t).stop(t,{requestId:'manager-shutdown',remaining:()=>5000}));}
+      catch(e){log('shutdown-stop-error',{toolId:t.id,code:e.code||'UNKNOWN_RESULT'});}
+    }
     await shutdown();
   });
 }

package/lib/tunnel.mjs

@@ -0,0 +1,71 @@
+// Bundled OpenAI tunnel-client: never resolve from PATH, Homebrew or Local Dev.
+import {createHash} from 'node:crypto';
+import {createRequire} from 'node:module';
+import {spawn} from 'node:child_process';
+import {readFileSync,statSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join,dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+const require=createRequire(import.meta.url);
+
+const supported=new Set(['darwin-x64','darwin-arm64']);
+export function bundledTunnel(){
+  const platform=process.platform+'-'+process.arch;
+  if(!supported.has(platform))throw Object.assign(Error('Bundled tunnel-client is not available on '+platform),
+    {code:'UNSUPPORTED_PLATFORM'});
+  const platformPackage='@tomflow/chatloop-tunnel-'+platform;
+  let base;
+  try{base=join(dirname(require.resolve(platformPackage+'/package.json')),'bin');}
+  catch{
+    // Repo-only test fallback. No sibling workspace in a published npm consumer.
+    base=fileURLToPath(new URL('../../tunnel-client-'+platform+'/bin/',import.meta.url));
+  }
+  const info=JSON.parse(readFileSync(join(base,'provenance.json'),'utf8'));
+  const binary=join(base,'tunnel-client');
+  const st=statSync(binary);
+  if(!st.isFile()||!(st.mode&0o111))
+    throw Object.assign(Error('Bundled executable missing'),{code:'INVALID_BUNDLE'});
+  const checksum=createHash('sha256').update(readFileSync(binary)).digest('hex');
+  if(checksum!==info.tunnelClientSha256)
+    throw Object.assign(Error('Bundled executable checksum mismatch'),{code:'INVALID_BUNDLE'});
+  const cloudflared=join(base,'cloudflared');
+  const cs=statSync(cloudflared);
+  const cloudHash=createHash('sha256').update(readFileSync(cloudflared)).digest('hex');
+  if(!cs.isFile()||!(cs.mode&0o111)||cloudHash!==info.cloudflaredSha256)
+    throw Object.assign(Error('Bundled cloudflared checksum mismatch'),{code:'INVALID_BUNDLE'});
+  return {binary,cloudflared,release:info.release,platform,checksum,base};
+}
+export function tunnelDoctor(){
+  try{
+    const b=bundledTunnel();
+    const cloudflared=createHash('sha256').update(readFileSync(b.cloudflared)).digest('hex');
+    const info=JSON.parse(readFileSync(join(b.base,'provenance.json'),'utf8'));
+    if(cloudflared!==info.cloudflaredSha256)
+      throw Object.assign(Error('Bundled cloudflared checksum mismatch'),{code:'INVALID_BUNDLE'});
+    return {status:'BUNDLED_READY',release:b.release,platform:b.platform,
+      executable:b.binary,cloudflared:b.cloudflared,verified:true,connection:'UNVERIFIED'};
+  }catch(e){return {status:'BLOCKED',code:e.code||'INVALID_BUNDLE',reason:e.message};}
+}
+// Explicitly scoped to this product. Do not touch a sibling Local Dev profile.
+export async function runTunnel(args){
+  const b=bundledTunnel();
+  if(args[0]==='run'){
+    const hasProfileDir=args.some(x=>x==='--profile-dir'||x.startsWith('--profile-dir='));
+    const hasProfile=args.some(x=>x==='--profile'||x.startsWith('--profile='));
+    if(!hasProfileDir)args=[...args,'--profile-dir',join(homedir(),'.chat-loop','tunnel','profiles')];
+    if(!hasProfile)args=[...args,'--profile','chat-loop'];
+  }
+  await new Promise((resolve,reject)=>{
+    const child=spawn(b.binary,args,{stdio:'inherit',env:process.env,windowsHide:true,
+      cwd:b.base}); // Only this package's verified binary. Never use the system PATH.
+    child.once('error',reject);
+    const forward=signal=>child.kill(signal);
+    process.on('SIGINT',forward);process.on('SIGTERM',forward);
+    child.once('exit',(code,signal)=>{
+      process.off('SIGINT',forward);process.off('SIGTERM',forward);
+      if(signal){process.exitCode=1;return resolve();}
+      process.exitCode=code===null?1:code;
+      resolve();
+    });
+  });
+}

package/package.json

@@ -3,9 +3,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
-  "description": "Chat Loop local tools: MCP gateway and unified tool lifecycle CLI",
+  "description": "Chat Loop local tools: MCP gateway, isolated bundled tunnel-client and unified CLI",
   "bin": {
     "chatloop-tools": "bin/cli.mjs",
     "chat-loop-local": "bin/cli.mjs"
@@ -25,5 +25,9 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "optionalDependencies": {
+    "@tomflow/chatloop-tunnel-darwin-x64": "0.0.19",
+    "@tomflow/chatloop-tunnel-darwin-arm64": "0.0.19"
   }
 }