@tasksai/install 0.1.38 → 0.1.40

package/src/managed-python.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+
+export const PYTHON_RELEASE='3.12.14+20260901';
+export function pythonArchiveTool(platform=process.platform,systemRoot=process.env.SystemRoot){
+  // Git's GNU tar can interpret Windows drive-letter paths as remote hosts.
+  // Select the OS archive reader instead of whichever tar appears on PATH.
+  return platform==='win32'?path.win32.join(systemRoot||'C:\\Windows','System32','tar.exe'):'/usr/bin/tar';
+}
+const builds={
+  'darwin-arm64':['aarch64-apple-darwin','3ee3ee547cedfeb7c2b16b2b7156039f7b470bb8f857e226fd3d2eb11db83c76'],
+  'darwin-x64':['x86_64-apple-darwin','2e31b23f3f1319f707d0e620b48847a0046577541d357276821f9f1b5492e0ba'],
+  'win32-arm64':['aarch64-pc-windows-msvc','4e852236277eb8f7105cbe0f5adf45592f521af238bc0f700c351856e2c2e41a'],
+  'win32-x64':['x86_64-pc-windows-msvc','e90c1b6419da3bd812dd73bb3de40287a21abf153438147639ec5e20375ea93f'],
+};
+
+export function managedPythonLocation(installDir,{platform=process.platform,arch=process.arch}={}){
+  const folder=path.join(installDir,'managed-python',`cpython-${PYTHON_RELEASE}-${platform}-${arch}`);
+  return {folder,executable:path.join(folder,'python',...(platform==='win32'?['python.exe']:['bin','python3.12']))};
+}
+
+export function probeManagedPython(executable,{run=spawnSync}={}){
+  const result=run(executable,['-I','-c','import json,sys,sqlite3,ssl,venv,pip; print(json.dumps(list(sys.version_info[:3])))'],{encoding:'utf8',timeout:10000,windowsHide:true,maxBuffer:16384});
+  try{return !result.error&&result.status===0&&JSON.stringify(JSON.parse(result.stdout))==='[3,12,14]';}catch{return false;}
+}
+
+export async function installManagedPython(installDir,{platform=process.platform,arch=process.arch,fetchImpl=fetch,run=spawnSync}={}){
+  const build=builds[`${platform}-${arch}`];
+  if(!build)throw Error('Automatic Python setup is supported on Mac and Windows. Install Python 3.10 or newer to continue on this platform.');
+  const {folder,executable}=managedPythonLocation(installDir,{platform,arch});
+  if(probeManagedPython(executable,{run}))return executable;
+  try{await fs.lstat(folder);throw Error('The TasksAI Python folder exists but could not be validated. It was preserved; repair is required before continuing.');}catch(error){if(error.code!=='ENOENT')throw error;}
+  await fs.mkdir(path.dirname(folder),{recursive:true});
+  const staging=await fs.mkdtemp(path.join(path.dirname(folder),'.prepare-'));
+  try{
+    const url=`https://github.com/astral-sh/python-build-standalone/releases/download/20260901/cpython-${encodeURIComponent(PYTHON_RELEASE)}-${build[0]}-install_only.tar.gz`;
+    const response=await fetchImpl(url,{signal:AbortSignal.timeout(120000)});
+    if(!response.ok)throw Error('The Python download failed. Existing TasksAI files are unchanged.');
+    if(response.url&& !['github.com','release-assets.githubusercontent.com'].includes(new URL(response.url).hostname))throw Error('Unexpected Python download destination.');
+    const chunks=[];let size=0;
+    for await(const chunk of response.body){size+=chunk.length;if(size>100*1024*1024)throw Error('Python download exceeds its size limit.');chunks.push(chunk);}
+    const bytes=Buffer.concat(chunks);
+    if(createHash('sha256').update(bytes).digest('hex')!==build[1])throw Error('Python download verification failed. Nothing was installed.');
+    const archive=path.join(staging,'python.tar.gz');await fs.writeFile(archive,bytes);
+    const options={encoding:'utf8',timeout:60000,windowsHide:true,maxBuffer:16*1024*1024};
+    const tar=pythonArchiveTool(platform);
+    const listing=run(tar,['-tzf',archive],options);
+    if(listing.error||listing.status!==0)throw Error('The Python archive could not be inspected.');
+    const entries=listing.stdout.split(/\r?\n/).filter(Boolean);
+    if(!entries.length||entries.some(name=>!name.startsWith('python/')||name.includes('\\')||name.split('/').includes('..')))throw Error('The Python archive contains an unexpected path.');
+    const extracted=run(tar,['-xzf',archive,'-C',staging],options);
+    if(extracted.error||extracted.status!==0)throw Error('The Python archive could not be extracted.');
+    const stagedExecutable=path.join(staging,path.relative(folder,executable));
+    if(!probeManagedPython(stagedExecutable,{run}))throw Error('The downloaded Python did not pass its local checks.');
+    await fs.unlink(archive);
+    await fs.writeFile(path.join(staging,'tasksai-python.json'),JSON.stringify({version:PYTHON_RELEASE,url,sha256:build[1]},null,2)+'\n');
+    await fs.rename(staging,folder);
+    if(!probeManagedPython(executable,{run}))throw Error('The installed Python could not start. Its files were retained for repair.');
+    return executable;
+  }finally{await fs.rm(staging,{recursive:true,force:true});}
+}

