deadbyte-mcp 0.15.23 → 0.15.24

package/proof/commander-closure-20260928/DIFFERENTIAL-CHECKPOINT.json

@@ -0,0 +1,111 @@
+{
+  "schema": "deadbyte.commander-differential-checkpoint.v1",
+  "status": "INCOMPLETE",
+  "observed_at_utc": "2026-09-28T15:19:36.8198652Z",
+  "source": {
+    "requested_path": "D:\\Projects\\deadbyte-mcp-r36-dev",
+    "requested_path_version": "0.12.0",
+    "actual_successor_workspace": "D:\\Projects\\deadbyte-mcp\\development\\deadbyte-mcp-r42-agentic-dev",
+    "version": "0.15.24",
+    "git_head": "f9037d4847a7204ce4e1f808758ee3f0e9e7a738",
+    "path_drift_classification": "requested source path is a historical snapshot and cannot produce a successor of active 0.15.23"
+  },
+  "reference": {
+    "path": "D:\\Projects\\desktop-commander-stage-20260922\\desktop-commander",
+    "package": "@wonderwhy-er/desktop-commander",
+    "version": "0.2.51",
+    "server_sha256": "dfc303bb7dd2e8d01debac50fc43bb8644d00089bffdf2887e149497cff8b305",
+    "schemas_sha256": "f342345e34e48769dabaefe1b932f09d41e2e207b422f7794a15ee50ffa8f140"
+  },
+  "live": {
+    "release_id": "v0.15.23-c97e3d21e792420e",
+    "release_manifest_sha256": "c97e3d21e792420ea90dada3c1360cd56e4c1f221daa86596d611b0d1ac351ec",
+    "generation_manifest_sha256": "4d2d3a4dc103576c39171c52db3436366e62d8b872bcafa4c55f2adb6d3a1126",
+    "bridge_pid": 2804,
+    "cloud_pid": 13704,
+    "state": "ONLINE",
+    "authority": "Process/Coding/Autonomous/Desktop/Host ARMED standing-grant"
+  },
+  "findings": [
+    {
+      "id": "reference-biff8",
+      "classification": "REFERENCE_DEFECT",
+      "red": "real OLE/BIFF8 fixture is rejected by the reference ExcelJS xlsx reader",
+      "green": "independent BIFF8 fixture test proves reference read rejection and OOXML bytes emitted under .xls",
+      "fixture_sha256": "096168376d0abf282546749fdf6765309f895d12fe81d45c52a2c54bb6c0d139"
+    },
+    {
+      "id": "incremental-pdf-revisions",
+      "classification": "REAL_DEADBYTE_DEFECT_FIXED_IN_SOURCE",
+      "red": "valid independent-oracle-readable incremental PDF failed with PDF duplicate object 3 0",
+      "green": "latest revision accepted only when both revisions are bound by a validated classic xref Prev chain; PDF suite 10/10 PASS"
+    },
+    {
+      "id": "powershell-command-byte-preservation",
+      "classification": "OBSERVED_PASS",
+      "green": "real policy-bound PowerShell REPL preserved variables, quotes, pipe and Unicode and returned more than 1 MiB through bounded chunk reads"
+    },
+    {
+      "id": "atomic-mutation-post-effect-observation",
+      "classification": "REAL_DEADBYTE_DEFECT_FIXED_IN_SOURCE",
+      "red": "machine filesystem, coding, and Host public boundaries collapsed a post-rename observation failure into a generic denied/failed response without uncertainty identity",
+      "green": "shared atomic mutation marks FAILED_AFTER_UNKNOWN_EFFECT with unknown side-effect state and expected-after SHA-256; machine filesystem, coding, and Host structured outputs preserve it"
+    },
+    {
+      "id": "read-file-directory-and-binary-semantics",
+      "classification": "REAL_DEADBYTE_DEFECT_FIXED_IN_SOURCE",
+      "red": "reference returns a bounded recursive listing for read_file(directory) and explicit binary guidance, while DEADBYTE attempted a file read or lossy UTF-8 decoding",
+      "green": "compatibility read_file uses policy-bound stat plus paged listing for directories and deterministic binary classification without replacement-character data loss"
+    },
+    {
+      "id": "docx-outline-and-content-search",
+      "classification": "REAL_DEADBYTE_DEFECT_FIXED_IN_SOURCE",
+      "red": "reference exposes drawing markers, header/footer text, and literal DOCX part search while DEADBYTE omitted those document parts and searched ZIP bytes",
+      "green": "native bounded DOCX parsing now exposes drawing/header/footer evidence and searches document/header/footer w:t parts through deterministic compatibility sessions"
+    }
+  ],
+  "focused_evidence": [
+    {"scope": "schema-search", "tests": 21, "pass": 21, "fail": 0, "skip": 0},
+    {"scope": "documents-wire-url", "tests": 49, "pass": 49, "fail": 0, "skip": 0},
+    {"scope": "biff-reference", "tests": 1, "pass": 1, "fail": 0, "skip": 0},
+    {"scope": "process-adjacent", "tests": 55, "pass": 55, "fail": 0, "skip": 0},
+    {"scope": "mcp-protocol", "tests": 9, "pass": 9, "fail": 0, "skip": 0},
+    {"scope": "mcp-protocol-adversarial", "tests": 3, "pass": 3, "fail": 0, "skip": 0},
+    {"scope": "atomic-mutation-public-boundaries", "tests": 15, "pass": 14, "fail": 0, "skip": 1},
+    {"scope": "full-regression-r48", "files": 211, "batches": 8, "fail": 0, "task_receipt_sha256": "7711039e4807f6c2af02bbda897d0032b067e0a6631f789fd3bf801258160d3f"},
+    {"scope": "npm-audit-production", "vulnerabilities": 0},
+    {"scope": "real-performance-sample", "iterations_per_workload": 50, "reference_byte_pins_verified": true, "status": "HISTORICAL_ONLY_FRESH_RUN_BLOCKED_REFERENCE_RUNTIME_DEPS",
+      "results": {"read_file": {"reference_ops_per_sec": 55, "deadbyte_ops_per_sec": 1058}, "list_directory": {"reference_ops_per_sec": 3818, "deadbyte_ops_per_sec": 1959}, "get_file_info": {"reference_ops_per_sec": 1805, "deadbyte_ops_per_sec": 2231}, "read_multiple_files": {"reference_ops_per_sec": 30, "deadbyte_ops_per_sec": 562}}}
+    ,{"scope": "filesystem-document-search-adjacent", "tests": 54, "pass": 54, "fail": 0, "skip": 0}
+  ],
+  "changed_file_sha256": {
+    "src/commander-pdf-r48.mjs": "23cda18e86daa4163003fb5a80e0069bc19541d454f32a9a38b1d901ee39f26b",
+    "src/coding-search.mjs": "7f15b59bc240d896beddc2057354f8c72f296fe189db30c200d2c84a67d65773",
+    "src/commander-wire-adapter-r47.mjs": "2ac8421b3dcdd52431001ac16ee1be8cc54a5483d6aab9700b118172ce0d44bd",
+    "src/commander-office-reader-r48.mjs": "7379825118da8fae16d63fe7c4d89b0ddb03e7649f3754adae58a4480f8b317f",
+    "test/commander-pdf-r48.test.mjs": "bfc2e6d7e1aa5332c1c81687001cdb5f923a45c5ce64925097fe11fd850e9214",
+    "test/commander-biff-reference-r48.test.mjs": "8e8b20604062a0398214e159729b10bedff334cb44bddfa4b4046b1ae396520f",
+    "test/commander-schema-differential-r48.test.mjs": "fb82a21e8752ccb82cbd6b631f3366bfe5af9a4c5a433db5a128c0a1fe703c66",
+    "test/commander-real-parity-r47.test.mjs": "cad9a9fc42c50e450a3b019e9ed066e7313631015179be7edbbdd094fea00a81"
+    ,"test/commander-wire-contract-r47.test.mjs": "d8e884e241c705b12797f911fb967a4a33b1ec6f3e15b433735882b3de4a34e5"
+    ,"test/commander-office-reader-r48.test.mjs": "abf1eb0977a064101420a0e908a4c2adbf9d606e9873433709910efafa2b4453"
+    ,"test/commander-core-bridge-r47.test.mjs": "16092ed097420b9da99573c1e84f62d011fcb5db069242d70ffd1649c704fd35"
+    ,"src/atomic-mutation.mjs": "622ee1d3c34c50a6343788cc7312e47cb43a87bdace78fb37ca7f51d453b19ad"
+    ,"src/machine-fs-mcp-tools.mjs": "5413fea537f9d72f73e89137b4c750530fbca41598b16bd9ede0e1c272111488"
+    ,"src/machine-fs-output-contracts.mjs": "d94e4478b7e465fa559065e508f65b9ef3eff815a8f2d7b2481bf2a0b05224c9"
+    ,"src/coding-mcp-tools.mjs": "c4e07aa6818cd989c43ce8d027dc7d467e05c8e2fe96b5548eea291285d3bbb1"
+    ,"src/coding-output-contracts.mjs": "059b4bef2ae6a6c2d7a706c463bea6e49d364faeb619372a429ba36c53004ab7"
+    ,"src/host-plane.mjs": "0ff88bce7ee34b22f48a1494efb16586b68c74bd46c608116eb9d9daa65fdc43"
+    ,"src/output-contracts.mjs": "6cbe72d14af097dde78e989bc7b28b48b9cb8990c989d0d40783633f3a7be465"
+    ,"src/mcp-server.mjs": "16e2250e20710b358b304a0bc41bb416ecb9a586c50d5933f6a4eb2230569b21"
+    ,"test/atomic-mutation.test.mjs": "98de1fc43092c27e0fa85f391607494b11e6cc0d53eaf47b6db1ab457c6d6a4b"
+    ,"test/coding-mcp-unknown-effect.test.mjs": "f37e260c2def4c48434b3f251a4cb756a1852843784c08cf6c39dba9045dfb69"
+    ,"scripts/commander-real-performance-benchmark-r47.mjs": "d7806aa408dc7ca74f05feec535ad6cc545f8c61892c51f0fe388bb13d975290"
+  },
+  "release_created": true,
+  "candidate_version": "0.15.24",
+  "publish_attempt": {"status":"BLOCKED_NPM_AUTH","npm_whoami":"E401 Unauthorized","registry_maintainer":"deadbytes <termay10000@gmail.com>","publish_error":"E404 package not found or no permission"},
+  "published": false,
+  "activated": false,
+  "remaining_scope": "restore npm authentication, registry round-trip, successor activation, exact 0.15.23 rollback, exact successor restore and independent final closure"
+}

