rootrework 1.0.2 → 1.0.4

package/README.md

@@ -0,0 +1,20 @@
+# rootRework
+
+Run either command on your computer with Node.js 22.13 or later:
+
+    npx -y @rootenterprise/rootrework@latest remote
+    npx -y rootrework@latest remote
+
+Both commands also start remote mode when `remote` is omitted. Complete the browser connection, then add rootRework in ChatGPT using `https://rootrework.com/mcp`, OAuth, and Dynamic Client Registration. Use the same browser for installation and ChatGPT authorization. No customer username, password, subscription activation, or device capability is required.
+
+Check the live connection at `https://rootrework.com/verify`. In ChatGPT, select rootRework using its **Try in chat** control or the plugin picker for each chat where you want to use it. The host may require a plugin selection for a later request; this reuses the connected account without repeating authorization. Existing account credentials remain optional for recovering older installations. The `session` command opens the current installation's browser workspace when you change browsers or clear site data. Keep installation state private.
+
+For a local MCP client, use command `npx` with arguments `-y`, `@rootenterprise/rootrework@latest`, `stdio`. Standard input and output carry MCP JSON messages; diagnostics use standard error. This local transport runs tools under the invoking operating-system user. OAuth DCR protects the public remote service.
+
+Use `rootrework status`, `diagnose`, `repair`, `restart`, `stop`, `update`, or `uninstall` through the same npx package command. Updates preserve valid registration, tokens, device identity and retained results. `uninstall` preserves data; `uninstall --purge` removes only that installation's owned data after its processes stop. No independent subscription or billing service is installed.
+
+State uses native conventions: `%LOCALAPPDATA%\rootRework` on Windows, `~/Library/Application Support/rootRework` on macOS, and `${XDG_STATE_HOME:-~/.local/state}/rootRework` on Linux. npm-cache projections are compatibility views; the writable native state directory preserves operation across cache removal.
+
+The `.org` domain redirects with HTTP 308. Configure MCP clients with the canonical `.com` URL. Some HTTP clients remove bearer authorization across origins; a redirect cannot force them to forward it.
+
+Tools run with the current user's permissions and can change files or execute commands. Tool availability reflects installed native capabilities. DOCX/XLSX editing preserves supported document parts; PDF extraction reads text layers and does not perform OCR. Scheduled commands require the device agent to be running.

package/bin/cli.mjs

@@ -1,2 +1,267 @@
 #!/usr/bin/env node