package/src/operation-lock.js

@@ -0,0 +1,22 @@
+import {promises as fs} from 'node:fs';
+
+// Never remove another process's lock, or assume that age means it is stale.
+export async function withLock(lockPath, callback) {
+  let handle;
+  try {
+    handle = await fs.open(lockPath, 'wx', 0o600);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw new Error(`Another TasksAI installation operation is running, or a previous operation was interrupted (${lockPath}). Let the running operation finish. If it was interrupted, preserve the installation for recovery before retrying.`);
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(JSON.stringify({pid: process.pid, startedAt: new Date().toISOString()}) + '\n');
+    await handle.sync();
+    return await callback();
+  } finally {
+    await handle.close();
+    await fs.unlink(lockPath);
+  }
+}

package/src/prepared-update.js

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import {promises as fs} from 'node:fs';
+import {writeUpdateJournal} from './update-journal.js';
+import {softwareHash} from './software-hash.js';
+import {withSoftwareStopped} from './software-use.js';
+
+async function exists(target){try{return await fs.lstat(target);}catch(error){if(error.code==='ENOENT')return null;throw error;}}
+
+// Prepare all replacement software before touching the installed copy. This
+// restores ordinary activation failures; crash recovery is a separate gate.
+export async function preparedUpdate(installDir,options){
+ return withSoftwareStopped(installDir,assertHeld=>prepareSoftware(installDir,{...options,assertHeld}));
+}
+
+async function prepareSoftware(installDir,{prepare,installDependencies,validate=async()=>{},skipDependencies=false,rename=fs.rename,assertHeld}){
+ // Even if an interrupted operation's lock was cleared, never replace software
+ // while its unfinished recovery copy remains. Successful backups are retained.
+ for(const entry of await fs.readdir(installDir,{withFileTypes:true})){
+  if(!entry.name.startsWith('.software-update-'))continue;
+  const prior=path.join(installDir,entry.name);
+  let completed=false;
+  if(entry.isDirectory()&&!entry.isSymbolicLink()){
+   const statePath=path.join(prior,'state.json');
+   const stat=await exists(statePath);
+   if(stat?.isFile()&&!stat.isSymbolicLink()&&stat.size<=4096){
+    try{completed=['activated','recovered'].includes(JSON.parse(await fs.readFile(statePath,'utf8')).status);}catch{}
+   }
+  }
+  if(!completed)throw Error('An unfinished software update requires recovery. Preserve '+prior+' and the installed files before retrying.');
+ }
+ const transaction=await fs.mkdtemp(path.join(installDir,'.software-update-'));
+ await fs.chmod(transaction,0o700);
+ const prepared=path.join(transaction,'prepared'),previous=path.join(transaction,'previous');
+ await fs.mkdir(prepared);await fs.mkdir(previous);
+ const names=[...(skipDependencies?[]:['python']),'runtime','agent-install.json','vertical.json','.env'];
+ const moved=[];let activationStarted=false;
+ try{
+  for(const name of names){const stat=await exists(path.join(installDir,name));if(stat?.isSymbolicLink())throw Error('Installed software paths cannot be symbolic links');}
+  const runtime=path.join(prepared,'runtime');
+  if(await exists(path.join(installDir,'runtime')))await fs.cp(path.join(installDir,'runtime'),runtime,{recursive:true,dereference:false,
+   filter:async source=>{if((await fs.lstat(source)).isSymbolicLink())throw Error('Installed runtime files cannot be symbolic links');return true;}});
+  else await fs.mkdir(runtime);
+  await prepare(prepared,runtime);
+  if(!skipDependencies)await installDependencies(runtime,path.join(prepared,'python'));
+  await validate(runtime,path.join(prepared,'python'));
+  for(const name of names)if(!(await exists(path.join(prepared,name))))throw Error('Prepared update is missing '+name);
+  const assets=[];
+  for(const name of names){
+   const beforeHash=await softwareHash(path.join(installDir,name));
+   assets.push({name,hadPrevious:beforeHash!==null,beforeHash,afterHash:await softwareHash(path.join(prepared,name)),phase:'pending'});
+  }
+  const state={format:2,status:'prepared',names,assets};
+  await writeUpdateJournal(transaction,state);
+  assertHeld();
+  activationStarted=true;
+  for(const asset of assets){
+   assertHeld();
+   const {name}=asset;
+   const target=path.join(installDir,name),backup=path.join(previous,name);
+   const item={name,hadPrevious:asset.hadPrevious,activated:false};moved.push(item);
+   if(item.hadPrevious){
+    await rename(target,backup);
+    asset.phase='original_moved';await writeUpdateJournal(transaction,state);
+   }
+   await rename(path.join(prepared,name),target);item.activated=true;
+   asset.phase='replacement_moved';await writeUpdateJournal(transaction,state);
+  }
+  state.status='activated';await writeUpdateJournal(transaction,state);
+  return {previousSoftware:previous};
+ }catch(error){
+  if(activationStarted)assertHeld();
+  let restoreError;
+  for(const item of [...moved].reverse()){
+   const target=path.join(installDir,item.name),backup=path.join(previous,item.name);
+   try{
+    if(item.activated)await fs.rename(target,path.join(prepared,item.name));
+    if(await exists(backup))await fs.rename(backup,target);
+   }catch(failure){restoreError=failure;}
+  }
+  if(restoreError)throw Error('Software update stopped and automatic software restoration failed. Preserve '+transaction+' for recovery. '+restoreError.message,{cause:error});
+  // All data here is a prepared software copy; project workspaces are never
+  // included. Keep successful previous software, discard failed preparations.
+  await fs.rm(transaction,{recursive:true,force:true});
+  throw Error(activationStarted?'Software update failed; previous software was restored. '+error.message:'Software preparation failed; installed software was not replaced. '+error.message,{cause:error});
+ }
+}