package/scripts/commander-real-performance-benchmark-r47.mjs

@@ -1,5 +1,5 @@
 import { performance } from 'node:perf_hooks';
-import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -9,7 +9,16 @@ import { loadCodingPolicy } from '../src/coding-plane.mjs';
 import { createMachineFsRuntime } from '../src/machine-fs.mjs';
 
 const N=50;
-const commanderFs=await import(pathToFileURL('D:/Projects/desktop-commander-stage-20260922/desktop-commander/dist/tools/filesystem.js').href);
+const referenceRoot=path.resolve(process.env.DEADBYTE_COMMANDER_REFERENCE_RUNTIME??'D:/Projects/desktop-commander-stage-20260922/desktop-commander');
+const expectedReferenceHashes={
+  'dist/server.js':'dfc303bb7dd2e8d01debac50fc43bb8644d00089bffdf2887e149497cff8b305',
+  'dist/tools/schemas.js':'f342345e34e48769dabaefe1b932f09d41e2e207b422f7794a15ee50ffa8f140'
+};
+for(const [relative,expected] of Object.entries(expectedReferenceHashes)){
+  const actual=createHash('sha256').update(await readFile(path.join(referenceRoot,relative))).digest('hex');
+  if(actual!==expected)throw new Error(`reference byte pin mismatch: ${relative}`);
+}
+const commanderFs=await import(pathToFileURL(path.join(referenceRoot,'dist','tools','filesystem.js')).href);
 const { readFileFromDisk, readMultipleFiles, listDirectory, getFileInfo }=commanderFs;
 const sha=b=>createHash('sha256').update(b).digest('hex');
 const root=await mkdtemp(path.join(os.tmpdir(),'deadbyte-commander-bench-'));