-import '@rootenterprise/rootrework/bin/cli.mjs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { packageRoot, statePath, readJson, writeJson, withLock, materialize, materializeProjection, activateInstallation, removeOwnedCode, login, api, alive, sleep, requestJson, openBrowser, initializeOwner } from '../src/client.mjs';
+import { installService, serviceAction, run, windowsProcessArguments } from '../src/service.mjs';
+import { runAgent } from '../src/agent.mjs';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => { const index = args.indexOf(name); if (index < 0) return fallback; if (!args[index + 1] || args[index + 1].startsWith('--')) throw new Error(`A value is required for ${name}.`); return args[index + 1]; };
+const command = args.includes('--help') || args.includes('-h') ? 'help' : args[0] && !args[0].startsWith('-') ? args[0] : 'remote';
+const stateDir = path.resolve(option('--state-dir', statePath()));
+const output = value => process.stdout.write(JSON.stringify(value) + '\n');
+const manifest = await readJson(path.join(packageRoot, 'package.json'));
+const locked = fn => withLock(path.join(stateDir, 'lifecycle.lock'), fn);
+async function processLive(pid) {
+  if (!alive(pid)) return false;
+  if (process.platform !== 'linux') return true;
+  const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8').catch(error => { if (error.code === 'ENOENT' || error.code === 'ESRCH') return ''; throw error; });
+  return Boolean(stat) && !/\) [ZX] /.test(stat);
+}
+const versionParts = v => v.split('+')[0].split('-');
+function compareVersion(a, b) {
+  const [ac, ap] = versionParts(a), [bc, bp] = versionParts(b);
+  const left = ac.split('.').map(Number), right = bc.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
+  if (ap === bp) return 0;
+  if (ap === undefined || bp === undefined) return ap === undefined ? 1 : -1;
+  const aa = ap.split('.'), bb = bp.split('.');
+  for (let i = 0; i < Math.max(aa.length, bb.length); i++) { if (aa[i] === bb[i]) continue; if (aa[i] === undefined || bb[i] === undefined) return aa[i] === undefined ? -1 : 1; const an = /^\d+$/.test(aa[i]), bn = /^\d+$/.test(bb[i]); if (an !== bn) return an ? -1 : 1; return (an ? Number(aa[i]) > Number(bb[i]) : aa[i] > bb[i]) ? 1 : -1; }
+  return 0;
+}
+async function ownedProcess(agent) {
+  if (!agent || !await processLive(agent.pid) || typeof agent.release !== 'string') return false;
+  if (process.platform === 'linux') {
+    const cmd = await fs.readFile(`/proc/${agent.pid}/cmdline`, 'utf8').catch(() => '');
+    const argv = cmd.split('\0'), index = argv.indexOf('--state-dir');
+    return argv.includes(path.join(agent.release, 'bin', 'cli.mjs')) && index >= 0 && argv[index + 1] === stateDir;
+  }
+  if (process.platform === 'win32') {
+    const argv = await windowsProcessArguments(agent.pid);
+    if (!argv) return false;
+    const samePath = (a, b) => typeof a === 'string' && path.win32.isAbsolute(a) && path.win32.normalize(a).toLowerCase() === path.win32.normalize(b).toLowerCase();
+    const script = argv.findIndex(value => samePath(value, path.join(agent.release, 'bin', 'cli.mjs')));
+    const state = argv.indexOf('--state-dir');
+    return script > 0 && argv[script + 1] === 'run' && state > script && samePath(argv[state + 1], stateDir);
+  }
+  const result = await run('ps', ['-p', String(agent.pid), '-o', 'command=']);
+  return result.code === 0 && result.stdout.includes(path.join(agent.release, 'bin', 'cli.mjs')) && result.stdout.includes(stateDir);
+}
+async function status() {
+  const current = await readJson(path.join(stateDir, 'status.json'), { state: 'uninstalled' });
+  const agent = await readJson(path.join(stateDir, 'agent.json'));
+  const running = Boolean(agent && await ownedProcess(agent));
+  return { ...current, running, stateDir, installation: await readJson(path.join(stateDir, 'installation.json')), service: await readJson(path.join(stateDir, 'service.json')), ...(current.state === 'ready' && !running ? { state: 'disconnected' } : {}), ...(agent && await processLive(agent.pid) && !running ? { identity_mismatch: true } : {}) };
+}
+async function stop() {
+  if (process.platform !== 'win32') await serviceAction(stateDir, 'stop');
+  const agent = await readJson(path.join(stateDir, 'agent.json'));
+  if (agent && await processLive(agent.pid)) {
+    if (!await ownedProcess(agent)) {
+      const present = await readJson(path.join(stateDir, 'agent.json'));
+      if (!present || present.instanceId !== agent.instanceId || !await processLive(agent.pid)) return status();
+      throw new Error('The recorded process identity no longer matches this installation.');
+    }
+    if (process.platform === 'win32') await writeJson(path.join(stateDir, 'agent-stop.json'), { instanceId: agent.instanceId, pid: agent.pid, requestedAt: Date.now() });
+    else process.kill(agent.pid, 'SIGTERM');
+    for (let count = 0; count < 150; count++) {
+      const current = await readJson(path.join(stateDir, 'agent.json'));
+      if (!current || current.instanceId !== agent.instanceId || !await processLive(agent.pid)) break;
+      await sleep(100);
+    }
+    const remaining = await readJson(path.join(stateDir, 'agent.json'));
+    if (remaining?.instanceId === agent.instanceId && await processLive(agent.pid)) throw new Error('The agent has not completed shutdown. Its process was not force-killed.');
+  }
+  if (process.platform === 'win32') await serviceAction(stateDir, 'stop');
+  return status();
+}
+async function launch(release, service) {
+  let manager = service ? await installService(stateDir, release) : null;
+  if (!manager?.installed) {
+    if (!service) await serviceAction(stateDir, 'uninstall');
+    const file = await fs.open(path.join(stateDir, 'agent.log'), 'a', 0o600);
+    const child = spawn(process.execPath, [path.join(release, 'bin', 'cli.mjs'), 'run', '--state-dir', stateDir], { detached: true, stdio: ['ignore', file.fd, file.fd], windowsHide: true });
+    try { await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); }); child.unref(); } finally { await file.close(); }
+    manager = { installed: false, mode: 'detached', pid: child.pid, stateDir, release, ...(manager?.reason ? { reason: manager.reason } : {}) };
+    await writeJson(path.join(stateDir, 'service.json'), manager);
+  }
+  return manager;
+}
+async function ready(prepared) {
+  const maximum = Number(option('--startup-timeout', 30000));
+  if (!Number.isSafeInteger(maximum) || maximum < 1) throw new Error('startup-timeout must be a positive number of milliseconds.');
+  const deadline = Date.now() + maximum;
+  while (Date.now() < deadline) {
+    const current = await status();
+    if (current.running && current.release === prepared.release && current.state === 'ready' && current.version === prepared.version) return current;
+    if (current.release === prepared.release && current.state === 'failed') throw new Error(current.error || 'The agent failed.');
+    if (current.identity_mismatch) throw new Error('The recorded process identity no longer matches this installation.');
+    await sleep(200);
+  }
+  throw Object.assign(new Error('The agent did not become ready before the startup deadline. Use status or diagnose to inspect the connection.'), { code: 'startup_timeout' });
+}
+async function transition(prepared, { service = true, restart = false } = {}) {
+  const current = await status(), journalFile = path.join(stateDir, 'transition.json');
+  const interrupted = await readJson(journalFile);
+  const previous = interrupted?.previous || current.installation;
+  const wasRunning = interrupted?.wasRunning ?? current.running;
+  const previousService = interrupted?.previousService || current.service;
+  if (current.running && current.release === prepared.release && current.state === 'ready' && !restart) {
+    await activateInstallation(stateDir, prepared); await fs.rm(journalFile, { force: true });
+    return { ...await status(), projection: prepared.projection, reused: true };
+  }
+  const check = await run(process.execPath, [path.join(prepared.release, 'bin', 'cli.mjs'), 'self-test']);
+  if (check.code !== 0) {
+    let detail; try { detail = JSON.parse(check.stdout.trim().split('\n').at(-1)).message; } catch {}
+    throw new Error('Candidate verification failed; the working installation is retained.' + (detail ? ' ' + detail : ''));
+  }
+  await writeJson(journalFile, { previous, next: prepared, wasRunning, previousService, service, startedAt: interrupted?.startedAt || Date.now() });
+  try {
+    let manager = current.service;
+    if (!current.running || current.release !== prepared.release || restart) {
+      if (current.running) await stop();
+      await activateInstallation(stateDir, prepared);
+      await writeJson(path.join(stateDir, 'status.json'), { state: 'connecting', release: prepared.release, version: prepared.version, updatedAt: Date.now() });
+      manager = await launch(prepared.release, service);
+    }
+    const result = await ready(prepared);
+    await activateInstallation(stateDir, prepared);
+    await fs.rm(journalFile, { force: true });
+    return { ...result, manager, projection: prepared.projection, reused: false };
+  } catch (error) {
+    let recovery = { state: 'not_available' };
+    try {
+      await stop();
+      if (previous?.release && previous.release !== prepared.release) {
+        await writeJson(path.join(stateDir, 'installation.json'), previous);
+        await materializeProjection(previous.release, stateDir, previous.version, prepared.projection, previous.release);
+        if (wasRunning) {
+          await writeJson(path.join(stateDir, 'status.json'), { state: 'connecting', release: previous.release, version: previous.version, updatedAt: Date.now() });
+          await launch(previous.release, Boolean(previousService?.installed));
+          const restored = await ready(previous);
+          recovery = { state: 'ready', version: restored.version, release: previous.release };
+        } else recovery = { state: 'configured', version: previous.version, release: previous.release };
+        await fs.rm(journalFile, { force: true });
+      } else recovery = { state: 'failed', message: 'No different previously selected release is available.' };
+    } catch (restoreError) { recovery = { state: 'failed', message: restoreError.message }; }
+    throw Object.assign(new Error(error.message), { code: error.code || 'startup_failed', recovery });
+  }
+}
+async function start({ service = true, restart = false, source = packageRoot, allowDowngrade = false } = {}) {
+  if (!await readJson(path.join(stateDir, 'session.json'))) await login(stateDir, { issuer: option('--issuer', 'https://rootrework.com') });
+  const selected = await readJson(path.join(source, 'package.json'));
+  const installed = await readJson(path.join(stateDir, 'installation.json'));
+  if (!allowDowngrade && installed && compareVersion(installed.version, selected.version) > 0 && await readJson(path.join(installed.release, 'package.json'))) source = installed.release;
+  const prepared = await materialize(stateDir, source, { activate: false, projectionRoot: packageRoot });
+  if (args.includes('--foreground')) {
+    const current = await status();
+    if (current.running) return { ...current, projection: prepared.projection, reused: true };
+    await activateInstallation(stateDir, prepared);
+    return { foreground: prepared.release, projection: prepared.projection };
+  }
+  return transition(prepared, { service, restart });
+}
+async function ownerInitialize(file) {
+  const result = await initializeOwner(stateDir, file);
+  return { ...result, ...await materialize(stateDir) };
+}
+async function npmInstall(candidate, version) {
+  const installArgs = ['install', '--prefix', candidate, '--ignore-scripts', '--no-audit', '--no-fund', `${manifest.name}@${version}`];
+  if (process.platform !== 'win32') return run('npm', installArgs, { timeout_ms: 300000 });
+  const locations = [path.dirname(process.execPath), ...(process.env.PATH || '').split(path.delimiter)];
+  for (const location of locations) { const cli = path.join(location, 'node_modules', 'npm', 'bin', 'npm-cli.js'); if (await fs.stat(cli).then(info => info.isFile(), () => false)) return run(process.execPath, [cli, ...installArgs], { timeout_ms: 300000 }); }
+  throw new Error('The installed npm executable could not be resolved.');
+}
+async function update() {
+  if (!['@rootenterprise/rootrework', 'rootrework'].includes(manifest.name)) throw new Error('The installed package identity is not supported.');
+  const metadata = await requestJson('https://registry.npmjs.org/' + encodeURIComponent(manifest.name));
+  const version = metadata['dist-tags']?.latest;
+  if (typeof version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(version) || !metadata.versions?.[version]) throw new Error('No valid published latest release is available.');
+  const prior = await readJson(path.join(stateDir, 'installation.json'));
+  if (prior?.version === version) return { ...await start({ service: !args.includes('--no-service') }), update: 'current' };
+  let candidate = path.join(stateDir, 'candidates', version);
+  const candidates = await readJson(path.join(stateDir, 'candidates.json'), []);
+  if (!candidates.includes(candidate) && await fs.stat(candidate).catch(() => null)) candidate += '-' + randomUUID();
+  if (!candidates.includes(candidate)) { candidates.push(candidate); await writeJson(path.join(stateDir, 'candidates.json'), candidates); }
+  await fs.mkdir(candidate, { recursive: true, mode: 0o700 });
+  const result = await npmInstall(candidate, version);
+  if (result.code !== 0) throw new Error('Candidate acquisition failed; the working installation is retained.');
+  const source = path.join(candidate, 'node_modules', ...manifest.name.split('/'));
+  const acquired = await readJson(path.join(source, 'package.json'));
+  if (acquired?.name !== manifest.name || acquired.version !== version) throw new Error('The acquired candidate does not match the selected registry release.');
+  return { ...await start({ service: !args.includes('--no-service'), source, allowDowngrade: true }), update: 'completed' };
+}
+async function selfTest() {
+  const testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'rootrework-'));
+  let backend;
+  try {
+    const { createBackend } = await import('../src/backend.mjs');
+    backend = await createBackend({ stateDir: testDir, packageRoot, deviceId: randomUUID() });
+    const info = await backend.call('system_info', {});
+    const task = await backend.call('exec', { executable: process.execPath, args: ['-e', 'process.stdout.write("ready")'], cwd: testDir, wait_ms: 10000, timeout_ms: 10000 });
+    const data = await backend.call('task_events', { task_id: task.task_id });
+    if (task.state !== 'completed_success' || task.exit_code !== 0 || Buffer.from(data.data, 'base64').toString() !== 'ready') throw new Error(`The candidate execution backend failed its readback check: state ${task.state}, exit ${task.exit_code ?? 'unknown'}, supervisor exit ${task.supervisor_exit?.code ?? 'unknown'}.`);
+    return { state: 'verified', version: manifest.version, tools: backend.tools.length, platform: info };
+  } finally { await backend?.close(); await fs.rm(testDir, { recursive: true, force: true }); }
+}
+try {
+  let result;
+  if (['--version', 'version', '-v'].includes(command) || args.includes('--version')) result = { version: manifest.version };
+  else if (command === 'stdio') { const { runStdio } = await import('../src/stdio.mjs'); await runStdio(path.join(stateDir, 'stdio')); }
+  else if (command === 'run') result = await runAgent(stateDir);
+  else if (command === 'owner-init') result = await locked(() => ownerInitialize(args[1]));
+  else if (command === 'login') { const s = await login(stateDir, { issuer: option('--issuer', 'https://rootrework.com') }); result = { state: 'configured', device_id: s.deviceId }; }
+  else if (command === 'status') result = await status();
+  else if (command === 'stop') result = await locked(stop);
+  else if (command === 'restart') result = await locked(() => start({ service: !args.includes('--no-service'), restart: true }));
+  else if (command === 'repair') result = await locked(async () => {
+    const previous = await readJson(path.join(stateDir, 'session.json'));
+    if (previous) {
+      try { await api(stateDir, '/agent/identity', undefined, { method: 'GET', body: undefined }); }
+      catch (error) {
+        if (!['invalid_client', 'invalid_grant', 'login_required'].includes(error.code)) throw error;
+        if (previous.ownerInput !== undefined) throw new Error('The private owner provisioning needs recovery. Its existing state was retained.');
+        await login(stateDir, { issuer: previous.issuer, replaceRegistration: error.code === 'invalid_client' });
+      }
+    }
+    return { ...await start({ service: !args.includes('--no-service') }), repair: 'completed' };
+  });
+  else if (command === 'update') result = await locked(update);
+  else if (command === 'verify' || command === 'diagnose') {
+    const s = await status();
+    const health = await requestJson('https://rootrework.com/health').catch(error => ({ error: error.message }));
+    result = { ...s, platform: { os: process.platform, arch: process.arch, node: process.version }, health, session_present: Boolean(await readJson(path.join(stateDir, 'session.json'))) };
+  } else if (command === 'session') {
+    result = await api(stateDir, '/oauth/session', { return_to: '/verify' });
+    if (result.verification_uri && !args.includes('--no-browser')) await openBrowser(result.verification_uri);
+    result = { verification_uri: result.verification_uri };
+  } else if (command === 'project') {
+    const destination = option('--destination');
+    if (!destination) throw new Error('A destination is required.');
+    result = await locked(async () => { const installed = await readJson(path.join(stateDir, 'installation.json')); return { path: await materializeProjection(installed?.release || packageRoot, stateDir, installed?.version || manifest.version, path.resolve(destination), installed?.release || packageRoot) }; });
+  } else if (command === 'uninstall') result = await locked(async () => {
+    await stop(); await serviceAction(stateDir, 'uninstall');
+    const removal = await removeOwnedCode(stateDir, { purge: args.includes('--purge') });
+    if (removal.retained_data) await writeJson(path.join(stateDir, 'status.json'), { state: 'uninstalled', updatedAt: Date.now(), retainedData: true });
+    return { state: 'uninstalled', stateDir, ...removal };
+  });
+  else if (command === 'self-test') result = await selfTest();
+  else if (['remote', 'install', 'start'].includes(command)) result = await locked(() => start({ service: !args.includes('--no-service') }));
+  else if (['help', '--help', '-h'].includes(command)) result = { usage: 'rootrework [remote|stdio|status|diagnose|repair|restart|stop|update|uninstall]', options: ['--state-dir PATH', '--foreground', '--no-service', '--startup-timeout MILLISECONDS', 'uninstall --purge'], default: 'remote' };
+  else throw new Error(`Unknown command: ${command}`);
+  if (result?.foreground) {
+    const child = spawn(process.execPath, [path.join(result.foreground, 'bin', 'cli.mjs'), 'run', '--state-dir', stateDir], { stdio: 'inherit', windowsHide: true });
+    const interrupt = () => { if (!child.killed) child.kill('SIGINT'); }, terminate = () => { if (!child.killed) child.kill('SIGTERM'); };
+    process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+    const outcome = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', (code, signal) => resolve({ code, signal })); });
+    process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', terminate);
+    process.exitCode = outcome.code ?? (outcome.signal === 'SIGINT' ? 130 : 143);
+  } else {
+    if (command === 'uninstall' && result.retained_data === false) await fs.rmdir(stateDir).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
+    if (command !== 'stdio') output(result);
+  }
+  if (result?.state === 'failed' && !(command === 'run' && result.recoverable === false)) process.exitCode = 1;
+} catch (error) { const value = { state: 'failed', code: error.code || 'operation_failed', message: error.message, ...(error.recovery ? { recovery: error.recovery } : {}) }; if (command === 'stdio') process.stderr.write(JSON.stringify(value) + '\n'); else output(value); process.exitCode = 1; }

