@miruzero/zero-agent 0.3.6 → 0.3.7

package/src/command/filesystem/walk.js

@@ -1,39 +1,36 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const entry = (fullPath, root) => {
-  const stat = fs.statSync(fullPath);
-  return {
-    path: fullPath,
-    relativePath: path.relative(root, fullPath).replace(/\\/g, '/'),
-    type: stat.isDirectory() ? 'directory' : 'file',
-    size: stat.size
-  };
-};
-
-const walk = (root, options = {}) => {
-  const depth = options.depth ?? Infinity;
-  const filesOnly = options.filesOnly === true;
-  const out = [];
-  const visit = (dir, level) => {
-    if (level > depth) return;
-    for (const name of fs.readdirSync(dir)) {
-      const full = path.join(dir, name);
-      const item = entry(full, root);
-      if (!filesOnly || item.type === 'file') out.push(item);
-      if (item.type === 'directory') visit(full, level + 1);
-    }
-  };
-  visit(root, 1);
-  return out;
-};
-
-const wildcard = (pattern) => new RegExp('^' + String(pattern)
-  .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  .replace(/\*/g, '.*')
-  .replace(/\?/g, '.') + '$', 'i');
-
-const walkModule = { entry, walk, wildcard };
-Object.assign(exports, walkModule);
+'use strict';
+
+const zero = require('../../zero');
+
+
+exports.entry = (fullPath, root) => {
+  const stat = zero.fs.statSync(fullPath);
+  return {
+    path: fullPath,
+    relativePath: zero.path.relative(root, fullPath).replace(/\\/g, '/'),
+    type: stat.isDirectory() ? 'directory' : 'file',
+    size: stat.size
+  };
+};
+
+exports.walk = (root, options = {}) => {
+  const depth = options.depth ?? Infinity;
+  const filesOnly = options.filesOnly === true;
+  const out = [];
+  const visit = (dir, level) => {
+    if (level > depth) return;
+    for (const name of zero.fs.readdirSync(dir)) {
+      const full = zero.path.join(dir, name);
+      const item = exports.entry(full, root);
+      if (!filesOnly || item.type === 'file') out.push(item);
+      if (item.type === 'directory') visit(full, level + 1);
+    }
+  };
+  visit(root, 1);
+  return out;
+};
+
+exports.wildcard = (pattern) => new RegExp('^' + String(pattern)
+  .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  .replace(/\*/g, '.*')
+  .replace(/\?/g, '.') + '$', 'i');

package/src/command/filesystem/write-file.js

@@ -1,11 +1,9 @@
 'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const zero = require('../../zero-runtime');
-const pathPolicy = require('./path-policy');
+const zero = require('../../zero');
 