@@ -37,5 +46,5 @@ rows.push(await t('Commander get_file_info',()=>getFileInfo(commanderFile)));
 rows.push(await t('DEADBYTE get_file_info',()=>db.stat({rootId:'bench',relativePath:'a.txt',hash:true})));
 rows.push(await t('Commander read_multiple_files',()=>readMultipleFiles([path.join(commanderDir,'a.txt'),path.join(commanderDir,'b.txt')])));
 rows.push(await t('DEADBYTE read_multiple_files', async()=>{ await db.read({rootId:'bench',relativePath:'a.txt',offset:0,maxBytes:4096}); await db.read({rootId:'bench',relativePath:'b.txt',offset:0,maxBytes:4096}); }));
-console.log(JSON.stringify({schema:'deadbyte.commander-real-performance-benchmark.v1',reference:'@wonderwhy-er/desktop-commander dist local stage',iterations:N,rows},null,2));
+console.log(JSON.stringify({schema:'deadbyte.commander-real-performance-benchmark.v1',reference:'@wonderwhy-er/desktop-commander@0.2.51',reference_hashes:expectedReferenceHashes,iterations:N,rows},null,2));
 await rm(root,{recursive:true,force:true});

package/src/atomic-mutation.mjs

@@ -74,11 +74,19 @@ export async function atomicMutation({
       throw error;
     }
 
-    const after = await readState(target);
     const expectedAfter = sha256Bytes(bytes);
-    if (!after.exists || after.sha256 !== expectedAfter) throw new Error('atomic mutation post-commit hash mismatch');
-    if (verifyPostcondition) await verifyPostcondition({ before, after, expected_after_sha256: expectedAfter });
-    return { before, after, expected_after_sha256: expectedAfter };
+    try {
+      const after = await readState(target);
+      if (!after.exists || after.sha256 !== expectedAfter) throw new Error('atomic mutation post-commit hash mismatch');
+      if (verifyPostcondition) await verifyPostcondition({ before, after, expected_after_sha256: expectedAfter });
+      return { before, after, expected_after_sha256: expectedAfter };
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      failure.outcome = 'FAILED_AFTER_UNKNOWN_EFFECT';
+      failure.side_effect_state = 'unknown';
+      failure.expected_after_sha256 = expectedAfter;
+      throw failure;
+    }
   } finally {
     await releaseLock();
   }