package/config/client.json

@@ -0,0 +1,7 @@
+{
+  "schema": 1,
+  "issuer": "https://rootrework.com",
+  "resource": "https://rootrework.com/mcp",
+  "authentication": "oauth-dcr",
+  "scope": "mcp"
+}

package/package.json

@@ -1,7 +1,11 @@
 {
-  "version": "1.0.2",
+  "name": "rootrework",
+  "version": "1.0.4",
   "description": "Remote computer tools with OAuth registration and persistent execution.",
   "type": "module",
+  "bin": {
+    "rootrework": "bin/cli.mjs"
+  },
   "engines": {
     "node": ">=22.13.0"
   },
@@ -12,19 +16,34 @@
     "type": "git",
     "url": "https://github.com/rootEnterprise/rootRework.git"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "name": "rootrework",
-  "bin": {
-    "rootrework": "bin/cli.mjs"
-  },
   "files": [
     "bin",
-    "LICENSE"
+    "src/client.mjs",
+    "src/service.mjs",
+    "src/agent.mjs",
+    "src/retention.mjs",
+    "src/backend.mjs",
+    "src/process.mjs",
+    "src/supervisor.mjs",
+    "src/search-worker.mjs",
+    "src/extended.mjs",
+    "config/client.json",
+    "LICENSE",
+    "src/stdio.mjs",
+    "README.md"
   ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "node --check bin/cli.mjs && node --check src/worker.mjs"
+  },
   "dependencies": {
-    "@rootenterprise/rootrework": "1.0.2"
+    "@lydell/node-pty": "1.2.0-beta.15",
+    "fflate": "0.8.3",
+    "@xmldom/xmldom": "0.9.12",
+    "pdfjs-dist": "6.4.299"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/src/agent.mjs

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { createBackend } from './backend.mjs';
+import { createExtensions } from './extended.mjs';
+import { createRetainer } from './retention.mjs';
+import { api, readJson, writeJson, alive, sleep, packageRoot } from './client.mjs';
+
+export async function runAgent(stateDir) {
+  const lockFile = path.join(stateDir, 'agent.json');
+  await fs.mkdir(stateDir, { recursive: true, mode: 0o700 });
+  const existing = await readJson(lockFile);
+  if (existing && alive(existing.pid)) return { state: 'already_running', pid: existing.pid, device_id: existing.deviceId };
+  const handle = await fs.open(lockFile, 'wx', 0o600).catch(async error => {
+    if (error.code !== 'EEXIST') throw error;
+    const stale = await readJson(lockFile);
+    if (stale && alive(stale.pid)) throw new Error('The agent is already running.');
+    await fs.rm(lockFile, { force: true });
+    return fs.open(lockFile, 'wx', 0o600);
+  });
+  const session = await readJson(path.join(stateDir, 'session.json'));
+  if (!session) { await handle.close(); await fs.rm(lockFile, { force: true }); throw new Error('Sign in before starting the agent.'); }
+  const identity = { pid: process.pid, instanceId: randomUUID(), deviceId: session.deviceId, startedAt: Date.now(), release: packageRoot };
+  await handle.writeFile(JSON.stringify(identity)); await handle.close();
+  let stopped = false;
+  const controller = new AbortController();
+  const inflight = new Map();
+  let backend, extensions, retainer, retentionLoop;
+  const status = async (state, detail = {}) => writeJson(path.join(stateDir, 'status.json'), { state, ...identity, updatedAt: Date.now(), ...detail });
+  const stop = () => { stopped = true; controller.abort(); };
+  process.once('SIGTERM', stop); process.once('SIGINT', stop);
+  const stopFile = path.join(stateDir, 'agent-stop.json');
+  let checkingStop = false;
+  const stopTimer = setInterval(() => {
+    if (checkingStop || stopped) return;
+    checkingStop = true;
+    readJson(stopFile).then(request => {
+      if (request?.instanceId === identity.instanceId && request.pid === identity.pid) stop();
+    }).catch(() => {}).finally(() => { checkingStop = false; });
+  }, 100);
+  stopTimer.unref();
+  try {
+    await status('materialising');
+    backend = await createBackend({ stateDir, packageRoot, deviceId: session.deviceId });
+    extensions = await createExtensions({ stateDir, packageRoot, deviceId: session.deviceId, backend });
+    const tools = [...backend.tools, ...extensions.tools];
+    const info = await backend.call('system_info', {});
+    const probe = path.join(stateDir, `.probe-${identity.instanceId}`);
+    await fs.writeFile(probe, identity.instanceId);
+    if (await fs.readFile(probe, 'utf8') !== identity.instanceId) throw new Error('State filesystem readback failed.');
+    await fs.rm(probe);
+    const executionProbe = await backend.call('exec', { executable: process.execPath, args: ['-e', 'process.stdout.write("ready")'], cwd: stateDir, wait_ms: 10000, timeout_ms: 10000 });
+    if (executionProbe.state !== 'completed_success' || executionProbe.exit_code !== 0) throw new Error('The local execution backend did not complete its startup check.');
+    const probeOutput = await backend.call('task_events', { task_id: executionProbe.task_id });
+    if (Buffer.from(probeOutput.data, 'base64').toString() !== 'ready') throw new Error('The local execution backend output did not pass readback.');
+    await fs.rm(path.join(stateDir, 'tasks', executionProbe.task_id), { recursive: true, force: true });
+    const manifest = await readJson(path.join(packageRoot, 'package.json'));
+    retainer = await createRetainer({ stateDir, deviceId: session.deviceId, backend, extensions, signal: controller.signal });
+    const register = async () => api(stateDir, '/agent/register', { deviceId: session.deviceId, name: session.deviceName || os.hostname(), version: manifest.version, platform: { os: process.platform, arch: process.arch }, capabilities: { ...info, ...extensions.capabilities, backendReady: true }, tools }, { signal: controller.signal });
+    const execute = async work => {
+      const file = path.join(stateDir, 'operations', work.id + '.json');
+      let operation = await readJson(file);
+      if (operation?.state === 'completed') {
+        await retainer.notify(work.name, operation.result, work.args);
+        await api(stateDir, '/agent/result', { deviceId: session.deviceId, id: work.id, result: operation.result, error: operation.error }, { signal: controller.signal });
+        return;
+      }
+      if (operation?.state === 'started' && !['exec', 'terminal_open', 'system_info', 'task_get', 'task_events', 'task_list', 'search_get', 'artifact_get', 'artifact_read', 'schedule_list', 'schedule_history'].includes(work.name)) {
+        operation = { ...operation, state: 'completed', result: { state: 'unknown_outcome', message: 'The agent stopped before the operation result was saved. Inspect the target before repeating it.' } };
+      } else {
+        await writeJson(file, { id: work.id, name: work.name, state: 'started', startedAt: Date.now() });
+        try {
+          const args = ['exec', 'terminal_open'].includes(work.name) ? { ...work.args, request_id: work.id } : work.args;
+          const target = backend.tools.some(t => t.name === work.name) ? backend : extensions;
+          const result = await target.call(work.name, args);
+          operation = { id: work.id, state: 'completed', result, finishedAt: Date.now() };
+        } catch (error) { operation = { id: work.id, state: 'completed', error: { code: error.code || 'operation_failed', message: error.message }, finishedAt: Date.now() }; }
+      }
+      await writeJson(file, operation);
+      await retainer.notify(work.name, operation.result, work.args);
+      await api(stateDir, '/agent/result', { deviceId: session.deviceId, id: work.id, result: operation.result, error: operation.error }, { signal: controller.signal });
+    };
+    let failures = 0, registered = false;
+    while (!stopped) {
+      try {
+        if (!registered) {
+          await status('connecting'); const attached = await register(); registered = true;
+          if (attached.cloud_retention && !retentionLoop) retentionLoop = retainer.run().catch(error => writeJson(path.join(stateDir, 'retention', 'status.json'), { state: 'failed', error: error.message, at: Date.now() }));
+        }
+        await status('ready', { version: manifest.version, tools: tools.length });
+        const batch = await api(stateDir, '/agent/poll', { deviceId: session.deviceId }, { signal: controller.signal });
+        for (const work of batch.operations || []) if (!inflight.has(work.id)) {
+          const task = execute(work).catch(async error => { if (!stopped) await status('reconnecting', { error: error.message }); }).finally(() => inflight.delete(work.id));
+          inflight.set(work.id, task);
+        }
+        failures = 0;
+        if (inflight.size) await Promise.race([...inflight.values(), sleep(1000)]);
+      } catch (error) {
+        if (stopped) break;
+        const recoverable = !['invalid_grant', 'invalid_client', 'device_revoked', 'device_not_found', 'login_required'].includes(error.code) && error.status !== 403;
+        await status(recoverable ? 'reconnecting' : 'failed', { recoverable, error: error.message });
+        if (!recoverable) break;
+        registered = false;
+        await sleep(Math.min(30000, 500 * 2 ** Math.min(failures++, 6)) + Math.floor(Math.random() * 300));
+      }
+    }
+    await Promise.allSettled([...inflight.values()]);
+  } finally {
+    clearInterval(stopTimer);
+    controller.abort();
+    await retentionLoop;
+    const lastSession = await readJson(path.join(stateDir, 'session.json'));
+    await fetch(`${lastSession.issuer}/agent/state`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${lastSession.token.access_token}` }, body: JSON.stringify({ deviceId: session.deviceId, state: 'stopped' }), signal: AbortSignal.timeout(3000) }).catch(() => {});
+    await extensions?.close?.(); await backend?.close?.();
+    const prior = await readJson(path.join(stateDir, 'status.json'));
+    if (prior?.state !== 'failed') await status('stopped');
+    const requested = await readJson(stopFile).catch(() => null);
+    if (requested?.instanceId === identity.instanceId && requested.pid === identity.pid) await fs.rm(stopFile, { force: true });
+    const current = await readJson(lockFile);
+    if (current?.instanceId === identity.instanceId) await fs.rm(lockFile, { force: true });
+    process.removeListener('SIGTERM', stop); process.removeListener('SIGINT', stop);
+  }
+  return await readJson(path.join(stateDir, 'status.json'));
+}