-const descriptor = zero.descriptor.validate({
+
+exports.descriptor = zero.descriptor.validate({
   name: 'zero.command.filesystem.writeFile',
   aliases: ['zero.command.writeFile'],
   description: 'Write or append text content to a file inside allowed roots.',
@@ -25,15 +23,12 @@ const descriptor = zero.descriptor.validate({
   }
 });
 
-const writeFile = (args = {}, context = {}) => {
-  const file = pathPolicy.resolveAllowed(args.path, context);
+exports.writeFile = (args = {}, context = {}) => {
+  const file = zero.pathPolicy.resolveAllowed(args.path, context);
   const mode = args.mode === 'append' ? 'append' : 'overwrite';
   const data = String(args.content ?? '');
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  if (mode === 'append') fs.appendFileSync(file, data, 'utf8');
-  else fs.writeFileSync(file, data, 'utf8');
+  zero.fs.mkdirSync(zero.path.dirname(file), { recursive: true });
+  if (mode === 'append') zero.fs.appendFileSync(file, data, 'utf8');
+  else zero.fs.writeFileSync(file, data, 'utf8');
   return { ok: true, path: file, mode, bytes: Buffer.byteLength(data) };
 };
-
-const writeFileModule = { descriptor, writeFile };
-Object.assign(exports, writeFileModule);

package/src/command/index.js

@@ -1,8 +1,7 @@
 'use strict';
 
-const zero = require('../zero-runtime');
-const filesystem = require('./filesystem');
-const pathTools = require('./path');
+const zero = require('../zero');
+
 
 const fsToolNames = [
   'readFile', 'readFiles', 'writeFile', 'appendFile', 'createFile', 'touchFile', 'replaceFile',
@@ -12,38 +11,34 @@ const fsToolNames = [
 const pathToolNames = [
   'resolvePath', 'normalizePath', 'joinPath', 'relativePath', 'getParentDirectory', 'getFilename', 'getExtension'
 ];
+const execToolNames = ['exec'];
 
 const descriptors = [
-  ...fsToolNames.map((name) => filesystem[`${name}Descriptor`]),
-  ...pathToolNames.map((name) => pathTools[`${name}Descriptor`])
+  ...fsToolNames.map((name) => zero.commandFilesystem[`${name}Descriptor`]),
+  ...pathToolNames.map((name) => zero.commandPath[`${name}Descriptor`]),
+  ...execToolNames.map((name) => zero.commandExec[`${name}Descriptor`])
 ];
 const catalog = zero.catalog.create(descriptors);
 const handlers = new Map([
-  ...fsToolNames.map((name) => [filesystem[`${name}Descriptor`].name, filesystem[name]]),
-  ...pathToolNames.map((name) => [pathTools[`${name}Descriptor`].name, pathTools[name]])
+  ...fsToolNames.map((name) => [zero.commandFilesystem[`${name}Descriptor`].name, zero.commandFilesystem[name]]),
+  ...pathToolNames.map((name) => [zero.commandPath[`${name}Descriptor`].name, zero.commandPath[name]]),
+  ...execToolNames.map((name) => [zero.commandExec[`${name}Descriptor`].name, zero.commandExec[name]])
 ]);
 
 const localAliasMap = {};
-for (const name of fsToolNames) {
-  localAliasMap[name] = `zero.command.${name}`;
-  localAliasMap[`command.${name}`] = `zero.command.${name}`;
-}
-for (const name of pathToolNames) {
+for (const name of [...fsToolNames, ...pathToolNames, ...execToolNames]) {
   localAliasMap[name] = `zero.command.${name}`;
   localAliasMap[`command.${name}`] = `zero.command.${name}`;
 }
 const localAlias = (name) => localAliasMap[name] || name;
 
-const command = {
-  filesystem: Object.fromEntries(fsToolNames.map((name) => [name, filesystem[name]])),
-  path: Object.fromEntries(pathToolNames.map((name) => [name, pathTools[name]])),
-  listTools: (filter = {}) => catalog.list(filter),
-  resolveTool: (name) => catalog.resolve(localAlias(name)),
-  callTool: (name, args = {}, context = {}) => {
-    const descriptor = catalog.resolve(localAlias(name));
-    const handler = handlers.get(descriptor.name);
-    return handler(args, context);
-  }
+exports.filesystem = Object.fromEntries(fsToolNames.map((name) => [name, zero.commandFilesystem[name]]));
+exports.path = Object.fromEntries(pathToolNames.map((name) => [name, zero.commandPath[name]]));
+exports.exec = Object.fromEntries(execToolNames.map((name) => [name, zero.commandExec[name]]));
+exports.listTools = (filter = {}) => catalog.list(filter);
+exports.resolveTool = (name) => catalog.resolve(localAlias(name));
+exports.callTool = (name, args = {}, context = {}) => {
+  const descriptor = catalog.resolve(localAlias(name));
+  const handler = handlers.get(descriptor.name);
+  return handler(args, context);
 };
-
-Object.assign(exports, command);

package/src/command/path/index.js

@@ -1,53 +1,46 @@
-'use strict';
-
-const path = require('node:path');
-const zero = require('../../zero-runtime');
-
-const descriptor = (name, description, properties, required = []) => zero.descriptor.validate({
-  name: `zero.command.path.${name}`,
-  aliases: [`zero.command.${name}`],
-  description,
-  capability: 'path.compute',
-  risk: 'read',
-  execution: 'target',
-  adapters: ['native'],
-  inputSchema: { type: 'object', properties, required, additionalProperties: false }
-});
-
-const resolvePathDescriptor = descriptor('resolvePath', 'Resolve a path against an optional base path.', {
-  path: { type: 'string' }, base: { type: 'string' }
-}, ['path']);
-const normalizePathDescriptor = descriptor('normalizePath', 'Normalize a path string for the target platform.', {
-  path: { type: 'string' }
-}, ['path']);
-const joinPathDescriptor = descriptor('joinPath', 'Join path segments for the target platform.', {
-  segments: { type: 'array', items: { type: 'string' }, minItems: 1 }
-}, ['segments']);
-const relativePathDescriptor = descriptor('relativePath', 'Compute a relative path between two paths.', {
-  from: { type: 'string' }, to: { type: 'string' }
-}, ['from', 'to']);
-const getParentDirectoryDescriptor = descriptor('getParentDirectory', 'Return the parent directory name for a path.', {
-  path: { type: 'string' }
-}, ['path']);
-const getFilenameDescriptor = descriptor('getFilename', 'Return the filename portion of a path.', {
-  path: { type: 'string' }, stripExtension: { type: 'boolean', default: false }
-}, ['path']);
-const getExtensionDescriptor = descriptor('getExtension', 'Return the extension portion of a path.', {
-  path: { type: 'string' }
-}, ['path']);
-
-const asText = (value) => String(value ?? '');
-const resolvePath = (args = {}) => ({ ok: true, path: args.base ? path.resolve(asText(args.base), asText(args.path)) : path.resolve(asText(args.path)) });
-const normalizePath = (args = {}) => ({ ok: true, path: path.normalize(asText(args.path)) });
-const joinPath = (args = {}) => ({ ok: true, path: path.join(...(Array.isArray(args.segments) ? args.segments.map(asText) : [])) });
-const relativePath = (args = {}) => ({ ok: true, path: path.relative(asText(args.from), asText(args.to)) });
-const getParentDirectory = (args = {}) => ({ ok: true, path: path.dirname(asText(args.path)) });
-const getFilename = (args = {}) => ({ ok: true, name: path.basename(asText(args.path), args.stripExtension ? path.extname(asText(args.path)) : undefined) });
-const getExtension = (args = {}) => ({ ok: true, extension: path.extname(asText(args.path)) });
-
-const pathTools = {
-  resolvePathDescriptor, normalizePathDescriptor, joinPathDescriptor, relativePathDescriptor,
-  getParentDirectoryDescriptor, getFilenameDescriptor, getExtensionDescriptor,
-  resolvePath, normalizePath, joinPath, relativePath, getParentDirectory, getFilename, getExtension
-};
-Object.assign(exports, pathTools);
+'use strict';
+
+const zero = require('../../zero');
+
+
+const descriptor = (name, description, properties, required = []) => zero.descriptor.validate({
+  name: `zero.command.path.${name}`,
+  aliases: [`zero.command.${name}`],
+  description,
+  capability: 'zero.path.compute',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: { type: 'object', properties, required, additionalProperties: false }
+});
+
+exports.resolvePathDescriptor = descriptor('resolvePath', 'Resolve a path against an optional base zero.path.', {
+  path: { type: 'string' }, base: { type: 'string' }
+}, ['path']);
+exports.normalizePathDescriptor = descriptor('normalizePath', 'Normalize a path string for the target platform.', {
+  path: { type: 'string' }
+}, ['path']);
+exports.joinPathDescriptor = descriptor('joinPath', 'Join path segments for the target platform.', {
+  segments: { type: 'array', items: { type: 'string' }, minItems: 1 }
+}, ['segments']);
+exports.relativePathDescriptor = descriptor('relativePath', 'Compute a relative path between two paths.', {
+  from: { type: 'string' }, to: { type: 'string' }
+}, ['from', 'to']);
+exports.getParentDirectoryDescriptor = descriptor('getParentDirectory', 'Return the parent directory name for a zero.path.', {
+  path: { type: 'string' }
+}, ['path']);
+exports.getFilenameDescriptor = descriptor('getFilename', 'Return the filename portion of a zero.path.', {
+  path: { type: 'string' }, stripExtension: { type: 'boolean', default: false }
+}, ['path']);
+exports.getExtensionDescriptor = descriptor('getExtension', 'Return the extension portion of a zero.path.', {
+  path: { type: 'string' }
+}, ['path']);
+
+const asText = (value) => String(value ?? '');
+exports.resolvePath = (args = {}) => ({ ok: true, path: args.base ? zero.path.resolve(asText(args.base), asText(args.path)) : zero.path.resolve(asText(args.path)) });
+exports.normalizePath = (args = {}) => ({ ok: true, path: zero.path.normalize(asText(args.path)) });
+exports.joinPath = (args = {}) => ({ ok: true, path: zero.path.join(...(Array.isArray(args.segments) ? args.segments.map(asText) : [])) });
+exports.relativePath = (args = {}) => ({ ok: true, path: zero.path.relative(asText(args.from), asText(args.to)) });
+exports.getParentDirectory = (args = {}) => ({ ok: true, path: zero.path.dirname(asText(args.path)) });
+exports.getFilename = (args = {}) => ({ ok: true, name: zero.path.basename(asText(args.path), args.stripExtension ? zero.path.extname(asText(args.path)) : undefined) });
+exports.getExtension = (args = {}) => ({ ok: true, extension: zero.path.extname(asText(args.path)) });

package/src/config.js

@@ -1,52 +1,40 @@
 'use strict';
 
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
+const zero = require('./zero');
 
-const defaultHome = () => path.join(os.homedir(), '.zero-agent');
 
-const agentHome = (env = process.env) => path.resolve(env.ZERO_AGENT_HOME || defaultHome());
-const deviceFile = (env = process.env) => path.join(agentHome(env), 'device.json');
-const logDir = (env = process.env) => path.join(agentHome(env), 'logs');
+const defaultHome = () => zero.path.join(zero.os.homedir(), '.zero-agent');
 
-const ensureDirs = (env = process.env) => {
-  fs.mkdirSync(agentHome(env), { recursive: true });
-  fs.mkdirSync(logDir(env), { recursive: true });
+exports.agentHome = (env = process.env) => zero.path.resolve(env.ZERO_AGENT_HOME || defaultHome());
+exports.deviceFile = (env = process.env) => zero.path.join(exports.agentHome(env), 'device.json');
+exports.logDir = (env = process.env) => zero.path.join(exports.agentHome(env), 'logs');
+
+exports.ensureDirs = (env = process.env) => {
+  zero.fs.mkdirSync(exports.agentHome(env), { recursive: true });
+  zero.fs.mkdirSync(exports.logDir(env), { recursive: true });
 };
 
-const readJson = (file, fallback = null) => {
-  if (!fs.existsSync(file)) return fallback;
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+exports.readJson = (file, fallback = null) => {
+  if (!zero.fs.existsSync(file)) return fallback;
+  return JSON.parse(zero.fs.readFileSync(file, 'utf8'));
 };
-const writeJson = (file, value) => {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+exports.writeJson = (file, value) => {
+  zero.fs.mkdirSync(zero.path.dirname(file), { recursive: true });
+  zero.fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
 };
 
-const loadDevice = (env = process.env) => readJson(deviceFile(env), null);
+exports.loadDevice = (env = process.env) => exports.readJson(exports.deviceFile(env), null);
 
-const saveDevice = (device, env = process.env) => {
-  ensureDirs(env);
-  writeJson(deviceFile(env), device);
-  return deviceFile(env);
+exports.saveDevice = (device, env = process.env) => {
+  exports.ensureDirs(env);
+  exports.writeJson(exports.deviceFile(env), device);
+  return exports.deviceFile(env);
 };
 
-const redactedDevice = (device) => {
+exports.redactedDevice = (device) => {
   if (!device) return null;
   const clone = { ...device };
   if (clone.device_token) clone.device_token = 'REDACTED';
   if (clone.token) clone.token = 'REDACTED';
   return clone;
 };
-module.exports = {
-  agentHome,
-  deviceFile,
-  logDir,
-  ensureDirs,
-  readJson,
-  writeJson,
-  loadDevice,
-  saveDevice,
-  redactedDevice
-};

package/src/device-paths.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const zero = require('./zero');
+
+exports.storeFile = (env = process.env) => zero.path.resolve(
+  env.ZERO_DEVICE_PATH_STORE || zero.path.join(zero.os.homedir(), '.zero', 'device-paths.json')
+);
+
+exports.normalizeRoots = (roots = []) => [...new Set(
+  roots.filter((item) => typeof item === 'string' && item.trim()).map((item) => zero.path.resolve(item.trim()))
+)];
+
+exports.saveAllowedRoots = (roots = [], env = process.env) => {
+  const allowed_roots = exports.normalizeRoots(roots);
+  const file = exports.storeFile(env);
+  const state = { allowed_roots, updated_at: new Date().toISOString() };
+  zero.fs.mkdirSync(zero.path.dirname(file), { recursive: true });
+  const temp = file + '.tmp-' + process.pid + '-' + Date.now();
+  zero.fs.writeFileSync(temp, JSON.stringify(state, null, 2));
+  zero.fs.renameSync(temp, file);
+  return { ok: true, store: file, ...state };
+};
+
+const defaultListDirectories = (root) => zero.fs.readdirSync(root, { withFileTypes: true })
+  .filter((item) => item.isDirectory())
+  .slice(0, 80)
+  .map((item) => item.name);
+
+exports.snapshot = (env = process.env, system = {}) => {
+  const platform = system.platform || process.platform;
+  const home = system.home || zero.os.homedir();
+  const cwd = system.cwd || process.cwd();
+  const exists = system.exists || zero.fs.existsSync;
+  const listDirectories = system.listDirectories || defaultListDirectories;
+  const drives = zero.storageRoots.discover({ platform, exists });
+  const locations = [];
+  for (const drive of drives) {
+    try {
+      for (const name of listDirectories(drive)) {
+        locations.push(platform === 'win32' ? zero.path.win32.join(drive, name) : zero.path.posix.join(drive, name));
+        if (locations.length >= 160) break;
+      }
+    } catch {}
+    if (locations.length >= 160) break;
+  }
+  return {
+    platform, home, cwd, drives, storage_roots: drives, locations,
+    allowed_roots: zero.pathPolicy.rootsFor({ storageRoots: drives }, env),
+    source: 'agent',
+    discovered_at: new Date().toISOString()
+  };
+};
+

package/src/enrollment-client.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const zero = require('./zero');
+
+
+const buildClaimPayload = (ticket, env = process.env) => ({
+  ticket_id: ticket,
+  device_id: zero.identityState.getDeviceId(env),
+  agent_id: zero.identityState.getAgentId(env)
+});
+
+const buildCompletionPayload = (ticket, env = process.env) => ({
+  ticket_id: ticket,
+  device_id: zero.identityState.getDeviceId(env),
+  identity_id: zero.identityState.getIdentityId(env)
+});
+
+exports.buildClaimPayload = buildClaimPayload;
+exports.buildCompletionPayload = buildCompletionPayload;

package/src/http.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const requestJson = async (url, { method = 'GET', token = null, body = null, timeoutMs = 15000 } = {}) => {
+exports.requestJson = async (url, { method = 'GET', token = null, body = null, timeoutMs = 15000 } = {}) => {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -22,4 +22,29 @@ const requestJson = async (url, { method = 'GET', token = null, body = null, tim
   }
 };
 
-module.exports = { requestJson };
+
+exports.consumeEventStream = async (url, { token = null, signal = undefined, onEvent = async () => {} } = {}) => {
+  const headers = { accept: 'text/event-stream' };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const response = await fetch(url, { method: 'GET', headers, signal });
+  if (!response.ok) return { ok: false, status: response.status };
+  let buffer = '';
+  const decoder = new TextDecoder();
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true }).replace(/\r\n/g, '\n');
+    let boundary;
+    while ((boundary = buffer.indexOf('\n\n')) >= 0) {
+      const block = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      if (!block || block.startsWith(':')) continue;
+      let event = 'message';
+      const data = [];
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+      }
+      if (data.length) await onEvent({ event, data: data.join('\n') });
+    }
+  }
+  return { ok: true, status: response.status };
+};

package/src/identity-state.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const zero = require('./zero');
+
+
+exports.buildLocalIdentity = (env = process.env) => {
+  const device = zero.config.loadDevice(env) || {};
+  const host = zero.os.hostname();
+  return {
+    device_id: device.device_id || null,
+    host,
+    machine_fingerprint: zero.crypto
+      .createHash('sha256')
+      .update(`${host}:${process.platform}:${process.arch}`)
+      .digest('hex'),
+    identity_state: device.device_id ? 'paired' : 'missing'
+  };
+};
+
+exports.verifyIdentity = (env = process.env) => {
+  const identity = exports.buildLocalIdentity(env);
+  return {
+    ok: identity.identity_state === 'paired',
+    identity
+  };
+};
+

package/src/index.js

@@ -1,7 +1,5 @@
 'use strict';
 
-const command = require('./command');
+const zero = require('./zero');
 
-const zeroAgent = { command };
-
-Object.assign(exports, zeroAgent);
+exports.command = zero.command;

package/src/instance.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const zero = require('./zero');
+const boot = Date.now();
+const nonce = zero.crypto.randomUUID();
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const failure = (code) => Object.assign(new Error(code), { code });
+exports.identity = (env = process.env) => {
+    const device = zero.config.loadDevice(env);
+    if (!device?.device_id || !device.server) throw failure('AGENT_NOT_PAIRED');
+    return zero.crypto.createHash('sha256').update(JSON.stringify([
+      device.server.replace(/\/+$/, '').toLowerCase(), device.device_id
+    ])).digest('hex');
+  };
+exports.request = (port, message) => new Promise((resolve, reject) => {
+    const socket = zero.net.connect({ host: '127.0.0.1', port });
+    let data = '';
+    socket.setTimeout(1000, () => socket.destroy(failure('AGENT_REPLACE_TIMEOUT')));
+    socket.on('error', reject);
+    socket.on('connect', () => socket.write(JSON.stringify(message) + '\n'));
+    socket.on('data', (chunk) => {
+      data += chunk;
+      if (data.length > 4096) return socket.destroy(failure('AGENT_INVALID_REPLY'));
+      if (!data.includes('\n')) return;
+      socket.destroy();
+      try { resolve(JSON.parse(data.split('\n')[0])); } catch (error) { reject(error); }
+    });
+    socket.on('end', () => { if (!data.includes('\n')) reject(failure('AGENT_EMPTY_REPLY')); });
+  });
+exports.acquire = async (env = process.env, options = {}) => {
+    const identity = options.identity || exports.identity(env);
+    const port = options.port || 30000 + parseInt(identity.slice(0, 8), 16) % 20000;
+    const order = options.order || [boot, nonce];
+    const onReplace = options.onReplace || (() => process.exit(0));
+    const deadline = Date.now() + 8000;
+    let replacedPid = null;
+    while (Date.now() < deadline) {
+      const server = zero.net.createServer((socket) => {
+        let data = '';
+        socket.setTimeout(1000, () => socket.destroy());
+        socket.on('error', () => {});
+        socket.on('data', (chunk) => {
+          data += chunk;
+          if (data.length > 4096) return socket.destroy();
+          if (!data.includes('\n')) return;
+          socket.removeAllListeners('data');
+          let request;
+          try { request = JSON.parse(data.split('\n')[0]); } catch { return socket.destroy(); }
+          const same = request.protocol === 'zero-agent-instance-v1' && request.identity === identity;
+          const newer = Array.isArray(request.order) && (
+            request.order[0] > order[0] || (request.order[0] === order[0] && request.order[1] > order[1]));
+          const accepted = same && newer && request.action === 'replace';
+          socket.end(JSON.stringify({ protocol: 'zero-agent-instance-v1', identity, pid: process.pid,
+            accepted, code: same ? 'AGENT_NEWER_INSTANCE_EXISTS' : 'AGENT_PORT_CONFLICT' }) + '\n', () => {
+            if (!accepted) return;
+            console.log(JSON.stringify({ event: 'agent.instance.replaced', pid: process.pid, by_pid: request.pid }));
+            server.close();
+            onReplace();
+          });
+        });
+      });
+      const error = await new Promise((resolve) => {
+        server.once('error', resolve);
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => resolve(null));
+      });
+      if (!error) {
+        server.unref();
+        return { pid: process.pid, port, replaced_pid: replacedPid, release: () => server.close() };
+      }
+      if (error.code !== 'EADDRINUSE') throw error;
+      try {
+        const reply = await exports.request(port, { protocol: 'zero-agent-instance-v1', identity,
+          action: 'replace', pid: process.pid, order });
+        if (reply.protocol !== 'zero-agent-instance-v1' || reply.identity !== identity)
+          throw failure('AGENT_PORT_CONFLICT');
+        if (!reply.accepted) throw failure(reply.code || 'AGENT_REPLACE_REJECTED');
+        replacedPid = reply.pid;
+      } catch (error) {
+        if (!['ECONNREFUSED', 'ECONNRESET'].includes(error.code)) throw error;
+      }
+      await sleep(100);
+    }
+    throw failure('AGENT_PREVIOUS_INSTANCE_DID_NOT_EXIT');
+  };
+