package/src/coding-mcp-tools.mjs

@@ -46,7 +46,21 @@ const taskStep = z.union([
 ]);
 
 function result(schema, value, isError = false) { return codingStructuredResult(schema, value, isError); }
-function fail(schema, error) { return result(schema, { status: 'failed', error: String(error) }, true); }
+function fail(schema, error) {
+  const base = { status: 'failed', error: String(error) };
+  if (error?.outcome === 'FAILED_AFTER_UNKNOWN_EFFECT'
+      && error?.side_effect_state === 'unknown'
+      && HEX64.test(error?.expected_after_sha256 ?? '')) {
+    const enriched = {
+      ...base,
+      outcome: error.outcome,
+      side_effect_state: error.side_effect_state,
+      expected_after_sha256: error.expected_after_sha256
+    };
+    if (schema.safeParse(enriched).success) return result(schema, enriched, true);
+  }
+  return result(schema, base, true);
+}
 export function registerCodingTools(server, { codingRuntime, taskRuntime, semanticRuntime }) {
   if (!codingRuntime || !taskRuntime || !semanticRuntime) throw new Error('coding tool registration requires runtimes');
 

package/src/coding-output-contracts.mjs

@@ -168,7 +168,9 @@ export const codingSymbolReplaceOutputSchema = statusContract({
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), previous_sha256: hex64.optional(),
     sha256: hex64.optional(), bytes: z.number().int().min(0).optional(), replacements: z.literal(1).optional(),
     receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional(),
-    symbol_id: hex64.optional(), symbol_name: z.string().min(1).max(256).optional(), engine: z.string().min(1).max(64).optional() },
+    symbol_id: hex64.optional(), symbol_name: z.string().min(1).max(256).optional(), engine: z.string().min(1).max(64).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','replacements','receipt_id','receipt_sha256','request_sha256','symbol_id','symbol_name','engine']
 });
 
