deadbyte-mcp 0.15.22 → 0.15.24

package/src/deadbyte-cli.mjs

@@ -13,7 +13,7 @@ import { openRemoteResultJournal, parseRemoteResultCursor } from './remote-resul
 import { DEADBYTE_VERSION } from './version.mjs';
 import { parseActivePointer } from './release-slot.mjs';
 import { printDoctor } from './doctor-r45.mjs';
-import { createLiveTimelineTracker, formatCompactAuditEvent, formatRemoteLifecycle, formatRemoteToolCall, formatRuntimeDiagnosticLine } from './remote-live-log.mjs';
+import { createLiveTimelineFilter, createLiveTimelineTracker, createLiveTimelineWriter, formatCompactAuditEvent, formatRemoteLifecycle, formatRemoteToolCall, formatRuntimeDiagnosticLine } from './remote-live-log.mjs';
 import { prepareRemoteConsole, remoteDisplayText } from './remote-console.mjs';
 
 const REMOTE_COMMANDS=new Set([
@@ -46,6 +46,8 @@ function printHelp(){
     `  npx -y ${exact} mcp                 # stdio MCP server for local clients`,
     `  npx -y ${exact} remote              # unified foreground device session + live timeline`,
     `  npx -y ${exact} remote --resume <cursor> # replay missed results, then reconnect`,
+    `  npx -y ${exact} remote --trace           # show trace/span identity without payload detail`,
+    `  npx -y ${exact} remote --filter <expr>   # presentation filter: tool/category/status/trace`,
     `  npx -y ${exact} remote status`,
     `  npx -y ${exact} remote restart`,
     `  npx -y ${exact} supervisor status`,
@@ -71,6 +73,21 @@ async function readActiveRuntimeBinding(root){
   try{return parseActivePointer(await readFile(file,'utf8'));}
   catch(error){if(error?.code==='ENOENT') return null;throw new Error(`active runtime pointer invalid: ${boundedSingleLine(error?.message||error,512)}`);}
 }
+async function readLiveRootPaths(root){
+  const active=await readActiveRuntimeBinding(root);
+  if(!active) return Object.freeze({});
+  const file=path.join(active.generation_root,'coding-policy.json');
+  let raw;
+  try{raw=JSON.parse(await readFile(file,'utf8'));}
+  catch(error){if(error?.code==='ENOENT') return Object.freeze({});throw new Error(`live root policy invalid: ${boundedSingleLine(error?.message||error,512)}`);}
+  if(raw?.schema!=='deadbyte.coding-policy.v1'||!raw.roots||typeof raw.roots!=='object'||Array.isArray(raw.roots)) throw new Error('live root policy schema invalid');
+  const roots={};
+  for(const [id,spec] of Object.entries(raw.roots)){
+    if(!/^[A-Za-z0-9._-]{1,64}$/.test(id)||!spec||typeof spec!=='object'||typeof spec.path!=='string'||!path.isAbsolute(spec.path)) continue;
+    roots[id]=path.resolve(spec.path);
+  }
+  return Object.freeze(roots);
+}
 async function reportVersionCoherence(root,{displayMode='ascii'}={}){
   const active=await readActiveRuntimeBinding(root);
   if(!active||active.version===DEADBYTE_VERSION) return active;
@@ -227,7 +244,22 @@ async function snapshotRemoteLogOffsets(root){
   }
   return offsets;
 }
-async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTracker=null,verbose=false,displayMode='unicode'}={}){
+function timelineFilterEvent(timeline){
+  if(!timeline) return null;
+  if(timeline.event_type==='tool.call') return {
+    event_type:'tool.request',request_id:timeline.request_id,tool:timeline.tool,args:timeline.arguments??{}
+  };
+  return {
+    event_type:'tool.result',request_id:timeline.request_id,tool:timeline.tool,
+    outcome:{
+      is_error:timeline.status==='error',
+      ...(Number.isFinite(Number(timeline.duration_ms))?{duration_ms:Number(timeline.duration_ms)}:{}),
+      ...(timeline.side_effect_state?{side_effect_state:timeline.side_effect_state}:{}),
+      ...(timeline.reason?{reason:timeline.reason}:{})
+    }
+  };
+}
+async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTracker=null,timelineFilter=null,timelineWriter=null,verbose=false,displayMode='unicode'}={}){
   process.stdout.write(verbose
     ? '[LOG] Verbose live timeline. Full sanitized request detail enabled; Ctrl+C disconnects and revokes authority.\n'
     : '[LOG] Human live timeline. Transport IN/OUT hidden; full replay/audit detail remains on disk. Ctrl+C disconnects and revokes authority.\n');
@@ -244,10 +276,14 @@ async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTra
           ? await journal.recordCall(timeline)
           : await journal.recordTerminal(timeline);
         if(recorded?.duplicate) continue;
+        const accepted=timelineFilter&&timeline?timelineFilter.accept(timelineFilterEvent(timeline)):true;
         const formatted=formatLogLine(file,line,{activityTracker,sequence:recorded?.event?.seq??null,verbose,displayMode});
-        if(!formatted) continue;
+        if(!formatted||!accepted) continue;
         const output=Array.isArray(formatted)?formatted:[formatted];
-        for(const item of output) if(item) process.stdout.write(`${item}\n`);
+        for(const item of output) if(item){
+          if(timelineWriter) timelineWriter.write(item,{event_type:timeline?.event_type??null,request_id:timeline?.request_id??null});
+          else process.stdout.write(`${item}\n`);
+        }
       }
     }
     try{await sleep(250,null,{signal});}catch(error){if(error?.name!=='AbortError') throw error;}