package/src/private-workflow.js

@@ -0,0 +1,116 @@
+// Explicit private-development route in the shared launcher. No license/billing API imports.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {createHash, randomUUID} from 'node:crypto';
+
+const runtime=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'../runtime');
+function run(command,args,options={}){
+ const result=spawnSync(command,args,{encoding:'utf8',...options});
+ if(result.error||result.status!==0)throw new Error(`Private workflow setup failed: ${result.error?.message||result.stderr?.slice(-3000)||'command failed'}`);
+ return result.stdout;
+}
+const q=value=>JSON.stringify(value); // TOML strings only, never shell interpolation.
+const sh=value=>"'"+value.replaceAll("'","'\\''")+"'";
+export async function installPrivateWorkflow(argv){
+ if(process.platform!=='darwin')throw new Error('This private trial has only been qualified for Mac.');
+ const options={};
+ for(let i=0;i<argv.length;i++){
+  if(argv[i]==='--enable-development')options.enabled=true;
+  else if(argv[i]==='--update')options.update=true;
+  else if(['--install-dir','--python'].includes(argv[i])){
+   const key=argv[i].slice(2);if(!argv[i+1]||argv[i+1].startsWith('--'))throw new Error(`Missing ${argv[i]} value`);
+   options[key]=argv[++i];
+  }else throw new Error(`Unsupported private workflow option: ${argv[i]}`);
+ }
+ if(!options.enabled)throw new Error('Private workflow requires explicit --enable-development.');
+ const root=path.resolve(options['install-dir']||path.join(os.homedir(),'TasksAI Private Trial'));
+ if(options.update)return updatePrivateWorkflow(root);
+ // Refuse overwrite; new installs cannot replace a workspace or a customer installation.
+ await fs.mkdir(root,{recursive:false,mode:0o700});
+ const marker=path.join(root,'INSTALLATION-INCOMPLETE.txt');
+ await fs.writeFile(marker,'Installation is incomplete. Retain this folder for diagnosis. No client profile was changed.\n',{mode:0o600});
+ const python=options.python||'python3';
+ run(python,['-c','import sys; assert (3,11)<=sys.version_info[:2]<(3,15), "Python 3.11–3.14 required"']);
+ const installed=path.join(root,'runtime');await fs.mkdir(installed,{mode:0o700});
+ await fs.cp(path.join(runtime,'workflows'),path.join(installed,'workflows'),{recursive:true,filter:s=>!s.includes('__pycache__')&&!s.endsWith('.pyc')});
+ await fs.copyFile(path.join(runtime,'document_renderer.py'),path.join(installed,'document_renderer.py'));
+ const requirements=path.join(root,'requirements.txt');
+ await fs.copyFile(path.join(runtime,'workflow-requirements.txt'),requirements);
+ // A clean environment excludes compiled packages from an existing customer installation.
+ run(python,['-m','venv',path.join(root,'python')]);
+ const executable=path.join(root,'python/bin/python');
+ console.log('Installing the private document and spreadsheet components…');
+ run(executable,['-m','pip','install','--disable-pip-version-check','-r',requirements],{timeout:240000});
+ const workspace=path.join(root,'Saved jobs'),inbox=path.join(root,'Inbox');
+ await fs.mkdir(workspace,{mode:0o700});await fs.mkdir(inbox,{mode:0o700});
+ const server={command:executable,args:['-m','workflows.mcp_dev','--enable-development','--workspace',workspace,'--owner','private-mac-trial','--inbox',inbox],cwd:installed,env:{PYTHONPATH:installed},startup_timeout_sec:30,tool_timeout_sec:180,default_tools_approval_mode:'approve'};
+ const lines=['[mcp_servers.tasksai_workflow_dev]',...Object.entries(server).filter(([k])=>k!=='env').map(([k,v])=>`${k} = ${q(v)}`),'[mcp_servers.tasksai_workflow_dev.env]',`PYTHONPATH = ${q(installed)}`,''];
+ await fs.writeFile(path.join(root,'connection.toml'),lines.join('\n'),{mode:0o600});
+ const overrides=[];
+ for(const [k,v] of Object.entries(server)){
+  if(k==='env')overrides.push('-c',`mcp_servers.tasksai_workflow_dev.env.PYTHONPATH=${q(installed)}`);
+  else overrides.push('-c',`mcp_servers.tasksai_workflow_dev.${k}=${q(v)}`);
+ }
+ let codex=process.env.TASKSAI_CODEX_EXECUTABLE;
+ if(!codex){
+  const app='/Applications/ChatGPT.app/Contents/Resources/codex';
+  try{await fs.access(app);codex=app;}catch{codex='codex';}
+ }
+ const login=spawnSync(codex,['login','status'],{encoding:'utf8'});
+ if(login.status!==0||!`${login.stdout}${login.stderr}`.includes('Logged in using ChatGPT'))throw new Error('Sign into Codex with ChatGPT, then retry in a new installation folder.');
+ // Preserve only model selection; every conversation uses isolated Codex exec.
+ const model=run(python,['-c','import pathlib,tomllib,json; p=pathlib.Path.home()/".codex/config.toml"; d=tomllib.loads(p.read_text()) if p.exists() else {}; print(json.dumps({k:d[k] for k in ("model","model_reasoning_effort") if k in d}))']);
+ await fs.writeFile(path.join(root,'model-settings.json'),model,{mode:0o600});
+ const launch=['#!/bin/zsh','set -e',`cd ${sh(installed)}`,`exec ${sh(executable)} -m workflows.launcher --root ${sh(root)} --codex ${sh(codex)}`,''];
+ await fs.writeFile(path.join(root,'Start TasksAI.command'),launch.join('\n'),{mode:0o700});
+ run(executable,['-c','from workflows.gateway import Gateway, TOOLS; from workflows.store import JobStore; import docx,xlsxwriter,pypdf; print(len(TOOLS))'],{cwd:installed,env:{...process.env,PYTHONPATH:installed}});
+ const files={};
+ async function hashTree(dir){for(const item of await fs.readdir(dir,{withFileTypes:true})){if(item.name==='__pycache__')continue;const p=path.join(dir,item.name);if(item.isDirectory())await hashTree(p);else files[path.relative(installed,p)]=createHash('sha256').update(await fs.readFile(p)).digest('hex');}}
+ await hashTree(installed);
+ const receipt={kind:'private-workflow-development',created_at:new Date().toISOString(),root,workspace,inbox,server,files,client_profile_changed:false,account_api_calls:0,dependencies:run(executable,['-m','pip','freeze']).trim().split('\n')};
+ await fs.writeFile(path.join(root,'installation.json'),JSON.stringify(receipt,null,2)+'\n',{mode:0o600});
+ await fs.writeFile(path.join(root,'Read me.txt'),'TasksAI private Mac trial\n\nUse fictional documents only. Put the selected PDF, Word or text files in Inbox. Double-click Start TasksAI.command to open an interactive Codex session using your existing ChatGPT sign-in. Ask it to compare the offers. You do not need to write structured data.\n\nSaved jobs contains the original documents, versioned Word/Excel packages and local job database. Keep this entire folder to preserve and resume work. Each launch starts a new conversation; ask to reopen your saved matter.\n\nText-bearing documents only; scanned images and password-protected PDFs need accessible copies. Check extracted text against originals. This trial does not send, accept or professionally approve offers. Excel edits are scenarios; ask the workflow to revise the job to update both files.\n\nThis installation is separate from customer installations and does not change any global AI app configuration. Using the AI session consumes your existing ChatGPT allowance. To stop using it, close the session; retain the folder for your saved work.\n',{mode:0o600});
+ await fs.unlink(marker);
+ console.log(JSON.stringify({status:'private_installation_complete',root,launcher:path.join(root,'Start TasksAI.command'),client_profile_changed:false}));
+ return receipt;
+}
+
+async function updatePrivateWorkflow(root){
+ const receiptPath=path.join(root,'installation.json');
+ const receipt=JSON.parse(await fs.readFile(receiptPath,'utf8'));
+ if(receipt.kind!=='private-workflow-development'||receipt.root!==root)throw new Error('Select an existing private workflow installation.');
+ if((await fs.readFile(path.join(root,'requirements.txt'),'utf8'))!==(await fs.readFile(path.join(runtime,'workflow-requirements.txt'),'utf8')))throw new Error('Dependencies changed; create a fresh private installation.');
+ const installed=path.join(root,'runtime');
+ for(const [file,expected] of Object.entries(receipt.files)){
+  const full=path.resolve(installed,file);
+  if(!full.startsWith(installed+path.sep))throw new Error('Invalid installed file path.');
+  const actual=createHash('sha256').update(await fs.readFile(full)).digest('hex');
+  if(actual!==expected)throw new Error('Installed code changed outside this installer. Preserve and inspect it before updating.');
+ }
+ const suffix=randomUUID();const next=path.join(root,'runtime-next-'+suffix);
+ await fs.mkdir(next,{mode:0o700});
+ await fs.cp(path.join(runtime,'workflows'),path.join(next,'workflows'),{recursive:true,filter:s=>!s.includes('__pycache__')&&!s.endsWith('.pyc')});
+ await fs.copyFile(path.join(runtime,'document_renderer.py'),path.join(next,'document_renderer.py'));
+ const {mergeReleaseHistory}=await import('./workspace-runtime.js');
+ const registryName='realtor-release-registry.json';
+ let priorRegistry;
+ try{priorRegistry=JSON.parse(await fs.readFile(path.join(installed,'workflows',registryName),'utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}
+ const nextRegistry=JSON.parse(await fs.readFile(path.join(next,'workflows',registryName),'utf8'));
+ await fs.writeFile(path.join(next,'workflows',registryName),JSON.stringify(mergeReleaseHistory(priorRegistry,nextRegistry),null,2)+'\n');
+
+ run(path.join(root,'python/bin/python'),['-c','from workflows.gateway import TOOLS; from workflows.realtor.adapter import SellerOfferAdapter; assert len(TOOLS)==13'],{cwd:next,env:{...process.env,PYTHONPATH:next}});
+ const files={};
+ async function hashTree(dir){for(const item of await fs.readdir(dir,{withFileTypes:true})){if(item.name==='__pycache__')continue;const p=path.join(dir,item.name);if(item.isDirectory())await hashTree(p);else files[path.relative(next,p)]=createHash('sha256').update(await fs.readFile(p)).digest('hex');}}
+ await hashTree(next);
+ const previous=path.join(root,'Previous implementations',suffix);await fs.mkdir(previous,{recursive:true,mode:0o700});
+ await fs.copyFile(receiptPath,path.join(previous,'installation.json'));
+ await fs.rename(installed,path.join(previous,'runtime'));
+ try{await fs.rename(next,installed);}catch(error){await fs.rename(path.join(previous,'runtime'),installed);throw error;}
+ const updated={...receipt,files,updated_at:new Date().toISOString(),previous_implementation:previous};
+ const temp=receiptPath+'.next';await fs.writeFile(temp,JSON.stringify(updated,null,2)+'\n',{mode:0o600});await fs.rename(temp,receiptPath);
+ console.log(JSON.stringify({status:'private_implementation_updated',root,previous,workspace_preserved:true}));
+ return updated;
+}

package/src/python-runtime.js

@@ -0,0 +1,50 @@
+import {spawnSync} from 'node:child_process';
+import path from 'node:path';
+import {managedPythonLocation,probeManagedPython,installManagedPython} from './managed-python.js';
+
+const probe='import json,sys; print(json.dumps({"version":list(sys.version_info[:3]),"executable":sys.executable}))';
+
+export function detectPython({platform=process.platform,run=spawnSync}={}){
+  const candidates=platform==='win32'?[['python',[]],['python3',[]],['py',['-3']]]:[['python3',[]],['python',[]]];
+  const paths=platform==='win32'?path.win32:path.posix;
+  for(const [command,prefix] of candidates){
+    const result=run(command,[...prefix,'-I','-c',probe],{encoding:'utf8',timeout:5000,windowsHide:true,maxBuffer:16384});
+    if(result.error||result.status!==0)continue;
+    try{
+      const info=JSON.parse(result.stdout);
+      if(!Array.isArray(info.version)||info.version[0]!==3||!Number.isInteger(info.version[1])||info.version[1]<10)continue;
+      if(typeof info.executable!=='string'||!paths.isAbsolute(info.executable)||/[\r\n\0]/.test(info.executable))continue;
+      return info.executable;
+    }catch{}
+  }
+  return null;
+}
+
+// One interpreter per installer process: dependency installation, client setup,
+// health checks and software-use coordination must not choose independently.
+let selected;
+let installRoot;
+export function setPythonInstallRoot(root){
+  if(installRoot!==root){installRoot=root;selected=undefined;}
+}
+function availablePython(){
+  if(installRoot){
+    const {executable}=managedPythonLocation(installRoot);
+    if(probeManagedPython(executable))return executable;
+  }
+  return detectPython();
+}
+export async function ensurePython(installDir){
+  setPythonInstallRoot(installDir);
+  selected??=availablePython();
+  if(!selected){
+    console.log('Installing the local Python needed by TasksAI. Your existing applications and project files are preserved.');
+    selected=await installManagedPython(installDir);
+  }
+  return selected;
+}
+export function requirePython(){
+  selected??=availablePython();
+  if(!selected)throw Error('TasksAI requires Python 3.10 or newer. No usable installation was found.');
+  return selected;
+}

package/src/recover-installation.js

@@ -0,0 +1,30 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {planUpdateRecovery,restoreUpdate} from './update-recovery.js';
+
+export async function recoverInstallation(installDir){
+  let entries;
+  try{entries=await fs.readdir(installDir,{withFileTypes:true});}
+  catch(error){if(error.code==='ENOENT')throw Error('No saved installation was found at '+installDir);throw error;}
+  const pending=[];
+  for(const entry of entries){
+    if(!entry.name.startsWith('.software-update-'))continue;
+    let complete=false;
+    if(entry.isDirectory()&&!entry.isSymbolicLink()){
+      try{
+        const file=path.join(installDir,entry.name,'state.json');
+        const stat=await fs.lstat(file);
+        if(stat.isFile()&&!stat.isSymbolicLink()&&stat.size<=4096)complete=['activated','recovered'].includes(JSON.parse(await fs.readFile(file,'utf8')).status);
+      }catch{}
+    }
+    if(!complete)pending.push(entry.name);
+  }
+  if(!pending.length){
+    if(entries.some(entry=>['.installer-operation.lock','.installer-recovery.lock'].includes(entry.name)))throw Error('An installation lock remains without a supported unfinished transaction. Preserve the installation for recovery review.');
+    return {status:'not_needed'};
+  }
+  if(pending.length!==1)throw Error('More than one unfinished update needs review. Preserve all recovery directories; no software was changed.');
+  // Establish a supported, unambiguous candidate before touching stale locks.
+  await planUpdateRecovery(installDir,pending[0]);
+  return restoreUpdate(installDir,pending[0],{recoverInterruptedLock:true});
+}

package/src/recovery-lock.js

@@ -0,0 +1,30 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {withLock} from './operation-lock.js';
+
+export async function withRecoveryLock(installDir,callback){
+  // Serialize recovery attempts. A crash of recovery itself remains fail-closed;
+  // do not recursively clear locks whose ownership cannot be established.
+  return withLock(path.join(installDir,'.installer-recovery.lock'),async()=>{
+    const lock=path.join(installDir,'.installer-operation.lock');
+    let stat;
+    try{stat=await fs.lstat(lock);}catch(error){if(error.code!=='ENOENT')throw error;}
+    if(stat){
+      if(!stat.isFile()||stat.isSymbolicLink()||stat.size>4096)throw Error('Cannot establish interrupted installer ownership');
+      const text=await fs.readFile(lock,'utf8');
+      let owner;
+      try{owner=JSON.parse(text);}catch{throw Error('Cannot establish interrupted installer ownership');}
+      if(!owner||!Number.isSafeInteger(owner.pid)||owner.pid<=0)throw Error('Cannot establish interrupted installer ownership');
+      try{
+        process.kill(owner.pid,0);
+        throw Error('The recorded installer process is still running; recovery has not started');
+      }catch(error){if(error.code!=='ESRCH')throw error;}
+      const current=await fs.lstat(lock);
+      if(current.ino!==stat.ino||current.isSymbolicLink()||await fs.readFile(lock,'utf8')!==text)throw Error('Installer ownership changed during recovery inspection');
+      await fs.rename(lock,path.join(installDir,'.interrupted-operation-'+randomUUID()+'.json'));
+    }
+    // A competing normal installer may acquire this first; in that case stop.
+    return withLock(lock,callback);
+  });
+}

package/src/software-hash.js

@@ -0,0 +1,24 @@
+import {promises as fs,createReadStream} from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+
+// Hash software only. Never follow links into a workspace or another directory.
+export async function softwareHash(target){
+  try{await fs.lstat(target);}catch(error){if(error.code==='ENOENT')return null;throw error;}
+  const hash=createHash('sha256');let count=0;
+  async function visit(file,relative,depth){
+    if(++count>100000||depth>128)throw Error('Software tree exceeds recovery inspection limits');
+    const stat=await fs.lstat(file);
+    if(stat.isSymbolicLink()||(!stat.isFile()&&!stat.isDirectory()))throw Error('Software recovery cannot inspect links or special files');
+    hash.update(JSON.stringify([relative,stat.isDirectory()?'directory':'file'])+'\n');
+    if(stat.isDirectory()){
+      for(const name of (await fs.readdir(file)).sort())await visit(path.join(file,name),relative?relative+'/'+name:name,depth+1);
+    }else{
+      hash.update(String(stat.size)+'\n');
+      for await(const chunk of createReadStream(file))hash.update(chunk);
+      const after=await fs.lstat(file);
+      if(after.size!==stat.size||after.mtimeMs!==stat.mtimeMs||after.ino!==stat.ino)throw Error('Software changed during recovery inspection');
+    }
+  }
+  await visit(target,'',0);return hash.digest('hex');
+}

package/src/software-use.js

@@ -0,0 +1,32 @@
+import {promises as fs} from 'node:fs';
+import {spawn} from 'node:child_process';
+import {requirePython} from './python-runtime.js';
+
+// Use the same standard-library OS lock as Python services. The child retains
+// the exclusive lock until stdin closes, including when the Node parent exits.
+export async function withSoftwareStopped(installDir,callback){
+  const source=await fs.readFile(new URL('../runtime/software_use.py',import.meta.url),'utf8');
+  const program=source+`\nimport sys\ntry:\n    with software_use(sys.argv[1], exclusive=True):\n        print('READY', flush=True)\n        sys.stdin.buffer.read()\nexcept (OSError, RuntimeError):\n    sys.exit(2)\n`;
+  const child=spawn(requirePython(),['-I','-c',program,installDir],{stdio:['pipe','pipe','pipe']});
+  child.stdin.on('error',()=>{}); // The child may reject the lock before stdin closes.
+  const exited=new Promise(resolve=>{child.once('exit',resolve);child.once('error',()=>resolve(null));});
+  child.stderr.resume();
+  try{
+    await new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>reject(Error('Could not check whether TasksAI software is in use')),15000);
+      const fail=()=>{clearTimeout(timer);reject(Error('Close the TasksAI workspace and its AI-app connection before updating or recovering the software'));};
+      child.once('error',fail);child.once('exit',fail);
+      child.stdout.once('data',data=>{
+        clearTimeout(timer);
+        if(data.toString().trim()==='READY')resolve();else reject(Error('Invalid software-use response'));
+      });
+    });
+    const assertHeld=()=>{if(child.exitCode!==null||child.signalCode!==null)throw Error('Software-use coordination ended unexpectedly; preserve recovery files');};
+    assertHeld();
+    return await callback(assertHeld);
+  }finally{
+    child.stdin.end();
+    const timer=setTimeout(()=>child.kill(),5000);
+    await exited;clearTimeout(timer);
+  }
+}