@@ -189,14 +191,18 @@ export const codingFileWriteOutputSchema = statusContract({
   statuses: ['committed', '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(), receipt_id: receiptId.optional(),
-    receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+    receipt_sha256: hex64.optional(), request_sha256: hex64.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', 'receipt_id', 'receipt_sha256', 'request_sha256']
 });
 export const codingTextReplaceOutputSchema = statusContract({
   statuses: ['committed', 'failed'],
   shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), previous_sha256: hex64.optional(),
     sha256: hex64.optional(), bytes: z.number().int().min(0).optional(), replacements: z.number().int().min(1).max(64).optional(),
-    receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+    receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.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', 'replacements', 'receipt_id', 'receipt_sha256', 'request_sha256']
 });
 export const codingCommandRunOutputSchema = statusContract({

package/src/commander-office-reader-r48.mjs

@@ -140,7 +140,7 @@ function prettyXml(xml){
   }
   return lines.join('\n');
 }
-function docxOutline(xml){
+function docxOutline(xml,files){
   const body=xml.match(/<w:body\b[^>]*>([\s\S]*?)<\/w:body>/)?.[1];
   if(body===undefined) return '[No w:body found in document.xml]';
   const elements=[...body.matchAll(/<w:(p|tbl)\b[\s\S]*?<\/w:\1>/g)].map(m=>({kind:m[1],xml:m[0]}));
@@ -152,6 +152,8 @@ function docxOutline(xml){
       let line=`[${i}] w:p`;
       if(style) line+=` style="${xmlDecode(style)}"`;
       const value=wordText(item.xml);
+      const hasDrawing=item.xml.includes('<w:drawing')||item.xml.includes('<mc:AlternateContent');
+      if(hasDrawing) line+=value?' (+ drawing/image)':` [drawing/image, ${(Buffer.byteLength(item.xml)/1024).toFixed(1)}KB]`;
       if(value) line+='\n  '+value;
       lines.push(line);
     }else{
@@ -163,7 +165,15 @@ function docxOutline(xml){
       }
     }
   }
-  return lines.join('\n');
+  const headersFooters=[];
+  for(const [name,bytes] of [...files.entries()].sort(([a],[b])=>a.localeCompare(b))){
+    if(!/^word\/(?:header|footer)[^/]*\.xml$/i.test(name)) continue;
+    try{
+      const value=wordText(decodeUtf8(bytes,name));
+      headersFooters.push(`${name.slice('word/'.length)}: ${value?`"${value.length>100?value.slice(0,100)+'...':value}"`:'(no text content)'}`);
+    }catch{/* malformed optional part is omitted; document.xml remains authoritative */}
+  }
+  return lines.join('\n')+(headersFooters.length?`\n\nHeaders/Footers:\n${headersFooters.join('\n')}`:'');
 }
 
 export function readDocxBytes(input,{path:displayPath='document.docx',offset=0,length=1000}={}){
@@ -180,11 +190,34 @@ export function readDocxBytes(input,{path:displayPath='document.docx',offset=0,l
     return {content:`[DOCX XML: lines ${start}-${Math.max(start,start+sliced.length-1)} of ${totalLines} (${remaining} remaining)]\n${sliced.join('\n')}`,
       mimeType:'application/xml',metadata:{isDocx:true,lineCount:totalLines},outline:false};
   }
-  const outline=docxOutline(xml);
+  const outline=docxOutline(xml,files);
   const rawSizeKB=(Buffer.byteLength(xml)/1024).toFixed(1);
   return {content:`${outline}\n\nRaw XML: ${totalLines} lines, ${rawSizeKB}KB.`,mimeType:'text/plain',metadata:{isDocx:true,lineCount:totalLines},outline:true};
 }
 
+export function searchDocxTextBytes(input,{pattern,ignoreCase=true,maxResults=500}={}){
+  if(typeof pattern!=='string'||pattern.length<1||pattern.length>4096) throw new Error('DOCX search pattern invalid');
+  if(!Number.isInteger(maxResults)||maxResults<1||maxResults>5000) throw new Error('DOCX search maxResults invalid');
+  const files=unzipOffice(input),needle=ignoreCase?pattern.toLowerCase():pattern,results=[];
+  const names=[...files.keys()].filter(name=>name==='word/document.xml'||/^word\/(?:header|footer)[^/]*\.xml$/i.test(name)).sort((a,b)=>{
+    if(a==='word/document.xml')return -1;if(b==='word/document.xml')return 1;return a.localeCompare(b);
+  });
+  for(const name of names){
+    let xml;
+    try{xml=decodeUtf8(files.get(name),name);}catch{continue;}
+    let line=0;
+    for(const match of xml.matchAll(/<w:t(?:\s[^>]*)?>([^<]*)<\/w:t>/g)){
+      const value=xmlDecode(match[1]??'');if(!value.trim())continue;line++;
+      const haystack=ignoreCase?value.toLowerCase():value,index=haystack.indexOf(needle);
+      if(index<0)continue;
+      const start=Math.max(0,index-50),end=Math.min(value.length,index+needle.length+50);
+      results.push({part:name,line,match:`${start>0?'...':''}${value.slice(start,end)}${end<value.length?'...':''}`});
+      if(results.length>=maxResults)return results;
+    }
+  }
+  return results;
+}
+
 
 export function createDocxBytes(content){
   if(typeof content!=='string') throw new Error('DOCX content must be string');

package/src/commander-pdf-r48.mjs

@@ -110,6 +110,37 @@ export function parseDeadbytePdf(input){
 const MAX_GENERIC_OBJECTS=10000;
 const MAX_GENERIC_STREAM_BYTES=16*1024*1024;
 
+function classicIncrementalObjectOffsets(text){
+  const starts=[...text.matchAll(/startxref\s+(\d+)\s+%%EOF/g)];
+  if(starts.length<2)return new Map();
+  const offsets=new Map(),visited=new Set();
+  let cursor=Number(starts.at(-1)[1]);
+  while(Number.isSafeInteger(cursor)&&cursor>=0&&!visited.has(cursor)){
+    visited.add(cursor);
+    if(text.slice(cursor,cursor+4)!=='xref')return new Map();
+    const trailerAt=text.indexOf('trailer',cursor+4);
+    if(trailerAt<0)return new Map();
+    const lines=text.slice(cursor+4,trailerAt).trim().split(/\r?\n/);
+    for(let i=0;i<lines.length;){
+      const header=lines[i++].trim().match(/^(\d+)\s+(\d+)$/);if(!header)return new Map();
+      const first=Number(header[1]),count=Number(header[2]);
+      if(!Number.isSafeInteger(first)||!Number.isSafeInteger(count)||count<0||count>MAX_GENERIC_OBJECTS)return new Map();
+      for(let n=0;n<count;n++){
+        const entry=lines[i++]?.trim().match(/^(\d{10})\s+(\d{5})\s+([nf])$/);if(!entry)return new Map();
+        if(entry[3]==='n'){
+          const key=`${first+n} ${Number(entry[2])}`;
+          const list=offsets.get(key)??[];list.push(Number(entry[1]));offsets.set(key,list);
+        }
+      }
+    }
+    const trailerEnd=text.indexOf('startxref',trailerAt+7);if(trailerEnd<0)return new Map();
+    const prev=text.slice(trailerAt+7,trailerEnd).match(/\/Prev\s+(\d+)/)?.[1];
+    if(prev===undefined)break;
+    const next=Number(prev);if(!Number.isSafeInteger(next)||next>=cursor)return new Map();cursor=next;
+  }
+  return offsets;
+}
+
 function decodePdfTextBytes(bytes){
   if(bytes.length>=2&&bytes[0]===0xfe&&bytes[1]===0xff){
     let out='';
@@ -186,6 +217,7 @@ function parseGenericPdfObjects(bytes){
   const text=bytes.toString('latin1');
   if(!text.startsWith('%PDF-')) throw new Error('invalid PDF header');
   if(/\/Encrypt\b/.test(text)) throw new Error('encrypted PDF is unsupported');
+  const incrementalOffsets=classicIncrementalObjectOffsets(text);
   const objects=new Map(),header=/(\d+)\s+(\d+)\s+obj\b/g;
   let match,count=0;
   while((match=header.exec(text))){
@@ -193,7 +225,10 @@ function parseGenericPdfObjects(bytes){
     const end=text.indexOf('endobj',header.lastIndex);
     if(end<0) throw new Error(`PDF object ${match[1]} ${match[2]} missing endobj`);
     const key=`${match[1]} ${match[2]}`;
-    if(objects.has(key)) throw new Error(`PDF duplicate object ${key}`);
+    if(objects.has(key)){
+      const revisions=incrementalOffsets.get(key)??[];
+      if(!revisions.includes(objects.get(key).offset)||!revisions.includes(match.index)) throw new Error(`PDF duplicate object ${key}`);
+    }
     objects.set(key,{id:Number(match[1]),generation:Number(match[2]),body:text.slice(header.lastIndex,end),offset:match.index});
     header.lastIndex=end+6;
   }

package/src/commander-wire-adapter-r47.mjs

@@ -2,8 +2,9 @@ import * as z from 'zod/v4';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { readCommanderUrl } from './commander-url-reader-r48.mjs';
-import { readDocxBytes, createDocxBytes, editDocxBytes, readXlsxBytes, editXlsxBytes, createXlsxBytes, appendXlsxBytes } from './commander-office-reader-r48.mjs';
+import { readDocxBytes, searchDocxTextBytes, createDocxBytes, editDocxBytes, readXlsxBytes, editXlsxBytes, createXlsxBytes, appendXlsxBytes } from './commander-office-reader-r48.mjs';
 import { editDeadbytePdf, parseDeadbytePdf, readPdfText } from './commander-pdf-r48.mjs';
+import { decodeUtf8Strict } from './text-policy.mjs';
 
 const sha256Bytes = bytes => createHash('sha256').update(bytes).digest('hex');
 const RDC_PROCESS_READ_CHUNK=256*1024;
@@ -122,6 +123,19 @@ function absoluteFor(runtime,rootId,relativePath){
 function linesFrom(bytes){
   return Buffer.from(bytes,'base64').toString('utf8').replaceAll('\\r\\n','\\n').replaceAll('\\r','\\n').split('\\n');
 }
+function isUnknownBinary(bytes){
+  if(bytes.includes(0)) return true;
+  try{decodeUtf8Strict(bytes);return false;}catch{return true;}
+}
+function directoryRows(entries,baseRelative){
+  const base=String(baseRelative??'.').replaceAll('\\','/').replace(/^\.\//,'').replace(/\/$/,'');
+  return entries.map(entry=>{
+    const raw=String(entry.path??'').replaceAll('\\','/').replace(/^\.\//,'');
+    const relative=base&&base!=='.'&&raw.startsWith(`${base}/`)?raw.slice(base.length+1):raw;
+    const display=process.platform==='win32'?relative.replaceAll('/','\\'):relative;
+    return `${(entry.kind??entry.type)==='directory'?'[DIR]':'[FILE]'} ${display}`;
+  });
+}
 function rdcFileResult(pathname,data){
   return {
     path:pathname,content:data.content,mimeType:data.mime_type,
@@ -171,6 +185,17 @@ export function createCommanderWireAdapter({machineFsRuntime=null,processRuntime
     }
     if(!machineFsRuntime) throw new Error('machine filesystem runtime is disabled');
     const target=resolveRdcPath(machineFsRuntime,args.path);
+    if(typeof machineFsRuntime.stat==='function'){
+      const info=await machineFsRuntime.stat({rootId:target.rootId,relativePath:target.relativePath,hash:false});
+      if(info?.kind==='directory'){
+        const listing=await listDirectory({path:args.path,depth:2});
+        const entries=listing.structuredContent?.entries??[];
+        const rows=directoryRows(entries,target.relativePath);
+        const content=`This is a directory, not a file. Use the list_directory tool instead of read_file for directories.\n\n${rows.join('\n')}`;
+        return text(content,false,{path:args.path,content,mimeType:'text/plain',isImage:false,isPdf:false,isDirectory:true,
+          entries,truncated:listing.structuredContent?.truncated===true,entryCount:entries.length});
+      }
+    }
     const ext=path.extname(args.path).toLowerCase();
     const richDocument=ext==='.docx'||ext==='.xlsx'||ext==='.xlsm'||ext==='.pdf';
     const imageMime={'.png':'image/png','.jpg':'image/jpeg','.jpeg':'image/jpeg','.gif':'image/gif','.webp':'image/webp'}[ext];
@@ -238,6 +263,10 @@ export function createCommanderWireAdapter({machineFsRuntime=null,processRuntime
     if(ext==='.xls') {
       throw new Error('format .xls requires a native BIFF adapter; request rejected rather than returned as plain text');
     }
+    if(isUnknownBinary(bytes)){
+      const content=`Cannot read binary file as text: ${path.basename(args.path)}\n\nUse start_process + interact_with_process to analyze binary files with appropriate tools (Node.js or Python libraries, command-line utilities, etc.).\n\nThe read_file tool only handles text files, images, and Excel files.`;
+      return text(content,false,{path:args.path,content,mimeType:'text/plain',isImage:false,isPdf:false,isBinary:true,fileSha256,...optionMeta});
+    }
     const all=linesFrom(raw.data_base64);
     const start=requestedOffset<0?Math.max(0,all.length+requestedOffset):Math.min(requestedOffset,all.length);
     const end=requestedOffset<0?all.length:Math.min(all.length,start+requestedLength);
@@ -381,7 +410,7 @@ export function createCommanderWireAdapter({machineFsRuntime=null,processRuntime
       }
       frontier=next;
     }
-    const rows=all.map(e=>`${(e.kind??e.type)==='directory'?'[DIR]':'[FILE]'} ${e.path}`);
+    const rows=directoryRows(all,target.relativePath);
     return text(rows.join('\n'),false,{path:args.path,depth,entries:all,truncated,entryCount:all.length});
   }
 
@@ -803,6 +832,31 @@ export function createCommanderWireAdapter({machineFsRuntime=null,processRuntime
             seenCursors.add(query.cursor);
           }
         }while(query.cursor!==null&&state.results.length<query.maxResults);
+        const docxSearchEnabled=String(args.filePattern??'').toLowerCase().includes('.docx')||String(args.path).toLowerCase().endsWith('.docx');
+        if(args.searchType==='content'&&machineFsRuntime&&docxSearchEnabled&&state.results.length<query.maxResults){
+          let docxEntries=[];
+          if(typeof machineFsRuntime.stat==='function'){
+            const info=await machineFsRuntime.stat({rootId:target.rootId,relativePath:target.relativePath,hash:false});
+            if(info?.kind==='file'&&target.relativePath.toLowerCase().endsWith('.docx'))docxEntries=[{path:target.relativePath,kind:'file'}];
+          }
+          if(docxEntries.length===0){
+            const listing=await listDirectory({path:args.path,depth:10});
+            docxEntries=(listing.structuredContent?.entries??[]).filter(entry=>(entry.kind??entry.type)==='file'&&String(entry.path).toLowerCase().endsWith('.docx'));
+          }
+          for(const entry of docxEntries){
+            if(state.cancelled||state.timedOut||state.results.length>=query.maxResults)break;
+            const raw=await machineFsRuntime.read({rootId:target.rootId,relativePath:entry.path,offset:0,
+              maxBytes:Math.min(64*1024*1024,machineFsRuntime.policy.max_read_bytes??64*1024*1024),hashFile:true});
+            if(raw.eof===false)continue;
+            const matches=searchDocxTextBytes(Buffer.from(raw.data_base64,'base64'),{
+              pattern:args.pattern,ignoreCase:args.ignoreCase!==false,maxResults:query.maxResults-state.results.length
+            });
+            for(const match of matches)state.results.push({
+              file:absoluteFor(machineFsRuntime,target.rootId,entry.path)+(match.part==='word/document.xml'?'':`:${match.part.slice('word/'.length)}`),
+              line:match.line,match:match.match,type:'content'
+            });
+          }
+        }
         if(!state.cancelled&&!state.timedOut) state.isComplete=true;
       }catch(error){if(!state.cancelled&&!state.timedOut){state.isError=true;state.error=String(error?.message??error);}state.isComplete=true;}
       finally{if(timeoutHandle!==null) clearTimeout(timeoutHandle);}

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) }]
   };
-}
+}