@tomflow/chatloop-tools 0.4.12 → 0.4.14

package/README.md

@@ -8,7 +8,7 @@ npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools --help
 
 ```text
 Usage: chatloop-tools <command> [target]
-Commands: doctor, mcp, start, stop, restart, status, tunnel, capabilities
+Commands: doctor, mcp, start, stop, restart, status, upgrade, tunnel, capabilities
 Run: chatloop-tools <command> --help
 ```
 
@@ -22,3 +22,12 @@ Start all enabled tools or one.
 ```
 
 Extension Actions 委托 `@tomflow/chatloop-extension` 公共 CLI，不复制浏览器操作。具体安全边界和协议见 [Local Tools 产品文档](../../docs/local-tools.md)，实际部署与已验证状态见 [CURRENT](../../context/CURRENT.md)。
+
+
+正式运行环境的版本切换命令：
+
+```sh
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools upgrade
+```
+
+升级先独立安装新版本、核实 Supervisor 所有权与运行状态，再通过原 Supervisor 停止旧版、将 Tunnel MCP 启动命令固定到新版本并启动；不在 Tunnel 正处理 MCP 调用时直接自我重启。若返回 `BLOCKED`，先核对原任务回执，不要盲重试。`start` 全量入口在正常用户安装环境检测到版本差异时复用此流程；带隔离状态目录的测试不触发升级。详情见 [Local Tools 主文档](../../docs/local-tools.md)。

package/bin/cli.mjs

@@ -10,15 +10,17 @@ import {CONTRACT,ACTIONS,registry,ensurePrivateDir,paths,
 import {runGateway} from '../lib/gateway.mjs';
 import {tunnelDoctor,runTunnel} from '../lib/tunnel.mjs';
 import {promptTunnelRuntimeKey,storeTunnelRuntimeKey} from '../lib/tunnel-auth.mjs';
+import {upgradeRuntime,runtimeNeedsUpgrade} from '../lib/release.mjs';
 
 const HELP={
-  '': 'Usage: chatloop-tools <command> [target]\nCommands: doctor, mcp, start, stop, restart, status, tunnel, capabilities\nRun: chatloop-tools <command> --help',
+  '': 'Usage: chatloop-tools <command> [target]\nCommands: doctor, mcp, start, stop, restart, status, upgrade, tunnel, capabilities\nRun: chatloop-tools <command> --help',
   doctor:'Usage: chatloop-tools doctor\nInspect local readiness without changing services.',
   mcp:'Usage: chatloop-tools mcp\nServe namespaced MCP tools over stdio.',
   start:'Usage: chatloop-tools start [desktop-commander|tunnel]\nStart all enabled tools or one.',
   stop:'Usage: chatloop-tools stop [desktop-commander|tunnel]\nStop all enabled tools or one.',
   restart:'Usage: chatloop-tools restart [desktop-commander|tunnel]\nRestart all or one.',
   status:'Usage: chatloop-tools status [desktop-commander|tunnel]\nRead runtime state.',
+  upgrade:'Usage: chatloop-tools upgrade\nStage an immutable release; verify owner, then switch the owned runtime and Tunnel together.',
   tunnel:'Usage: chatloop-tools tunnel <doctor|auth|--version|run>\nTunnel runs under Supervisor; auth requires explicit setup.',
   capabilities:'Usage: chatloop-tools capabilities\nList supported tool categories.'
 };
@@ -116,6 +118,15 @@ async function runControl(action=command, params=extra){
 if(command==='mcp'){
   if(extra.length){process.stderr.write(JSON.stringify(fail('INVALID_ARGUMENT'))+'\n');process.exitCode=2;}
   else runGateway();
+}else if(command==='upgrade'){
+  const result=await upgradeRuntime({args:extra});
+  emit(result);if(result.status!=='OK')process.exitCode=result.status==='STARTING'?4:5;
+}else if(command==='start'&&extra.length===0&&
+  !process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES&&
+  !process.env.CHAT_LOOP_LOCAL_TOOLS_STATE_DIR&&
+  process.env.CHAT_LOOP_SKIP_UPGRADE!=='1'&&runtimeNeedsUpgrade()){
+  emit({command:'start',status:'BLOCKED',code:'VERSION_MISMATCH_USE_UPGRADE'});
+  process.exitCode=5;
 }else if(ACTIONS.has(command))await runControl();
 else if(command==='doctor'){
   if(extra.length){emit(fail('INVALID_ARGUMENT'));process.exitCode=2;}
@@ -150,7 +161,7 @@ else if(command==='doctor'){
 }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','tunnel'],
+    implemented:['capabilities','doctor','mcp','start','stop','restart','status','upgrade','tunnel'],
     lifecycle:'SUPERVISOR_MCP_GATEWAY',mcpTools:'Namespaced tool catalog',
     tunnel:'BUNDLED_SUPERVISOR_MANAGED'});
 }else{emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',code:'UNKNOWN_COMMAND'});process.exitCode=1;}

package/lib/adapters/mcp-child.mjs

@@ -3,7 +3,7 @@ import {createRequire} from 'node:module';
 import {dirname,join} from 'node:path';
 import {mkdirSync,readFileSync} from 'node:fs';
 import {randomUUID} from 'node:crypto';
-import {paths} from '../control.mjs';
+import {paths,toolCallDeadlineMs} from '../control.mjs';
 
 const require=createRequire(import.meta.url);
 const catalog=JSON.parse(readFileSync(new URL('../desktop-commander-tools.json',import.meta.url),'utf8'));
@@ -11,34 +11,53 @@ const fingerprint=tools=>JSON.stringify(tools.map(({name,inputSchema})=>({name,i
 const expected=fingerprint(catalog);
 const err=code=>({code});
 const result=(tool,before,after,outcome,error=null,pid=null,evidence=null)=>({toolId:tool.id,enabled:tool.enabled,before,after,outcome,pid,evidence,error});
-// Cold Desktop Commander initialization can exceed 9s on a busy macOS host.
-// Startup has its own budget; ordinary tool calls keep the stricter deadline.
-const timeout=ctx=>Math.max(0,Math.min(ctx.remaining(),9000));
-export const startupHandshakeBudget=ctx=>Math.max(0,Math.min(ctx.remaining(),24000));
+// Deadlines bound an individual caller's wait, not a child process' lifetime.
+const timeout=ctx=>Math.max(0,ctx.remaining());
+export const startupHandshakeBudget=ctx=>Math.max(0,ctx.remaining());
 function entryFor(tool){
   if(tool.id!=='desktop-commander')throw Object.assign(Error('Unknown MCP child'),{code:'UNKNOWN_TOOL'});
   const pkg=require.resolve('@wonderwhy-er/desktop-commander/package.json');
   return join(dirname(pkg),'dist','index.js');
 }
-export function createMcpChildAdapter({records,log}){
-  function request(rec,method,params,ms){
+export function createMcpChildAdapter({records,log},options={}){
+  const spawnChild=options.spawnChild||spawn;
+  const childEntry=options.childEntry||entryFor;
+  function request(rec,method,params,ms,onLate=null){
     return new Promise((resolve,reject)=>{
       if(rec.exited||!rec.child.stdin.writable)return reject(Object.assign(Error('Closed'),{code:'TOOL_UNAVAILABLE'}));
-      if(ms<1)return reject(Object.assign(Error('Deadline'),{code:'TIMEOUT'}));
+      if(ms!==null&&ms<1)return reject(Object.assign(Error('Caller deadline'),{code:'TIMEOUT'}));
       const id=randomUUID();
-      const timer=setTimeout(()=>finish(Object.assign(Error('Deadline'),{code:'TIMEOUT'})),ms);
+      let settled=false, timer;
       const finish=(error,value)=>{
-        clearTimeout(timer);rec.pending.delete(id);
+        clearTimeout(timer);
+        rec.pending.delete(id);
+        if(rec.unconfirmed.delete(id)){
+          log('late-mcp-reply',{toolId:rec.toolId,requestId:id});
+          if(onLate)onLate(error,value);
+        }
+        if(settled)return;
+        settled=true;
         error?reject(error):resolve(value);
       };
       rec.pending.set(id,finish);
+      if(ms!==null)timer=setTimeout(()=>{
+        if(settled)return;
+        settled=true;
+        // Keep the callback until the real reply or child exit. Never treat the
+        // caller's timeout as evidence that the child is dead or retry the task.
+        if(method==='tools/call'){
+          rec.unconfirmed.add(id);
+          log('mcp-call-unconfirmed',{toolId:rec.toolId,requestId:id});
+        }else rec.pending.delete(id);
+        reject(Object.assign(Error('Caller deadline'),{code:'TIMEOUT'}));
+      },ms);
       rec.child.stdin.write(JSON.stringify({jsonrpc:'2.0',id,method,params})+'\n',e=>{
         if(e&&rec.pending.has(id))finish(Object.assign(e,{code:'TOOL_UNAVAILABLE'}));
       });
     });
   }
   function setup(tool,child){
-    const rec={child,pid:child.pid,state:'STARTING',exited:false,pending:new Map(),active:0};
+    const rec={child,toolId:tool.id,pid:child.pid,state:'STARTING',exited:false,pending:new Map(),unconfirmed:new Set(),active:0};
     records.set(tool.id,rec);
     let buffer='';
     child.stdout.on('data',chunk=>{
@@ -60,58 +79,75 @@ export function createMcpChildAdapter({records,log}){
     child.on('exit',(code,signal)=>{
       rec.exited=true;rec.state=rec.state==='STOPPING'?'STOPPED':'FAILED';
       for(const settle of rec.pending.values())settle(Object.assign(Error('Child exit'),{code:'TOOL_UNAVAILABLE'}));
-      rec.pending.clear();log('child-exit',{toolId:tool.id,pid:rec.pid,code,signal});
+      rec.pending.clear();rec.unconfirmed.clear();log('child-exit',{toolId:tool.id,pid:rec.pid,code,signal});
     });
     return rec;
   }
   async function launch(tool,ctx){
     const old=records.get(tool.id),before=old?.state||'STOPPED';
     if(old&&!old.exited){
+      if(old.state==='STARTING')return result(tool,before,'STARTING','HANDSHAKE_PENDING',null,old.pid,'MCP_INITIALIZING');
+      if(old.unconfirmed.size)return result(tool,before,'DEGRADED','UNCONFIRMED_OPERATIONS',err('OPERATION_UNCONFIRMED'),old.pid,'MCP_REPLY_PENDING');
       if(old.state!=='RUNNING')return result(tool,before,'UNKNOWN','IDENTITY_UNCERTAIN',err('UNKNOWN_RESULT'),old.pid);
       const health=await inspect(tool,ctx);
       if(health.after==='RUNNING')return result(tool,before,'RUNNING','ALREADY_RUNNING',null,old.pid,'MCP_TOOLS_LIST');
-      return result(tool,before,'UNKNOWN','IDENTITY_UNCERTAIN',health.error,old.pid);
+      return {...health,outcome:'HEALTH_NOT_CONFIRMED'};
     }
-    if(startupHandshakeBudget(ctx)<100)return result(tool,before,before,'DEADLINE_EXPIRED',err('TIMEOUT'));
     const home=join(paths().dir,'tools',tool.id,'home');
     mkdirSync(home,{recursive:true,mode:0o700});
     const env={HOME:home,PATH:process.env.PATH||'/usr/bin:/bin',LANG:process.env.LANG||'en_US.UTF-8',
       TMPDIR:process.env.TMPDIR||'/tmp',USER:process.env.USER||'',DESKTOP_COMMANDER_DISABLE_TELEMETRY:'true',
       DC_REMOTE_DEVICE:'false'};
-    const child=spawn(process.execPath,[entryFor(tool),'--no-onboarding'],
+    const child=spawnChild(process.execPath,[childEntry(tool),'--no-onboarding'],
       {stdio:['pipe','pipe','pipe'],env,windowsHide:true});
     const rec=setup(tool,child);
-    try{
-      const info=await request(rec,'initialize',{protocolVersion:'2025-03-26',
-        capabilities:{},clientInfo:{name:'chat-loop-local-tools',version:'0.4.4'}},startupHandshakeBudget(ctx));
-      if(!info?.protocolVersion)throw Object.assign(Error('Handshake failed'),{code:'MCP_HANDSHAKE_FAILED'});
-      child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'})+'\n');
-      const listed=await request(rec,'tools/list',{},startupHandshakeBudget(ctx));
-      if(!listed||fingerprint(listed.tools||[])!==expected)
-        throw Object.assign(Error('Tool schema changed'),{code:'SCHEMA_MISMATCH'});
-      rec.state='RUNNING';log('tool-start',{requestId:ctx.requestId,toolId:tool.id,pid:rec.pid});
-      return result(tool,before,'RUNNING','STARTED',null,rec.pid,'MCP_TOOLS_LIST');
-    }catch(e){
-      rec.state='UNKNOWN';
-      // Failed start never acquires a reusable healthy process.
-      if(!rec.exited)child.kill('SIGTERM');
-      return result(tool,before,'UNKNOWN','START_FAILED',err(e.code||'UNKNOWN_RESULT'),rec.pid,'NO_VALID_HANDSHAKE');
-    }
+    // Initialization may take arbitrarily long. The CLI can return STARTING;
+    // the same owned child will become RUNNING when its MCP reply arrives.
+    const handshake=(async()=>{
+      try{
+        const info=await request(rec,'initialize',{protocolVersion:'2025-03-26',
+          capabilities:{},clientInfo:{name:'chat-loop-local-tools',version:'0.4.4'}},null);
+        if(!info?.protocolVersion)throw Object.assign(Error('Handshake failed'),{code:'MCP_HANDSHAKE_FAILED'});
+        child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'})+'\n');
+        const listed=await request(rec,'tools/list',{},null);
+        if(!listed||fingerprint(listed.tools||[])!==expected)
+          throw Object.assign(Error('Tool schema changed'),{code:'SCHEMA_MISMATCH'});
+        if(rec.exited||rec.state==='STOPPING')return result(tool,before,'FAILED','START_FAILED',err('CHILD_EXIT'),rec.pid);
+        rec.state='RUNNING';log('tool-start',{requestId:ctx.requestId,toolId:tool.id,pid:rec.pid});
+        return result(tool,before,'RUNNING','STARTED',null,rec.pid,'MCP_TOOLS_LIST');
+      }catch(e){
+        if(!rec.exited)rec.state='UNKNOWN';
+        return result(tool,before,'UNKNOWN','START_FAILED',err(e.code||'UNKNOWN_RESULT'),rec.pid,'NO_VALID_HANDSHAKE');
+      }
+    })();
+    const wait=ctx.remaining();
+    if(wait<1)return result(tool,before,'STARTING','HANDSHAKE_PENDING',null,rec.pid,'MCP_INITIALIZING');
+    return Promise.race([
+      handshake,
+      new Promise(resolve=>setTimeout(()=>resolve(result(tool,before,'STARTING','HANDSHAKE_PENDING',null,rec.pid,'MCP_INITIALIZING')),wait))
+    ]);
   }
   async function inspect(tool,ctx){
     const rec=records.get(tool.id);
     if(!rec)return result(tool,'STOPPED','STOPPED','OBSERVED',null,null,'NO_OWNED_PROCESS');
     if(rec.exited)return result(tool,rec.state,rec.state,'OBSERVED',null,null,'CHILD_EXIT');
-    if(rec.state!=='RUNNING')return result(tool,rec.state,'UNKNOWN','OBSERVED',err('UNKNOWN_RESULT'),rec.pid);
+    if(rec.state==='STARTING')return result(tool,'STARTING','STARTING','OBSERVED',null,rec.pid,'MCP_INITIALIZING');
+    if(rec.state!=='RUNNING'&&rec.state!=='UNKNOWN')return result(tool,rec.state,'UNKNOWN','OBSERVED',err('UNKNOWN_RESULT'),rec.pid);
+    if(rec.unconfirmed.size)return result(tool,'RUNNING','DEGRADED','OBSERVED',err('OPERATION_UNCONFIRMED'),rec.pid,'MCP_REPLY_PENDING');
+    if(rec.active)return result(tool,'RUNNING','DEGRADED','OBSERVED',err('ACTIVE_REQUESTS'),rec.pid,'MCP_CALL_IN_FLIGHT');
     try{
       const listed=await request(rec,'tools/list',{},Math.min(timeout(ctx),1000));
       if(fingerprint(listed.tools||[])!==expected)throw Object.assign(Error('Changed schema'),{code:'SCHEMA_MISMATCH'});
-      return result(tool,'RUNNING','RUNNING','OBSERVED',null,rec.pid,'MCP_TOOLS_LIST');
-    }catch(e){rec.state='UNKNOWN';return result(tool,'RUNNING','UNKNOWN','OBSERVED',err(e.code||'UNKNOWN_RESULT'),rec.pid);}
+      rec.state='RUNNING';return result(tool,'RUNNING','RUNNING','OBSERVED',null,rec.pid,'MCP_TOOLS_LIST');
+    }catch(e){
+      // One unanswered health probe does not mutate the running child state.
+      return result(tool,'RUNNING','DEGRADED','OBSERVED',err(e.code||'UNKNOWN_RESULT'),rec.pid,'MCP_PROBE_UNANSWERED');
+    }
   }
   async function stop(tool,ctx){
     const rec=records.get(tool.id),before=rec?.state||'STOPPED';
     if(!rec||rec.exited)return result(tool,before,'STOPPED','ALREADY_STOPPED',null,null,'NO_LIVE_OWNED_CHILD');
+    if(rec.unconfirmed.size||rec.active)return result(tool,before,'DEGRADED','ACTIVE_REQUESTS',err('OPERATION_UNCONFIRMED'),rec.pid,'MCP_REPLY_PENDING');
     if(timeout(ctx)<1)return result(tool,before,before,'DEADLINE_EXPIRED',err('TIMEOUT'),rec.pid,'NO_SIGNAL_SENT');
     rec.state='STOPPING';
     // A direct ChildProcess handle only. Never kill by saved PID or process name.
@@ -129,11 +165,17 @@ export function createMcpChildAdapter({records,log}){
     const rec=records.get(tool.id);
     if(!rec||rec.exited||rec.state!=='RUNNING')throw Object.assign(Error('Not running'),{code:'TOOL_UNAVAILABLE'});
     if(!catalog.some(t=>t.name===name))throw Object.assign(Error('No such tool'),{code:'UNKNOWN_TOOL'});
+    // A prior timed-out write may still be running. Read-only probes may still
+    // proceed, but never enqueue another uncertain mutating operation.
+    const harmless=new Set(['read_file','read_multiple_files','list_directory','get_file_info',
+      'list_sessions','list_processes','get_usage_stats','get_recent_tool_calls']);
+    if(rec.unconfirmed.size&&!harmless.has(name))
+      throw Object.assign(Error('Previous request outcome unconfirmed'),{code:'OPERATION_UNCONFIRMED'});
     rec.active++;
     try{
-      return await request(rec,'tools/call',{name,arguments:args},timeout(ctx));
-    }catch(e){if(e.code==='TIMEOUT')rec.state='UNKNOWN';throw e;}
-    finally{rec.active--;}
+      const ms=Math.max(0,Math.min(ctx.remaining(),toolCallDeadlineMs(args)-2000));
+      return await request(rec,'tools/call',{name,arguments:args},ms,(error,value)=>ctx.onLate?.(error,value));
+    }finally{rec.active--;}
   }
   return {launch,stop,inspect,call,catalog};
 }

package/lib/adapters/tunnel.mjs

@@ -25,7 +25,7 @@ function probe(socketPath,ms=350){
 function safeUnlink(file){
   try{unlinkSync(file);}catch(e){if(e.code!=='ENOENT')throw e;}
 }
-export function createTunnelAdapter({records,log},options={}){
+export function createTunnelAdapter({records,log,onChildExit=()=>{}},options={}){
   const locate=options.locate||bundledTunnel;
   const spawnChild=options.spawnChild||spawn;
   const profileDir=options.profileDir||join(homedir(),'.chat-loop','tunnel','profiles');
@@ -68,7 +68,7 @@ export function createTunnelAdapter({records,log},options={}){
     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');}
+    if(!ready)return result(t,before,'DEGRADED','OBSERVED',err('READINESS_UNCONFIRMED'),rec.pid,'READYZ_NOT_200');
     rec.state='RUNNING';
     return result(t,before,'RUNNING','OBSERVED',null,rec.pid,'LOCAL_READYZ');
   }
@@ -118,6 +118,7 @@ export function createTunnelAdapter({records,log},options={}){
       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});
+      if(rec.state==='FAILED'&&!rec.authRequired)onChildExit(t,rec);
     }
     child.once('exit',onExit);
     // spawn ENOENT emits error then close, potentially without an exit event.

package/lib/control.mjs

@@ -4,7 +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.7';
+export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+// All peers must be from one published runtime; never mix an old npx Gateway
+// with a newly activated Supervisor under an unchanged protocol banner.
+export const VERSION = PACKAGE_VERSION;
+// Bounded end-to-end tool calls: long-running Desktop Commander operations may wait up to timeout_ms.
+export const toolCallDeadlineMs = args => {
+  const requested = Number.isSafeInteger(args?.timeout_ms) && args.timeout_ms > 0 ? args.timeout_ms : 0;
+  return Math.min(42000, Math.max(12000, requested + 8000));
+};
 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')});
@@ -77,7 +85,7 @@ export function send(request, timeout=3000) {
 }
 export async function talk(request,timeout=12000){
   const hello=await send({action:'__ping'},1200);
-  if(hello.contract!==CONTRACT||hello.version!==VERSION||
+  if(hello.contract!==CONTRACT||hello.version!==VERSION||hello.packageVersion!==PACKAGE_VERSION||
       hello.registrySignature!==registry().map(t=>t.id+':'+t.enabled).join('|'))
     throw Object.assign(new Error('Version or registry mismatch'),{code:'INCOMPATIBLE_VERSION'});
   verifyOwner(hello);

package/lib/gateway.mjs

@@ -1,8 +1,9 @@
 // Stdio MCP entrypoint: protocol framing and routing only; never owns child processes.
 import {randomUUID} from 'node:crypto';
 import {readFileSync} from 'node:fs';
-import {CONTRACT,registry,talk} from './control.mjs';
+import {CONTRACT,PACKAGE_VERSION,registry,talk,toolCallDeadlineMs} from './control.mjs';
 import {extensionTools,forwardExtensionAction} from './extension-proxy.mjs';
+import {runtimeNeedsUpgrade} from './release.mjs';
 
 const desktopTools=JSON.parse(readFileSync(new URL('./desktop-commander-tools.json',import.meta.url),'utf8'));
 const fixtureTool={name:'ping',description:'Inert lifecycle test health check',
@@ -12,10 +13,15 @@ const prefix=id=>id.replaceAll('-','_')+'__';
 // The pinned child's UI metadata advertises resources this tools-only Gateway does not serve.
 // Do not expose those references until resources/read is explicitly supported.
 const extEnabled=()=>process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES!=='1';
+const receiptTool={name:'chat_loop_runtime__operation_status',
+  description:'Read a previously timed-out MCP request receipt without replaying its side effects.',
+  inputSchema:{type:'object',required:['requestId'],additionalProperties:false,
+    properties:{requestId:{type:'string'}}}};
 const published=()=>[
   ...registry().filter(t=>t.enabled).flatMap(t=>
     toolsFor(t).map(({_meta,...x})=>({...x,name:prefix(t.id)+x.name}))),
-  ...(extEnabled()?extensionTools.map(t=>({...t,name:'chat_loop_extension__'+t.name})):[])
+  ...(extEnabled()?extensionTools.map(t=>({...t,name:'chat_loop_extension__'+t.name})):[]),
+  receiptTool
 ];
 function resolveTool(name){
   if(extEnabled()&&typeof name==='string'&&name.startsWith('chat_loop_extension__')){
@@ -46,7 +52,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.12'}});
+        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:PACKAGE_VERSION}});
     }
     // A modern MCP client probes discovery before falling back to legacy initialize.
     // We only implement the legacy handshake era, so report unsupported method.
@@ -55,17 +61,29 @@ export function runGateway(){
     if(m.method==='ping')return reply(m.id,{});
     if(m.method==='tools/list')return reply(m.id,{tools:published()});
     if(m.method==='tools/call'){
-      const routed=resolveTool(m.params?.name);
+      const routed=m.params?.name===receiptTool.name?
+        {toolId:'runtime',name:'operation_status'}:resolveTool(m.params?.name);
       if(!routed)return reply(m.id,failure('UNKNOWN_TOOL'));
       const args=m.params?.arguments??{};
       if(args===null||typeof args!=='object'||Array.isArray(args))
         return reply(m.id,failure('INVALID_ARGUMENT'));
       try{
+        if(routed.toolId==='runtime'){
+          const res=await talk({contract:CONTRACT,action:'receipt',requestId:randomUUID(),
+            targetRequestId:args.requestId},4000);
+          return reply(m.id,res.status==='OK'?{operation:res.operation}:failure('RECEIPT_UNAVAILABLE'));
+        }
+        if(routed.toolId!=='chat-loop-extension'&&
+           !process.env.CHAT_LOOP_LOCAL_TOOLS_STATE_DIR&&
+           !process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES&&runtimeNeedsUpgrade())
+          return reply(m.id,failure('RUNTIME_UPGRADE_REQUIRED'));
         if(routed.toolId==='chat-loop-extension')
           return reply(m.id,await forwardExtensionAction(routed.name,args));
-        const res=await talk({contract:CONTRACT,requestId:randomUUID(),action:'call',
-          scope:'tool',toolId:routed.toolId,name:routed.name,args,deadlineMs:12000},13000);
-        if(res.status!=='OK')return reply(m.id,failure(res.error?.code||'TOOL_UNAVAILABLE'));
+        const deadlineMs=toolCallDeadlineMs(args),requestId=randomUUID();
+        const res=await talk({contract:CONTRACT,requestId,action:'call',
+          scope:'tool',toolId:routed.toolId,name:routed.name,args,deadlineMs},deadlineMs+2000);
+        if(res.status!=='OK')return reply(m.id,failure(res.error?.code==='TIMEOUT'?
+          'OPERATION_UNCONFIRMED:'+requestId:res.error?.code||'TOOL_UNAVAILABLE'));
         return reply(m.id,res.result);
       }catch(e){
         return reply(m.id,failure(['ENOENT','ECONNREFUSED'].includes(e.code)?'TOOL_UNAVAILABLE':

package/lib/release.mjs

@@ -0,0 +1,136 @@
+// Owner-verified stop-and-start upgrade. Failure is reported, never auto-rolled back.
+import {spawn} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {existsSync,readFileSync,writeFileSync,openSync,closeSync,unlinkSync,mkdirSync,renameSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join,dirname} from 'node:path';
+import {PACKAGE_VERSION} from './control.mjs';
+
+const name='@tomflow/chatloop-tools';
+const entryIn=prefix=>join(prefix,'node_modules','@tomflow','chatloop-tools','bin','cli.mjs');
+const runtimeRoot=()=>join(homedir(),'.chat-loop');
+const readJson=path=>JSON.parse(readFileSync(path,'utf8'));
+const delay=ms=>new Promise(r=>setTimeout(r,ms));
+const safeVersion=v=>/^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.-]+)?$/.test(v);
+const quote=s=>JSON.stringify(s);
+const freshResult=(status,extra={})=>({command:'upgrade',status,version:PACKAGE_VERSION,...extra});
+
+export function upgradeLayout(base=runtimeRoot(),version=PACKAGE_VERSION){
+  if(!safeVersion(version))throw Error('INVALID_VERSION');
+  return {
+    base,version,
+    releases:join(base,'releases'),
+    stage:join(base,'releases','chatloop-tools-'+version),
+    entry:entryIn(join(base,'releases','chatloop-tools-'+version)),
+    legacy:entryIn(join(base,'npm')),
+    profile:join(base,'tunnel','profiles','chat-loop.yaml'),
+    current:join(base,'runtime.json'),
+    lock:join(base,'upgrade.lock')
+  };
+}
+function atomicWrite(path,content){
+  const tmp=path+'.'+randomUUID()+'.tmp';
+  writeFileSync(tmp,content,{mode:0o600,flag:'wx'});
+  renameSync(tmp,path);
+}
+function run(bin,args,opts={}){
+  return new Promise((resolve,reject)=>{
+    const child=spawn(bin,args,{env:opts.env||process.env,stdio:['ignore','pipe','pipe'],windowsHide:true});
+    let stdout='',stderr='';
+    child.stdout.on('data',x=>stdout+=x.toString());
+    child.stderr.on('data',x=>stderr+=x.toString().slice(0,2048));
+    child.once('error',reject);
+    child.once('close',code=>code===0?resolve(stdout):reject(Object.assign(Error('COMMAND_FAILED'),{
+      code:'COMMAND_FAILED',command:args[0],status:code,stdout,detail:stderr.slice(-300)})));
+  });
+}
+async function cli(entry,action,opts={}){
+  let raw;
+  try{raw=await run(process.execPath,[entry,action],opts);}
+  catch(e){if(!e.stdout)throw e;raw=e.stdout;}
+  try{return JSON.parse(raw.trim());}
+  catch{throw Object.assign(Error('INVALID_CLI_REPLY'),{code:'INVALID_CLI_REPLY'});}
+}
+async function awaitStopped(entry,opts={}){
+  // A completed stop is verified by the former owner's lock disappearing.
+  const p=opts.lockPath;
+  for(let i=0;i<80;i++){
+    if(!existsSync(p))return;
+    await delay(100);
+  }
+  throw Object.assign(Error('OWNER_STILL_RUNNING'),{code:'OWNER_STILL_RUNNING'});
+}
+export function runtimeNeedsUpgrade(base=runtimeRoot(),version=PACKAGE_VERSION){
+  const p=upgradeLayout(base,version);
+  const runtime=existsSync(p.current)?readJson(p.current):null;
+  if(runtime)return runtime.version!==version;
+  if(!existsSync(p.legacy))return false;
+  const current=readJson(join(dirname(dirname(p.legacy)),'package.json')).version;
+  return current!==version;
+}
+export async function upgradeRuntime(options={}){
+  if(options.args?.length)return freshResult('FAILED',{code:'INVALID_ARGUMENT'});
+  const p=upgradeLayout(options.base,options.version||PACKAGE_VERSION);
+  mkdirSync(p.base,{recursive:true,mode:0o700});
+  mkdirSync(p.releases,{recursive:true,mode:0o700});
+  let fd;
+  try{fd=openSync(p.lock,'wx',0o600);}
+  catch{return freshResult('BLOCKED',{code:'UPGRADE_IN_PROGRESS'});}
+  const runner=options.run||run;
+  let oldEntry, oldStatus, phase='preflight';
+  try{
+    if(!existsSync(p.profile))return freshResult('BLOCKED',{code:'PROFILE_NOT_FOUND'});
+    const profile=readJson(p.profile);
+    if(!profile?.mcp?.commands?.some(x=>x.channel==='main'))
+      return freshResult('BLOCKED',{code:'PROFILE_MCP_NOT_FOUND'});
+    const runtime=existsSync(p.current)?readJson(p.current):null;
+    oldEntry=runtime?.entry||p.legacy;
+    if(!existsSync(oldEntry))return freshResult('BLOCKED',{code:'PREVIOUS_RUNTIME_NOT_FOUND'});
+    const currentVersion=readJson(join(dirname(dirname(oldEntry)),'package.json')).version;
+    if(currentVersion===p.version&&runtime?.entry===p.entry){
+      const active=await cli(p.entry,'status');
+      return active.status==='OK'?freshResult('OK',{outcome:'ALREADY_ACTIVE'}):
+        freshResult('BLOCKED',{code:'ACTIVE_RUNTIME_NOT_HEALTHY'});
+    }
+    // Prepare a new immutable install without touching the running service.
+    phase='prepare';
+    if(!existsSync(p.entry)){
+      await runner(process.platform==='win32'?'npm.cmd':'npm',
+        ['install','--prefix',p.stage,'--save-exact','--ignore-scripts',name+'@'+p.version],
+        {env:process.env});
+    }
+    if(!existsSync(p.entry)||readJson(join(dirname(dirname(p.entry)),'package.json')).version!==p.version)
+      return freshResult('BLOCKED',{code:'STAGE_VERSION_MISMATCH'});
+    const ready=await cli(p.entry,'doctor');
+    if(ready.status!=='LOCAL_READY')return freshResult('BLOCKED',{code:'STAGE_DOCTOR_FAILED'});
+    // The staged Gateway is prepared independently; Tunnel binds only on activation.
+    phase='check-owner';
+    oldStatus=await cli(oldEntry,'status');
+    if(oldStatus.status!=='OK'||oldStatus.results?.some(r=>r.after!=='RUNNING'&&r.after!=='STOPPED'&&r.after!=='DISABLED'))
+      return freshResult('BLOCKED',{code:'OWNER_NOT_QUIESCENT',previousStatus:oldStatus.status});
+    phase='stop-old';
+    const oldStopped=await cli(oldEntry,'stop');
+    if(oldStopped.status!=='OK')return freshResult('BLOCKED',{code:'STOP_UNCONFIRMED'});
+    phase='verify-stopped';
+    await awaitStopped(oldEntry,{lockPath:join(p.base,'local-tools','manager.lock')});
+    phase='configure-new';
+    const main=profile.mcp.commands.find(x=>x.channel==='main');
+    main.command=quote(process.execPath)+' '+quote(p.entry)+' mcp';
+    atomicWrite(p.profile,JSON.stringify(profile,null,2)+'\n');
+    phase='start-new';
+    const started=await cli(p.entry,'start',{env:{...process.env,CHAT_LOOP_SKIP_UPGRADE:'1'}});
+    if(!['OK','STARTING'].includes(started.status))
+      throw Object.assign(Error('NEW_RUNTIME_UNHEALTHY'),{code:'NEW_RUNTIME_UNHEALTHY'});
+    phase='record-new';
+    atomicWrite(p.current,JSON.stringify({version:p.version,entry:p.entry,
+      status:started.status==='OK'?'ACTIVE':'STARTING'},null,2)+'\n');
+    return freshResult(started.status,{outcome:started.status==='OK'?'ACTIVATED':'STARTING'});
+  }catch(e){
+    // Fail closed and retain the exact failure site. Never restart an unknown
+    // old/new owner or mutate another process as a "recovery" side effect.
+    return freshResult('BLOCKED',{code:e.code||'UPGRADE_FAILED',phase});
+  }finally{
+    if(fd!==undefined)closeSync(fd);
+    try{unlinkSync(p.lock);}catch{}
+  }
+}

package/lib/supervisor.mjs

@@ -1,17 +1,31 @@
 import {randomUUID} from 'node:crypto';
 import {appendFileSync, closeSync, existsSync, openSync, readFileSync, unlinkSync, writeFileSync, chmodSync} from 'node:fs';
 import {createServer} from 'node:net';
-import {CONTRACT,VERSION,registry,paths,ensurePrivateDir,ACTIONS} from './control.mjs';
+import {CONTRACT,VERSION,PACKAGE_VERSION,registry,paths,ensurePrivateDir,ACTIONS} from './control.mjs';
 import {createAdapter} from './adapters/index.mjs';
 
-const catalog=registry(), records=new Map(), queues=new Map(), seen=new Map();
+const catalog=registry(), records=new Map(), queues=new Map(), seen=new Map(), receipts=new Map();
 const p=paths(), nonce=randomUUID();
+const desiredTunnel=new Set(), recoveryAttempts=new Map();
 let lockFd, server, idleTimer;
 const log=(event,detail={})=>{
   try{appendFileSync(p.log,JSON.stringify({time:new Date().toISOString(),event,...detail})+'\n',{mode:0o600});}catch{}
 };
 const error=(code,message=code)=>({code,message});
 const after=rec=>rec ? rec.state : 'STOPPED';
+function saveReceipt(id,state,result=null,errorCode=null){
+  receipts.delete(id);
+  receipts.set(id,{state,result,errorCode});
+  if(receipts.size>128)receipts.delete(receipts.keys().next().value);
+}
+function receipt(req){
+  const id=req?.targetRequestId;
+  if(req?.contract!==CONTRACT||typeof id!=='string'||!/^[a-f0-9-]{36}$/.test(id))
+    return bad(req,'INVALID_ARGUMENT');
+  const record=receipts.get(id);
+  return {contract:CONTRACT,requestId:req.requestId,status:'OK',
+    operation:record||{state:'UNKNOWN',result:null,errorCode:'NOT_FOUND'}};
+}
 function serial(id,fn){
   const prev=queues.get(id)||Promise.resolve();
   const next=prev.catch(()=>{}).then(fn);
@@ -21,9 +35,24 @@ function serial(id,fn){
 }
 const adapters=new Map();
 function adapterFor(tool){
-  if(!adapters.has(tool.kind))adapters.set(tool.kind,createAdapter(tool.kind,{records,log}));
+  if(!adapters.has(tool.kind))adapters.set(tool.kind,createAdapter(tool.kind,{records,log,onChildExit:queueTunnelRecovery}));
   return adapters.get(tool.kind);
 }
+function queueTunnelRecovery(tool){
+  if(!desiredTunnel.has(tool.id))return;
+  const now=Date.now(), old=recoveryAttempts.get(tool.id)||[];
+  const attempts=old.filter(t=>now-t<300000);
+  if(attempts.length>=3){desiredTunnel.delete(tool.id);log('tunnel-recovery-blocked',{toolId:tool.id,reason:'REPEATED_CRASH'});return;}
+  attempts.push(now);recoveryAttempts.set(tool.id,attempts);
+  // Only the same Supervisor and its owned child handle can relaunch. Explicit
+  // stop/update disables the desired state before the old child is signalled.
+  void serial(tool.id,async()=>{
+    if(!desiredTunnel.has(tool.id))return;
+    const reply=await adapterFor(tool).launch(tool,{requestId:'tunnel-recovery',remaining:()=>25000});
+    log('tunnel-recovery',{toolId:tool.id,status:reply.after,outcome:reply.outcome});
+    if(reply.after!=='RUNNING')desiredTunnel.delete(tool.id);
+  }).catch(e=>log('tunnel-recovery-error',{toolId:tool.id,code:e.code||'UNKNOWN_RESULT'}));
+}
 function targets(req){
   const found=req.scope==='tool'?catalog.filter(t=>t.id===req.toolId):
     catalog.filter(t=>req.action==='status'||t.enabled);
@@ -40,7 +69,7 @@ async function executeCall(req){
   if(typeof req.requestId!=='string'||req.requestId.length<6||req.requestId.length>128||
      req.scope!=='tool'||typeof req.toolId!=='string'||typeof req.name!=='string'||
      !req.args||typeof req.args!=='object'||Array.isArray(req.args)||
-     !Number.isInteger(req.deadlineMs)||req.deadlineMs<1000||req.deadlineMs>30000)return invalid();
+     !Number.isInteger(req.deadlineMs)||req.deadlineMs<1000||req.deadlineMs>45000)return invalid();
   const tool=catalog.find(t=>t.id===req.toolId);
   if(!tool)return bad(req,'UNKNOWN_TOOL');
   if(!tool.enabled)return bad(req,'DISABLED_TOOL');
@@ -48,16 +77,21 @@ async function executeCall(req){
   const prev=seen.get(req.requestId);
   if(prev)return prev.payload===argsKey?prev.promise:bad(req,'REQUEST_ID_REUSE');
   const expires=Date.now()+req.deadlineMs;
+  saveReceipt(req.requestId,'RUNNING');
   const promise=serial(tool.id,async()=>{
     try{
       const adapter=adapterFor(tool);
       if(typeof adapter.call!=='function')return bad(req,'TOOL_UNAVAILABLE');
       const value=await adapter.call(tool,req.name,req.args,
-        {requestId:req.requestId,remaining:()=>Math.max(0,expires-Date.now())});
+        {requestId:req.requestId,remaining:()=>Math.max(0,expires-Date.now()),
+          onLate:(error,value)=>saveReceipt(req.requestId,error?'FAILED':'COMPLETED',error?null:value,
+            error?.code||null)});
+      saveReceipt(req.requestId,'COMPLETED',value);
       log('tool-call',{requestId:req.requestId,toolId:tool.id,toolName:req.name,status:'OK'});
       return {contract:CONTRACT,requestId:req.requestId,status:'OK',result:value};
     }catch(e){
       const code=e.code||'UNKNOWN_RESULT';
+      saveReceipt(req.requestId,code==='TIMEOUT'?'UNCONFIRMED':'FAILED',null,code);
       log('tool-call',{requestId:req.requestId,toolId:tool.id,toolName:req.name,status:'FAILED',errorCode:code});
       return bad(req,code);
     }
@@ -93,11 +127,17 @@ async function execute(req){
             outcome:'OBSERVED',pid:null,evidence:'REGISTRY',error:null};
           return adapterFor(t).inspect(t,ctx);
         }
-        if(req.action==='start')return adapterFor(t).launch(t,ctx);
+        if(req.action==='start'){
+          const began=await adapterFor(t).launch(t,ctx);
+          if(t.id==='tunnel'&&began.after==='RUNNING')desiredTunnel.add(t.id);
+          return began;
+        }
+        if(t.id==='tunnel')desiredTunnel.delete(t.id);
         if(req.action==='stop')return adapterFor(t).stop(t,ctx);
         const ended=await adapterFor(t).stop(t,ctx);
         if(ended.error)return {...ended,outcome:'RESTART_FAILED'};
         const began=await adapterFor(t).launch(t,ctx);
+        if(t.id==='tunnel'&&began.after==='RUNNING')desiredTunnel.add(t.id);
         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',
@@ -105,7 +145,10 @@ async function execute(req){
       results.push(item);
     }
     const failures=results.filter(r=>r.error);
-    const status=results.some(r=>r.after==='UNKNOWN')?'UNKNOWN':failures.length===0?'OK':failures.length===results.length?'FAILED':'PARTIAL';
+    const status=results.some(r=>r.after==='UNKNOWN')?'UNKNOWN':
+      results.some(r=>r.after==='DEGRADED')?'DEGRADED':
+      results.some(r=>r.after==='STARTING')?'STARTING':
+      failures.length===0?'OK':failures.length===results.length?'FAILED':'PARTIAL';
     const response={contract:CONTRACT,requestId:req.requestId,action:req.action,scope:req.scope,target:req.toolId||null,status,results,managerPid:process.pid};
     log('control',{requestId:req.requestId,action:req.action,scope:req.scope,toolId:req.toolId||null,status,
       results:results.map(r=>({toolId:r.toolId,after:r.after,outcome:r.outcome,errorCode:r.error?.code||null}))});
@@ -147,7 +190,7 @@ async function main(){
       handled=true;
       let req;try{req=JSON.parse(buf.slice(0,n));}catch{socket.end(JSON.stringify(bad({},'INVALID_ARGUMENT'))+'\n');return;}
       const work=req?.action==='__ping'?
-        Promise.resolve({contract:CONTRACT,version:VERSION,registrySignature:catalog.map(t=>t.id+':'+t.enabled).join('|'),ownerNonce:nonce,managerPid:process.pid}):req?.action==='call'?executeCall(req):execute(req);
+        Promise.resolve({contract:CONTRACT,version:VERSION,packageVersion:PACKAGE_VERSION,registrySignature:catalog.map(t=>t.id+':'+t.enabled).join('|'),ownerNonce:nonce,managerPid:process.pid}):req?.action==='call'?executeCall(req):req?.action==='receipt'?Promise.resolve(receipt(req)):execute(req);
       work.then(value=>socket.end(JSON.stringify(value)+'\n')).catch(err=>{
         log('ipc-error',{code:err.code||'INTERNAL_ERROR'});
         socket.end(JSON.stringify(bad(req,'INTERNAL_ERROR'))+'\n');

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.12",
+  "version": "0.4.14",
   "type": "module",
   "description": "Chat Loop local tools: MCP gateway, isolated bundled tunnel-client and unified CLI",
   "bin": {