package/src/update-journal.js

@@ -0,0 +1,24 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+
+// Replace the state record as a complete file, rather than truncating the last
+// valid record. Windows directory flushing requires separate native coverage.
+export async function writeUpdateJournal(transaction,state,{rename=fs.rename}={}){
+  const temporary=path.join(transaction,'.state-'+randomUUID());
+  let handle;
+  try{
+    handle=await fs.open(temporary,'wx',0o600);
+    await handle.writeFile(JSON.stringify(state)+'\n');
+    await handle.sync();
+    await handle.close();handle=null;
+    await rename(temporary,path.join(transaction,'state.json'));
+    if(process.platform!=='win32'){
+      const directory=await fs.open(transaction,'r');
+      try{await directory.sync();}finally{await directory.close();}
+    }
+  }finally{
+    if(handle)await handle.close();
+    await fs.rm(temporary,{force:true});
+  }
+}

package/src/update-recovery.js

@@ -0,0 +1,72 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {softwareHash} from './software-hash.js';
+import {writeUpdateJournal} from './update-journal.js';
+import {withLock} from './operation-lock.js';
+import {withRecoveryLock} from './recovery-lock.js';
+import {withSoftwareStopped} from './software-use.js';
+
+const SOFTWARE=['python','runtime','agent-install.json','vertical.json','.env'];
+const digest=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value);
+
+// Read-only planning. Callers must coordinate writers before executing a plan;
+// a recorded phase alone never proves which files actually reached a location.
+export async function planUpdateRecovery(installDir,transactionName){
+  if(!/^\.software-update-[A-Za-z0-9]+$/.test(transactionName))throw Error('Invalid recovery directory');
+  const transaction=path.join(installDir,transactionName);
+  for(const directory of [installDir,transaction,path.join(transaction,'prepared'),path.join(transaction,'previous')]){
+    const stat=await fs.lstat(directory);
+    if(!stat.isDirectory()||stat.isSymbolicLink())throw Error('Recovery directories must be ordinary local directories');
+  }
+  const statePath=path.join(transaction,'state.json'),stat=await fs.lstat(statePath);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.size>4096)throw Error('Invalid recovery record');
+  const state=JSON.parse(await fs.readFile(statePath,'utf8'));
+  if(state.format!==2||!['prepared','recovered'].includes(state.status)||!Array.isArray(state.names)||!Array.isArray(state.assets))throw Error('This update does not have a supported unfinished recovery record');
+  const expected=state.names.includes('python')?SOFTWARE:SOFTWARE.slice(1);
+  if(JSON.stringify(state.names)!==JSON.stringify(expected)||state.assets.length!==expected.length)throw Error('Invalid recovery component list');
+  const actions=[];
+  for(let i=0;i<expected.length;i++){
+    const asset=state.assets[i],name=expected[i];
+    if(asset.name!==name||typeof asset.hadPrevious!=='boolean'||!digest(asset.afterHash)||
+      (asset.hadPrevious?!digest(asset.beforeHash):asset.beforeHash!==null)||
+      !['pending','original_moved','replacement_moved'].includes(asset.phase))throw Error('Invalid recovery component evidence');
+    const active=path.join(installDir,name),previous=path.join(transaction,'previous',name),prepared=path.join(transaction,'prepared',name);
+    const a=await softwareHash(active),b=await softwareHash(previous),p=await softwareHash(prepared);
+    if(asset.hadPrevious&&b===null&&a===asset.beforeHash&&p===asset.afterHash)continue;
+    if(asset.hadPrevious&&b===asset.beforeHash){
+      if(a===null&&p===asset.afterHash){actions.unshift({name,moves:[{from:previous,to:active,hash:b}]});continue;}
+      if(a===asset.afterHash&&p===null){actions.unshift({name,moves:[{from:active,to:prepared,hash:a},{from:previous,to:active,hash:b}]});continue;}
+    }
+    if(!asset.hadPrevious&&b===null){
+      if(a===null&&p===asset.afterHash)continue;
+      if(a===asset.afterHash&&p===null){actions.unshift({name,moves:[{from:active,to:prepared,hash:a}]});continue;}
+    }
+    throw Error('Recovery files are missing, changed or ambiguous for '+name+'. Preserve all copies for review.');
+  }
+  if(state.status==='recovered'&&actions.length)throw Error('Recovered software has changed; preserve the recovery copies for review');
+  return {transaction,state,actions};
+}
+
+// Active workspace coordination and the customer command remain separate.
+export async function restoreUpdate(installDir,transactionName,{rename=fs.rename,recoverInterruptedLock=false}={}){
+  const lock=callback=>recoverInterruptedLock?withRecoveryLock(installDir,callback):withLock(path.join(installDir,'.installer-operation.lock'),callback);
+  return lock(()=>withSoftwareStopped(installDir,async assertHeld=>{
+    const initial=await planUpdateRecovery(installDir,transactionName);
+    let moved=0;
+    for(const action of initial.actions){
+      for(const move of action.moves){
+        assertHeld();
+        if(await softwareHash(move.from)!==move.hash||await softwareHash(move.to)!==null)throw Error('Recovery files changed before restoration; preserve all copies');
+        await rename(move.from,move.to);moved++;
+        // The initial identities plus actual locations make a retry possible
+        // even when interruption occurs before this progress record is saved.
+        await writeUpdateJournal(initial.transaction,{...initial.state,recoveryMoves:moved});
+      }
+    }
+    assertHeld();
+    const verified=await planUpdateRecovery(installDir,transactionName);
+    if(verified.actions.length)throw Error('Software restoration is incomplete; preserve the recovery copies');
+    await writeUpdateJournal(verified.transaction,{...verified.state,status:'recovered'});
+    return {status:'recovered',transaction:verified.transaction,moved};
+  }));
+}

