deadbyte-mcp 0.15.46 → 0.15.48

package/src/epoch-lock-r85.mjs

@@ -0,0 +1,48 @@
+import {createHash, randomBytes} from 'node:crypto';
+import {lstat,readFile} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {inspectTrustedInstallation,privilegedEpochInstallFiles} from './privileged-install-trust-r89.mjs';
+
+const root=path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const binary=path.join(root,'bin','deadbyte-epoch-lock-r85.node');
+const metadata=path.join(root,'docs','R85-EPOCH-LOCK-BINARY.json');
+const require=createRequire(import.meta.url);
+const hex64=/^[0-9a-f]{64}$/;
+let addon=null;
+
+async function loadVerifiedAddon(){
+  if(process.platform!=='win32'||process.arch!=='x64')throw new Error('epoch held-handle lock requires Windows x64');
+  await inspectTrustedInstallation(privilegedEpochInstallFiles(root,process.execPath));
+  const meta=JSON.parse(await readFile(metadata,'utf8'));
+  if(meta.schema!=='deadbyte.r85-epoch-lock-binary.v1'||meta.platform!=='win32-x64'||
+    meta.addon!=='bin/deadbyte-epoch-lock-r85.node'||meta.source!=='native/deadbyte-epoch-lock-r85.cpp'||
+    meta.node_api_version>Number(process.versions.napi)||!hex64.test(meta.addon_sha256)||!hex64.test(meta.source_sha256))
+    throw new Error('epoch held-handle binary metadata invalid');
+  const [st,bytes,sourceBytes]=await Promise.all([lstat(binary),readFile(binary),readFile(path.join(root,meta.source))]);
+  if(!st.isFile()||st.isSymbolicLink()||
+    createHash('sha256').update(bytes).digest('hex')!==meta.addon_sha256||
+    createHash('sha256').update(sourceBytes).digest('hex')!==meta.source_sha256)
+    throw new Error('epoch held-handle binary/source hash mismatch');
+  addon??=require(binary);
+  if(typeof addon.acquire!=='function'||typeof addon.release!=='function')
+    throw new Error('epoch held-handle exports invalid');
+  return addon;
+}
+
+export async function acquireHeldEpochLock(file,bytes){
+  if(!Buffer.isBuffer(bytes)||bytes.length<2||bytes.length>16384||typeof file!=='string'||!path.isAbsolute(file))
+    throw new Error('epoch held-handle lock arguments invalid');
+  const native=await loadVerifiedAddon();
+  const handle=native.acquire(file,bytes,randomBytes(16).toString('hex'));
+  if(handle===null)return null;
+  let released=false;
+  return Object.freeze({
+    async release(){
+      if(released)throw new Error('epoch held-handle lock already released');
+      native.release(handle);
+      released=true;
+    }
+  });
+}

package/src/foreground-marker-cas-win32.mjs