@@ -341,7 +377,7 @@ async function releaseRemoteSession(ctx,marker,{displayMode='unicode'}={}){
   const same=current?.schema==='deadbyte.remote-session.v2'&&current.owner_pid===marker.owner_pid&&current.session_nonce===marker.session_nonce;
   if(same) await rm(remoteSessionMarker(ctx.root),{force:true});
 }
-async function runRemoteSession({resumeCursor=null,verbose=false}={}){
+async function runRemoteSession({resumeCursor=null,verbose=false,trace=false,filterExpression=''}={}){
   const display=prepareRemoteConsole();
   const displayMode=display.mode;
   const ctx=await remoteContext();
@@ -353,7 +389,10 @@ async function runRemoteSession({resumeCursor=null,verbose=false}={}){
   const resultJournal=await openRemoteResultJournal({
     filePath:remoteResultJournalPath(ctx.root,marker.result_session_id),sessionId:marker.result_session_id,maxEntries:2048
   });
-  const activityTracker=createLiveTimelineTracker({verbose,displayMode});
+  const rootPaths=await readLiveRootPaths(ctx.root);
+  const activityTracker=createLiveTimelineTracker({verbose,displayMode,rootPaths,trace});
+  const timelineFilter=filterExpression?createLiveTimelineFilter(filterExpression):null;
+  const timelineWriter=createLiveTimelineWriter({stream:process.stdout,displayMode,rewrite:!verbose});
   const aborter=new AbortController();
   const abort=()=>aborter.abort();
   const watchStdin=!process.stdin.isTTY;
@@ -366,7 +405,7 @@ async function runRemoteSession({resumeCursor=null,verbose=false}={}){
     process.stdout.write(`${formatRemoteLifecycle('device_start',{displayMode})}\n`);
     process.stdout.write(`${formatRemoteLifecycle(resumeCursor!==null?'session_restored':'session_new',{displayMode})}\n`);
     const logOffsets=await snapshotRemoteLogOffsets(ctx.root);
-    logTask=tailRemoteLogs(ctx.root,aborter.signal,{journal:resultJournal,offsets:logOffsets,activityTracker,verbose,displayMode});
+    logTask=tailRemoteLogs(ctx.root,aborter.signal,{journal:resultJournal,offsets:logOffsets,activityTracker,timelineFilter,timelineWriter,verbose,displayMode});
     process.stdout.write('[BOOT] Starting local + remote runtime...\n');
     const preflight=invokeController(ctx,'status',{capture:true,allowFailure:true,echoCaptured:false,timeoutMs:REMOTE_STATUS_TIMEOUT_MS});
     let startText=preflight.stdout||'';
@@ -415,6 +454,7 @@ async function runRemoteSession({resumeCursor=null,verbose=false}={}){
     const wasAborted=aborter.signal.aborted;
     aborter.abort();
     if(logTask) await logTask.catch(()=>{});
+    timelineWriter.flush();
     for(const line of activityTracker.reconcileInterrupted('session_end')) process.stdout.write(`${line}\n`);
     process.stdout.write(`${activityTracker.summary()}\n`);
     process.removeListener('SIGINT',abort);process.removeListener('SIGTERM',abort);
@@ -426,14 +466,29 @@ async function runRemoteSession({resumeCursor=null,verbose=false}={}){
   }
 }
 async function runRemote(args){
-  if(args.length===0){await runRemoteSession();return;}
-  const verbose=args.includes('--verbose')||args.includes('-v');
-  const filtered=args.filter(arg=>arg!=='--verbose'&&arg!=='-v');
-  if(filtered.length===0){await runRemoteSession({verbose});return;}
-  if(filtered.length===2&&filtered[0]==='--resume'){await runRemoteSession({resumeCursor:filtered[1],verbose});return;}
-  if(verbose) throw new Error('remote --verbose/-v is valid only for foreground session or --resume <cursor>');
-  if(filtered.length>1) throw new Error('remote accepts one controller command or --resume <cursor>');
-  const command=filtered[0];if(!REMOTE_COMMANDS.has(command)) throw new Error(`unsupported remote command '${command}'`);
+  let verbose=false,trace=false,filterExpression='',resumeCursor=null;
+  const positional=[];
+  for(let index=0;index<args.length;index++){
+    const arg=args[index];
+    if(arg==='--verbose'||arg==='-v'){verbose=true;continue;}
+    if(arg==='--trace'){trace=true;continue;}
+    if(arg==='--filter'){
+      if(filterExpression) throw new Error('remote --filter may be specified once');
+      if(index+1>=args.length) throw new Error('remote --filter requires an expression');
+      filterExpression=args[++index];continue;
+    }
+    if(arg==='--resume'){
+      if(resumeCursor!==null) throw new Error('remote --resume may be specified once');
+      if(index+1>=args.length) throw new Error('remote --resume requires a cursor');
+      resumeCursor=args[++index];continue;
+    }
+    positional.push(arg);
+  }
+  const presentation=verbose||trace||Boolean(filterExpression)||resumeCursor!==null;
+  if(positional.length===0){await runRemoteSession({resumeCursor,verbose,trace,filterExpression});return;}
+  if(presentation) throw new Error('remote presentation flags are valid only for foreground session');
+  if(positional.length>1) throw new Error('remote accepts one controller command');
+  const command=positional[0];if(!REMOTE_COMMANDS.has(command)) throw new Error(`unsupported remote command '${command}'`);
   const ctx=await remoteContext();
   await reportVersionCoherence(ctx.root,{displayMode:'ascii'});
   const result=invokeController(ctx,command,{allowFailure:true});

package/src/host-plane.mjs

@@ -1,19 +1,16 @@
-import { createHash, randomBytes } from 'node:crypto';
-import { constants as fsConstants } from 'node:fs';
+import { createHash } from 'node:crypto';
 import {
   lstat,
   mkdir,
-  open,
   readFile,
   realpath,
-  rename,
-  rm,
   stat
 } from 'node:fs/promises';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { decodeUtf8Strict } from './text-policy.mjs';
 import { isInside, validatePortableRelativePath } from './path-policy.mjs';
+import { atomicMutation } from './atomic-mutation.mjs';
 
 export const HOST_POLICY_SCHEMA = 'deadbyte.host-policy.v1';
 export const HOST_POLICY_SCHEMA_V2 = 'deadbyte.host-policy.v2';
@@ -315,32 +312,14 @@ export async function hostFileWrite(policy, { rootId, relativePath, content, enc
   const bytes = decodeWriteContent(content, encoding);
   if (bytes.length > policy.max_write_bytes) throw new Error(`host write exceeds ${policy.max_write_bytes} byte limit`);
 
-  const before = await currentTargetState(lexical);
-  checkExpectedState(before, expectedSha256);
-
-  const temp = path.join(path.dirname(lexical), `.${path.basename(lexical)}.deadbyte-${process.pid}-${randomBytes(8).toString('hex')}.tmp`);
-  let handle;
-  try {
-    await authorityCheck();
-    handle = await open(temp, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
-    await handle.writeFile(bytes);
-    await handle.sync();
-    await handle.close();
-    handle = null;
-
-    const raceCheck = await currentTargetState(lexical);
-    checkExpectedState(raceCheck, expectedSha256);
-    await authorityCheck();
-    await rename(temp, lexical);
-  } catch (error) {
-    if (handle) await handle.close().catch(() => {});
-    await rm(temp, { force: true }).catch(() => {});
-    throw error;
-  }
-
-  const after = await currentTargetState(lexical);
-  const expectedAfter = sha256Bytes(bytes);
-  if (!after.exists || after.sha256 !== expectedAfter) throw new Error('host write post-commit hash mismatch');
+  const { before, after } = await atomicMutation({
+    target: lexical,
+    bytes,
+    expected: expectedSha256,
+    readState: currentTargetState,
+    assertExpected: checkExpectedState,
+    authorityCheck
+  });
   return {
     previous_sha256: before.sha256,
     sha256: after.sha256,

package/src/machine-fs-mcp-tools.mjs

@@ -10,7 +10,13 @@ const rel = z.string().min(1).max(2048);
 const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
 const expectedFile = z.string().regex(/^(?:absent|[0-9a-f]{64})$/);
 const ok = (schema, value) => machineFsStructuredResult(schema, value, false);
-const fail = (schema, error) => machineFsStructuredResult(schema, { status:'denied', error:String(error) }, true);
+const fail = (schema, error) => {
+  const unknown=error?.side_effect_state==='unknown'&&error?.outcome==='FAILED_AFTER_UNKNOWN_EFFECT';
+  return machineFsStructuredResult(schema, {
+    status:unknown?'failed':'denied',error:String(error),
+    ...(unknown?{outcome:error.outcome,side_effect_state:'unknown',expected_after_sha256:error.expected_after_sha256}: {})
+  }, true);
+};
 
 export function registerMachineFsTools(server, { runtime }) {
   if (!server || !runtime) throw new Error('machine fs tool registration requires server/runtime');

package/src/machine-fs-output-contracts.mjs

@@ -7,6 +7,11 @@ const pathText = z.string().min(1).max(2048);
 const statusOk = z.enum(['ok','denied','failed']);
 const statusCommit = z.enum(['committed','denied','failed']);
 const error = z.string().min(1).max(4096).optional();
+const unknownEffect = {
+  outcome: z.literal('FAILED_AFTER_UNKNOWN_EFFECT').optional(),
+  side_effect_state: z.literal('unknown').optional(),
+  expected_after_sha256: hex64.optional()
+};
 
 export const machineFsStatOutputSchema = z.strictObject({
   status: statusOk, error,
@@ -38,6 +43,7 @@ export const machineFsReadOutputSchema = z.strictObject({
 
 const commitBase = {
   status: statusCommit, error,
+  ...unknownEffect,
   root_id: z.string().min(1).max(64).optional(),
   receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional()
 };

package/src/mcp-server.mjs

@@ -5,6 +5,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { DeadbyteStdioServerTransport } from './stdio-protocol-guard.mjs';
 import * as z from 'zod/v4';
 import { executeProof } from './executor.mjs';
 import { CONTAINED_TRANSFORM_OPERATIONS, executeContainedTransform } from './contained-executor.mjs';
@@ -529,7 +530,18 @@ serveStdio(() => {
           });
           return textResult(hostFileWriteOutputSchema, { status: 'committed', root_id, path: relativePath, ...result });
         } catch (error) {
-          return textResult(hostFileWriteOutputSchema, { status: 'denied', error: String(error) }, true);
+          const unknown = error?.outcome === 'FAILED_AFTER_UNKNOWN_EFFECT'
+            && error?.side_effect_state === 'unknown'
+            && /^[0-9a-f]{64}$/.test(error?.expected_after_sha256 ?? '');
+          return textResult(hostFileWriteOutputSchema, {
+            status: unknown ? 'failed' : 'denied',
+            error: String(error),
+            ...(unknown ? {
+              outcome: error.outcome,
+              side_effect_state: error.side_effect_state,
+              expected_after_sha256: error.expected_after_sha256
+            } : {})
+          }, true);
         }
       }
     );
@@ -618,4 +630,4 @@ serveStdio(() => {
   }
 
   return server;
-}, { legacy: 'reject' });
+}, { legacy: 'reject', transport: new DeadbyteStdioServerTransport() });

package/src/output-contracts.mjs

@@ -217,13 +217,15 @@ export const hostFileReadOutputSchema = statusContract({
 });
 
 export const hostFileWriteOutputSchema = statusContract({
-  statuses: ['committed', 'denied'],
+  statuses: ['committed', 'denied', 'failed'],
   shape: {
     root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
     previous_sha256: hex64.nullable().optional(), sha256: hex64.optional(),
-    bytes: z.number().int().min(0).optional(), created: z.boolean().optional()
+    bytes: z.number().int().min(0).optional(), created: z.boolean().optional(),
+    outcome: z.literal('FAILED_AFTER_UNKNOWN_EFFECT').optional(),
+    side_effect_state: z.literal('unknown').optional(), expected_after_sha256: hex64.optional()
   },
-  successStatuses: ['committed'], successRequired: ['root_id', 'path', 'previous_sha256', 'sha256', 'bytes', 'created'], errorStatuses: ['denied']
+  successStatuses: ['committed'], successRequired: ['root_id', 'path', 'previous_sha256', 'sha256', 'bytes', 'created'], errorStatuses: ['denied', 'failed']
 });
 
 export const hostExecOutputSchema = z.strictObject({
@@ -265,4 +267,4 @@ export function structuredToolResult(schema, object, isError = false) {
     structuredContent: parsed.data,
     content: [{ type: 'text', text: JSON.stringify(parsed.data) }]
   };
-}
+}

package/src/remote-live-log.mjs

@@ -1,8 +1,9 @@
+import path from 'node:path';
 import { canonicalJson } from './canonical-json.mjs';
 import { sanitizeAuditArgs } from './tool-audit.mjs';
 import { remoteDisplayText, REMOTE_DISPLAY_MODES } from './remote-console.mjs';
 
-const SAFE_ARG_KEYS=Object.freeze(['root_id','path','pattern','command_id','profile_id','session_id','goal_id','task_id','step_id','mode']);
+const SAFE_ARG_KEYS=Object.freeze(['root_id','path','pattern','command_id','profile_id','session_id','goal_id','task_id','step_id','mode','op']);
 const LIFECYCLE=Object.freeze({
   device_start:'🚀 [DEVICE] Starting DEADBYTE MCP...',
   bridge_connected:'🔌 [BRIDGE] Local bridge connected',
@@ -74,19 +75,47 @@ function shortValue(value,max=12){
 function payloadByteCount(value){
   return value&&typeof value==='object'&&value.redacted===true&&Number.isFinite(Number(value.byte_count))?Number(value.byte_count):null;
 }
-function rootPath(args){
-  const root=safeAtom(args?.root_id);const p=safeAtom(args?.path);
-  if(root&&p) return root+':'+p;
-  return root||p||'';
-}
-export function summarizeLiveToolArgs(tool,rawArgs){
-  const args=sanitizeAuditArgs(rawArgs??{});const where=rootPath(args);
-  if(/(?:file_read|files_read)$/.test(tool)) return where;
-  if(/file_write$/.test(tool)){const bytes=payloadByteCount(args.content);return [where,bytes!==null?'('+bytes+'B)':''].filter(Boolean).join(' ');}
-  if(/text_replace$|symbol_replace$/.test(tool)){const bytes=payloadByteCount(args.new_string);return [where,bytes!==null?'('+bytes+'B new)':''].filter(Boolean).join(' ');}
-  if(/coding_tree$/.test(tool)) return where;
-  if(/coding_(?:search|inspect)$/.test(tool)) return [where,args.pattern?'\"'+clipped(String(args.pattern),36)+'\"':'',args.op?String(args.op):''].filter(Boolean).join(' ');
-  if(/(?:command|benchmark)_run$/.test(tool)) return [safeAtom(args.root_id),safeAtom(args.command_id),safeAtom(args.script_path)].filter(Boolean).join(' ');
+function safePathAtom(value){
+  if(typeof value!=='string'||value.length<1||value.length>2048||/[\r\n\0]/.test(value)) return null;
+  return value;
+}
+function rootedPath(args,key='path',rootPaths={}){
+  const root=safeAtom(args?.root_id);const p=safePathAtom(args?.[key]);
+  if(root&&p){
+    const base=safePathAtom(rootPaths?.[root]);
+    if(base){
+      const flavor=/^(?:[A-Za-z]:[\\/]|\\\\)/.test(base)?path.win32:path.posix;
+      const absolute=p==='.'?flavor.resolve(base):flavor.resolve(base,p);
+      return absolute+' [root='+root+']';
+    }
+    return root+':'+p;
+  }
+  if(root) return 'root='+root;
+  return p?'path='+p:'';
+}
+function displayToolName(tool,args){
+  const op=safeAtom(args?.op);
+  if(op&&['machine_fs','coding_inspect','process_session','desktop_control','machine_observe'].includes(tool)) return tool+'.'+op;
+  return tool;
+}
+export function summarizeLiveToolArgs(tool,rawArgs,{rootPaths={}}={}){
+  const args=sanitizeAuditArgs(rawArgs??{});const where=rootedPath(args,'path',rootPaths);
+  if(/(?:file_read|files_read)$/.test(tool)||/^machine_fs\.(?:read|stat|list)$/.test(tool)) return where;
+  if(/file_write$/.test(tool)||/^machine_fs\.write$/.test(tool)){const bytes=payloadByteCount(args.content);return [where,bytes!==null?'('+bytes+'B)':''].filter(Boolean).join(' ');}
+  if(/text_replace$|symbol_replace$/.test(tool)||/^machine_fs\.edit_exact$/.test(tool)){const bytes=payloadByteCount(args.new_string);return [where,bytes!==null?'('+bytes+'B new)':''].filter(Boolean).join(' ');}
+  if(/^machine_fs\.(?:mkdir|delete)$/.test(tool)||/coding_tree$/.test(tool)) return where;
+  if(/^machine_fs\.move$/.test(tool)) return [
+    rootedPath({...args,path:args.source_path},'path',rootPaths),
+    '->',
+    rootedPath({...args,path:args.destination_path},'path',rootPaths)
+  ].filter(Boolean).join(' ');
+  if(/coding_(?:search|inspect)(?:\.|$)/.test(tool)) return [where,args.pattern?'\"'+clipped(String(args.pattern),36)+'\"':''].filter(Boolean).join(' ');
+  if(/(?:command|benchmark)_run$/.test(tool)){
+    const root=safeAtom(args.root_id);const command=safeAtom(args.command_id);const scriptPath=safePathAtom(args.script_path);
+    if(root&&safePathAtom(rootPaths?.[root])) return [rootedPath({...args,path:scriptPath},'path',rootPaths),command].filter(Boolean).join(' ');
+    return [root,command,scriptPath].filter(Boolean).join(' ');
+  }
+  if(/^host_exec$/.test(tool)) return [rootedPath(args,'path',rootPaths),safeAtom(args.command_id),safeAtom(args.mode)].filter(Boolean).join(' ');
   if(/^machine_(?:ping|status|system_status|list)$/.test(tool)) return safeAtom(args.nonce)?'nonce='+shortValue(String(args.nonce),24):'';
   if(/^process_session/.test(tool)) return [safeAtom(args.profile_id),shortValue(safeAtom(args.session_id)||'',12),safeAtom(args.op)].filter(Boolean).join(' ');
   if(/^desktop_/.test(tool)) return [shortValue(safeAtom(args.frame_id)||'',10),shortValue(safeAtom(args.target_id)||'',10),safeAtom(args.op)].filter(Boolean).join(' ');
@@ -98,11 +127,11 @@ function categoryForTool(tool){
   if(/^autonomous_/.test(tool)) return 'autonomous';
   if(HEARTBEAT_TOOLS.has(tool)) return 'heartbeat';
   if(/(?:receipt_verify|evidence_verify|goal_verify|task_verify|audit|release_gate|native_diff_verify)/.test(tool)) return 'verify';
-  if(/(?:search|inspect|symbol_(?:definition|references|implementations|outline|diagnostics)|_stat$|_tree$)/.test(tool)) return 'search';
-  if(/(?:file_read|files_read|machine_fs_read|process_session_read)/.test(tool)) return 'read';
-  if(/(?:file_write|machine_fs_write|mkdir|move|delete)/.test(tool)) return 'write';
+  if(/(?:search|inspect|symbol_(?:definition|references|implementations|outline|diagnostics)|(?:^|[._])stat$|(?:^|[._])list$|_tree$)/.test(tool)) return 'search';
+  if(/(?:file_read|files_read|machine_fs[._]read|process_session[._]read|host_file_read)/.test(tool)) return 'read';
+  if(/(?:file_write|machine_fs[._]write|host_file_write|(?:^|[._])mkdir$|(?:^|[._])move$|(?:^|[._])delete$)/.test(tool)) return 'write';
   if(/(?:replace|edit_exact|native_diff_apply)/.test(tool)) return 'edit';
-  if(/(?:command_run|benchmark_run|task_run|goal_run|process_session_(?:start|action|terminate))/.test(tool)) return 'run';
+  if(/(?:command_run|benchmark_run|task_run|goal_run|process_session[._](?:start|action|terminate)|host_exec)/.test(tool)) return 'run';
   if(/^process_/.test(tool)) return 'process';
   return 'generic';
 }
@@ -110,7 +139,10 @@ function iconForTool(tool,displayMode='unicode'){
   const icons=displayMode==='ascii'?TOOL_ICONS_ASCII:TOOL_ICONS;
   return icons[categoryForTool(tool)]??icons.generic;
 }
-function visibleStart(tool){return START_VISIBLE_PATTERNS.some(pattern=>pattern.test(tool));}
+function visibleStart(tool){
+  if(['write','edit','run'].includes(categoryForTool(tool))) return true;
+  return START_VISIBLE_PATTERNS.some(pattern=>pattern.test(tool));
+}
 
 function displayTimestamp(ms){
   const shifted=new Date(ms+DISPLAY_UTC_OFFSET_MINUTES*60*1000).toISOString();
@@ -189,24 +221,121 @@ export function createLiveActivityTracker(){
 function shortSpanId(requestId){
   return typeof requestId==='string'&&requestId.length?requestId.slice(0,8):'????????';
 }
+function traceIdentity(event,args=event?.args??{}){
+  const context=event?.context&&typeof event.context==='object'&&!Array.isArray(event.context)?event.context:{};
+  const first=(...values)=>values.map(safeAtom).find(Boolean)||null;
+  const spanId=safeAtom(event?.request_id);
+  return {
+    trace_id:first(context.trace_id,context.job_id,context.session_id,args.goal_id,args.task_id,args.job_id,args.session_id,spanId),
+    span_id:spanId,
+    parent_span_id:first(context.parent_span_id,context.parent_request_id)
+  };
+}
+function shortTraceValue(value,displayMode){
+  if(typeof value!=='string'||!value) return '';
+  if(value.length<=8) return value;
+  return value.slice(0,8)+(displayMode==='ascii'?'...':'…');
+}
+function traceText(meta,displayMode='unicode'){
+  if(!meta?.trace_id||!meta?.span_id) return '';
+  return 'trace='+shortTraceValue(meta.trace_id,displayMode)+' span='+shortTraceValue(meta.span_id,displayMode)+
+    (meta.parent_span_id?' parent='+shortTraceValue(meta.parent_span_id,displayMode):'');
+}
+function outcomeClass(event){
+  if(event?.outcome?.side_effect_state==='unknown') return 'unknown';
+  return event?.outcome?.is_error===true?'error':'ok';
+}
+function parseFilterExpression(expression){
+  if(expression===null||expression===undefined||expression==='') return Object.freeze({});
+  if(typeof expression!=='string'||expression.length>512) throw new Error('timeline filter invalid');
+  const out={};
+  for(const raw of expression.split(',')){
+    const part=raw.trim();if(!part) continue;
+    const at=part.indexOf('=');if(at<1||at===part.length-1) throw new Error('timeline filter term must be key=value');
+    const key=part.slice(0,at).trim();const value=part.slice(at+1).trim();
+    if(!['tool','category','status','trace'].includes(key)) throw new Error(`timeline filter key '${key}' unsupported`);
+    if(Object.hasOwn(out,key)) throw new Error(`timeline filter key '${key}' repeated`);
+    if(key==='status'&&!['ok','error','unknown'].includes(value)) throw new Error('timeline filter status invalid');
+    if(key==='category'&&!Object.hasOwn(TOOL_ICONS,value)) throw new Error('timeline filter category invalid');
+    out[key]=value;
+  }
+  return Object.freeze(out);
+}
+function toolFilterMatch(pattern,tool){
+  if(!pattern) return true;
+  return pattern.endsWith('*')?tool.startsWith(pattern.slice(0,-1)):tool===pattern;
+}
+export function createLiveTimelineFilter(expression=''){
+  const spec=parseFilterExpression(expression);
+  const pending=new Map();
+  const baseMatch=meta=>(!spec.tool||toolFilterMatch(spec.tool,meta.tool))&&(!spec.category||spec.category===meta.category)&&(!spec.trace||spec.trace===meta.trace_id);
+  return Object.freeze({
+    accept(event){
+      if(!event||typeof event!=='object'||Array.isArray(event)) return false;
+      const requestId=safeAtom(event.request_id);const rawTool=safeAtom(event.tool);
+      if(!requestId||!rawTool) return false;
+      if(event.event_type==='tool.request'){
+        const args=event.args??{};const tool=displayToolName(rawTool,args);const trace=traceIdentity(event,args);
+        const meta={tool,category:categoryForTool(tool),trace_id:trace.trace_id};
+        pending.set(requestId,meta);
+        return spec.status?false:baseMatch(meta);
+      }
+      if(event.event_type==='tool.result'){
+        const meta=pending.get(requestId)??{tool:rawTool,category:categoryForTool(rawTool),trace_id:traceIdentity(event).trace_id};
+        pending.delete(requestId);
+        return baseMatch(meta)&&(!spec.status||spec.status===outcomeClass(event));
+      }
+      return false;
+    },
+    spec
+  });
+}
+export function createLiveTimelineWriter({stream=process.stdout,displayMode='unicode',rewrite=true}={}){
+  if(!stream||typeof stream.write!=='function') throw new Error('timeline writer stream invalid');
+  if(!REMOTE_DISPLAY_MODES.includes(displayMode)) throw new Error('timeline writer display mode invalid');
+  if(typeof rewrite!=='boolean') throw new Error('timeline writer rewrite invalid');
+  let active=null;
+  function flush(){
+    if(active){stream.write('\n');active=null;}
+  }
+  function write(line,{event_type=null,request_id=null}={}){
+    if(typeof line!=='string'||!line) return;
+    const tty=stream.isTTY===true&&rewrite;
+    if(!tty){stream.write(line+'\n');return;}
+    if(active&&event_type==='tool.result'&&request_id&&request_id===active.request_id){
+      stream.write('\r\x1b[2K'+line+'\n');active=null;return;
+    }
+    if(active) flush();
+    if(event_type==='tool.call'&&request_id){stream.write(line);active={request_id};return;}
+    stream.write(line+'\n');
+  }
+  return Object.freeze({write,flush,pending(){return active?{...active}:null;}});
+}
 
-export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,heartbeatBurstLimit=10,heartbeatWindowMs=3000,displayMode='unicode'}={}){
+export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,heartbeatBurstLimit=10,heartbeatWindowMs=3000,displayMode='unicode',rootPaths={},trace=false}={}){
   if(typeof clock!=='function') throw new Error('live timeline clock must be a function');
   if(!REMOTE_DISPLAY_MODES.includes(displayMode)) throw new Error('remote display mode invalid');
   if(!Number.isInteger(heartbeatBurstLimit)||heartbeatBurstLimit<2||heartbeatBurstLimit>100) throw new Error('heartbeatBurstLimit invalid');
   if(!Number.isInteger(heartbeatWindowMs)||heartbeatWindowMs<250||heartbeatWindowMs>60000) throw new Error('heartbeatWindowMs invalid');
+  if(!rootPaths||typeof rootPaths!=='object'||Array.isArray(rootPaths)) throw new Error('live timeline rootPaths invalid');
+  if(typeof trace!=='boolean') throw new Error('live timeline trace invalid');
   const pending=new Map();
   const completed=new Set();
   const toolCounts=new Map();
-  let resultCount=0,errorCount=0,totalDurationMs=0,burst=null,foldedHeartbeatLines=0;
+  const durationSamples=[];
+  let resultCount=0,okCount=0,errorCount=0,unknownCount=0,mutationCount=0,totalDurationMs=0,slowest=null,burst=null,foldedHeartbeatLines=0;
 
-  function eventPrefix(event,sequence){
+  function eventPrefix(event,sequence,{displayTool=null,icon=null}={}){
     const seq=Number.isSafeInteger(sequence)&&sequence>0?'#'+sequence+'  ':'';
-    return iconForTool(event.tool,displayMode)+'  '+displayClock(eventMs(event,clock))+'  '+seq+'['+shortSpanId(event.request_id)+']  '+event.tool;
+    const tool=displayTool||event.tool;
+    const visual=icon||iconForTool(tool,displayMode);
+    return visual+'  '+displayClock(eventMs(event,clock))+'  '+seq+'['+shortSpanId(event.request_id)+']  '+tool;
   }
+  function traceSuffix(meta){return trace&&meta?'  '+traceText(meta,displayMode):'';}
   function resultLine(event,span,sequence){
     const error=event.outcome?.is_error===true;
     const unknown=event.outcome?.side_effect_state==='unknown';
+    const displayTool=span?.display_tool||event.tool;
     const duration=Number.isFinite(Number(event.outcome?.duration_ms))
       ?formatDuration(event.outcome.duration_ms)
       :span?formatDuration(Math.max(0,clock()-span.started_at_ms)):'';
@@ -214,8 +343,17 @@ export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,he
     const rawReason=typeof event.outcome?.reason==='string'&&event.outcome.reason?event.outcome.reason:
       (unknown&&typeof event.outcome?.recovery?.reason==='string'?event.outcome.recovery.reason:'');
     const reason=rawReason?clipped(rawReason,180):(unknown?'terminal result unavailable; inspect state before retry':'');
-    const marker=unknown?'OUTCOME_UNKNOWN':error?(displayMode==='ascii'?'ERR':'✗'):(displayMode==='ascii'?'OK':'✓');
-    return remoteDisplayText(eventPrefix(event,sequence)+(summary?'  '+summary:'')+(duration?'  '+duration:'')+'  '+marker+(reason?' — '+reason:''),displayMode);
+    const category=categoryForTool(displayTool);
+    const receipt=Array.isArray(event.outcome?.receipt_sha256s)&&typeof event.outcome.receipt_sha256s[0]==='string'
+      ?shortValue(event.outcome.receipt_sha256s[0],8):'';
+    const marker=unknown?'FAILED_AFTER_UNKNOWN_EFFECT':
+      error?(displayMode==='ascii'?'ERR':'✗'):
+      ['write','edit','run'].includes(category)?(displayMode==='ascii'?'SUCCEEDED':'✅ SUCCEEDED'):
+      (displayMode==='ascii'?'OK':'✓');
+    const prefixIcon=unknown?(displayMode==='ascii'?'WARN':'⚠️'):null;
+    const evidence=receipt?'  '+(displayMode==='ascii'?'RECEIPT':'🧾 receipt')+(displayMode==='ascii'?'=':'=')+receipt:'';
+    const reasonSep=displayMode==='ascii'?' - ':' — ';
+    return remoteDisplayText(eventPrefix(event,sequence,{displayTool,icon:prefixIcon})+traceSuffix(span?.trace_meta)+(summary?'  '+summary:'')+(duration?'  '+duration:'')+'  '+marker+evidence+(reason?reasonSep+reason:''),displayMode);
   }
   function burstLine(value){
     if(!value) return null;
@@ -233,12 +371,19 @@ export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,he
     burst=null;
     return line;
   }
-  function addStats(event){
+  function addStats(event,span){
     resultCount++;
-    toolCounts.set(event.tool,(toolCounts.get(event.tool)??0)+1);
+    const displayTool=span?.display_tool||event.tool;
+    toolCounts.set(displayTool,(toolCounts.get(displayTool)??0)+1);
+    const outcome=outcomeClass(event);
+    if(outcome==='unknown') unknownCount++;else if(outcome==='error') errorCount++;else okCount++;
+    if(['write','edit','run'].includes(categoryForTool(displayTool))) mutationCount++;
     const duration=Number(event.outcome?.duration_ms);
-    if(Number.isFinite(duration)&&duration>=0) totalDurationMs+=duration;
-    if(event.outcome?.is_error===true) errorCount++;
+    if(Number.isFinite(duration)&&duration>=0){
+      totalDurationMs+=duration;
+      if(durationSamples.length<2048) durationSamples.push(duration);
+      if(!slowest||duration>slowest.duration_ms) slowest={tool:displayTool,duration_ms:duration};
+    }
   }
   function observe(event,{sequence=null}={}){
     if(!event||typeof event!=='object'||Array.isArray(event)) return null;
@@ -246,10 +391,13 @@ export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,he
     const tool=typeof event.tool==='string'&&event.tool?event.tool:null;
     if(event.event_type==='tool.request'&&requestId&&tool){
       if(pending.has(requestId)||completed.has(requestId)) return null;
-      const summary=summarizeLiveToolArgs(tool,event.args??{});
-      pending.set(requestId,{request_id:requestId,tool,summary,started_at_ms:clock()});
-      if(verbose) return formatRemoteToolCall(event,{clock,displayMode});
-      if(visibleStart(tool)) return eventPrefix(event,sequence)+(summary?'  '+summary:'')+'  …';
+      const args=event.args??{};
+      const displayTool=displayToolName(tool,args);
+      const summary=summarizeLiveToolArgs(displayTool,args,{rootPaths});
+      const traceMeta=traceIdentity(event,args);
+      pending.set(requestId,{request_id:requestId,tool,display_tool:displayTool,summary,trace_meta:traceMeta,started_at_ms:clock()});
+      if(verbose) return formatRemoteToolCall({...event,tool:displayTool},{clock,displayMode})+traceSuffix(traceMeta);
+      if(visibleStart(displayTool)) return eventPrefix(event,sequence,{displayTool})+traceSuffix(traceMeta)+(summary?'  '+summary:'')+'  …';
       return null;
     }
     if(event.event_type==='tool.result'&&requestId&&tool){
@@ -257,7 +405,7 @@ export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,he
       const span=pending.get(requestId)??null;
       pending.delete(requestId);
       completed.add(requestId);
-      addStats(event);
+      addStats(event,span);
       const error=event.outcome?.is_error===true;
       const nowMs=eventMs(event,clock);
       if(HEARTBEAT_TOOLS.has(tool)&&!error){
@@ -297,8 +445,14 @@ export function createLiveTimelineTracker({clock=()=>Date.now(),verbose=false,he
   function summary(){
     const top=[...toolCounts.entries()].sort((a,b)=>b[1]-a[1]||a[0].localeCompare(b[0])).slice(0,3)
       .map(([tool,count])=>tool+'×'+count).join(', ');
-    return remoteDisplayText((displayMode==='ascii'?'[SUMMARY]':'📊 [SUMMARY]')+' '+resultCount+' calls | '+errorCount+' error'+(errorCount===1?'':'s')+
+    const sorted=[...durationSamples].sort((a,b)=>a-b);
+    const p50=sorted.length?(sorted.length%2?sorted[(sorted.length-1)/2]:(sorted[sorted.length/2-1]+sorted[sorted.length/2])/2):null;
+    const p95=sorted.length?sorted[Math.max(0,Math.ceil(sorted.length*0.95)-1)]:null;
+    return remoteDisplayText((displayMode==='ascii'?'[SUMMARY]':'📊 [SUMMARY]')+' '+resultCount+' calls | '+okCount+' ok | '+
+      errorCount+' error'+(errorCount===1?'':'s')+' | '+unknownCount+' unknown | '+mutationCount+' mutation'+(mutationCount===1?'':'s')+
       ' | tool time '+(formatDuration(totalDurationMs)||'0ms')+
+      (p50!==null?' | p50 '+formatDuration(p50)+' | p95 '+formatDuration(p95):'')+
+      (slowest?' | slowest '+slowest.tool+' '+formatDuration(slowest.duration_ms):'')+
       (foldedHeartbeatLines?' | folded '+foldedHeartbeatLines+' heartbeat lines':'')+
       (top?' | top: '+top:''),displayMode);
   }