@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/lib/host-control/client.ts

@@ -1,172 +0,0 @@
-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

@@ -1,60 +0,0 @@
-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

@@ -1,167 +0,0 @@
-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;
-}

package/lib/host-control/server.ts

@@ -1,180 +0,0 @@
-import fs from 'node:fs';
-import net from 'node:net';
-import { createHash } from 'node:crypto';
-
-import {
-  HOST_CONTROL_DIRECTORY_MODE,
-  HOST_CONTROL_SOCKET_MODE,
-  ensureHostControlWorkerToken,
-  inspectHostControlEndpoint,
-  prepareHostControlDirectory,
-  removeHostControlWorkerToken,
-  resolveHostControlEndpoint
-} from './path.ts';
-import {
-  HOST_CONTROL_MAX_REQUEST_BYTES,
-  validateHostControlRequest,
-  type HostControlRequest,
-  type HostControlResponse
-} from './client.ts';
-import { acquireFileLock } from '../fs/file-lock.ts';
-import { appendHostControlAudit } from './audit.ts';
-
-export type HostControlDispatch = (request: HostControlRequest) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
-
-export type HostControlAudit = Readonly<{
-  requestId: string;
-  taskId: string | null;
-  operation: string;
-  scope: string;
-  phase: 'accepted' | 'completed' | 'rejected';
-  outcome: string;
-  authorityKind: 'host-broker';
-  transportKind: 'host-fixed-transport';
-  identityDigest: string;
-}>;
-
-export type HostControlServerOptions = Readonly<{
-  endpoint?: string;
-  dispatch: HostControlDispatch;
-  audit?: (entry: HostControlAudit) => void;
-}>;
-
-function auditFor(request: HostControlRequest, phase: HostControlAudit['phase'], outcome: string): HostControlAudit {
-  return {
-    requestId: request.id,
-    taskId: request.taskId,
-    operation: request.operation,
-    scope: request.scope,
-    phase,
-    outcome,
-    authorityKind: 'host-broker',
-    transportKind: 'host-fixed-transport',
-    identityDigest: createHash('sha256').update(`${request.taskId ?? '-'}\0${request.generation ?? '-'}`, 'utf8').digest('hex')
-  };
-}
-
-function failedResponse(id: string, status: 'rejected' | 'unknown', code: string, message: string): HostControlResponse {
-  const error = { code, message };
-  const stdout = `${JSON.stringify({ status: 'failed', changed: status === 'rejected' ? false : null, error })}\n`;
-  return { version: 1, id, status, exitCode: 1, stdout, stderr: '', error };
-}
-
-async function handleConnection(socket: net.Socket, options: HostControlServerOptions): Promise<void> {
-  await new Promise<void>((resolve) => {
-    let input = '';
-    let completed = false;
-    let processing = false;
-    socket.setEncoding('utf8');
-    // A disconnected caller does not cancel an already dispatched domain operation.
-    socket.on('error', () => socket.destroy());
-    socket.on('close', () => { if (!processing) resolve(); });
-    socket.on('end', () => { if (!processing) socket.end(); });
-    const finish = (value: HostControlResponse): void => {
-      if (completed || socket.destroyed) return;
-      completed = true;
-      socket.end(`${JSON.stringify(value)}\n`);
-    };
-    socket.on('data', async (chunk: string) => {
-      if (completed || processing) return;
-      input += chunk;
-      if (Buffer.byteLength(input, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) {
-        finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit'));
-        return;
-      }
-      const newline = input.indexOf('\n');
-      if (newline < 0) return;
-      const raw = input.slice(0, newline);
-      let request: HostControlRequest;
-      try { request = validateHostControlRequest(JSON.parse(raw)); }
-      catch (error) {
-        finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_INVALID', error instanceof Error ? error.message : String(error)));
-        return;
-      }
-      processing = true;
-      let started = false;
-      try {
-        options.audit?.(auditFor(request, 'accepted', 'in-progress'));
-        started = true;
-        const result = await options.dispatch(request);
-        options.audit?.(auditFor(request, 'completed', result.exitCode === 0 ? 'success' : 'failure'));
-        finish({ version: 1, id: request.id, status: 'completed', ...result, error: null });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'HOST_CONTROL_DISPATCH_FAILED';
-        const status = started ? 'unknown' : 'rejected';
-        try { options.audit?.(auditFor(request, started ? 'completed' : 'rejected', status)); }
-        catch { /* Return the uncertainty even when the audit sink is unavailable. */ }
-        finish(failedResponse(request.id, status, code, message));
-      } finally {
-        resolve();
-      }
-    });
-  });
-}
-
-export type RunningHostControlServer = Readonly<{
-  endpoint: string;
-  server: net.Server;
-  close: () => Promise<void>;
-}>;
-
-export async function startHostControlServer(options: HostControlServerOptions): Promise<RunningHostControlServer> {
-  const endpoint = options.endpoint ?? resolveHostControlEndpoint();
-  const audit = options.audit ?? ((entry: HostControlAudit) => appendHostControlAudit(endpoint, entry));
-  prepareHostControlDirectory(endpoint);
-  const lock = acquireFileLock(`${endpoint}.lock`);
-  let server: net.Server | undefined;
-  try {
-    ensureHostControlWorkerToken(endpoint);
-    try {
-      const existing = fs.lstatSync(endpoint);
-      if (existing.isSymbolicLink() || !existing.isSocket()) throw new Error('HOST_CONTROL_ENDPOINT_INVALID');
-      fs.unlinkSync(endpoint);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    }
-    const connections = new Set<Promise<void>>();
-    server = net.createServer({ allowHalfOpen: true }, (socket) => {
-      const connection = handleConnection(socket, { ...options, audit });
-      connections.add(connection);
-      void connection.finally(() => connections.delete(connection));
-    });
-    const listeningServer = server;
-    await new Promise<void>((resolve, reject) => {
-      listeningServer.once('error', reject);
-      listeningServer.listen(endpoint, () => { listeningServer.off('error', reject); resolve(); });
-    });
-    fs.chmodSync(endpoint, HOST_CONTROL_SOCKET_MODE);
-    const inspection = inspectHostControlEndpoint(endpoint, { uid: process.getuid?.() });
-    if (!inspection.ok) {
-      await new Promise<void>((resolve) => listeningServer.close(() => resolve()));
-      removeHostControlWorkerToken(endpoint);
-      throw new Error(inspection.code ?? 'HOST_CONTROL_ENDPOINT_INVALID');
-    }
-    let closing: Promise<void> | undefined;
-    return {
-      endpoint,
-      server,
-      close: () => closing ??= (async () => {
-        try {
-          await new Promise<void>((resolve) => listeningServer.close(() => resolve()));
-          await Promise.all(connections);
-          await fs.promises.rm(endpoint, { force: true });
-          removeHostControlWorkerToken(endpoint);
-        } finally { lock.release(); }
-      })()
-    };
-  } catch (error) {
-    if (server?.listening) await new Promise<void>((resolve) => server!.close(() => resolve()));
-    lock.release();
-    throw error;
-  }
-}
-
-export async function serveHostControl(options: HostControlServerOptions, signal?: AbortSignal): Promise<void> {
-  const running = await startHostControlServer(options);
-  if (!signal) return;
-  if (signal.aborted) { await running.close(); return; }
-  await new Promise<void>((resolve) => signal.addEventListener('abort', () => { void running.close().then(resolve); }, { once: true }));
-}