@@ -0,0 +1,284 @@
+// Windows-only, handle-bound conditional deletion. Never use pathname rm after a read.
+import {createHash} from 'node:crypto';
+import {lstat,readFile} from 'node:fs/promises';
+import {spawnSync} from 'node:child_process';
+import path from 'node:path';
+import {windowsPowerShellEnvironment} from './windows-powershell-environment.mjs';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const digest=bytes=>createHash('sha256').update(bytes).digest('hex');
+const sameFile=(a,b)=>a&&b&&a.isFile()&&b.isFile()&&!a.isSymbolicLink()&&!b.isSymbolicLink()&&
+  a.dev===b.dev&&a.ino===b.ino&&a.size===b.size&&a.mtimeMs===b.mtimeMs&&a.ctimeMs===b.ctimeMs;
+
+export async function readRemoteMarkerSnapshot(file){
+  let before;
+  try{before=await lstat(file);}catch(error){if(error?.code==='ENOENT')return null;throw error;}
+  if(!before.isFile()||before.isSymbolicLink()||before.size>16384||before.size<2)
+    throw new Error('remote marker not a bounded regular file');
+  const bytes=await readFile(file);
+  const after=await lstat(file);
+  if(!sameFile(before,after)||bytes.length!==before.size)
+    throw new Error('remote marker identity changed during snapshot');
+  let marker;
+  try{marker=JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/,''));}
+  catch{throw new Error('remote marker JSON invalid');}
+  return Object.freeze({marker,sha256:digest(bytes)});
+}
+
+// Native ancestor handles pin the non-reparse path chain, then a single leaf handle owns read/hash/deletion.
+// Open share=READ only: concurrent replace, rename, delete and writes must fail.
+// Do not replace this with a Node readFile()+rm(), rename(), or link()+unlink().
+const nativeCommand=String.raw`
+$ErrorActionPreference='Stop'
+$source=@'
+using System;
+using System.IO;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Security.Cryptography;
+using Microsoft.Win32.SafeHandles;
+using System.Collections.Generic;
+public static class DeadbytePinnedDeleteV2 {
+  const uint FILE_READ_DATA = 0x0001;
+  const uint FILE_WRITE_DATA = 0x0002;
+  const uint FILE_READ_ATTRIBUTES = 0x0080;
+  const uint DELETE = 0x00010000;
+  const uint FILE_SHARE_READ = 0x00000001;
+  const uint OPEN_EXISTING = 3;
+  const uint CREATE_NEW = 1;
+  const uint FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000;
+  const uint FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
+  const uint FILE_ATTRIBUTE_DIRECTORY = 0x00000010;
+  const uint FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400;
+  [StructLayout(LayoutKind.Sequential)] struct FILE_ATTRIBUTE_TAG_INFO {
+    public uint FileAttributes;
+    public uint ReparseTag;
+  }
+  // FileIdInfo = 18, FILE_ID_INFO = 8-byte volume serial + 16-byte file ID.
+  // No fallback to filename, hashes, inode heuristics, or legacy 64-bit file index.
+  [StructLayout(LayoutKind.Sequential)] struct FILE_ID_INFO {
+    public ulong VolumeSerialNumber;
+    [MarshalAs(UnmanagedType.ByValArray, SizeConst=16)] public byte[] FileId;
+  }
+  [DllImport("kernel32.dll",EntryPoint="CreateFileW",CharSet=CharSet.Unicode,SetLastError=true)]
+  static extern SafeFileHandle CreateFile(string file,uint access,uint share,IntPtr security,uint creation,uint flags,IntPtr templateFile);
+  [DllImport("kernel32.dll",SetLastError=true)]
+  static extern bool GetFileInformationByHandleEx(SafeFileHandle file,int cls,out FILE_ATTRIBUTE_TAG_INFO info,uint size);
+  [DllImport("kernel32.dll",EntryPoint="GetFileInformationByHandleEx",SetLastError=true)]
+  static extern bool GetFileIdInformationByHandleEx(SafeFileHandle file,int cls,out FILE_ID_INFO info,uint size);
+  [DllImport("kernel32.dll",SetLastError=true)]
+  static extern bool SetFileInformationByHandle(SafeFileHandle file,int cls,IntPtr info,uint size);
+  // Pin the ENTIRE local-drive ancestor chain from the drive root to the leaf's parent.
+  // Share=READ only denies concurrent write/rename/delete of each pinned component.
+  // Checking names separately and closing each handle would reintroduce the race.
+  static void PinAncestor(string directory,List<SafeFileHandle> pins) {
+    var handle=CreateFile(directory,FILE_READ_ATTRIBUTES,FILE_SHARE_READ,
+      IntPtr.Zero,OPEN_EXISTING,FILE_FLAG_BACKUP_SEMANTICS|FILE_FLAG_OPEN_REPARSE_POINT,IntPtr.Zero);
+    if(handle.IsInvalid){
+      int error=Marshal.GetLastWin32Error();handle.Dispose();
+      throw new Win32Exception(error,"cannot pin path ancestor (fail closed)");
+    }
+    try {
+      FILE_ATTRIBUTE_TAG_INFO attr;
+      if(!GetFileInformationByHandleEx(handle,9,out attr,(uint)Marshal.SizeOf(typeof(FILE_ATTRIBUTE_TAG_INFO))))
+        throw new Win32Exception(Marshal.GetLastWin32Error(),"ancestor attributes unavailable");
+      if((attr.FileAttributes&FILE_ATTRIBUTE_DIRECTORY)==0 ||
+         (attr.FileAttributes&FILE_ATTRIBUTE_REPARSE_POINT)!=0)
+        throw new InvalidOperationException("ancestor is a junction, symlink, reparse point or non-directory");
+      pins.Add(handle);
+    } catch {handle.Dispose();throw;}
+  }
+  static string FileIdentity(SafeFileHandle handle) {
+    FILE_ID_INFO info;
+    if(!GetFileIdInformationByHandleEx(handle,18,out info,(uint)Marshal.SizeOf(typeof(FILE_ID_INFO))))
+      throw new Win32Exception(Marshal.GetLastWin32Error(),"128-bit native File ID unavailable; fail closed");
+    if(info.FileId==null||info.FileId.Length!=16)
+      throw new InvalidOperationException("native file identity unavailable");
+    bool allZero=true;
+    foreach(byte b in info.FileId)if(b!=0){allZero=false;break;}
+    if(allZero)throw new InvalidOperationException("zero native File ID; fail closed");
+    return info.VolumeSerialNumber.ToString("x16")+":"+BitConverter.ToString(info.FileId).Replace("-","").ToLowerInvariant();
+  }
+  public static string DeleteIfHash(string file,string expectedSha,string expectedId) {
+    return WithPinnedAncestors(file,"delete",expectedSha,expectedId,null);
+  }
+  public static string Snapshot(string file) {
+    return WithPinnedAncestors(file,"snapshot",null,null,null);
+  }
+  public static string CreateLock(string file,string encodedBytes) {
+    return WithPinnedAncestors(file,"create",null,null,encodedBytes);
+  }
+  static string WithPinnedAncestors(string file,string operation,string expectedSha,string expectedId,string encodedBytes) {
+    string full=Path.GetFullPath(file);
+    // No UNC paths, device paths, ADS or extended-path aliases in this safety boundary.
+    if(full.Length<4 || !Char.IsLetter(full[0]) || full[1]!=':' || full[2]!='\\' ||
+       full.IndexOf(':',2)>=0 || String.IsNullOrEmpty(Path.GetFileName(full)))
+      throw new InvalidOperationException("pinned deletion requires an ordinary local drive file path");
+    string root=Path.GetPathRoot(full);
+    string parent=Path.GetDirectoryName(full);
+    var pins=new List<SafeFileHandle>();
+    try {
+      string current=root;
+      PinAncestor(current,pins);
+      string tail=parent.Substring(root.Length);
+      foreach(string component in tail.Split(new[]{'\\'},StringSplitOptions.RemoveEmptyEntries)){
+        current=Path.Combine(current,component);
+        PinAncestor(current,pins);
+      }
+      if(operation=="snapshot")return SnapshotPinnedLeaf(full);
+      if(operation=="create")return CreatePinnedLeaf(full,encodedBytes);
+      return DeletePinnedLeaf(full,expectedSha,expectedId);
+    } finally {
+      for(int i=pins.Count-1;i>=0;i--)pins[i].Dispose();
+    }
+  }
+  static byte[] ReadBoundedLeaf(SafeFileHandle handle){
+    using(var stream=new FileStream(handle,FileAccess.Read)){
+      if(stream.Length<2||stream.Length>16384)throw new InvalidOperationException("pinned file size invalid");
+      byte[] content=new byte[(int)stream.Length];int index=0,read;
+      while(index<content.Length&&(read=stream.Read(content,index,content.Length-index))>0)index+=read;
+      if(index!=content.Length)throw new IOException("pinned file truncated");
+      return content;
+    }
+  }
+  static void ValidateLeaf(SafeFileHandle handle){
+    FILE_ATTRIBUTE_TAG_INFO attr;
+    if(!GetFileInformationByHandleEx(handle,9,out attr,(uint)Marshal.SizeOf(typeof(FILE_ATTRIBUTE_TAG_INFO))))
+      throw new Win32Exception(Marshal.GetLastWin32Error(),"pinned leaf attributes unavailable");
+    if((attr.FileAttributes&(FILE_ATTRIBUTE_DIRECTORY|FILE_ATTRIBUTE_REPARSE_POINT))!=0)
+      throw new InvalidOperationException("pinned leaf is a reparse point or directory");
+  }
+  static string SnapshotPinnedLeaf(string file){
+    using(var handle=CreateFile(file,FILE_READ_DATA|FILE_READ_ATTRIBUTES,FILE_SHARE_READ,IntPtr.Zero,OPEN_EXISTING,FILE_FLAG_OPEN_REPARSE_POINT,IntPtr.Zero)){
+      if(handle.IsInvalid){
+        int error=Marshal.GetLastWin32Error();
+        if(error==2||error==3)return "MISSING";
+        throw new Win32Exception(error,"epoch lock could not be pinned for identity snapshot");
+      }
+      ValidateLeaf(handle);
+      string id=FileIdentity(handle);
+      byte[] bytes=ReadBoundedLeaf(handle);
+      string hash=BitConverter.ToString(SHA256.Create().ComputeHash(bytes)).Replace("-","").ToLowerInvariant();
+      return "SNAPSHOT|"+id+"|"+hash+"|"+Convert.ToBase64String(bytes);
+    }
+  }
+  static string CreatePinnedLeaf(string file,string encodedBytes){
+    byte[] bytes=Convert.FromBase64String(encodedBytes);
+    if(bytes.Length<2||bytes.Length>16384)throw new InvalidOperationException("epoch lock bytes invalid");
+    using(var handle=CreateFile(file,FILE_READ_DATA|FILE_WRITE_DATA|FILE_READ_ATTRIBUTES,
+      FILE_SHARE_READ,IntPtr.Zero,CREATE_NEW,FILE_FLAG_OPEN_REPARSE_POINT,IntPtr.Zero)){
+      if(handle.IsInvalid){
+        int error=Marshal.GetLastWin32Error();
+        if(error==80||error==183)return "EXISTS";
+        throw new Win32Exception(error,"epoch lock creation failed closed");
+      }
+      ValidateLeaf(handle);
+      string id=FileIdentity(handle);
+      using(var stream=new FileStream(handle,FileAccess.ReadWrite)){
+        stream.Write(bytes,0,bytes.Length);
+        stream.Flush(true);
+      }
+      string hash=BitConverter.ToString(SHA256.Create().ComputeHash(bytes)).Replace("-","").ToLowerInvariant();
+      return "CREATED|"+id+"|"+hash;
+    }
+  }
+  static string DeletePinnedLeaf(string file,string expectedSha,string expectedId) {
+    using(var handle=CreateFile(file,FILE_READ_DATA|FILE_READ_ATTRIBUTES|DELETE,FILE_SHARE_READ,IntPtr.Zero,OPEN_EXISTING,FILE_FLAG_OPEN_REPARSE_POINT,IntPtr.Zero)) {
+      if(handle.IsInvalid){
+        int error=Marshal.GetLastWin32Error();
+        if(error==2||error==3)return "MISSING";
+        throw new Win32Exception(error,"remote marker cannot be exclusively pinned");
+      }
+      ValidateLeaf(handle);
+      // PowerShell can marshal $null to an empty string for a C# string parameter.
+      // Only epoch-lock callers with an explicit File ID require this comparison.
+      string actualId=String.IsNullOrEmpty(expectedId)?null:FileIdentity(handle);
+      // Identity must be checked on the SAME handle used for hash and disposition.
+      if(!String.IsNullOrEmpty(expectedId)&&!String.Equals(actualId,expectedId,StringComparison.Ordinal))return "CHANGED";
+      using(var stream=new FileStream(handle,FileAccess.Read)){
+        if(stream.Length<2||stream.Length>16384)throw new InvalidOperationException("pinned file size invalid");
+        byte[] content=new byte[(int)stream.Length];int index=0,read;
+        while(index<content.Length&&(read=stream.Read(content,index,content.Length-index))>0)index+=read;
+        if(index!=content.Length)throw new IOException("pinned file truncated");
+        string actual=BitConverter.ToString(SHA256.Create().ComputeHash(content)).Replace("-","").ToLowerInvariant();
+        if(!String.Equals(actual,expectedSha,StringComparison.Ordinal))return "CHANGED";
+        IntPtr flag=Marshal.AllocHGlobal(4);
+        try {
+          Marshal.WriteInt32(flag,1);
+          if(!SetFileInformationByHandle(handle,4,flag,4))
+            throw new Win32Exception(Marshal.GetLastWin32Error(),"pinned file delete disposition denied");
+        } finally {Marshal.FreeHGlobal(flag);}
+        return "REMOVED";
+      }
+    }
+  }
+}
+'@
+Add-Type -TypeDefinition $source -Language CSharp -ErrorAction Stop | Out-Null
+$file=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($env:DEADBYTE_PINNED_MARKER_B64))
+$sha=$env:DEADBYTE_PINNED_MARKER_SHA
+$id=$env:DEADBYTE_PINNED_MARKER_FILE_ID
+if($env:DEADBYTE_PINNED_MARKER_OP -eq 'snapshot') {
+  [Console]::Out.WriteLine([DeadbytePinnedDeleteV2]::Snapshot($file))
+} elseif($env:DEADBYTE_PINNED_MARKER_OP -eq 'create') {
+  [Console]::Out.WriteLine([DeadbytePinnedDeleteV2]::CreateLock($file,$env:DEADBYTE_PINNED_MARKER_BYTES_B64))
+} else {
+  if([String]::IsNullOrEmpty($id)){$id=$null}
+  [Console]::Out.WriteLine([DeadbytePinnedDeleteV2]::DeleteIfHash($file,$sha,$id))
+}
+`;
+
+const FILE_ID_PATTERN=/^[0-9a-f]{16}:[0-9a-f]{32}$/;
+function invokePinnedNative(file,{op,sha=null,fileId=null,bytes=null}={}){
+  if(process.platform!=='win32')throw new Error('native pinned file I/O is Windows-only');
+  if(typeof file!=='string'||!path.isAbsolute(file)||!['snapshot','delete','create'].includes(op)||
+    (op==='delete'&&!HEX64.test(sha??''))||
+    (op==='create'&&(!Buffer.isBuffer(bytes)||bytes.length<2||bytes.length>16384))||
+    (fileId!==null&&!FILE_ID_PATTERN.test(fileId)))
+    throw new Error('native pinned file arguments invalid');
+  const powershell='C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
+  const result=spawnSync(powershell,['-NoLogo','-NoProfile','-NonInteractive','-EncodedCommand',
+    Buffer.from(nativeCommand,'utf16le').toString('base64')],{
+    encoding:'utf8',windowsHide:true,shell:false,timeout:25000,maxBuffer:262144,
+    env:windowsPowerShellEnvironment({...process.env,SystemRoot:'C:\\Windows',WINDIR:'C:\\Windows',
+      DEADBYTE_PINNED_MARKER_B64:Buffer.from(file,'utf8').toString('base64'),
+      DEADBYTE_PINNED_MARKER_SHA:sha??'',
+      DEADBYTE_PINNED_MARKER_FILE_ID:fileId??'',
+      DEADBYTE_PINNED_MARKER_BYTES_B64:bytes?.toString('base64')??'',
+      DEADBYTE_PINNED_MARKER_OP:op})
+  });
+  if(result.error||result.status!==0)throw new Error('native pinned file I/O failed closed');
+  return result.stdout.trim();
+}
+
+// Snapshot locks using one native handle for owner bytes, SHA-256, and FileIdInfo.
+// Node lstat dev/ino is insufficient as the sole cross-API identity authority.
+export function readPinnedEpochLockSnapshot(file){
+  const result=invokePinnedNative(file,{op:'snapshot'});
+  if(result==='MISSING')return null;
+  const match=/^SNAPSHOT\|([0-9a-f]{16}:[0-9a-f]{32})\|([0-9a-f]{64})\|([A-Za-z0-9+/]+={0,2})$/.exec(result);
+  if(!match)throw new Error('native pinned epoch lock snapshot malformed');
+  const bytes=Buffer.from(match[3],'base64');
+  if(bytes.length<2||bytes.length>16384||bytes.toString('base64')!==match[3]||digest(bytes)!==match[2])
+    throw new Error('native pinned epoch lock snapshot content mismatch');
+  return Object.freeze({bytes,sha256:match[2],fileId:match[1]});
+}
+
+// Creation is pinned under the same non-reparse ancestor chain. The returned
+// File ID belongs to the handle that wrote and flushed the original lock bytes.
+export function createPinnedEpochLock(file,bytes){
+  const result=invokePinnedNative(file,{op:'create',bytes});
+  if(result==='EXISTS')return null;
+  const match=/^CREATED\|([0-9a-f]{16}:[0-9a-f]{32})\|([0-9a-f]{64})$/.exec(result);
+  if(!match||digest(bytes)!==match[2])throw new Error('native epoch lock creation identity invalid');
+  return Object.freeze({fileId:match[1],sha256:match[2]});
+}
+
+// Existing remote-marker API remains content-CAS for backward compatibility.
+// Epoch locks MUST pass an expected FileIdInfo captured from a native snapshot.
+export function deletePinnedRemoteMarker(file,expectedSha256,options={}){
+  const expectedFileId=options?.expectedFileId??null;
+  const answer=invokePinnedNative(file,{op:'delete',sha:expectedSha256,fileId:expectedFileId});
+  if(!['REMOVED','MISSING','CHANGED'].includes(answer))throw new Error('handle-bound deletion result invalid');
+  return answer;
+}