package/src/workspace-runtime.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import {promises as fs} from 'node:fs';
+
+// Copy only release-owned workflow files. Customer projects live elsewhere.
+export async function installWorkspaceRuntime(bundledRuntime, runtimeDir) {
+  const source=path.join(bundledRuntime,'workflows');
+  const destination=path.join(runtimeDir,'workflows');
+  const registryName='realtor-release-registry.json';
+  let previous;
+  try { previous=JSON.parse(await fs.readFile(path.join(destination,registryName),'utf8')); }
+  catch(error) { if(error.code!=='ENOENT') throw error; }
+  const merged=mergeReleaseHistory(previous,JSON.parse(await fs.readFile(path.join(source,registryName),'utf8')));
+
+  await fs.cp(source,destination,{recursive:true,force:true,dereference:false,
+    filter: async entry=>{
+      const stat=await fs.lstat(entry);
+      if(stat.isSymbolicLink()) throw new Error('Bundled workflow files must not be symbolic links');
+      const name=path.basename(entry);
+      return name!=='__pycache__' && !name.endsWith('.pyc') && !name.endsWith('.pyo');
+    }});
+  await fs.writeFile(path.join(destination,registryName),JSON.stringify(merged,null,2)+'\n','utf8');
+  const workflowRequirements=await fs.readFile(path.join(bundledRuntime,'workflow-requirements.txt'),'utf8');
+  await fs.writeFile(path.join(runtimeDir,'workflow-requirements.txt'),workflowRequirements,'utf8');
+  const requirements=path.join(runtimeDir,'requirements.txt');
+  const base=await fs.readFile(requirements,'utf8');
+  const include='-r workflow-requirements.txt';
+  if(!base.split(/\r?\n/).includes(include)) await fs.writeFile(requirements,base.trimEnd()+'\n'+include+'\n','utf8');
+}
+
+export function mergeReleaseHistory(previous, next) {
+  if (!previous) return next;
+  if(previous.product_id!=='realtor'||next.product_id!=='realtor') throw new Error('Invalid release registry product');
+  const merged=structuredClone(next);
+  for(const [id,old] of Object.entries(previous.skills)) {
+    if(!merged.skills[id]) throw new Error('An installed skill is missing from the update; preserve its migration before continuing');
+    const current=merged.skills[id];const versions=new Map();
+    for(const item of [current,...(current.history||[]),old,...(old.history||[])]) {
+      if(typeof item.version!=='string'||!/^[0-9a-f]{64}$/.test(item.content_sha256)) throw new Error('Invalid saved skill version');
+      if(versions.has(item.version)&&versions.get(item.version)!==item.content_sha256) throw new Error('An immutable skill version has conflicting content');
+      versions.set(item.version,item.content_sha256);
+    }
+    current.history=[...versions].filter(([version])=>version!==current.version).map(([version,content_sha256])=>({version,content_sha256}));
+  }
+  return merged;
+}