rootrework 1.0.2 → 1.0.4

package/src/retention.mjs

@@ -0,0 +1,193 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { accessSession, readJson, writeJson } from './client.mjs';
+
+const validId = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+const finished = new Set(['completed_success', 'completed_failure', 'cancelled', 'timed_out']);
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+export async function createRetainer({ stateDir, deviceId, backend, extensions, signal, transport }) {
+  const journal = path.join(stateDir, 'retention');
+  await fs.mkdir(journal, { recursive: true, mode: 0o700 });
+  const send = transport || (async (route, { method = 'GET', body, headers = {} } = {}) => {
+    let session = await accessSession(stateDir);
+    const invoke = () => fetch(new URL(route, session.issuer), { method, redirect: 'error',
+      headers: { ...headers, authorization: `Bearer ${session.token.access_token}`, ...(body === undefined ? {} : { 'content-type': body instanceof Uint8Array ? 'application/octet-stream' : 'application/json' }) },
+      ...(body === undefined ? {} : { body: body instanceof Uint8Array ? body : JSON.stringify(body) }),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60000)]) : AbortSignal.timeout(60000) });
+    let response = await invoke();
+    if (response.status === 401) { await response.body?.cancel(); session = await accessSession(stateDir, { refresh: true }); response = await invoke(); }
+    return response;
+  });
+  const call = async (route, options) => {
+    const response = await send(route, options);
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) throw Object.assign(new Error(data.error_description || data.error || `HTTP ${response.status}`), { code: data.error, status: response.status });
+    return data;
+  };
+  const jobFile = (kind, id) => path.join(journal, `${kind}-${id}.json`);
+  const locks = new Map();
+  const locked = async (file, operation) => {
+    const task = (locks.get(file) || Promise.resolve()).catch(() => {}).then(operation);
+    locks.set(file, task);
+    try { return await task; } finally { if (locks.get(file) === task) locks.delete(file); }
+  };
+  const enqueue = async (kind, id, deleting = false) => {
+    if (!['artifact', 'task'].includes(kind) || !validId(id)) return;
+    const file = jobFile(kind, id);
+    await locked(file, async () => {
+      const existing = await readJson(file);
+      if (existing && !deleting) return;
+      await writeJson(file, { ...(existing || {}), kind, id, state: deleting ? 'deleting' : 'pending', attempts: 0, nextAttemptAt: 0 });
+    });
+  };
+  const scan = async () => {
+    for (const [folder, kind] of [['artifacts', 'artifact'], ['tasks', 'task']]) {
+      const dir = path.join(stateDir, folder);
+      const entries = await fs.readdir(dir, { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+      for (const entry of entries) if (entry.isDirectory() && validId(entry.name)) await enqueue(kind, entry.name);
+    }
+  };
+  const save = job => {
+    const file = jobFile(job.kind, job.id);
+    return locked(file, async () => {
+      const current = await readJson(file);
+      if (current?.state === 'deleting' && !['deleting', 'deleted'].includes(job.state)) return;
+      await writeJson(file, job);
+    });
+  };
+  const endpoint = (kind, id) => `/agent/retention/${deviceId}/${kind}/${id}`;
+
+  async function retainFile(job, kind, file, metadata, name, size) {
+    const route = endpoint(kind, job.id);
+    const handle = size ? await fs.open(file, 'r') : await fs.open(file, 'r').catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    try {
+      const before = handle ? await handle.stat() : { size: 0, mtimeMs: 0, ino: 0 };
+      if (before.size !== size || (handle && !before.isFile())) throw failure('SOURCE_CHANGED', 'Retained source size changed.');
+      const signature = { size: before.size, modified: before.mtimeMs, inode: before.ino };
+      job.sources ||= {};
+      if (job.sources[kind] && JSON.stringify(job.sources[kind]) !== JSON.stringify(signature)) throw failure('SOURCE_CHANGED', 'Retained source changed during an interrupted transfer.');
+      job.sources[kind] = signature;
+      await save(job);
+      let remote = await call(route, { method: 'POST', body: { size, name, metadata } });
+      if (!Number.isSafeInteger(remote.next_offset) || remote.next_offset < 0 || remote.next_offset > size || !Number.isSafeInteger(remote.chunk_bytes) || remote.chunk_bytes < 1 || remote.chunk_bytes > 16 * 1024 * 1024) throw failure('INVALID_RETENTION_STATE', 'Cloud storage returned an invalid transfer state.');
+      for (let offset = remote.next_offset; offset < size;) {
+        if (signal?.aborted) throw signal.reason;
+        const length = Math.min(remote.chunk_bytes, size - offset);
+        const bytes = Buffer.alloc(length);
+        let obtained = 0;
+        while (obtained < length) {
+          const { bytesRead } = await handle.read(bytes, obtained, length - obtained, offset + obtained);
+          if (!bytesRead) throw failure('SOURCE_CHANGED', 'The retained source ended before its complete size.');
+          obtained += bytesRead;
+        }
+        remote = await call(route + '?offset=' + offset, { method: 'PUT', body: bytes });
+        if (remote.next_offset !== offset + length) throw failure('NONCONTIGUOUS_RETENTION', 'Cloud storage did not accept the complete contiguous chunk.');
+        offset = remote.next_offset;
+      }
+      while (remote.state !== 'retained') {
+        if (signal?.aborted) throw signal.reason;
+        const previous = remote.verified_bytes || 0;
+        remote = await call(route + '/finish', { method: 'POST', body: {} });
+        if (remote.state !== 'retained' && (!(remote.verified_bytes > previous) || remote.verified_bytes > size)) throw failure('INVALID_RETENTION_STATE', 'Cloud verification did not advance.');
+      }
+      job.readback ||= {};
+      let offset = job.readback[kind] || 0, emptyPending = size === 0;
+      if (!Number.isSafeInteger(offset) || offset < 0 || offset > size) throw failure('INVALID_RETENTION_STATE', 'Saved cloud readback offset is invalid.');
+      while (offset < size || emptyPending) {
+        const end = Math.min(size, offset + remote.chunk_bytes);
+        const response = await send(route + '/data', size ? { headers: { range: `bytes=${offset}-${end - 1}` } } : {});
+        if (response.status !== (size ? 206 : 200) || (size && response.headers.get('content-range') !== `bytes ${offset}-${end - 1}/${size}`)) {
+          await response.body?.cancel(); throw failure('RETENTION_READBACK_FAILED', `Cloud range readback returned HTTP ${response.status}.`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader) throw failure('RETENTION_READBACK_FAILED', 'Cloud readback did not contain a readable body.');
+        try {
+          for (;;) {
+            const part = await reader.read();
+            if (part.done) break;
+            if (offset + part.value.byteLength > end) throw failure('RETENTION_READBACK_FAILED', 'Cloud readback exceeded the requested byte range.');
+            const expected = Buffer.alloc(part.value.byteLength);
+            let obtained = 0;
+            while (obtained < expected.length) {
+              const { bytesRead } = await handle.read(expected, obtained, expected.length - obtained, offset + obtained);
+              if (!bytesRead) throw failure('SOURCE_CHANGED', 'The source changed during cloud readback.');
+              obtained += bytesRead;
+            }
+            if (!expected.equals(Buffer.from(part.value))) throw failure('RETENTION_CONTENT_MISMATCH', 'Cloud readback differs from the complete retained source.');
+            offset += part.value.byteLength;
+          }
+        } catch (error) { await reader.cancel().catch(() => {}); throw error; }
+        finally { reader.releaseLock(); }
+        if (offset !== end) throw failure('RETENTION_READBACK_FAILED', 'Cloud readback ended before the complete requested range.');
+        job.readback[kind] = offset;
+        await save(job);
+        emptyPending = false;
+      }
+      if (offset !== size) throw failure('RETENTION_READBACK_FAILED', 'Cloud readback ended before the complete retained size.');
+      const after = handle ? await handle.stat() : before;
+      if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ino !== before.ino) throw failure('SOURCE_CHANGED', 'The source changed during cloud retention.');
+      return remote;
+    } finally { await handle?.close(); }
+  }
+
+  async function execute(job) {
+    if (job.kind === 'artifact') {
+      const metadata = await extensions.call('artifact_get', { artifact_id: job.id });
+      if (job.state === 'deleting' || metadata.state === 'deleted') {
+        await call(endpoint('artifact', job.id), { method: 'DELETE' });
+        return { ...job, state: 'deleted', completedAt: Date.now() };
+      }
+      if (!['retained', 'published'].includes(metadata.state) || metadata.retained_bytes !== metadata.size) return { ...job, state: 'pending', nextAttemptAt: Date.now() + 30000 };
+      await retainFile(job, 'artifact', path.join(stateDir, 'artifacts', job.id, 'data.bin'), metadata, metadata.name || 'download', metadata.size);
+    } else {
+      const task = await backend.call('task_get', { task_id: job.id });
+      await call('/agent/task-state', { method: 'POST', body: { deviceId, task } });
+      if (!finished.has(task.state)) return { ...job, state: task.state === 'unknown_outcome' ? 'unknown_outcome' : 'pending', nextAttemptAt: Date.now() + 30000 };
+      for (const stream of ['stdout', 'stderr', 'terminal']) {
+        const size = task.output_bytes?.[stream] || 0;
+        task.output_bytes[stream] = size;
+        await retainFile(job, stream, path.join(stateDir, 'tasks', job.id, stream + '.bin'), task, `${job.id}-${stream}.bin`, size);
+      }
+      await call('/agent/task-state', { method: 'POST', body: { deviceId, task } });
+    }
+    return { ...job, state: 'retained', completedAt: Date.now(), nextAttemptAt: 0 };
+  }
+  let flushing;
+  const flush = () => flushing ||= (async () => {
+    await scan();
+    for (const name of await fs.readdir(journal)) {
+      if (signal?.aborted) break;
+      if (!/^(artifact|task)-[A-Za-z0-9_-]+\.json$/.test(name)) continue;
+      const job = await readJson(path.join(journal, name));
+      if (!job || ['retained', 'deleted', 'failed', 'unknown_outcome'].includes(job.state) || job.nextAttemptAt > Date.now()) continue;
+      try { await save(await execute(job)); }
+      catch (error) {
+        if (signal?.aborted) break;
+        const recoverable = !['SOURCE_CHANGED', 'RETENTION_CONTENT_MISMATCH', 'chunk_conflict', 'retention_conflict', 'device_binding_mismatch', 'invalid_grant', 'invalid_client', 'login_required'].includes(error.code) && ![400, 403, 410].includes(error.status);
+        const attempts = (job.attempts || 0) + 1;
+        await save({ ...job, state: recoverable ? 'pending' : 'failed', attempts, nextAttemptAt: Date.now() + Math.min(300000, 1000 * 2 ** Math.min(attempts, 8)), error: { code: error.code || 'retention_failed', message: error.message }, recoverable });
+      }
+    }
+  })().finally(() => { flushing = null; });
+  return {
+    flush,
+    async notify(name, result, args = {}) {
+      if (name === 'artifact_delete') await enqueue('artifact', args.artifact_id || result?.artifact_id, true);
+      else if (result?.artifact_id && ['retained', 'published'].includes(result.state)) await enqueue('artifact', result.artifact_id);
+      const id = result?.task_id || result?.task?.task_id;
+      if (id) await enqueue('task', id);
+    },
+    async run() {
+      while (!signal?.aborted) {
+        await flush();
+        if (signal?.aborted) break;
+        await new Promise(resolve => {
+          const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
+          const timer = setTimeout(done, 30000);
+          signal?.addEventListener('abort', done, { once: true });
+        });
+      }
+    },
+  };
+}

package/src/search-worker.mjs

@@ -0,0 +1,70 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { once } from 'node:events';
+
+const options = JSON.parse(process.argv[2]);
+const visited = new Set();
+const expression = options.regex ? new RegExp(options.query, options.case_sensitive ? 'u' : 'iu') : null;
+const needle = options.case_sensitive ? options.query : options.query.toLowerCase();
+const counts = { files: 0, directories: 0, matches: 0, errors: 0, excluded: 0 };
+function matches(value) { return expression ? expression.test(value) : (options.case_sensitive ? value : value.toLowerCase()).includes(needle); }
+async function emit(record) { if (!process.stdout.write(JSON.stringify(record) + '\n')) await once(process.stdout, 'drain'); }
+async function issue(type, file, reason) { counts[type === 'error' ? 'errors' : 'excluded']++; await emit({ type, path: file, reason }); }
+async function searchFile(file) {
+  counts.files++;
+  const handle = await fs.open(file, 'r');
+  try {
+    const prefix = Buffer.alloc(8192); const first = await handle.read(prefix, 0, prefix.length, 0); const sample = prefix.subarray(0, first.bytesRead);
+    const encoding = sample[0] === 0xff && sample[1] === 0xfe ? 'utf-16le' : sample[0] === 0xfe && sample[1] === 0xff ? 'utf-16be' : 'utf-8';
+    if (encoding === 'utf-8' && sample.includes(0)) { await issue('excluded', file, 'binary'); return; }
+    const decoder = new TextDecoder(encoding, { fatal: true });
+    let pending = '', line = 1, offset = 0;
+    async function consume(value, final = false) {
+      pending += value;
+      let start = 0, end;
+      while ((end = pending.indexOf('\n', start)) >= 0) { await inspect(pending.slice(start, end).replace(/\r$/, ''), line++); start = end + 1; }
+      pending = pending.slice(start);
+      if (final && pending.length) await inspect(pending, line);
+    }
+    async function inspect(value, number) {
+      if (!matches(value)) return;
+      counts.matches++;
+      const snippet = Buffer.from(value).subarray(0, 8192);
+      let preview;
+      for (let trim = 0; trim < 4; trim++) { try { preview = new TextDecoder('utf-8', { fatal: true }).decode(snippet.subarray(0, snippet.length - trim)); break; } catch {} }
+      await emit({ type: 'match', path: file, line: number, text: preview ?? '', text_truncated: Buffer.byteLength(value) > snippet.length, encoding });
+    }
+    while (true) {
+      const b = Buffer.alloc(65536); const read = await handle.read(b, 0, b.length, offset);
+      if (!read.bytesRead) break;
+      offset += read.bytesRead;
+      await consume(decoder.decode(b.subarray(0, read.bytesRead), { stream: true }));
+    }
+    await consume(decoder.decode(), true);
+  } finally { await handle.close(); }
+}
+async function walk(file) {
+  let stat;
+  try {
+    stat = await fs.lstat(file);
+    if (options.mode === 'filename' && matches(path.basename(file))) { counts.matches++; await emit({ type: 'match', path: file, name: path.basename(file), kind: stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : 'file' }); }
+    if (stat.isSymbolicLink()) {
+      if (!options.follow_symlinks) { await issue('excluded', file, 'symlink_not_followed'); return; }
+      stat = await fs.stat(file);
+    }
+    if (stat.isDirectory()) {
+      const identity = await fs.realpath(file);
+      if (visited.has(identity)) { await issue('excluded', file, 'cycle_or_duplicate_directory'); return; }
+      visited.add(identity); counts.directories++;
+      for await (const item of await fs.opendir(file)) {
+        if (!options.include_hidden && item.name.startsWith('.')) { await issue('excluded', path.join(file, item.name), 'hidden'); continue; }
+        const child = path.join(file, item.name);
+        await walk(child);
+      }
+    } else if (stat.isFile()) {
+      if (options.mode === 'content') await searchFile(file); else counts.files++;
+    } else await issue('excluded', file, 'non_regular_file');
+  } catch (e) { await issue('error', file, e.code || (e instanceof TypeError ? 'invalid_text_encoding' : 'read_failed')); }
+}
+try { await walk(options.path); await emit({ type: 'summary', ...counts, complete: true }); }
+catch (e) { await emit({ type: 'error', reason: e.code || 'search_failed' }); process.exitCode = 1; }

package/src/service.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { readJson, writeJson } from './client.mjs';
+
+export function run(executable, args, options = {}) {
+  const { timeout_ms = 30000, ...nativeOptions } = options;
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { windowsHide: true, timeout: timeout_ms, ...nativeOptions });
+    let stdout = '', stderr = '';
+    child.stdout?.on('data', chunk => { stdout += chunk; });
+    child.stderr?.on('data', chunk => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code, signal) => resolve({ code, signal, stdout, stderr }));
+  });
+}
+const systemdQuote = value => '"' + value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', '$$$$').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
+const xml = value => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const psQuote = value => "'" + value.replaceAll("'", "''") + "'";
+const windowsQuote = value => '"' + value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1') + '"';
+
+export async function powershell() {
+  for (const name of ['pwsh.exe', 'powershell.exe']) for (const directory of (process.env.PATH || '').split(path.delimiter)) {
+    const file = path.join(directory, name);
+    if (await fs.stat(file).then(info => info.isFile(), () => false)) return file;
+  }
+  throw new Error('No installed PowerShell executable is available.');
+}
+export function windowsArguments(commandLine) {
+  const args = []; let index = 0;
+  while (index < commandLine.length) {
+    while (/[ \t]/.test(commandLine[index] || '') && index < commandLine.length) index++;
+    if (index === commandLine.length) break;
+    let value = '', quoted = false;
+    while (index < commandLine.length && (quoted || !/[ \t]/.test(commandLine[index]))) {
+      let slashes = 0;
+      while (commandLine[index] === '\\') { slashes++; index++; }
+      if (commandLine[index] === '"') {
+        value += '\\'.repeat(Math.floor(slashes / 2)); index++;
+        if (slashes % 2) value += '"';
+        else if (quoted && commandLine[index] === '"') { value += '"'; index++; }
+        else quoted = !quoted;
+      } else {
+        value += '\\'.repeat(slashes);
+        if (index < commandLine.length && (quoted || !/[ \t]/.test(commandLine[index]))) value += commandLine[index++];
+      }
+    }
+    args.push(value);
+  }
+  return args;
+}
+export async function windowsProcessArguments(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  const command = `$ErrorActionPreference='Stop';$line=[string](Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine;[Console]::Write([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($line)))`;
+  const result = await run(await powershell(), ['-NoProfile', '-NonInteractive', '-Command', command]);
+  const encoded = result.stdout.trim();
+  if (result.code !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) return null;
+  return windowsArguments(Buffer.from(encoded, 'base64').toString('utf8'));
+}
+const ps = async command => run(await powershell(), ['-NoProfile', '-NonInteractive', '-Command', "$ErrorActionPreference='Stop';" + command]);
+const scheduledGuard = stateDir => `if($existing){if($existing.Description -ne ${psQuote('rootRework agent: ' + stateDir)} -and !($existing.Description -eq 'rootRework agent' -and $existing.Actions.Arguments.Contains(${psQuote('--state-dir ' + windowsQuote(stateDir))}))){throw 'The task belongs to another installation'}};`;
+const check = result => { if (result.code !== 0) throw new Error(result.stderr.trim() || 'The native service operation failed.'); return result; };
+
+async function assertOwned(stateDir, record) {
+  if (record.stateDir && path.resolve(record.stateDir) !== path.resolve(stateDir)) throw new Error('The service belongs to another installation.');
+  if (record.manager === 'systemd') {
+    const text = await fs.readFile(record.file, 'utf8').catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (text && (!text.includes('Description=rootRework agent\n') || !text.includes(`--state-dir ${systemdQuote(stateDir)}`))) throw new Error('The service ownership has changed.');
+    return text !== null;
+  }
+  if (record.manager === 'launchd') {
+    const text = await fs.readFile(record.file, 'utf8').catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (text && (!text.includes('<string>com.rootrework.agent</string>') || !text.includes(`<string>${xml(stateDir)}</string>`))) throw new Error('The launch agent ownership has changed.');
+    return text !== null;
+  }
+  if (record.manager === 'scheduled-task') {
+    const result = check(await ps(`$existing=Get-ScheduledTask -TaskName ${psQuote(record.name)} -ErrorAction SilentlyContinue;${scheduledGuard(stateDir)}if($existing){'present'}`));
+    return result.stdout.trim() === 'present';
+  }
+  throw new Error('Unknown service manager.');
+}
+
+export async function installService(stateDir, release) {
+  const script = path.join(release, 'bin', 'cli.mjs');
+  let record;
+  if (process.platform === 'linux') {
+    const system = process.getuid?.() === 0, prefix = system ? [] : ['--user'];
+    const available = await run('systemctl', [...prefix, 'show-environment']).catch(() => null);
+    if (!available || available.code !== 0) return { installed: false, reason: 'No usable systemd user or system manager.', mode: 'detached' };
+    const directory = system ? '/etc/systemd/system' : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
+    record = { installed: true, manager: 'systemd', system, file: path.join(directory, 'rootrework.service'), name: 'rootrework.service', stateDir, release, executable: process.execPath };
+    await assertOwned(stateDir, record);
+    await fs.mkdir(directory, { recursive: true });
+    const unit = `[Unit]\nDescription=rootRework agent\nAfter=network-online.target\nWants=network-online.target\n[Service]\nType=simple\nExecStart=${systemdQuote(process.execPath)} ${systemdQuote(script)} run --state-dir ${systemdQuote(stateDir)}\nRestart=on-failure\nRestartSec=5\nKillMode=process\n[Install]\nWantedBy=${system ? 'multi-user.target' : 'default.target'}\n`;
+    const prior = await fs.readFile(record.file, 'utf8').catch(() => null);
+    await fs.writeFile(record.file, unit, { mode: 0o644 });
+    await writeJson(path.join(stateDir, 'service.json'), record);
+    check(await run('systemctl', [...prefix, 'daemon-reload']));
+    check(await run('systemctl', [...prefix, 'enable', record.name]));
+    check(await run('systemctl', [...prefix, prior && prior !== unit ? 'restart' : 'start', record.name]));
+  } else if (process.platform === 'darwin') {
+    const name = 'com.rootrework.agent', domain = `gui/${process.getuid()}`;
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', name + '.plist');
+    record = { installed: true, manager: 'launchd', file, domain, name, stateDir, release, executable: process.execPath };
+    await assertOwned(stateDir, record);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const argv = [process.execPath, script, 'run', '--state-dir', stateDir].map(x => `<string>${xml(x)}</string>`).join('');
+    const content = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>${name}</string><key>ProgramArguments</key><array>${argv}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict></dict></plist>`;
+    const prior = await fs.readFile(file, 'utf8').catch(() => null);
+    const active = await run('launchctl', ['print', `${domain}/${name}`]);
+    if (active.code === 0 && prior !== content) check(await run('launchctl', ['bootout', `${domain}/${name}`]));
+    await fs.writeFile(file, content, { mode: 0o600 });
+    await writeJson(path.join(stateDir, 'service.json'), record);
+    if (active.code !== 0 || prior !== content) check(await run('launchctl', ['bootstrap', domain, file]));
+    else check(await run('launchctl', ['kickstart', `${domain}/${name}`]));
+  } else if (process.platform === 'win32') {
+    const name = 'rootRework';
+    const argument = [script, 'run', '--state-dir', stateDir].map(windowsQuote).join(' ');
+    const existing = `$existing=Get-ScheduledTask -TaskName ${psQuote(name)} -ErrorAction SilentlyContinue;${scheduledGuard(stateDir)}`;
+    const command = `${existing}if($existing){Stop-ScheduledTask -TaskName ${psQuote(name)}};$action=New-ScheduledTaskAction -Execute ${psQuote(process.execPath)} -Argument ${psQuote(argument)};$trigger=New-ScheduledTaskTrigger -AtLogOn -User ([System.Security.Principal.WindowsIdentity]::GetCurrent().Name);$settings=New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) -MultipleInstances IgnoreNew;Register-ScheduledTask -TaskName ${psQuote(name)} -Action $action -Trigger $trigger -Settings $settings -Description ${psQuote('rootRework agent: ' + stateDir)} -Force|Out-Null;Start-ScheduledTask -TaskName ${psQuote(name)}`;
+    check(await ps(command));
+    record = { installed: true, manager: 'scheduled-task', name, stateDir, release, executable: process.execPath };
+    await writeJson(path.join(stateDir, 'service.json'), record);
+  } else return { installed: false, mode: 'detached', reason: 'No supported native service manager.' };
+  return record;
+}
+
+export async function serviceAction(stateDir, action) {
+  if (!['stop', 'restart', 'uninstall'].includes(action)) throw new Error('Unknown service operation.');
+  const record = await readJson(path.join(stateDir, 'service.json'));
+  if (!record?.installed) {
+    if (action === 'uninstall' && record?.mode === 'detached' && path.resolve(record.stateDir || '') === path.resolve(stateDir)) await fs.rm(path.join(stateDir, 'service.json'), { force: true });
+    return false;
+  }
+  if (!await assertOwned(stateDir, record)) {
+    if (action === 'uninstall') await fs.rm(path.join(stateDir, 'service.json'), { force: true });
+    return false;
+  }
+  if (record.manager === 'systemd') {
+    const prefix = record.system ? [] : ['--user'];
+    if (action === 'uninstall') {
+      check(await run('systemctl', [...prefix, 'disable', '--now', record.name]));
+      await fs.rm(record.file);
+      check(await run('systemctl', [...prefix, 'daemon-reload']));
+    } else check(await run('systemctl', [...prefix, action, record.name]));
+  } else if (record.manager === 'launchd') {
+    const active = await run('launchctl', ['print', `${record.domain}/${record.name}`]);
+    if (active.code === 0) check(await run('launchctl', ['bootout', `${record.domain}/${record.name}`]));
+    if (action === 'restart') check(await run('launchctl', ['bootstrap', record.domain, record.file]));
+    if (action === 'uninstall') await fs.rm(record.file, { force: true });
+  } else {
+    const command = `$existing=Get-ScheduledTask -TaskName ${psQuote(record.name)} -ErrorAction SilentlyContinue;${scheduledGuard(stateDir)}if($existing){Stop-ScheduledTask -TaskName ${psQuote(record.name)};${action === 'uninstall' ? `Unregister-ScheduledTask -TaskName ${psQuote(record.name)} -Confirm:$false` : action === 'restart' ? `Start-ScheduledTask -TaskName ${psQuote(record.name)}` : ''}}`;
+    check(await ps(command));
+  }
+  if (action === 'uninstall') await fs.rm(path.join(stateDir, 'service.json'), { force: true });
+  return true;
+}

package/src/stdio.mjs

@@ -0,0 +1,46 @@
+import readline from 'node:readline';
+import path from 'node:path';
+import { once } from 'node:events';
+import { createBackend } from './backend.mjs';
+import { createExtensions } from './extended.mjs';
+import { packageRoot, readJson } from './client.mjs';
+
+const versions = ['2025-03-26', '2025-06-18', '2025-11-25', '2026-07-28'];
+export async function runStdio(stateDir, input = process.stdin, output = process.stdout) {
+  const manifest = await readJson(path.join(packageRoot, 'package.json'));
+  const backend = createBackend({ stateDir, packageRoot, deviceId: 'local' });
+  const extensions = await createExtensions({ stateDir, packageRoot, deviceId: 'local', backend });
+  const tools = [...backend.tools, ...extensions.tools];
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const active = new Set();
+  let writes = Promise.resolve();
+  const write = value => { writes = writes.then(async () => { if (!output.write(JSON.stringify(value) + '\n')) await once(output, 'drain'); }); return writes; };
+  async function handle(line) {
+    let message;
+    try { message = JSON.parse(line); }
+    catch { return write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); }
+    const fail = (code, text) => write({ jsonrpc: '2.0', id: message?.id ?? null, error: { code, message: text } });
+    if (!message || Array.isArray(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string' || Object.hasOwn(message, 'id') && !(typeof message.id === 'string' || Number.isSafeInteger(message.id))) return fail(-32600, 'Invalid request');
+    if (!Object.hasOwn(message, 'id')) return;
+    const version = message.params?._meta?.['io.modelcontextprotocol/protocolVersion'] || message.params?.protocolVersion;
+    if (version && !versions.includes(version)) return fail(-32022, 'Unsupported protocol version');
+    let result;
+    if (message.method === 'initialize') result = { protocolVersion: version && version !== '2026-07-28' ? version : '2025-11-25', capabilities: { tools: {} }, serverInfo: { name: 'rootRework', version: manifest.version } };
+    else if (message.method === 'server/discover') result = { supportedVersions: versions, capabilities: { tools: {} } };
+    else if (message.method === 'ping') result = {};
+    else if (message.method === 'tools/list') result = { tools };
+    else if (message.method === 'tools/call') {
+      const name = message.params?.name;
+      const target = backend.tools.some(tool => tool.name === name) ? backend : extensions;
+      if (!tools.some(tool => tool.name === name)) return fail(-32602, 'Unknown tool');
+      try { const value = await target.call(name, message.params.arguments || {}); result = { content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value }; }
+      catch (error) { result = { content: [{ type: 'text', text: error.message }], isError: true }; }
+    } else return fail(-32601, 'Method not found');
+    if (version === '2026-07-28') result = { ...result, resultType: 'complete', _meta: { 'io.modelcontextprotocol/serverInfo': { name: 'rootRework', version: manifest.version } } };
+    return write({ jsonrpc: '2.0', id: message.id, result });
+  }
+  try {
+    for await (const line of lines) { const request = handle(line).finally(() => active.delete(request)); active.add(request); }
+    await Promise.all(active); await writes;
+  } finally { lines.close(); await extensions.close(); await backend.close(); }
+}

package/src/supervisor.mjs

@@ -0,0 +1,119 @@
+import fs from 'node:fs/promises';
+import sync from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { atomic, json, envWith, killTree, processIdentity, delay, finished } from './process.mjs';
+
+const dir = process.argv[2];
+let state, child, pty, stopping, done = false, busy = false, beat, poll, timeout, force;
+const fds = {};
+process.on('uncaughtExceptionMonitor', error => {
+  try { sync.writeFileSync(path.join(dir, 'supervisor-error.json'), JSON.stringify({ code: error.code || 'SUPERVISOR_FAILED', syscall: error.syscall || null, observed_state: state?.state || 'initializing', at: new Date().toISOString() }), { mode: 0o600 }); } catch {}
+});
+async function persist() { state.updated_at = new Date().toISOString(); await atomic(path.join(dir, 'state.json'), state); }
+let chain = Promise.resolve();
+function save() { chain = chain.then(persist, persist); return chain; }
+function write(stream, data) {
+  if (done) return;
+  try {
+    const b = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    let offset = 0;
+    while (offset < b.length) offset += sync.writeSync(fds[stream], b, offset, b.length - offset);
+    state.output_bytes[stream] += b.length;
+  } catch (error) { state.storage_error = error.code || 'OUTPUT_WRITE_FAILED'; void stop('completed_failure'); }
+}
+async function finish(code, signal, error) {
+  if (done) return;
+  done = true;
+  clearInterval(beat); clearInterval(poll); clearTimeout(timeout);
+  if (force) { await force; }
+  for (const fd of Object.values(fds)) { try { sync.fsyncSync(fd); sync.closeSync(fd); } catch {} }
+  state.state = stopping || (error || code !== 0 ? 'completed_failure' : 'completed_success');
+  state.exit_code = Number.isInteger(code) ? code : null;
+  state.signal = signal || null;
+  if (error) state.error = { code: error.code || 'SPAWN_FAILED', message: error.code === 'ENOENT' ? 'Executable was not found.' : 'Process could not run.' };
+  state.finished_at = new Date().toISOString();
+  await save();
+}
+async function stop(reason) {
+  if (done || stopping) return;
+  stopping = reason;
+  state.termination_requested_at = new Date().toISOString();
+  state.termination_reason = reason;
+  await save();
+  if (!child) return finish(null, null);
+  const pid = child.pid;
+  try {
+    await killTree(pid, 'SIGTERM');
+    if (pty && process.platform === 'win32') child.kill();
+    if (process.platform !== 'win32') force = delay(750).then(() => killTree(pid, 'SIGKILL')).catch(() => {});
+  } catch (error) { state.termination_error = error.code || 'TERMINATION_FAILED'; await save(); }
+}
+async function control() {
+  if (busy || done) return;
+  busy = true;
+  try {
+    for (const name of (await fs.readdir(path.join(dir, 'controls'))).filter(n => n.endsWith('.request.json')).sort()) {
+      const request = path.join(dir, 'controls', name);
+      const working = request.replace('.request.json', '.working.json');
+      let op;
+      try { await fs.rename(request, working); op = await json(working); } catch { continue; }
+      let result;
+      try {
+        if (op.operation === 'cancel' || op.operation === 'close') { await stop('cancelled'); result = { accepted: true }; }
+        else if (!pty) throw Object.assign(new Error('This task is not a terminal.'), { code: 'NOT_TERMINAL' });
+        else if (op.operation === 'input') { child.write(Buffer.from(op.data, 'base64')); result = { accepted: true, bytes: Buffer.byteLength(op.data, 'base64') }; }
+        else if (op.operation === 'resize') { child.resize(op.cols, op.rows); state.cols = op.cols; state.rows = op.rows; await save(); result = { cols: op.cols, rows: op.rows }; }
+        else if (op.operation === 'interrupt') { child.write('\x03'); result = { accepted: true }; }
+        else throw Object.assign(new Error('Unsupported control operation.'), { code: 'INVALID_ARGUMENT' });
+      } catch (e) { result = { error: { code: e.code || 'CONTROL_FAILED', message: 'Control operation failed.' } }; }
+      await atomic(request.replace('.request.json', '.result.json'), result);
+      await fs.rm(working, { force: true });
+    }
+  } catch (e) { state.control_error = e.code || 'CONTROL_FAILED'; }
+  finally { busy = false; }
+}
+try {
+  const spec = await json(path.join(dir, 'spec.json'));
+  state = await json(path.join(dir, 'state.json'));
+  if (state.state !== 'queued') process.exit(0);
+  state.state = 'starting'; state.supervisor_pid = process.pid; state.supervisor_identity = await processIdentity(process.pid);
+  state.started_at = new Date().toISOString(); state.output_bytes = { stdout: 0, stderr: 0, terminal: 0 };
+  for (const stream of Object.keys(state.output_bytes)) fds[stream] = sync.openSync(path.join(dir, `${stream}.bin`), 'a', 0o600);
+  await save();
+  const env = envWith(spec.env);
+  if (spec.kind === 'terminal') {
+    pty = createRequire(path.join(spec.packageRoot, 'package.json'))('@lydell/node-pty');
+    child = pty.spawn(spec.executable, spec.args, { name: env.TERM || 'xterm-256color', cols: spec.cols, rows: spec.rows, cwd: spec.cwd, env, encoding: null });
+    child.onData(data => write('terminal', data));
+    child.onExit(({ exitCode, signal }) => { void finish(exitCode, signal); });
+    if (spec.stdin) child.write(Buffer.from(spec.stdin, 'base64'));
+  } else {
+    child = spawn(spec.executable, spec.args, { cwd: spec.cwd, env, detached: process.platform !== 'win32', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    child.stdout.on('data', data => write('stdout', data));
+    child.stderr.on('data', data => write('stderr', data));
+    child.once('error', e => { void finish(null, null, e); });
+    child.once('exit', (code, signal) => { state.root_exited = { exit_code: code, signal, at: new Date().toISOString() }; });
+    child.once('close', (code, signal) => { void finish(code, signal); });
+    child.stdin.on('error', error => { state.stdin_error = error.code || 'STDIN_WRITE_FAILED'; });
+    child.stdin.end(spec.stdin ? Buffer.from(spec.stdin, 'base64') : undefined);
+  }
+  state.pid = child.pid;
+  if (!done) { state.state = 'running'; await save(); }
+  if (!done) {
+    beat = setInterval(() => { if (!done) void save().catch(() => stop('completed_failure')); }, 1000);
+    poll = setInterval(() => { void control(); }, 75);
+    if (spec.timeout_ms > 0) {
+      const deadline = performance.now() + spec.timeout_ms;
+      const checkTimeout = () => { const left = deadline - performance.now(); if (left <= 0) void stop('timed_out'); else timeout = setTimeout(checkTimeout, Math.min(left, 2147483647)); };
+      checkTimeout();
+    }
+  }
+  process.on('SIGTERM', () => { void stop('cancelled'); });
+  process.on('SIGINT', () => { void stop('cancelled'); });
+  await fs.rm(path.join(dir, 'spec.json'), { force: true });
+} catch (error) {
+  if (state) await finish(null, null, error);
+  process.exitCode = 1;
+}