package/src/foreground-process-identity.mjs

@@ -1,7 +1,7 @@
 import {spawnSync} from 'node:child_process';
 import {createHash} from 'node:crypto';
 import path from 'node:path';
-import {windowsPowerShellEnvironment} from './runtime-update.mjs';
+import {windowsPowerShellEnvironment} from './windows-powershell-environment.mjs';
 
 export function validForegroundIdentity(value){
  return value?.schema==='deadbyte.foreground-process.v1'&&Number.isSafeInteger(value.pid)&&value.pid>0&&Number.isSafeInteger(value.parent_pid)&&value.parent_pid>=0&&typeof value.creation_utc==='string'&&/^\d{4}-\d\d-\d\dT.*Z$/.test(value.creation_utc)&&Number.isFinite(Date.parse(value.creation_utc))&&typeof value.executable_path==='string'&&path.isAbsolute(value.executable_path)&&/^[0-9a-f]{64}$/.test(value.command_line_sha256??'');
@@ -14,9 +14,9 @@ export function foregroundIdentityMatches(expected,observed){
 }
 export function queryForegroundIdentity(pid){
  if(process.platform!=='win32'||!Number.isSafeInteger(pid)||pid<1)throw new Error('foreground identity requires a positive Windows PID');
- const root=process.env.SystemRoot||process.env.WINDIR;if(!root)throw new Error('Windows system root missing');
+ const powershell='C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
  const command=`$p=Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; if ($null -eq $p) {Write-Output 'null';exit 0}; [pscustomobject]@{pid=$p.ProcessId;parent_pid=$p.ParentProcessId;creation_utc=$p.CreationDate.ToUniversalTime().ToString('o');executable_path=$p.ExecutablePath;command_line=$p.CommandLine} | ConvertTo-Json -Compress`;
- const result=spawnSync(path.join(root,'System32/WindowsPowerShell/v1.0/powershell.exe'),['-NoLogo','-NoProfile','-Command',command],{encoding:'utf8',windowsHide:true,env:windowsPowerShellEnvironment(process.env),timeout:15000,maxBuffer:1024*1024});
+ const result=spawnSync(powershell,['-NoLogo','-NoProfile','-Command',command],{encoding:'utf8',windowsHide:true,env:windowsPowerShellEnvironment({...process.env,SystemRoot:'C:\\Windows',WINDIR:'C:\\Windows'}),timeout:15000,maxBuffer:1024*1024});
  if(result.error||result.status!==0)throw new Error('foreground process identity query failed');
  let raw;try{raw=JSON.parse(result.stdout);}catch{throw new Error('foreground process identity query malformed');}
  if(raw===null)return null;

package/src/kernel-lock-r74.mjs

@@ -0,0 +1,125 @@
+import {spawn} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {lstat, readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {performance} from 'node:perf_hooks';
+import {fileURLToPath} from 'node:url';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const exePath = path.join(root, 'bin', 'deadbyte-kernel-lock-r74.exe');
+const metaPath = path.join(root, 'docs', 'R74-KERNEL-LOCK-BINARY.json');
+
+const sha256Bytes = bytes => createHash('sha256').update(bytes).digest('hex');
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+export async function verifyKernelLockBinary() {
+  if (process.platform !== 'win32') {
+    return { ok: false, reason: 'unsupported platform; win32 required' };
+  }
+  try {
+    const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    if (meta?.schema !== 'deadbyte.r74-kernel-lock-binary.v1' ||
+        meta?.exe !== 'bin/deadbyte-kernel-lock-r74.exe' ||
+        !/^[0-9a-f]{64}$/.test(String(meta?.sha256 ?? ''))) {
+      return { ok: false, reason: 'R74 kernel lock metadata invalid' };
+    }
+    const info = await lstat(exePath);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      return { ok: false, reason: 'R74 kernel lock executable is not a regular file' };
+    }
+    const bytes = await readFile(exePath);
+    const hash = sha256Bytes(bytes);
+    if (hash !== meta.sha256) {
+      return { ok: false, reason: 'R74 kernel lock executable hash pin mismatch' };
+    }
+    return { ok: true, path: exePath, sha256: hash };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+export async function acquireKernelExclusiveLock(lockPath, { timeoutMs = 30000, pollMs = 20 } = {}) {
+  const verified = await verifyKernelLockBinary();
+  if (!verified.ok) {
+    throw new Error(`atomic mutation lock recovery blocked: native exclusive locking unavailable (${verified.reason})`);
+  }
+
+  const started = performance.now();
+  while (true) {
+    let child = null;
+    try {
+      const outcome = await new Promise((resolve, reject) => {
+        child = spawn(verified.path, ['acquire', path.resolve(lockPath)], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          windowsHide: true,
+          shell: false
+        });
+        let line = '';
+        let resolved = false;
+
+        child.stdout.on('data', chunk => {
+          if (resolved) return;
+          line += chunk.toString('utf8');
+          const newline = line.indexOf('\n');
+          if (newline !== -1) {
+            resolved = true;
+            try {
+              const parsed = JSON.parse(line.slice(0, newline).trim());
+              resolve(parsed);
+            } catch (parseError) {
+              reject(parseError);
+            }
+          }
+        });
+
+        child.once('error', err => {
+          if (!resolved) {
+            resolved = true;
+            reject(err);
+          }
+        });
+
+        child.once('close', code => {
+          if (!resolved) {
+            resolved = true;
+            resolve({ status: 'exited', code });
+          }
+        });
+      });
+
+      if (outcome.status === 'acquired') {
+        const lockChild = child;
+        const release = async () => {
+          if (lockChild.exitCode !== null) {
+            throw new Error('atomic mutation lock ownership lost: lock process exited unexpectedly');
+          }
+          try {
+            lockChild.stdin.write('q\n');
+            lockChild.stdin.end();
+          } catch {}
+          await new Promise(resolve => {
+            if (lockChild.exitCode !== null) return resolve();
+            lockChild.once('close', resolve);
+          });
+        };
+        release.pid = outcome.pid;
+        return release;
+      }
+
+      if (outcome.status === 'locked') {
+        if (performance.now() - started >= timeoutMs) {
+          throw new Error('atomic mutation lock timed out');
+        }
+        await sleep(pollMs);
+        continue;
+      }
+
+      throw new Error(`atomic mutation lock acquisition failed: ${JSON.stringify(outcome)}`);
+    } catch (err) {
+      if (child && child.exitCode === null) {
+        child.kill('SIGKILL');
+      }
+      throw err;
+    }
+  }
+}