deadbyte-mcp 0.15.22 → 0.15.24

package/scripts/pcb-skill-src-pcb_constraint_gate.py.txt

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+import json, sys
+
+def load(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def main():
+    if len(sys.argv) != 3:
+        raise SystemExit("usage: pcb_constraint_gate.py board-probe.json board-contract.json")
+    probe = load(sys.argv[1])
+    contract = load(sys.argv[2])
+    if probe.get("schema") != "deadbyte.kicad-pcb-probe.v1":
+        raise SystemExit("unsupported probe schema")
+
+    checks = []
+    def add(rule, ok, observed, required):
+        checks.append({"rule": rule, "ok": bool(ok), "observed": observed, "required": required})
+
+    if "required_layers" in contract:
+        observed = set(x.get("name") for x in probe.get("layers", []))
+        req = list(contract["required_layers"])
+        add("required_layers", all(x in observed for x in req), sorted(observed), req)
+
+    if "min_copper_layers" in contract:
+        observed = probe.get("copper_layer_count")
+        req = int(contract["min_copper_layers"])
+        add("min_copper_layers", isinstance(observed, int) and observed >= req, observed, req)
+
+    for key, probe_key in [
+        ("min_track_width_mm", "track_width_mm"),
+        ("min_via_diameter_mm", "via_diameter_mm"),
+        ("min_via_drill_mm", "via_drill_mm"),
+    ]:
+        if key in contract:
+            observed = (probe.get(probe_key) or {}).get("min")
+            req = float(contract[key])
+            add(key, observed is not None and float(observed) >= req, observed, req)
+
+    if "required_nets" in contract:
+        observed = set(probe.get("nets", []))
+        req = list(contract["required_nets"])
+        add("required_nets", all(x in observed for x in req), sorted(observed), req)
+
+    for key, count_key in [
+        ("min_footprints", "footprints"),
+        ("min_segments", "segments"),
+        ("min_vias", "vias"),
+        ("min_zones", "zones"),
+    ]:
+        if key in contract:
+            observed = (probe.get("counts") or {}).get(count_key)
+            req = int(contract[key])
+            add(key, isinstance(observed, int) and observed >= req, observed, req)
+
+    allowed = {
+        "required_layers", "min_copper_layers", "min_track_width_mm",
+        "min_via_diameter_mm", "min_via_drill_mm", "required_nets",
+        "min_footprints", "min_segments", "min_vias", "min_zones"
+    }
+    unknown = sorted(set(contract) - allowed)
+    if unknown:
+        checks.append({"rule": "unknown_contract_keys", "ok": False, "observed": unknown, "required": "no unsupported keys"})
+
+    passed = all(x["ok"] for x in checks)
+    out = {
+        "schema": "deadbyte.pcb-constraint-gate.v1",
+        "status": "PASS" if passed else "FAIL",
+        "probe_sha256": probe.get("sha256"),
+        "checks": checks
+    }
+    print(json.dumps(out, indent=2, sort_keys=True))
+    raise SystemExit(0 if passed else 2)
+
+if __name__ == "__main__":
+    main()

package/scripts/pcb-skill-src-power-integrity.md.txt

@@ -0,0 +1,15 @@
+# Power Integrity and Thermal
+
+Power integrity begins with current loops, not capacitor count.
+
+For each regulator trace the input current path, keep the high di/dt input loop compact, bound switch-node copper, place bootstrap/gate-drive parts by topology, protect the feedback sense path, close the output-current loop, and provide a credible thermal path.
+
+For decoupling separate bulk-energy storage from local high-frequency charge. Account for capacitor mounting inductance, vias, planes, and package inductance. Printed capacitance alone does not prove useful impedance at frequency.
+
+For planes and pours verify neck-downs at pads, vias, connectors, and thermal spokes; identify slots caused by keepouts and antipads; preserve return continuity; and check both DC drop and transient current paths.
+
+For sensitive analog control where digital and switching currents return. Do not split ground reflexively. Placement, loop control, filtering, and current-path ownership matter more than labels.
+
+Thermal claims require dissipation, package thermal path, copper geometry, ambient, airflow, and enclosure assumptions. Missing inputs mean thermal margin UNKNOWN.
+
+Bench evidence should include rail voltage, ripple/noise with correct probing, startup sequencing, relevant load transient behavior, and regulator temperature under representative load.

package/scripts/prepare-skill-creator-1.1.1.mjs

@@ -0,0 +1,113 @@
+import { readFile, writeFile, mkdir, rm, cp } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+import { createHash, createPrivateKey, createPublicKey, sign } from "node:crypto";
+import { createSkillPlane } from "../src/skill-plane-r44.mjs";
+
+const ex = promisify(execFile);
+const home = os.homedir();
+const stateDir = path.join(home, ".deadbyte-mcp");
+const skillsRoot = path.join(stateDir, "skills");
+const active = path.join(skillsRoot, "skill-creator");
+const expectedOldManifest = "f34b3953db176c8ae9a5e08e7702b39f12b60b013edcd2f4d63a6268af9ba432";
+const oldEnv = JSON.parse(await readFile(path.join(active, "skill.json"), "utf8"));
+if (oldEnv.manifest_sha256 !== expectedOldManifest) {
+  throw new Error("unexpected active skill-creator manifest: " + oldEnv.manifest_sha256);
+}
+if (oldEnv.body.version !== "1.1.0") throw new Error("expected active skill-creator 1.1.0");
+
+const history = path.join(stateDir, "skill-history", "skill-creator", "1.1.0-" + expectedOldManifest);
+await mkdir(path.dirname(history), {recursive:true});
+try {
+  const prior = JSON.parse(await readFile(path.join(history, "skill.json"), "utf8"));
+  if (prior.manifest_sha256 !== expectedOldManifest) throw new Error("history path collision");
+} catch (e) {
+  if (e.code !== "ENOENT") throw e;
+  await cp(active, history, {recursive:true, errorOnExist:true});
+}
+const archived = JSON.parse(await readFile(path.join(history, "skill.json"), "utf8"));
+if (archived.manifest_sha256 !== expectedOldManifest) throw new Error("archive manifest mismatch");
+
+const stageParent = path.join(stateDir, "skill-staging", "skill-creator-1.1.1");
+const stage = path.join(stageParent, "skill-creator");
+await rm(stageParent, {recursive:true, force:true});
+await mkdir(stageParent, {recursive:true});
+await cp(active, stage, {recursive:true});
+await rm(path.join(stage, "references", "skills_cache.json"), {force:true});
+
+const createPath = path.join(stage, "scripts", "create-skill.mjs");
+const oldCreate = await readFile(createPath, "utf8");
+const oldRegex = "const VERSION=/^[0-9]+\\\\.[0-9]+\\\\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/;";
+const newRegex = "const VERSION=/^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/;";
+if (!oldCreate.includes(oldRegex)) throw new Error("expected defective VERSION regex not found");
+if (oldCreate.split(oldRegex).length !== 2) throw new Error("VERSION regex occurrence count != 1");
+await writeFile(createPath, oldCreate.replace(oldRegex, newRegex), "utf8");
+
+const skillPath = path.join(stage, "SKILL.md");
+const oldSkill = await readFile(skillPath, "utf8");
+const versionLine = "version: 1.1.0";
+if (!oldSkill.includes(versionLine) || oldSkill.split(versionLine).length !== 2) {
+  throw new Error("SKILL.md version occurrence count != 1");
+}
+await writeFile(skillPath, oldSkill.replace(versionLine, "version: 1.1.1"), "utf8");
+
+const sha = b => createHash("sha256").update(b).digest("hex");
+const canonical = v => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object"
+  ? Object.fromEntries(Object.keys(v).sort((a,b)=>a.localeCompare(b,"en")).map(k=>[k,canonical(v[k])]))
+  : v;
+
+const body = structuredClone(oldEnv.body);
+body.version = "1.1.1";
+body.skill_md_sha256 = sha(await readFile(skillPath));
+body.provenance = {
+  ...body.provenance,
+  source_revision: "r47.1-semver-regex-repair-2026-09-27"
+};
+for (const resource of body.resources) {
+  resource.sha256 = sha(await readFile(path.join(stage, ...resource.path.split("/"))));
+}
+const bodyBytes = Buffer.from(JSON.stringify(canonical(body)), "utf8");
+const body_sha256 = sha(bodyBytes);
+const priv = createPrivateKey(await readFile(path.join(stateDir, "trust", "ed25519-private.pem")));
+const pub = createPublicKey(priv);
+const keyId = sha(pub.export({type:"spki", format:"der"}));
+const attestation = {
+  algorithm: "ed25519",
+  domain: "DEADBYTE-SKILL-MANIFEST-V1",
+  key_id: keyId,
+  signature_base64: sign(null, Buffer.concat([Buffer.from("DEADBYTE-SKILL-MANIFEST-V1\0", "utf8"), bodyBytes]), priv).toString("base64")
+};
+const unsigned = {body, body_sha256, attestation};
+const envelope = {
+  ...unsigned,
+  manifest_sha256: sha(Buffer.from(JSON.stringify(canonical(unsigned)), "utf8"))
+};
+await writeFile(path.join(stage, "skill.json"), JSON.stringify(envelope, null, 2), "utf8");
+
+const validator = await ex(process.execPath, [path.join(stage, "scripts", "validate-skill.mjs"), stage], {
+  timeout: 30000,
+  maxBuffer: 1024 * 1024
+});
+
+const plane = await createSkillPlane({
+  root: stageParent,
+  verifyKeyPath: path.join(stateDir, "trust", "ed25519-public.pem")
+});
+const loaded = await plane.load({name:"skill-creator"});
+if (!loaded.verified || loaded.version !== "1.1.1") throw new Error("staging Skill Plane verification failed");
+
+console.log(JSON.stringify({
+  status:"STAGED",
+  active_manifest:oldEnv.manifest_sha256,
+  archived_path:history,
+  archived_manifest:archived.manifest_sha256,
+  stage_parent:stageParent,
+  stage_skill:stage,
+  candidate_manifest:envelope.manifest_sha256,
+  candidate_body_sha256:body_sha256,
+  verify_key_id:keyId,
+  validator:validator.stdout.trim(),
+  skill_plane_verified:loaded.verified
+}, null, 2));

package/scripts/test-skill-creator-semver-matrix.mjs

@@ -0,0 +1,30 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+const ex=promisify(execFile);
+const creator=process.argv[2];
+if(!creator) throw new Error("creator path required");
+const valid=["1.0.0","0.0.1","1.1.1","12.34.56","1.0.0-rc.1"];
+const invalid=["1.0","v1.0.0","1.a.0","",String.fromCharCode(49,92,97,48,92,98,48)];
+const results=[];
+for(const version of valid){
+  const tmp=await mkdtemp(path.join(os.tmpdir(),"deadbyte-semver-valid-"));
+  try{
+    await ex(process.execPath,[creator,tmp,"fixture",version],{timeout:30000,maxBuffer:1048576});
+    results.push({version,expected:"PASS",observed:"PASS"});
+  }finally{await rm(tmp,{recursive:true,force:true});}
+}
+for(const version of invalid){
+  const tmp=await mkdtemp(path.join(os.tmpdir(),"deadbyte-semver-invalid-"));
+  let rejected=false;
+  try{
+    await ex(process.execPath,[creator,tmp,"fixture",version],{timeout:30000,maxBuffer:1048576});
+  }catch(e){
+    if(e.code===1 && String(e.stderr).includes("invalid version")) rejected=true;
+  }finally{await rm(tmp,{recursive:true,force:true});}
+  if(!rejected) throw new Error("invalid version accepted: "+JSON.stringify(version));
+  results.push({version,expected:"FAIL",observed:"FAIL"});
+}
+console.log(JSON.stringify({status:"PASS",cases:results},null,2));

package/scripts/test-skill-creator-semver.mjs

@@ -0,0 +1,22 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+
+const ex = promisify(execFile);
+const creator = process.argv[2];
+if (!creator) throw new Error("usage: node test-skill-creator-semver.mjs <create-skill.mjs>");
+const tmp = await mkdtemp(path.join(os.tmpdir(), "deadbyte-skill-creator-semver-"));
+try {
+  const r = await ex(process.execPath, [creator, tmp, "semver-regression-fixture", "1.0.0"], {
+    timeout: 30000,
+    maxBuffer: 1024 * 1024
+  });
+  if (!r.stdout.includes("semver-regression-fixture")) {
+    throw new Error("create-skill returned success without fixture path");
+  }
+  console.log(JSON.stringify({status:"PASS", version:"1.0.0", stdout:r.stdout.trim()}));
+} finally {
+  await rm(tmp, {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);}