@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/agent-clients/adapters/codex-lifecycle/store.ts

@@ -43,11 +43,23 @@ type ActiveCodexLifecycleEvidenceQuery = Readonly<{
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
+const RECOVERY_CONSUMER_RE = /^lifecycle-recovery:([^:\r\n]+):([^:\r\n]+)$/u;
 
 function digest(value: string): string {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
+function isRecoveryConsumer(value: string): boolean {
+  return RECOVERY_CONSUMER_RE.test(value);
+}
+
+function recoveryConsumer(taskId: string, receiptId: string): string {
+  if (!/^[^:\r\n]+$/u.test(taskId) || !/^[^:\r\n]+$/u.test(receiptId)) {
+    throw new Error('Codex lifecycle recovery claim identity is invalid');
+  }
+  return `lifecycle-recovery:${taskId}:${receiptId}`;
+}
+
 function readRecord(file: string): StoredCodexLifecycle {
   const value = JSON.parse(fs.readFileSync(file, 'utf8')) as StoredCodexLifecycle;
   if (
@@ -249,11 +261,12 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
 
   function read(childThreadId: string): StoredCodexLifecycle {
     const matches = findByChild(childThreadId);
-    if (matches.length !== 1) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+    if (matches.length === 0) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+    if (matches.length > 1) throw new Error(`Codex lifecycle child '${childThreadId}' is ambiguous`);
     return readRecord(matches[0]!);
   }
 
-  function consume(
+  function consumeInternal(
     childThreadId: string,
     consumer: string,
     expectedHookDefinitionHash?: string
@@ -291,12 +304,51 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     });
   }
 
+  function consume(
+    childThreadId: string,
+    consumer: string,
+    expectedHookDefinitionHash?: string
+  ): StoredCodexLifecycle {
+    if (!consumer.trim()) throw new Error('Codex lifecycle consumer is required');
+    if (consumer.startsWith('lifecycle-recovery:')) {
+      throw new Error('Codex lifecycle recovery claims require claimRecovery');
+    }
+    return consumeInternal(childThreadId, consumer, expectedHookDefinitionHash);
+  }
+
+  function claimRecovery(
+    childThreadId: string,
+    taskId: string,
+    receiptId: string,
+    expectedHookDefinitionHash?: string
+  ): StoredCodexLifecycle {
+    return consumeInternal(
+      childThreadId,
+      recoveryConsumer(taskId, receiptId),
+      expectedHookDefinitionHash
+    );
+  }
+
+  function releaseRecovery(childThreadId: string, consumer: string): boolean {
+    if (!/^lifecycle-recovery:[^:\r\n]+:[^:\r\n]+$/.test(consumer)) return false;
+    return withWriteLock(() => {
+      const matches = findByChild(childThreadId);
+      if (matches.length !== 1) return false;
+      const file = matches[0]!;
+      const current = readRecord(file);
+      if (current.state.status !== 'stop-ready' || current.consumer !== consumer || !current.consumedAt) return false;
+      fs.unlinkSync(file);
+      return true;
+    });
+  }
+
   function expireBefore(cutoff: string): number {
     return withWriteLock(() => {
       let changed = 0;
       for (const file of recordFiles(root)) {
         const current = readRecord(file);
         if (current.updatedAt >= cutoff) continue;
+        if (current.consumer && isRecoveryConsumer(current.consumer)) continue;
         if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
           fs.unlinkSync(file);
           changed += 1;
@@ -316,7 +368,7 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     });
   }
 
-  return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
+  return Object.freeze({ root, apply, applyToSpawn, consume, claimRecovery, releaseRecovery, expireBefore, findByParent, read });
 }
 
 export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };

package/lib/fs/durable-write.ts

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export function fsyncDirectory(directory: string): void {
+  if (process.platform === 'win32') return;
+  const descriptor = fs.openSync(directory, 'r');
+  try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+}
+
+/** The caller owns directory validation and the meaning of an existing target. */
+export function writeDurableFile(
+  target: string,
+  content: string,
+  options: Readonly<{ mode: number; replace: boolean }>
+): void {
+  const directory = path.dirname(target);
+  const temporary = path.join(directory, `.${path.basename(target)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    const descriptor = fs.openSync(temporary, 'wx', options.mode);
+    try {
+      fs.writeFileSync(descriptor, content, { encoding: 'utf8' });
+      fs.fchmodSync(descriptor, options.mode);
+      fs.fsyncSync(descriptor);
+    } finally { fs.closeSync(descriptor); }
+    if (options.replace) fs.renameSync(temporary, target);
+    else fs.linkSync(temporary, target);
+    fsyncDirectory(directory);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}

package/lib/fs/file-lock.ts

@@ -0,0 +1,113 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+type NativeFsExtensions = Readonly<{
+  tryLock: (fd: number) => boolean;
+  unlock: (fd: number) => void;
+}>;
+
+export type FileLockCapability = Readonly<{
+  supported: boolean;
+  primitive: 'flock' | 'F_OFD_SETLK' | 'LockFileEx' | 'unavailable';
+  reason?: string;
+}>;
+
+const require = createRequire(import.meta.url);
+export const NATIVE_LOCK_PRIMITIVE = process.platform === 'win32' ? 'LockFileEx'
+  : process.platform === 'linux' ? 'F_OFD_SETLK' : 'flock';
+
+function loadNative(): NativeFsExtensions {
+  try {
+    return require('fs-native-extensions') as NativeFsExtensions;
+  } catch (error) {
+    throw new Error(
+      `FILE_LOCK_UNSUPPORTED: native lock module is unavailable for Node ${process.version} (${process.platform}-${process.arch}). `
+      + 'Verify that fs-native-extensions includes a prebuilt binary for this platform and reinstall @fitlab-ai/agent-infra. '
+      + `Cause: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+export function probeNativeLockCapability(): FileLockCapability {
+  try {
+    loadNative();
+    return {
+      supported: true,
+      primitive: NATIVE_LOCK_PRIMITIVE
+    };
+  } catch (error) {
+    return {
+      supported: false,
+      primitive: 'unavailable',
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+/** Hold a stable lock file; callers own its namespace and must never unlink it. */
+export function acquireFileLock(filePath: string): Readonly<{ release(): void }> {
+  const native = loadNative();
+  if (fs.existsSync(filePath)) {
+    const existing = fs.lstatSync(filePath);
+    if (existing.isSymbolicLink() || !existing.isFile()) {
+      throw new Error('FILE_LOCK_UNSUPPORTED: lock object is not a regular file');
+    }
+    if (process.platform !== 'win32' && typeof process.getuid === 'function'
+      && existing.uid !== process.getuid()) {
+      throw new Error('FILE_LOCK_UNSUPPORTED: lock object owner mismatch');
+    }
+  }
+  let fd: number | undefined;
+  try {
+    const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+      ? fs.constants.O_NOFOLLOW : 0;
+    fd = fs.openSync(filePath, fs.constants.O_CREAT | fs.constants.O_RDWR | noFollow, 0o600);
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile()) throw new Error('lock object must be a regular file');
+    if (process.platform !== 'win32') {
+      if (typeof process.getuid === 'function' && opened.uid !== process.getuid()) {
+        throw new Error('lock object owner mismatch');
+      }
+      fs.fchmodSync(fd, 0o600);
+    }
+    if (!native.tryLock(fd)) {
+      fs.closeSync(fd);
+      fd = undefined;
+    } else {
+      const current = fs.lstatSync(filePath);
+      if (!current.isFile() || current.dev !== opened.dev || current.ino !== opened.ino) {
+        throw new Error('lock object changed during acquisition');
+      }
+    }
+  } catch (error) {
+    try {
+      if (fd !== undefined) fs.closeSync(fd);
+    } catch {
+      // Preserve the lock acquisition error.
+    }
+    throw new Error(`FILE_LOCK_UNSUPPORTED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (fd === undefined) throw new Error('FILE_LOCK_BUSY');
+
+  let released = false;
+  return {
+    release() {
+      if (released) return;
+      released = true;
+      let failure: unknown = null;
+      try {
+        if (fd === undefined) throw new Error('descriptor is missing');
+        native.unlock(fd);
+      } catch (error) {
+        failure = error;
+      } finally {
+        try {
+          if (fd !== undefined) fs.closeSync(fd);
+        } catch (error) {
+          failure ??= error;
+        }
+      }
+      if (failure) throw new Error(`FILE_LOCK_RELEASE_FAILED: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+  };
+}

package/lib/host-control/audit.ts

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { HostControlAudit } from './server.ts';
+
+export const HOST_CONTROL_AUDIT_FILE = 'audit.ndjson';
+
+export function hostControlAuditPath(endpoint: string): string {
+  return path.join(path.dirname(endpoint), HOST_CONTROL_AUDIT_FILE);
+}
+
+export function appendHostControlAudit(endpoint: string, entry: HostControlAudit, at = Date.now()): void {
+  const filePath = hostControlAuditPath(endpoint);
+  const descriptor = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.fchmodSync(descriptor, 0o600);
+    fs.writeFileSync(descriptor, `${JSON.stringify({ version: 1, at, ...entry })}\n`, 'utf8');
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}

package/lib/host-control/client.ts

@@ -0,0 +1,172 @@
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+
+import {
+  inspectHostControlEndpoint,
+  resolveHostControlEndpoint
+} from './path.ts';
+
+export const HOST_CONTROL_MAX_REQUEST_BYTES = 64 * 1024;
+
+export const HOST_CONTROL_COMMANDS = Object.freeze([
+  'task-lifecycle', 'task-orchestration', 'task-finalization',
+  'task-artifact', 'task-review', 'task-event', 'task-ledger',
+  'task-invalidation', 'task-warning'
+] as const);
+export type HostControlCommand = typeof HOST_CONTROL_COMMANDS[number];
+
+export type HostControlCommandPayload = Readonly<{
+  workingDirectory: string;
+  args: readonly string[];
+  environment?: Readonly<Record<string, string>>;
+}>;
+
+export const HOST_CONTROL_TEST_ENVIRONMENT_KEYS = Object.freeze([
+  'TZ', 'AGENT_INFRA_GH_BIN', 'AGENT_INFRA_GH_ARGS_JSON', 'GH_FAKE_PR_PATH', 'GH_FAKE_ARGS_PATH'
+] as const);
+
+export type HostControlRequest = Readonly<{
+  version: 1;
+  id: string;
+  taskId: string | null;
+  generation: string | null;
+  operation: HostControlCommand;
+  scope: 'host-command';
+  payload: HostControlCommandPayload;
+}>;
+
+export type HostControlResponse = Readonly<{
+  version: 1;
+  id: string;
+  status: 'completed' | 'rejected' | 'unknown';
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  error: Readonly<{ code: string; message: string }> | null;
+}>;
+
+export class HostControlClientError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly changed: false | null;
+  constructor(code: string, message: string, retryable = false, submitted = false) {
+    super(`${code}: ${message}`);
+    this.name = 'HostControlClientError';
+    this.code = code;
+    this.retryable = retryable && !submitted;
+    this.changed = submitted ? null : false;
+  }
+}
+
+function reject(message: string): never {
+  throw new HostControlClientError('HOST_CONTROL_REQUEST_INVALID', message);
+}
+
+export function validateHostControlRequest(value: unknown): HostControlRequest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) reject('request must be an object');
+  const request = value as HostControlRequest;
+  if (Object.keys(request).sort().join(',') !== 'generation,id,operation,payload,scope,taskId,version'
+    || request.version !== 1 || typeof request.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.id)
+    || (request.taskId !== null && (typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)))
+    || (request.generation !== null && (typeof request.generation !== 'string' || !request.generation))
+    || request.scope !== 'host-command' || !HOST_CONTROL_COMMANDS.includes(request.operation as HostControlCommand)) reject('request schema is invalid');
+  const payload = request.payload;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+    || !['args,environment,workingDirectory', 'args,workingDirectory'].includes(Object.keys(payload).sort().join(','))
+    || !Array.isArray(payload.args) || payload.args.length > 128
+    || !payload.args.every((arg) => typeof arg === 'string' && !/[\r\n]/u.test(arg))
+    || typeof payload.workingDirectory !== 'string' || !payload.workingDirectory.startsWith('/')) reject('host-command payload is invalid');
+  if (payload.environment !== undefined) {
+    if (!payload.environment || typeof payload.environment !== 'object' || Array.isArray(payload.environment)) reject('host-command environment is invalid');
+    for (const [key, value] of Object.entries(payload.environment)) {
+      if (!HOST_CONTROL_TEST_ENVIRONMENT_KEYS.includes(key as typeof HOST_CONTROL_TEST_ENVIRONMENT_KEYS[number])
+        || typeof value !== 'string' || /[\r\n]/u.test(value)) reject('host-command environment is invalid');
+    }
+  }
+  return request;
+}
+
+export function hostControlRequestForCommand(
+  command: HostControlCommand,
+  args: readonly string[],
+  workingDirectory: string,
+  environment: Readonly<Record<string, string>> = {}
+): HostControlRequest {
+  if (!HOST_CONTROL_COMMANDS.includes(command)) reject('host-command is unsupported');
+  const taskArg = args[0];
+  const taskId = taskArg && /^TASK-\d{8}-\d{6}$/u.test(taskArg) ? taskArg : null;
+  return validateHostControlRequest({
+    version: 1,
+    id: randomUUID(),
+    taskId,
+    generation: null,
+    operation: command,
+    scope: 'host-command',
+    payload: {
+      workingDirectory,
+      args: [...args],
+      ...(Object.keys(environment).length > 0 ? { environment } : {})
+    }
+  });
+}
+
+function parseResponse(value: unknown, id: string): HostControlResponse {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HostControlClientError('HOST_CONTROL_RESPONSE_INVALID', 'response must be an object');
+  const response = value as Record<string, unknown>;
+  if (Object.keys(response).sort().join(',') !== 'error,exitCode,id,status,stderr,stdout,version'
+    || response.version !== 1 || response.id !== id
+    || !['completed', 'rejected', 'unknown'].includes(response.status as string)
+    || !Number.isSafeInteger(response.exitCode)
+    || typeof response.stdout !== 'string' || typeof response.stderr !== 'string'
+    || (response.error !== null && (!response.error || typeof response.error !== 'object'))) {
+    throw new HostControlClientError('HOST_CONTROL_RESPONSE_INVALID', 'response schema is invalid');
+  }
+  return response as HostControlResponse;
+}
+
+export async function requestHostControl(params: Readonly<{
+  request: HostControlRequest;
+  endpoint?: string;
+  timeoutMs?: number;
+}>): Promise<HostControlResponse> {
+  const request = validateHostControlRequest(params.request);
+  const endpoint = params.endpoint ?? resolveHostControlEndpoint();
+  const inspection = inspectHostControlEndpoint(endpoint, { uid: process.getuid?.() });
+  if (!inspection.ok) throw new HostControlClientError(inspection.code ?? 'HOST_CONTROL_UNAVAILABLE', 'fixed host-control endpoint is unavailable', true);
+  const encoded = `${JSON.stringify(request)}\n`;
+  if (Buffer.byteLength(encoded, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) throw new HostControlClientError('HOST_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
+  const timeoutMs = params.timeoutMs ?? 30_000;
+  return await new Promise<HostControlResponse>((resolve, rejectPromise) => {
+    const socket = net.createConnection(endpoint);
+    let output = '';
+    let settled = false;
+    let submitted = false;
+    const failure = (code: string, message: string, retryable = false) =>
+      new HostControlClientError(code, message, retryable, submitted);
+    const finish = (error?: Error, response?: HostControlResponse): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) rejectPromise(error); else resolve(response!);
+    };
+    const timer = setTimeout(() => finish(failure('HOST_CONTROL_TIMEOUT', 'host-control did not respond; inspect task state before retrying', true)), timeoutMs);
+    socket.setEncoding('utf8');
+    socket.on('connect', () => { submitted = true; socket.end(encoded); });
+    socket.on('data', (chunk: string) => {
+      output += chunk;
+      if (Buffer.byteLength(output, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) {
+        finish(failure('HOST_CONTROL_RESPONSE_TOO_LARGE', 'host-control response exceeds the control limit'));
+        return;
+      }
+      const newline = output.indexOf('\n');
+      if (newline < 0) return;
+      try { finish(undefined, parseResponse(JSON.parse(output.slice(0, newline)), request.id)); }
+      catch (error) { finish(failure('HOST_CONTROL_RESPONSE_INVALID', String(error))); }
+    });
+    socket.on('error', (error) => finish(failure('HOST_CONTROL_UNAVAILABLE', error.message, true)));
+    socket.on('close', () => {
+      if (!settled) finish(failure('HOST_CONTROL_RESPONSE_INVALID', 'host-control closed without a response'));
+    });
+  });
+}

package/lib/host-control/command.ts

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import type { HostControlRequest } from './client.ts';
+import { readHostControlWorkerToken, resolveHostControlEndpoint } from './path.ts';
+
+type HostCommandResult = Readonly<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}>;
+
+export async function dispatchHostControlCommand(
+  request: Pick<HostControlRequest, 'operation' | 'payload'>
+): Promise<HostCommandResult> {
+  const { payload } = request;
+  const compiledEntry = fileURLToPath(new URL('../../bin/internal-cli.js', import.meta.url));
+  const sourceEntry = fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url));
+  const entry = fs.existsSync(compiledEntry) ? compiledEntry : sourceEntry;
+  const payloadEnvironment = payload.environment ?? {};
+  const env = { ...process.env, ...payloadEnvironment };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('AGENT_INFRA_CONTROL_')
+      || key === 'AGENT_INFRA_TASK_ID'
+      || key === 'AGENT_INFRA_RUNTIME_DIR'
+      || key === 'AGENT_INFRA_EXECUTOR_MANIFEST'
+      || key === 'AGENT_INFRA_HOST_CONTROL_SOCKET') {
+      delete env[key];
+    }
+  }
+  delete env.NODE_OPTIONS;
+  delete env.NODE_PATH;
+  delete env.AGENT_INFRA_HOST_CONTROL_WORKER;
+  delete env.AGENT_INFRA_HOST_CONTROL_WORKER_TOKEN;
+  env.AGENT_INFRA_HOST_CONTROL_WORKER = '1';
+  env.AGENT_INFRA_HOST_CONTROL_WORKER_TOKEN = readHostControlWorkerToken(
+    process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT ?? resolveHostControlEndpoint()
+  );
+
+  return await new Promise<HostCommandResult>((resolve, reject) => {
+    const runtimeArgs = entry.endsWith('.ts') ? ['--experimental-strip-types', '--no-warnings', entry] : [entry];
+    const child = spawn(process.execPath, [...runtimeArgs, request.operation, ...payload.args], {
+      cwd: payload.workingDirectory,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => { stdout += chunk; });
+    child.stderr.on('data', (chunk: string) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (signal) reject(new Error(`HOST_CONTROL_WORKER_TERMINATED: ${signal}`));
+      else resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+  });
+}

package/lib/host-control/path.ts

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+export const HOST_CONTROL_DIRECTORY_MODE = 0o700;
+export const HOST_CONTROL_SOCKET_MODE = 0o600;
+export const HOST_CONTROL_WORKER_TOKEN_MODE = 0o600;
+
+export type HostControlPlatform = 'linux' | 'darwin' | 'unsupported';
+
+export type HostControlEndpointOptions = Readonly<{
+  platform?: HostControlPlatform;
+  uid?: number;
+  username?: string;
+}>;
+
+function currentPlatform(): HostControlPlatform {
+  if (process.platform === 'linux' || process.platform === 'darwin') return process.platform;
+  return 'unsupported';
+}
+
+function validUid(uid: number | undefined): number {
+  const resolved = uid ?? process.getuid?.();
+  if (!Number.isInteger(resolved) || resolved === undefined || resolved < 0) {
+    throw new Error('HOST_CONTROL_ENDPOINT_INVALID: uid is unavailable');
+  }
+  return resolved;
+}
+
+function validUsername(username: string | undefined): string {
+  const resolved = username ?? os.userInfo({ encoding: 'utf8' }).username;
+  if (!/^[A-Za-z0-9._-]+$/u.test(resolved)) {
+    throw new Error('HOST_CONTROL_ENDPOINT_INVALID: username is invalid');
+  }
+  return resolved;
+}
+
+export function resolveHostControlEndpoint(options: HostControlEndpointOptions = {}): string {
+  const platform = options.platform ?? currentPlatform();
+  if (platform === 'linux') return `/run/user/${validUid(options.uid)}/agent-infra/host-control.sock`;
+  if (platform === 'darwin') return path.posix.join(
+    '/Users',
+    validUsername(options.username),
+    'Library',
+    'Application Support',
+    'agent-infra',
+    'run',
+    'host-control.sock'
+  );
+  throw new Error('HOST_CONTROL_UNSUPPORTED_PLATFORM');
+}
+
+export function hostControlWorkerTokenPath(endpoint: string): string {
+  return `${endpoint}.worker-token`;
+}
+
+function assertWorkerTokenFile(tokenPath: string, uid = process.getuid?.()): string {
+  const stat = fs.lstatSync(tokenPath);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('HOST_CONTROL_WORKER_TOKEN_INVALID');
+  if ((stat.mode & 0o777) !== HOST_CONTROL_WORKER_TOKEN_MODE) throw new Error('HOST_CONTROL_WORKER_TOKEN_MODE_INVALID');
+  if (uid !== undefined && stat.uid !== uid) throw new Error('HOST_CONTROL_WORKER_TOKEN_OWNER_INVALID');
+  const token = fs.readFileSync(tokenPath, 'utf8').trim();
+  if (!/^[a-f0-9]{64}$/u.test(token)) throw new Error('HOST_CONTROL_WORKER_TOKEN_INVALID');
+  return token;
+}
+
+export function ensureHostControlWorkerToken(endpoint: string, uid = process.getuid?.()): string {
+  const tokenPath = hostControlWorkerTokenPath(endpoint);
+  try {
+    return assertWorkerTokenFile(tokenPath, uid);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  const token = randomBytes(32).toString('hex');
+  try {
+    const fd = fs.openSync(tokenPath, 'wx', HOST_CONTROL_WORKER_TOKEN_MODE);
+    try {
+      fs.writeFileSync(fd, `${token}\n`, 'utf8');
+      fs.fchmodSync(fd, HOST_CONTROL_WORKER_TOKEN_MODE);
+      if (uid !== undefined && process.getuid?.() === uid) fs.fchownSync(fd, uid, process.getgid?.() ?? -1);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+  }
+  return assertWorkerTokenFile(tokenPath, uid);
+}
+
+export function readHostControlWorkerToken(endpoint: string, uid = process.getuid?.()): string {
+  return assertWorkerTokenFile(hostControlWorkerTokenPath(endpoint), uid);
+}
+
+export function removeHostControlWorkerToken(endpoint: string): void {
+  try {
+    fs.unlinkSync(hostControlWorkerTokenPath(endpoint));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+
+export type HostControlEndpointInspection = Readonly<{
+  ok: boolean;
+  code: string | null;
+  ownerUid?: number;
+  mode?: number;
+  parentMode?: number;
+}>;
+
+export function inspectHostControlEndpoint(
+  endpoint: string,
+  expected: Readonly<{ uid?: number }> = {}
+): HostControlEndpointInspection {
+  let endpointStat: fs.Stats;
+  let parentStat: fs.Stats;
+  try {
+    endpointStat = fs.lstatSync(endpoint);
+    parentStat = fs.lstatSync(path.dirname(endpoint));
+  } catch {
+    return { ok: false, code: 'HOST_CONTROL_ENDPOINT_MISSING' };
+  }
+  if (endpointStat.isSymbolicLink()) return { ok: false, code: 'HOST_CONTROL_ENDPOINT_SYMLINK' };
+  if (!endpointStat.isSocket()) return { ok: false, code: 'HOST_CONTROL_ENDPOINT_NOT_SOCKET' };
+  if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) {
+    return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' };
+  }
+  let ancestor = path.dirname(endpoint);
+  while (true) {
+    let stat: fs.Stats;
+    try { stat = fs.lstatSync(ancestor); } catch { return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' }; }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' };
+    const next = path.dirname(ancestor);
+    if (next === ancestor) break;
+    ancestor = next;
+  }
+  const mode = endpointStat.mode & 0o777;
+  const parentMode = parentStat.mode & 0o777;
+  if (mode !== HOST_CONTROL_SOCKET_MODE) return { ok: false, code: 'HOST_CONTROL_ENDPOINT_MODE_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+  if (parentMode !== HOST_CONTROL_DIRECTORY_MODE) return { ok: false, code: 'HOST_CONTROL_PARENT_MODE_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+  if (expected.uid !== undefined && endpointStat.uid !== expected.uid) {
+    return { ok: false, code: 'HOST_CONTROL_ENDPOINT_OWNER_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+  }
+  if (expected.uid !== undefined && parentStat.uid !== expected.uid) {
+    return { ok: false, code: 'HOST_CONTROL_PARENT_OWNER_INVALID', ownerUid: parentStat.uid, mode, parentMode };
+  }
+  return { ok: true, code: null, ownerUid: endpointStat.uid, mode, parentMode };
+}
+
+export function prepareHostControlDirectory(endpoint: string, uid = process.getuid?.()): string {
+  const directory = path.dirname(endpoint);
+  const segments = path.resolve(directory).split(path.sep);
+  let current = path.isAbsolute(directory) ? path.sep : '';
+  for (const segment of segments.filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const stat = fs.lstatSync(current);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('HOST_CONTROL_PARENT_INVALID');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+  fs.mkdirSync(directory, { recursive: true, mode: HOST_CONTROL_DIRECTORY_MODE });
+  fs.chmodSync(directory, HOST_CONTROL_DIRECTORY_MODE);
+  if (uid !== undefined && process.getuid?.() === uid) fs.chownSync(directory, uid, process.getgid?.() ?? -1);
+  return directory;
+}