@engineeros/connector 0.14.4 → 0.15.0

package/bin/engineeros-connector.mjs

@@ -1,965 +1,1010 @@
-#!/usr/bin/env node
-import os from "node:os";
-import path from "node:path";
-import {
-  assessmentResultUrl,
-  connectorResumeCredentials,
-  loadConfig,
-  mergePairedConfig,
-  resultUrl,
-  saveConfig,
-  socketUrl,
-  workspaceUrl,
-} from "../src/config.mjs";
-import {
-  ASSESSMENT_OUTPUT_FLUSH_INTERVAL_MS,
-  ASSESSMENT_RESULT_TIMEOUT_MS,
-  assessmentWorkerSnapshots,
-  assessmentInactivityFailure,
-  assessmentProgressMessage,
-  assessmentStreamDelta,
-  applyAcceptedChange,
-  enqueueWorkspaceAssessment,
-  executeAssignment,
-  executeConnectedPrompt,
-  executeWorkspaceAssessment,
-  inspectCodingAgent,
-  promptStreamEvent,
-  requeueInterruptedAssessment,
-  stopProcess,
-  submitAssessmentResultWithRetry,
-  takeWorkspaceAssessmentWave,
-  workspaceAssessmentWorkerLimit,
-  workspaceSnapshot,
-} from "../src/runner.mjs";
-import { disposeAcpRuntimes } from "../src/acp-client.mjs";
-import {
-  installRegisteredAgent,
-  inspectRegisteredAgent,
-  registeredAgentConfig,
-  registeredAgents,
-} from "../src/agent-registry.mjs";
-import {
-  describeRejectedResponse,
-  describeWebSocketError,
-  protocolFailureMessage,
-  startConnectionWatchdog,
-} from "../src/connection.mjs";
-import { advertisedCapabilities } from "../src/capabilities.mjs";
-import { parseConnectorArgs } from "../src/cli-args.mjs";
-import { runMcpServer } from "../src/mcp-server.mjs";
-import packageJson from "../package.json" with { type: "json" };
-
-const { command, positional, flags } = parseConnectorArgs(
-  process.argv.slice(2),
-);
-
-if (command === "agents") {
-  let agents;
-  try {
-    agents = await registeredAgents();
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  const statuses = await Promise.all(
-    agents.map(async (agent) => {
-      try {
-        await inspectRegisteredAgent(agent.id);
-        return `${agent.id}: ready (${agent.name} ${agent.version}, ${agent.distribution_type})`;
-      } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        return `${agent.id}: setup needed (${agent.name} ${agent.version}, ${agent.distribution_type}) - ${detail}`;
-      }
-    }),
-  );
-  for (const status of statuses) {
-    console.log(status);
-  }
-  process.exit(0);
-}
-
-if (command === "agent") {
-  const agentId = positional[0];
-  const action = positional[1] || "check";
-  if (!agentId || !["check", "install"].includes(action)) {
-    fail("Usage: engineeros-connector agent AGENT_ID [check|install]");
-  }
-  try {
-    const installed =
-      action === "install"
-        ? await installRegisteredAgent(agentId)
-        : await inspectRegisteredAgent(agentId);
-    console.log(
-      `${installed.name} is ready (${installed.version}, ${installed.distribution}).`,
-    );
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  process.exit(0);
-}
-
-if (command === "mcp") {
-  const config = await loadConfig(flags.workspace || process.cwd());
-  if (!config) fail("This workspace is not paired with EngineerOS.");
-  const runId = flags["run-id"] || positional[0];
-  if (!runId)
-    fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
-  await runMcpServer({
-    config,
-    runId,
-    version: packageJson.version,
-    input: process.stdin,
-    output: process.stdout,
-  });
-  process.exit(0);
-}
-
-if (command === "status") {
-  const config = await loadConfig(flags.workspace || process.cwd());
-  console.log(
-    config
-      ? `Paired as ${config.name} (${config.connector_id}) for ${config.workspace}`
-      : "Not paired",
-  );
-  process.exit(config ? 0 : 1);
-}
-
-let config;
-let firstMessage;
-let existingConfig;
-if (command === "pair") {
-  const pairingCode = positional[0];
-  if (!pairingCode)
-    fail(
-      "Usage: engineeros-connector pair CODE --url URL [--agent AGENT_ID] [--name NAME] [--workspace PATH] [--skip-git-repo-check]",
-    );
-  const url = flags.url;
-  if (!url) fail("Pairing requires --url with the EngineerOS backend address.");
-  if (flags.agent && flags["agent-command"]) {
-    fail("Use either --agent or --agent-command, not both.");
-  }
-  let agentConfig = {};
-  try {
-    if (flags.agent) {
-      await inspectRegisteredAgent(flags.agent);
-      agentConfig = await registeredAgentConfig(flags.agent);
-    }
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  config = {
-    server_url: socketUrl(url),
-    workspace: path.resolve(flags.workspace || process.cwd()),
-    onboard: flags.onboard === true,
-    onboarding_pending: flags.onboard === true,
-    agent_protocol: flags["agent-command"] ? "acp" : "codex",
-    agent_command: flags["agent-command"] || null,
-    agent_args: parseAgentArgs(flags["agent-args"]),
-    agent_name: flags["agent-name"] || null,
-    ...agentConfig,
-    skip_git_repo_check: flags["skip-git-repo-check"] === true,
-    name:
-      flags.name ||
-      `${os.hostname()} - ${path.basename(path.resolve(flags.workspace || process.cwd()))}`,
-  };
-  existingConfig = await loadConfig(config.workspace);
-  firstMessage = {
-    type: "pair",
-    pairing_code: pairingCode,
-    name: config.name,
-    capabilities: {},
-    ...connectorResumeCredentials(existingConfig, config.server_url),
-  };
-} else if (command === "start") {
-  config = await loadConfig(flags.workspace || process.cwd());
-  if (!config)
-    fail(
-      "This connector is not paired. Create a pairing command in EngineerOS first.",
-    );
-  firstMessage = {
-    type: "authenticate",
-    connector_id: config.connector_id,
-    token: config.token,
-  };
-} else {
-  fail(
-    "Use `engineeros-connector pair`, `start`, `status`, `agents`, `agent`, or `mcp`.",
-  );
-}
-
-let codingAgent;
-try {
-  codingAgent = await inspectCodingAgent(config, config.workspace);
-} catch (error) {
-  fail(error instanceof Error ? error.message : String(error));
-}
-console.log(
-  `Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`,
-);
-const capabilities = advertisedCapabilities(config, codingAgent);
-firstMessage.capabilities = capabilities;
-
-let stopped = false;
-let active = null;
-const activeAssessments = new Map();
-const ASSESSMENT_WORKER_LIMIT = workspaceAssessmentWorkerLimit(
-  codingAgent.protocol,
-);
-console.log(
-  `Assessment supervisor can run up to ${ASSESSMENT_WORKER_LIMIT} independent ${codingAgent.name} workers.`,
-);
-const available = [];
-const assessments = [];
-const activePrompts = new Map();
-let socket;
-let pingTimer;
-let reconnectTimer;
-let clearConnectionWatchdog;
-let reconnectDelay = 1_000;
-let connectionRejected = false;
-let lastConnectionError;
-let snapshotInFlight = false;
-
-process.on("SIGINT", async () => {
-  stopped = true;
-  clearConnectionWatchdog?.();
-  clearTimeout(reconnectTimer);
-  clearInterval(pingTimer);
-  await Promise.all([
-    stopProcess(active?.child),
-    ...[...activeAssessments.values()].map((state) => stopProcess(state.child)),
-  ]);
-  await Promise.all([...activePrompts.values()].map(cancelPrompt));
-  await disposeAcpRuntimes();
-  socket?.close();
-  process.exit(0);
-});
-
-await connect();
-
-async function connect() {
-  console.log(`Connecting ${config.name} to ${config.server_url}`);
-  connectionRejected = false;
-  lastConnectionError = undefined;
-  socket = new WebSocket(config.server_url);
-  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
-    onTimeout: (message) => {
-      lastConnectionError = message;
-      console.error(message);
-      scheduleReconnect();
-    },
-  });
-  socket.addEventListener("open", () =>
-    socket.send(JSON.stringify(firstMessage)),
-  );
-  socket.addEventListener("message", async (event) => {
-    const message = JSON.parse(String(event.data));
-    if (message.type === "paired") {
-      clearConnectionWatchdog?.();
-      const reusedConnector =
-        existingConfig?.connector_id === message.connector.id;
-      config = mergePairedConfig(
-        config,
-        existingConfig,
-        message.connector.id,
-        message.token,
-      );
-      await saveConfig(config);
-      firstMessage = {
-        type: "authenticate",
-        connector_id: config.connector_id,
-        token: config.token,
-        capabilities,
-      };
-      console.log(
-        reusedConnector
-          ? `Reconnected existing workspace connector ${config.connector_id}; assessment history is preserved.`
-          : `Paired. Connector ${config.connector_id} is online.`,
-      );
-      reconnectDelay = 1_000;
-      startPings();
-      if (config.onboarding_pending) void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "authenticated") {
-      clearConnectionWatchdog?.();
-      console.log("Connected and waiting for EngineerOS runs.");
-      reconnectDelay = 1_000;
-      startPings();
-      if (config.onboarding_pending) void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "workspace.refresh") {
-      void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "workspace.assessment") {
-      const assessmentKey = `${message.assessment_id}:${message.stage}`;
-      const disposition = enqueueWorkspaceAssessment(
-        assessments,
-        activeAssessments.get(assessmentKey),
-        message,
-      );
-      if (disposition === "deferred") {
-        console.log(
-          `Assessment stage ${message.stage} is still active after reconnect; preserving the replay until it finishes.`,
-        );
-      }
-      pump();
-      return;
-    }
-    if (message.type === "prompt.execute") {
-      if (!activePrompts.has(message.prompt_id)) void executePrompt(message);
-      return;
-    }
-    if (message.type === "prompt.cancel") {
-      const promptState = activePrompts.get(message.prompt_id);
-      if (promptState) await cancelPrompt(promptState);
-      return;
-    }
-    if (message.type === "run.available") {
-      if (!available.includes(message.run_id)) available.push(message.run_id);
-      pump();
-      return;
-    }
-    if (message.type === "run.assignment") {
-      await execute(message);
-      return;
-    }
-    if (message.type === "run.cancelled" && active?.runId === message.run_id) {
-      console.log(`Run ${message.run_id} cancelled by EngineerOS.`);
-      active.cancelled = true;
-      await stopProcess(active.child);
-      return;
-    }
-    if (message.type === "connector.revoked") {
-      stopped = true;
-      console.error("This connector was revoked in EngineerOS.");
-      socket.close();
-      return;
-    }
-    if (message.type === "run.error") {
-      console.error(`EngineerOS: ${message.message}`);
-      if (!message.run_id) snapshotInFlight = false;
-      if (active?.runId === message.run_id && !active.child) {
-        active = null;
-        pump();
-      }
-    }
-    if (message.type === "connection.error") {
-      connectionRejected = true;
-      console.error(`EngineerOS: ${message.message}`);
-    }
-  });
-  socket.addEventListener("close", (event) => {
-    clearConnectionWatchdog?.();
-    clearInterval(pingTimer);
-    for (const promptState of activePrompts.values())
-      void cancelPrompt(promptState);
-    for (const assessmentState of activeAssessments.values()) {
-      if (event.code === 4001) void stopProcess(assessmentState.child);
-    }
-    if (connectionRejected) {
-      stopped = true;
-      console.error(
-        "Connection rejected. Create a new pairing command in EngineerOS if this connector was revoked.",
-      );
-      return;
-    }
-    if (stopped) return;
-    scheduleReconnect();
-  });
-  socket.addEventListener("error", (event) => {
-    lastConnectionError = describeWebSocketError(event);
-    console.error(
-      `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
-    );
-  });
-}
-
-function scheduleReconnect() {
-  if (stopped || connectionRejected || reconnectTimer) return;
-  const detail = lastConnectionError
-    ? ` Last error: ${lastConnectionError}`
-    : "";
-  console.error(
-    `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
-  );
-  reconnectTimer = setTimeout(() => {
-    reconnectTimer = undefined;
-    void connect();
-  }, reconnectDelay);
-  reconnectDelay = Math.min(30_000, reconnectDelay * 2);
-}
-
-async function submitWorkspaceSnapshot() {
-  if (snapshotInFlight || socket.readyState !== WebSocket.OPEN) return;
-  snapshotInFlight = true;
-  console.log("Inspecting the workspace without executing its code.");
-  try {
-    const snapshot = await workspaceSnapshot(config.workspace);
-    const response = await fetch(
-      workspaceUrl(config.server_url, config.connector_id),
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.token}`,
-        },
-        body: JSON.stringify(snapshot),
-      },
-    );
-    if (!response.ok) {
-      throw new Error(
-        await describeRejectedResponse(response, "the workspace"),
-      );
-    }
-    const result = await response.json();
-    config = { ...config, onboarding_pending: false };
-    await saveConfig(config);
-    console.log(
-      `Inventoried ${snapshot.total_file_count.toLocaleString()} safe file(s).`,
-    );
-    console.log(
-      `Uploaded ${snapshot.evidence_file_count.toLocaleString()} prioritized source file(s).`,
-    );
-    console.log(
-      `Excluded ${snapshot.excluded_file_count.toLocaleString()} sensitive or generated file(s).`,
-    );
-    if (snapshot.omitted_evidence_file_count > 0) {
-      console.log(
-        `${snapshot.omitted_evidence_file_count.toLocaleString()} additional file(s) remain available to the connected Agent locally.`,
-      );
-    }
-    const executionProfiles =
-      result.connector?.capabilities?.execution_profiles;
-    const canSelectAssessmentModel =
-      executionProfiles?.model_selection === true &&
-      Array.isArray(executionProfiles.models) &&
-      executionProfiles.models.length > 0;
-    console.log(
-      canSelectAssessmentModel
-        ? `Workspace inventory registered as ${result.workspace_kind}. Select the assessment model in EngineerOS to continue.`
-        : `Workspace inventory registered as ${result.workspace_kind}. This agent did not advertise selectable models; update it and reconnect before starting the baseline assessment.`,
-    );
-    snapshotInFlight = false;
-  } catch (error) {
-    snapshotInFlight = false;
-    console.error(
-      `Workspace assessment failed: ${protocolFailureMessage(error)}`,
-    );
-  }
-}
-
-function startPings() {
-  clearInterval(pingTimer);
-  sendPing();
-  pingTimer = setInterval(sendPing, 10_000);
-}
-
-function sendPing() {
-  if (socket.readyState !== WebSocket.OPEN) return;
-  try {
-    socket.send(
-      JSON.stringify({
-        type: "ping",
-        active_run_id: active?.kind === "goal" ? active.runId : null,
-        assessment_workers: assessmentWorkerSnapshots(activeAssessments),
-      }),
-    );
-  } catch (error) {
-    lastConnectionError = protocolFailureMessage(error);
-    try {
-      socket.close();
-    } catch {
-      // The reconnect timer below owns recovery.
-    }
-    scheduleReconnect();
-  }
-}
-
-function sendPromptEvent(promptId, event) {
-  if (!event || socket.readyState !== WebSocket.OPEN) return;
-  const payload = {
-    type: "prompt.event",
-    prompt_id: promptId,
-    kind: event.kind,
-  };
-  if (event.message) payload.message = String(event.message).slice(0, 500);
-  if (event.delta) payload.delta = String(event.delta).slice(0, 50_000);
-  if (event.status) payload.status = String(event.status).slice(0, 100);
-  socket.send(JSON.stringify(payload));
-}
-
-function pump() {
-  if (socket.readyState !== WebSocket.OPEN || active) return;
-  const wave = takeWorkspaceAssessmentWave(
-    assessments,
-    activeAssessments.size,
-    ASSESSMENT_WORKER_LIMIT,
-  );
-  for (const assessment of wave) {
-    const assessmentKey = `${assessment.assessment_id}:${assessment.stage}`;
-    const assessmentState = {
-      kind: "assessment",
-      key: assessmentKey,
-      runId: assessment.assessment_id,
-      stage: assessment.stage,
-      child: null,
-      resumeAssignment: null,
-      phase: "starting",
-      progressPercent: 5,
-      lastMessage: `Starting ${assessment.stage} assessment stage`,
-      startedAt: Date.now(),
-      lastActivityAt: Date.now(),
-      eventCount: 0,
-    };
-    activeAssessments.set(assessmentKey, assessmentState);
-    void executeAssessment(assessment, assessmentState);
-  }
-  if (wave.length > 0) sendPing();
-  if (activeAssessments.size > 0 || assessments.length > 0) return;
-  const runId = available.shift();
-  if (!runId) return;
-  active = { kind: "goal", runId, child: null, cancelled: false };
-  socket.send(
-    JSON.stringify({
-      type: "run.claim",
-      run_id: runId,
-      runner_name: codingAgent.name,
-      metadata: {
-        hostname: os.hostname(),
-        workspace_name: path.basename(config.workspace),
-      },
-    }),
-  );
-}
-
-async function executePrompt(assignment) {
-  const promptId = assignment.prompt_id;
-  const promptState = {
-    runId: promptId,
-    child: null,
-    controller: null,
-    cancelled: false,
-  };
-  activePrompts.set(promptId, promptState);
-  let lastEvent;
-  const reportEvent = (event) => {
-    const serialized = event ? JSON.stringify(event) : null;
-    if (
-      !serialized ||
-      serialized === lastEvent ||
-      socket.readyState !== WebSocket.OPEN ||
-      activePrompts.get(promptId) !== promptState
-    ) {
-      return;
-    }
-    lastEvent = serialized;
-    sendPromptEvent(promptId, event);
-  };
-  sendPromptEvent(promptId, {
-    kind: "status",
-    message: "Agent started this request",
-  });
-  console.log(
-    `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
-  );
-  try {
-    const result = await executeConnectedPrompt(assignment, config, {
-      onProcess: (child) => {
-        if (activePrompts.get(promptId) === promptState)
-          promptState.child = child;
-      },
-      onController: (controller) => {
-        if (activePrompts.get(promptId) === promptState) {
-          promptState.controller = controller;
-        }
-      },
-      onEvent: (event) => reportEvent(promptStreamEvent(event)),
-    });
-    config = {
-      ...config,
-      sessions: {
-        ...(config.sessions || {}),
-        [result.sessionKey]: result.sessionId,
-      },
-    };
-    await saveConfig(config);
-    if (promptState.cancelled || socket.readyState !== WebSocket.OPEN) return;
-    socket.send(
-      JSON.stringify({
-        type: "prompt.completed",
-        prompt_id: promptId,
-        content: result.content,
-        model: result.model,
-        session_id: result.sessionId,
-        usage: result.usage,
-      }),
-    );
-  } catch (error) {
-    const message = protocolFailureMessage(error);
-    if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "prompt.failed",
-          prompt_id: promptId,
-          message,
-        }),
-      );
-    }
-    if (!promptState.cancelled) {
-      console.error(message);
-    }
-  } finally {
-    if (activePrompts.get(promptId) === promptState)
-      activePrompts.delete(promptId);
-  }
-}
-
-async function cancelPrompt(promptState) {
-  promptState.cancelled = true;
-  if (typeof promptState.controller?.cancel === "function") {
-    await promptState.controller.cancel();
-    return;
-  }
-  await stopProcess(promptState.child);
-}
-
-async function executeAssessment(assignment, assessmentState) {
-  const assessmentId = assignment.assessment_id;
-  const stage = assignment.stage;
-  console.log(`Agent is running assessment stage ${stage} (${assessmentId}).`);
-  const stageStartedAt = assessmentState.startedAt;
-  let agentProcessStarted = false;
-  let agentCompleted = false;
-  let statusTicks = 0;
-  let progress = 5;
-  let outputBuffer = "";
-  let outputLength = 0;
-  let outputTimer;
-  let accepted = false;
-  let failureReported = false;
-  let inactivityFailure = null;
-  let lastReportedMilestone = null;
-  const creditedMilestones = new Set();
-  const isActiveAssessment = () =>
-    activeAssessments.get(assessmentState.key) === assessmentState;
-  const sendAssessmentMessage = (payload) => {
-    if (socket.readyState !== WebSocket.OPEN) return false;
-    try {
-      socket.send(JSON.stringify(payload));
-      return true;
-    } catch (error) {
-      lastConnectionError = protocolFailureMessage(error);
-      try {
-        socket.close();
-      } catch {
-        // The reconnect timer below owns recovery.
-      }
-      scheduleReconnect();
-      return false;
-    }
-  };
-  const reportProgress = (message, { milestone = true } = {}) => {
-    if (!isActiveAssessment()) return;
-    if (milestone && lastReportedMilestone === message) return;
-    if (milestone) {
-      lastReportedMilestone = message;
-      if (!creditedMilestones.has(message)) {
-        creditedMilestones.add(message);
-        progress = Math.min(90, progress + 10);
-      }
-      console.log(`[assessment:${stage}] ${message}.`);
-    }
-    const boundedMessage = String(message).slice(0, 500);
-    assessmentState.progressPercent = progress;
-    assessmentState.lastMessage = boundedMessage;
-  };
-  const flushOutput = () => {
-    if (outputTimer) clearTimeout(outputTimer);
-    outputTimer = undefined;
-    const output = outputBuffer;
-    outputBuffer = "";
-    if (
-      !output ||
-      socket.readyState !== WebSocket.OPEN ||
-      !isActiveAssessment()
-    ) {
-      return;
-    }
-    for (let offset = 0; offset < output.length; offset += 50_000) {
-      sendAssessmentMessage({
-        type: "workspace.assessment.output",
-        assessment_id: assessmentId,
-        stage,
-        delta: output.slice(offset, offset + 50_000),
-      });
-    }
-  };
-  const reportOutput = (delta) => {
-    const remaining = 120_000 - outputLength;
-    if (!delta || remaining <= 0) return;
-    const bounded = String(delta).slice(0, remaining);
-    outputBuffer += bounded;
-    outputLength += bounded.length;
-    if (outputBuffer.length >= 50_000) {
-      flushOutput();
-    } else if (!outputTimer) {
-      outputTimer = setTimeout(
-        flushOutput,
-        ASSESSMENT_OUTPUT_FLUSH_INTERVAL_MS,
-      );
-    }
-  };
-  reportProgress(`Starting ${stage} assessment stage`);
-  const heartbeat = setInterval(() => {
-    const now = Date.now();
-    const inactiveMs = now - assessmentState.lastActivityAt;
-    const nextInactivityFailure = agentProcessStarted && !agentCompleted
-      ? assessmentInactivityFailure(stage, inactiveMs)
-      : null;
-    if (!inactivityFailure && nextInactivityFailure) {
-      inactivityFailure = nextInactivityFailure;
-      console.error(`[assessment:${stage}] ${inactivityFailure}`);
-      void stopProcess(assessmentState.child);
-      return;
-    }
-    if (inactivityFailure) return;
-    statusTicks += 1;
-    if (statusTicks % 2 === 0) {
-      console.log(
-        `[assessment:${stage}] ${formatAssessmentDuration(now - stageStartedAt)} elapsed · ` +
-          `${assessmentState.lastMessage} · last agent activity ${formatAssessmentDuration(inactiveMs)} ago ` +
-          `(${assessmentState.eventCount.toLocaleString()} events).`,
-      );
-    }
-  }, 15_000);
-  try {
-    if (assignment.assessment_mode === "incremental") {
-      progress = 15;
-      reportProgress("Calculating changed files and affected behavior");
-    }
-    let result = await executeWorkspaceAssessment(assignment, config, {
-      onProcess: (child) => {
-        if (isActiveAssessment()) {
-          assessmentState.child = child;
-          agentProcessStarted = true;
-          assessmentState.phase = "running";
-          assessmentState.lastActivityAt = Date.now();
-          reportProgress("Connected agent process started");
-        }
-      },
-      onEvent: (event) => {
-        assessmentState.lastActivityAt = Date.now();
-        assessmentState.eventCount += 1;
-        reportOutput(assessmentStreamDelta(event));
-        const message = assessmentProgressMessage(event);
-        if (message) reportProgress(message);
-      },
-    });
-    agentCompleted = true;
-    assessmentState.phase = "delivering";
-    assessmentState.progressPercent = 95;
-    assessmentState.lastMessage = "Delivering completed stage result";
-    flushOutput();
-    const submitResult = (payload) =>
-      fetch(
-        assessmentResultUrl(
-          config.server_url,
-          config.connector_id,
-          assessmentId,
-        ),
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${config.token}`,
-          },
-          body: JSON.stringify(payload),
-          signal: AbortSignal.timeout(ASSESSMENT_RESULT_TIMEOUT_MS),
-        },
-      );
-    const deliverResult = (payload) =>
-      submitAssessmentResultWithRetry(payload, submitResult, {
-        isActive: () => isActiveAssessment() && !stopped,
-        onRetry: (error, delayMs) => {
-          reportProgress("Completed result is waiting for EngineerOS", {
-            milestone: false,
-          });
-          console.warn(
-            `[assessment:${stage}] Completed result delivery failed: ${protocolFailureMessage(error)} ` +
-              `Retrying in ${Math.round(delayMs / 1_000)}s without rerunning the agent.`,
-          );
-        },
-      });
-    let response = await deliverResult(result);
-    if (response.status === 422 && result.correctAfterRejection) {
-      const rejection = await describeRejectedResponse(
-        response,
-        "the assessment",
-      );
-      agentCompleted = false;
-      assessmentState.phase = "correcting";
-      assessmentState.lastMessage = "Correcting a rejected stage result";
-      result = await result.correctAfterRejection(rejection);
-      agentCompleted = true;
-      assessmentState.phase = "delivering";
-      assessmentState.lastMessage = "Delivering corrected stage result";
-      flushOutput();
-      response = await deliverResult(result);
-    }
-    if (!response.ok) {
-      throw new Error(
-        await describeRejectedResponse(response, "the assessment"),
-      );
-    }
-    accepted = true;
-    console.log(`Workspace assessment stage ${stage} was accepted by EngineerOS.`);
-  } catch (error) {
-    flushOutput();
-    const message = inactivityFailure || protocolFailureMessage(error);
-    if (isActiveAssessment()) {
-      failureReported = sendAssessmentMessage({
-        type: "workspace.assessment.failed",
-        assessment_id: assessmentId,
-        stage,
-        message,
-      });
-    }
-    console.error(message);
-  } finally {
-    if (outputTimer) clearTimeout(outputTimer);
-    clearInterval(heartbeat);
-    if (isActiveAssessment()) {
-      activeAssessments.delete(assessmentState.key);
-      const replayQueued = requeueInterruptedAssessment(
-        assessments,
-        assessmentState,
-        { accepted, failureReported },
-      );
-      if (replayQueued) {
-        console.log(`Restarting interrupted assessment stage ${stage}.`);
-      }
-      pump();
-    }
-  }
-}
-
-function formatAssessmentDuration(milliseconds) {
-  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  return minutes ? `${minutes}m ${seconds}s` : `${seconds}s`;
-}
-
-async function execute(assignment) {
-  const runId = assignment.run_id;
-  console.log(`Running Goal ${runId} with ${codingAgent.name}.`);
-  let progress = 10;
-  const heartbeat = setInterval(() => {
-    if (socket.readyState === WebSocket.OPEN && active?.runId === runId) {
-      progress = Math.min(90, progress + 5);
-      socket.send(
-        JSON.stringify({
-          type: "run.progress",
-          run_id: runId,
-          progress_percent: progress,
-          message: "Agent is working",
-        }),
-      );
-    }
-  }, 15_000);
-  try {
-    const result = await executeAssignment(assignment, config, {
-      onProcess: (child) => {
-        if (active?.runId === runId) active.child = child;
-      },
-      onEvent: (event) => {
-        const message =
-          event.message || event.item?.text || event.type || "Agent is working";
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(
-            JSON.stringify({
-              type: "run.progress",
-              run_id: runId,
-              progress_percent: progress,
-              message: String(message).slice(0, 500),
-            }),
-          );
-        }
-      },
-    });
-    if (active?.cancelled) return;
-    const response = await fetch(
-      resultUrl(config.server_url, config.connector_id, runId),
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.token}`,
-        },
-        body: JSON.stringify(result),
-      },
-    );
-    if (!response.ok) {
-      throw new Error(await describeRejectedResponse(response, "the result"));
-    }
-    const integration = await applyAcceptedChange(
-      config.workspace,
-      assignment.base_revision,
-      result.head_revision,
-    );
-    if (integration.applied) {
-      console.log(
-        `Run accepted and applied to the connected repository at ${integration.revision}.`,
-      );
-    } else {
-      console.warn(
-        `Run accepted but not applied locally. ${integration.reason}`,
-      );
-      console.warn(
-        `The verified run workspace remains at ${result.run_workspace}.`,
-      );
-    }
-  } catch (error) {
-    const message = protocolFailureMessage(error);
-    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "run.failed",
-          run_id: runId,
-          message,
-        }),
-      );
-    }
-    if (!active?.cancelled) console.error(message);
-  } finally {
-    clearInterval(heartbeat);
-    active = null;
-    pump();
-  }
-}
-
-function parseAgentArgs(value) {
-  if (!value) return [];
-  try {
-    const parsed = JSON.parse(value);
-    if (
-      !Array.isArray(parsed) ||
-      parsed.some((item) => typeof item !== "string")
-    ) {
-      throw new Error();
-    }
-    return parsed;
-  } catch {
-    fail(
-      '--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"',
-    );
-  }
-}
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import {
+  assessmentResultUrl,
+  connectorResumeCredentials,
+  loadConfig,
+  mergePairedConfig,
+  resultUrl,
+  saveConfig,
+  socketUrl,
+  workspaceUrl,
+} from "../src/config.mjs";
+import {
+  ASSESSMENT_RESULT_TIMEOUT_MS,
+  assessmentWorkerSnapshots,
+  assessmentInactivityFailure,
+  assessmentProgressMessage,
+  applyAcceptedChange,
+  enqueueWorkspaceAssessment,
+  executeAssignment,
+  executeConnectedPrompt,
+  executeWorkspaceAssessment,
+  inspectCodingAgent,
+  promptStreamEvent,
+  requeueInterruptedAssessment,
+  stopProcess,
+  submitAssessmentResultWithRetry,
+  takeWorkspaceAssessmentWave,
+  workspaceAssessmentWorkerLimit,
+  workspaceSnapshot,
+} from "../src/runner.mjs";
+import {
+  assessmentCheckpointPayload,
+  assessmentCompletionBundle,
+  clearAssessmentSpool,
+  loadAssessmentStageResult,
+  persistAssessmentStageResult,
+  prepareLocalAssessmentAssignment,
+  removeAssessmentStageResult,
+} from "../src/assessment-spool.mjs";
+import { disposeAcpRuntimes } from "../src/acp-client.mjs";
+import {
+  installRegisteredAgent,
+  inspectRegisteredAgent,
+  registeredAgentConfig,
+  registeredAgents,
+} from "../src/agent-registry.mjs";
+import {
+  describeRejectedResponse,
+  describeWebSocketError,
+  protocolFailureMessage,
+  startConnectionWatchdog,
+} from "../src/connection.mjs";
+import { advertisedCapabilities } from "../src/capabilities.mjs";
+import { parseConnectorArgs } from "../src/cli-args.mjs";
+import { runMcpServer } from "../src/mcp-server.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+const { command, positional, flags } = parseConnectorArgs(
+  process.argv.slice(2),
+);
+
+if (command === "agents") {
+  let agents;
+  try {
+    agents = await registeredAgents();
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  const statuses = await Promise.all(
+    agents.map(async (agent) => {
+      try {
+        await inspectRegisteredAgent(agent.id);
+        return `${agent.id}: ready (${agent.name} ${agent.version}, ${agent.distribution_type})`;
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return `${agent.id}: setup needed (${agent.name} ${agent.version}, ${agent.distribution_type}) - ${detail}`;
+      }
+    }),
+  );
+  for (const status of statuses) {
+    console.log(status);
+  }
+  process.exit(0);
+}
+
+if (command === "agent") {
+  const agentId = positional[0];
+  const action = positional[1] || "check";
+  if (!agentId || !["check", "install"].includes(action)) {
+    fail("Usage: engineeros-connector agent AGENT_ID [check|install]");
+  }
+  try {
+    const installed =
+      action === "install"
+        ? await installRegisteredAgent(agentId)
+        : await inspectRegisteredAgent(agentId);
+    console.log(
+      `${installed.name} is ready (${installed.version}, ${installed.distribution}).`,
+    );
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(0);
+}
+
+if (command === "mcp") {
+  const config = await loadConfig(flags.workspace || process.cwd());
+  if (!config) fail("This workspace is not paired with EngineerOS.");
+  const runId = flags["run-id"] || positional[0];
+  if (!runId)
+    fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
+  await runMcpServer({
+    config,
+    runId,
+    version: packageJson.version,
+    input: process.stdin,
+    output: process.stdout,
+  });
+  process.exit(0);
+}
+
+if (command === "status") {
+  const config = await loadConfig(flags.workspace || process.cwd());
+  console.log(
+    config
+      ? `Paired as ${config.name} (${config.connector_id}) for ${config.workspace}`
+      : "Not paired",
+  );
+  process.exit(config ? 0 : 1);
+}
+
+let config;
+let firstMessage;
+let existingConfig;
+if (command === "pair") {
+  const pairingCode = positional[0];
+  if (!pairingCode)
+    fail(
+      "Usage: engineeros-connector pair CODE --url URL [--agent AGENT_ID] [--name NAME] [--workspace PATH] [--assessment-workers COUNT] [--skip-git-repo-check]",
+    );
+  const url = flags.url;
+  if (!url) fail("Pairing requires --url with the EngineerOS backend address.");
+  if (flags.agent && flags["agent-command"]) {
+    fail("Use either --agent or --agent-command, not both.");
+  }
+  let agentConfig = {};
+  try {
+    if (flags.agent) {
+      await inspectRegisteredAgent(flags.agent);
+      agentConfig = await registeredAgentConfig(flags.agent);
+    }
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  config = {
+    server_url: socketUrl(url),
+    workspace: path.resolve(flags.workspace || process.cwd()),
+    onboard: flags.onboard === true,
+    onboarding_pending: flags.onboard === true,
+    agent_protocol: flags["agent-command"] ? "acp" : "codex",
+    agent_command: flags["agent-command"] || null,
+    agent_args: parseAgentArgs(flags["agent-args"]),
+    agent_name: flags["agent-name"] || null,
+    ...agentConfig,
+    ...(flags["assessment-workers"] === undefined
+      ? {}
+      : {
+          assessment_workers: configuredAssessmentWorkerLimit(
+            flags["assessment-workers"],
+          ),
+        }),
+    skip_git_repo_check: flags["skip-git-repo-check"] === true,
+    name:
+      flags.name ||
+      `${os.hostname()} - ${path.basename(path.resolve(flags.workspace || process.cwd()))}`,
+  };
+  existingConfig = await loadConfig(config.workspace);
+  firstMessage = {
+    type: "pair",
+    pairing_code: pairingCode,
+    name: config.name,
+    capabilities: {},
+    ...connectorResumeCredentials(existingConfig, config.server_url),
+  };
+} else if (command === "start") {
+  config = await loadConfig(flags.workspace || process.cwd());
+  if (!config)
+    fail(
+      "This connector is not paired. Create a pairing command in EngineerOS first.",
+    );
+  firstMessage = {
+    type: "authenticate",
+    connector_id: config.connector_id,
+    token: config.token,
+  };
+} else {
+  fail(
+    "Use `engineeros-connector pair`, `start`, `status`, `agents`, `agent`, or `mcp`.",
+  );
+}
+
+let codingAgent;
+try {
+  codingAgent = await inspectCodingAgent(config, config.workspace);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+console.log(
+  `Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`,
+);
+const capabilities = advertisedCapabilities(config, codingAgent);
+firstMessage.capabilities = capabilities;
+
+let stopped = false;
+let active = null;
+const activeAssessments = new Map();
+const ASSESSMENT_WORKER_LIMIT = configuredAssessmentWorkerLimit(
+  flags["assessment-workers"] ?? config.assessment_workers,
+);
+console.log(
+  `Assessment supervisor can run up to ${ASSESSMENT_WORKER_LIMIT} independent ${codingAgent.name} stages.`,
+);
+const available = [];
+const assessments = [];
+const activePrompts = new Map();
+let socket;
+let pingTimer;
+let reconnectTimer;
+let clearConnectionWatchdog;
+let reconnectDelay = 1_000;
+let connectionRejected = false;
+let lastConnectionError;
+let snapshotInFlight = false;
+
+process.on("SIGINT", async () => {
+  stopped = true;
+  clearConnectionWatchdog?.();
+  clearTimeout(reconnectTimer);
+  clearInterval(pingTimer);
+  await Promise.all([
+    stopProcess(active?.child),
+    ...[...activeAssessments.values()].map((state) => stopProcess(state.child)),
+  ]);
+  await Promise.all([...activePrompts.values()].map(cancelPrompt));
+  await disposeAcpRuntimes();
+  socket?.close();
+  process.exit(0);
+});
+
+await connect();
+
+async function connect() {
+  console.log(`Connecting ${config.name} to ${config.server_url}`);
+  connectionRejected = false;
+  lastConnectionError = undefined;
+  socket = new WebSocket(config.server_url);
+  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
+    onTimeout: (message) => {
+      lastConnectionError = message;
+      console.error(message);
+      scheduleReconnect();
+    },
+  });
+  socket.addEventListener("open", () =>
+    socket.send(JSON.stringify(firstMessage)),
+  );
+  socket.addEventListener("message", async (event) => {
+    const message = JSON.parse(String(event.data));
+    if (message.type === "paired") {
+      clearConnectionWatchdog?.();
+      const reusedConnector =
+        existingConfig?.connector_id === message.connector.id;
+      config = mergePairedConfig(
+        config,
+        existingConfig,
+        message.connector.id,
+        message.token,
+      );
+      await saveConfig(config);
+      firstMessage = {
+        type: "authenticate",
+        connector_id: config.connector_id,
+        token: config.token,
+        capabilities,
+      };
+      console.log(
+        reusedConnector
+          ? `Reconnected existing workspace connector ${config.connector_id}; assessment history is preserved.`
+          : `Paired. Connector ${config.connector_id} is online.`,
+      );
+      reconnectDelay = 1_000;
+      startPings();
+      if (config.onboarding_pending) void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "authenticated") {
+      clearConnectionWatchdog?.();
+      console.log("Connected and waiting for EngineerOS runs.");
+      reconnectDelay = 1_000;
+      startPings();
+      if (config.onboarding_pending) void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "workspace.refresh") {
+      void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "workspace.assessment") {
+      const assessmentKey = `${message.assessment_id}:${message.stage}`;
+      const disposition = enqueueWorkspaceAssessment(
+        assessments,
+        activeAssessments.get(assessmentKey),
+        message,
+      );
+      if (disposition === "deferred") {
+        console.log(
+          `Assessment stage ${message.stage} is still active after reconnect; preserving the replay until it finishes.`,
+        );
+      }
+      pump();
+      return;
+    }
+    if (message.type === "prompt.execute") {
+      if (!activePrompts.has(message.prompt_id)) void executePrompt(message);
+      return;
+    }
+    if (message.type === "prompt.cancel") {
+      const promptState = activePrompts.get(message.prompt_id);
+      if (promptState) await cancelPrompt(promptState);
+      return;
+    }
+    if (message.type === "run.available") {
+      if (!available.includes(message.run_id)) available.push(message.run_id);
+      pump();
+      return;
+    }
+    if (message.type === "run.assignment") {
+      await execute(message);
+      return;
+    }
+    if (message.type === "run.cancelled" && active?.runId === message.run_id) {
+      console.log(`Run ${message.run_id} cancelled by EngineerOS.`);
+      active.cancelled = true;
+      await stopProcess(active.child);
+      return;
+    }
+    if (message.type === "connector.revoked") {
+      stopped = true;
+      console.error("This connector was revoked in EngineerOS.");
+      socket.close();
+      return;
+    }
+    if (message.type === "run.error") {
+      console.error(`EngineerOS: ${message.message}`);
+      if (!message.run_id) snapshotInFlight = false;
+      if (active?.runId === message.run_id && !active.child) {
+        active = null;
+        pump();
+      }
+    }
+    if (message.type === "connection.error") {
+      connectionRejected = true;
+      console.error(`EngineerOS: ${message.message}`);
+    }
+  });
+  socket.addEventListener("close", (event) => {
+    clearConnectionWatchdog?.();
+    clearInterval(pingTimer);
+    for (const promptState of activePrompts.values())
+      void cancelPrompt(promptState);
+    for (const assessmentState of activeAssessments.values()) {
+      if (event.code === 4001) void stopProcess(assessmentState.child);
+    }
+    if (connectionRejected) {
+      stopped = true;
+      console.error(
+        "Connection rejected. Create a new pairing command in EngineerOS if this connector was revoked.",
+      );
+      return;
+    }
+    if (stopped) return;
+    scheduleReconnect();
+  });
+  socket.addEventListener("error", (event) => {
+    lastConnectionError = describeWebSocketError(event);
+    console.error(
+      `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
+    );
+  });
+}
+
+function scheduleReconnect() {
+  if (stopped || connectionRejected || reconnectTimer) return;
+  const detail = lastConnectionError
+    ? ` Last error: ${lastConnectionError}`
+    : "";
+  console.error(
+    `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
+  );
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = undefined;
+    void connect();
+  }, reconnectDelay);
+  reconnectDelay = Math.min(30_000, reconnectDelay * 2);
+}
+
+async function submitWorkspaceSnapshot() {
+  if (snapshotInFlight || socket.readyState !== WebSocket.OPEN) return;
+  snapshotInFlight = true;
+  console.log("Inspecting the workspace without executing its code.");
+  try {
+    const snapshot = await workspaceSnapshot(config.workspace);
+    const response = await fetch(
+      workspaceUrl(config.server_url, config.connector_id),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(snapshot),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(
+        await describeRejectedResponse(response, "the workspace"),
+      );
+    }
+    const result = await response.json();
+    config = { ...config, onboarding_pending: false };
+    await saveConfig(config);
+    console.log(
+      `Inventoried ${snapshot.total_file_count.toLocaleString()} safe file(s).`,
+    );
+    console.log(
+      `Uploaded ${snapshot.evidence_file_count.toLocaleString()} prioritized source file(s).`,
+    );
+    console.log(
+      `Excluded ${snapshot.excluded_file_count.toLocaleString()} sensitive or generated file(s).`,
+    );
+    if (snapshot.omitted_evidence_file_count > 0) {
+      console.log(
+        `${snapshot.omitted_evidence_file_count.toLocaleString()} additional file(s) remain available to the connected Agent locally.`,
+      );
+    }
+    const executionProfiles =
+      result.connector?.capabilities?.execution_profiles;
+    const canSelectAssessmentModel =
+      executionProfiles?.model_selection === true &&
+      Array.isArray(executionProfiles.models) &&
+      executionProfiles.models.length > 0;
+    console.log(
+      canSelectAssessmentModel
+        ? `Workspace inventory registered as ${result.workspace_kind}. Select the assessment model in EngineerOS to continue.`
+        : `Workspace inventory registered as ${result.workspace_kind}. This agent did not advertise selectable models; update it and reconnect before starting the baseline assessment.`,
+    );
+    snapshotInFlight = false;
+  } catch (error) {
+    snapshotInFlight = false;
+    console.error(
+      `Workspace assessment failed: ${protocolFailureMessage(error)}`,
+    );
+  }
+}
+
+function startPings() {
+  clearInterval(pingTimer);
+  sendPing();
+  pingTimer = setInterval(sendPing, 10_000);
+}
+
+function sendPing() {
+  if (socket.readyState !== WebSocket.OPEN) return;
+  try {
+    socket.send(
+      JSON.stringify({
+        type: "ping",
+        active_run_id: active?.kind === "goal" ? active.runId : null,
+        assessment_workers: assessmentWorkerSnapshots(activeAssessments),
+      }),
+    );
+  } catch (error) {
+    lastConnectionError = protocolFailureMessage(error);
+    try {
+      socket.close();
+    } catch {
+      // The reconnect timer below owns recovery.
+    }
+    scheduleReconnect();
+  }
+}
+
+function sendPromptEvent(promptId, event) {
+  if (!event || socket.readyState !== WebSocket.OPEN) return;
+  const payload = {
+    type: "prompt.event",
+    prompt_id: promptId,
+    kind: event.kind,
+  };
+  if (event.message) payload.message = String(event.message).slice(0, 500);
+  if (event.delta) payload.delta = String(event.delta).slice(0, 50_000);
+  if (event.status) payload.status = String(event.status).slice(0, 100);
+  socket.send(JSON.stringify(payload));
+}
+
+function pump() {
+  if (socket.readyState !== WebSocket.OPEN || active) return;
+  const wave = takeWorkspaceAssessmentWave(
+    assessments,
+    activeAssessments.size,
+    ASSESSMENT_WORKER_LIMIT,
+  );
+  for (const assessment of wave) {
+    const assessmentKey = `${assessment.assessment_id}:${assessment.stage}`;
+    const assessmentState = {
+      kind: "assessment",
+      key: assessmentKey,
+      runId: assessment.assessment_id,
+      stage: assessment.stage,
+      child: null,
+      controller: null,
+      resumeAssignment: null,
+      phase: "starting",
+      progressPercent: 5,
+      lastMessage: `Starting ${assessment.stage} assessment stage`,
+      startedAt: Date.now(),
+      lastActivityAt: Date.now(),
+      eventCount: 0,
+    };
+    activeAssessments.set(assessmentKey, assessmentState);
+    void executeAssessment(assessment, assessmentState);
+  }
+  if (wave.length > 0) sendPing();
+  if (activeAssessments.size > 0 || assessments.length > 0) return;
+  const runId = available.shift();
+  if (!runId) return;
+  active = { kind: "goal", runId, child: null, cancelled: false };
+  socket.send(
+    JSON.stringify({
+      type: "run.claim",
+      run_id: runId,
+      runner_name: codingAgent.name,
+      metadata: {
+        hostname: os.hostname(),
+        workspace_name: path.basename(config.workspace),
+      },
+    }),
+  );
+}
+
+async function executePrompt(assignment) {
+  const promptId = assignment.prompt_id;
+  const promptState = {
+    runId: promptId,
+    child: null,
+    controller: null,
+    cancelled: false,
+  };
+  activePrompts.set(promptId, promptState);
+  let lastEvent;
+  const reportEvent = (event) => {
+    const serialized = event ? JSON.stringify(event) : null;
+    if (
+      !serialized ||
+      serialized === lastEvent ||
+      socket.readyState !== WebSocket.OPEN ||
+      activePrompts.get(promptId) !== promptState
+    ) {
+      return;
+    }
+    lastEvent = serialized;
+    sendPromptEvent(promptId, event);
+  };
+  sendPromptEvent(promptId, {
+    kind: "status",
+    message: "Agent started this request",
+  });
+  console.log(
+    `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
+  );
+  try {
+    const result = await executeConnectedPrompt(assignment, config, {
+      onProcess: (child) => {
+        if (activePrompts.get(promptId) === promptState)
+          promptState.child = child;
+      },
+      onController: (controller) => {
+        if (activePrompts.get(promptId) === promptState) {
+          promptState.controller = controller;
+        }
+      },
+      onEvent: (event) => reportEvent(promptStreamEvent(event)),
+    });
+    config = {
+      ...config,
+      sessions: {
+        ...(config.sessions || {}),
+        [result.sessionKey]: result.sessionId,
+      },
+    };
+    await saveConfig(config);
+    if (promptState.cancelled || socket.readyState !== WebSocket.OPEN) return;
+    socket.send(
+      JSON.stringify({
+        type: "prompt.completed",
+        prompt_id: promptId,
+        content: result.content,
+        model: result.model,
+        session_id: result.sessionId,
+        usage: result.usage,
+      }),
+    );
+  } catch (error) {
+    const message = protocolFailureMessage(error);
+    if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "prompt.failed",
+          prompt_id: promptId,
+          message,
+        }),
+      );
+    }
+    if (!promptState.cancelled) {
+      console.error(message);
+    }
+  } finally {
+    if (activePrompts.get(promptId) === promptState)
+      activePrompts.delete(promptId);
+  }
+}
+
+async function cancelPrompt(promptState) {
+  promptState.cancelled = true;
+  if (typeof promptState.controller?.cancel === "function") {
+    await promptState.controller.cancel();
+    return;
+  }
+  await stopProcess(promptState.child);
+}
+
+async function cancelAssessment(assessmentState) {
+  if (typeof assessmentState.controller?.cancel === "function") {
+    await assessmentState.controller.cancel();
+    return;
+  }
+  await stopProcess(assessmentState.child);
+}
+
+async function executeAssessment(assignment, assessmentState) {
+  const assessmentId = assignment.assessment_id;
+  const stage = assignment.stage;
+  console.log(`Agent is running assessment stage ${stage} (${assessmentId}).`);
+  const stageStartedAt = assessmentState.startedAt;
+  let agentProcessStarted = false;
+  let agentCompleted = false;
+  let statusTicks = 0;
+  let progress = 5;
+  let accepted = false;
+  let failureReported = false;
+  let inactivityFailure = null;
+  let lastReportedMilestone = null;
+  const creditedMilestones = new Set();
+  const isActiveAssessment = () =>
+    activeAssessments.get(assessmentState.key) === assessmentState;
+  const sendAssessmentMessage = (payload) => {
+    if (socket.readyState !== WebSocket.OPEN) return false;
+    try {
+      socket.send(JSON.stringify(payload));
+      return true;
+    } catch (error) {
+      lastConnectionError = protocolFailureMessage(error);
+      try {
+        socket.close();
+      } catch {
+        // The reconnect timer below owns recovery.
+      }
+      scheduleReconnect();
+      return false;
+    }
+  };
+  const reportProgress = (message, { milestone = true } = {}) => {
+    if (!isActiveAssessment()) return;
+    if (milestone && lastReportedMilestone === message) return;
+    if (milestone) {
+      lastReportedMilestone = message;
+      if (!creditedMilestones.has(message)) {
+        creditedMilestones.add(message);
+        progress = Math.min(90, progress + 10);
+      }
+      console.log(`[assessment:${stage}] ${message}.`);
+    }
+    const boundedMessage = String(message).slice(0, 500);
+    assessmentState.progressPercent = progress;
+    assessmentState.lastMessage = boundedMessage;
+  };
+  reportProgress(`Starting ${stage} assessment stage`);
+  const heartbeat = setInterval(() => {
+    const now = Date.now();
+    const inactiveMs = now - assessmentState.lastActivityAt;
+    const nextInactivityFailure =
+      agentProcessStarted && !agentCompleted
+        ? assessmentInactivityFailure(stage, inactiveMs)
+        : null;
+    if (!inactivityFailure && nextInactivityFailure) {
+      inactivityFailure = nextInactivityFailure;
+      console.error(`[assessment:${stage}] ${inactivityFailure}`);
+      void cancelAssessment(assessmentState);
+      return;
+    }
+    if (inactivityFailure) return;
+    statusTicks += 1;
+    if (statusTicks % 2 === 0) {
+      console.log(
+        `[assessment:${stage}] ${formatAssessmentDuration(now - stageStartedAt)} elapsed · ` +
+          `${assessmentState.lastMessage} · last agent activity ${formatAssessmentDuration(inactiveMs)} ago ` +
+          `(${assessmentState.eventCount.toLocaleString()} events).`,
+      );
+    }
+  }, 15_000);
+  try {
+    if (assignment.assessment_mode === "incremental") {
+      progress = 15;
+      reportProgress("Calculating changed files and affected behavior");
+    }
+    const preparedAssignment = await prepareLocalAssessmentAssignment(
+      config.workspace,
+      assignment,
+    );
+    let result = await loadAssessmentStageResult(
+      config.workspace,
+      assessmentId,
+      stage,
+    );
+    if (result) {
+      reportProgress("Recovered completed stage report from connector storage");
+    } else {
+      result = await executeWorkspaceAssessment(preparedAssignment, config, {
+        onController: (controller) => {
+          if (isActiveAssessment()) assessmentState.controller = controller;
+        },
+        onProcess: (child) => {
+          if (isActiveAssessment()) {
+            assessmentState.child = child;
+            agentProcessStarted = true;
+            assessmentState.phase = "running";
+            assessmentState.lastActivityAt = Date.now();
+            reportProgress("Connected agent process started");
+          }
+        },
+        onEvent: (event) => {
+          assessmentState.lastActivityAt = Date.now();
+          assessmentState.eventCount += 1;
+          const message = assessmentProgressMessage(event);
+          if (message) reportProgress(message);
+        },
+      });
+      await persistAssessmentStageResult(
+        config.workspace,
+        assessmentId,
+        preparedAssignment,
+        result,
+      );
+    }
+    agentCompleted = true;
+    assessmentState.phase = "delivering";
+    assessmentState.progressPercent = 95;
+    assessmentState.lastMessage =
+      stage === "synthesis"
+        ? "Delivering completed assessment bundle"
+        : "Checkpointing connector-local stage result";
+    const submitResult = (payload) =>
+      fetch(
+        assessmentResultUrl(
+          config.server_url,
+          config.connector_id,
+          assessmentId,
+        ),
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.token}`,
+          },
+          body: JSON.stringify(payload),
+          signal: AbortSignal.timeout(ASSESSMENT_RESULT_TIMEOUT_MS),
+        },
+      );
+    const deliverResult = (payload) =>
+      submitAssessmentResultWithRetry(payload, submitResult, {
+        isActive: () => isActiveAssessment() && !stopped,
+        onRetry: (error, delayMs) => {
+          reportProgress("Completed result is waiting for EngineerOS", {
+            milestone: false,
+          });
+          console.warn(
+            `[assessment:${stage}] Completed result delivery failed: ${protocolFailureMessage(error)} ` +
+              `Retrying in ${Math.round(delayMs / 1_000)}s without rerunning the agent.`,
+          );
+        },
+      });
+    const deliveryPayload =
+      stage === "synthesis"
+        ? await assessmentCompletionBundle(
+            config.workspace,
+            assessmentId,
+            result,
+          )
+        : assessmentCheckpointPayload(result);
+    let response = await deliverResult(deliveryPayload);
+    if (response.status === 422 && result.correctAfterRejection) {
+      const rejection = await describeRejectedResponse(
+        response,
+        "the assessment",
+      );
+      agentCompleted = false;
+      assessmentState.phase = "correcting";
+      assessmentState.lastMessage = "Correcting a rejected stage result";
+      result = await result.correctAfterRejection(rejection);
+      await removeAssessmentStageResult(config.workspace, assessmentId, stage);
+      await persistAssessmentStageResult(
+        config.workspace,
+        assessmentId,
+        preparedAssignment,
+        result,
+      );
+      agentCompleted = true;
+      assessmentState.phase = "delivering";
+      assessmentState.lastMessage = "Delivering corrected stage result";
+      response = await deliverResult(
+        stage === "synthesis"
+          ? await assessmentCompletionBundle(
+              config.workspace,
+              assessmentId,
+              result,
+            )
+          : assessmentCheckpointPayload(result),
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        await describeRejectedResponse(response, "the assessment"),
+      );
+    }
+    accepted = true;
+    if (stage === "synthesis") {
+      await clearAssessmentSpool(config.workspace, assessmentId);
+      console.log(
+        `Workspace assessment ${assessmentId} was accepted by EngineerOS.`,
+      );
+    } else {
+      console.log(
+        `Workspace assessment stage ${stage} was checkpointed by EngineerOS.`,
+      );
+    }
+  } catch (error) {
+    const message = inactivityFailure || protocolFailureMessage(error);
+    if (isActiveAssessment()) {
+      failureReported = sendAssessmentMessage({
+        type: "workspace.assessment.failed",
+        assessment_id: assessmentId,
+        stage,
+        message,
+      });
+    }
+    console.error(message);
+  } finally {
+    clearInterval(heartbeat);
+    if (isActiveAssessment()) {
+      activeAssessments.delete(assessmentState.key);
+      const replayQueued = requeueInterruptedAssessment(
+        assessments,
+        assessmentState,
+        { accepted, failureReported },
+      );
+      if (replayQueued) {
+        console.log(`Restarting interrupted assessment stage ${stage}.`);
+      }
+      pump();
+    }
+  }
+}
+
+function formatAssessmentDuration(milliseconds) {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+async function execute(assignment) {
+  const runId = assignment.run_id;
+  console.log(`Running Goal ${runId} with ${codingAgent.name}.`);
+  let progress = 10;
+  const heartbeat = setInterval(() => {
+    if (socket.readyState === WebSocket.OPEN && active?.runId === runId) {
+      progress = Math.min(90, progress + 5);
+      socket.send(
+        JSON.stringify({
+          type: "run.progress",
+          run_id: runId,
+          progress_percent: progress,
+          message: "Agent is working",
+        }),
+      );
+    }
+  }, 15_000);
+  try {
+    const result = await executeAssignment(assignment, config, {
+      onProcess: (child) => {
+        if (active?.runId === runId) active.child = child;
+      },
+      onEvent: (event) => {
+        const message =
+          event.message || event.item?.text || event.type || "Agent is working";
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(
+            JSON.stringify({
+              type: "run.progress",
+              run_id: runId,
+              progress_percent: progress,
+              message: String(message).slice(0, 500),
+            }),
+          );
+        }
+      },
+    });
+    if (active?.cancelled) return;
+    const response = await fetch(
+      resultUrl(config.server_url, config.connector_id, runId),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(result),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(await describeRejectedResponse(response, "the result"));
+    }
+    const integration = await applyAcceptedChange(
+      config.workspace,
+      assignment.base_revision,
+      result.head_revision,
+    );
+    if (integration.applied) {
+      console.log(
+        `Run accepted and applied to the connected repository at ${integration.revision}.`,
+      );
+    } else {
+      console.warn(
+        `Run accepted but not applied locally. ${integration.reason}`,
+      );
+      console.warn(
+        `The verified run workspace remains at ${result.run_workspace}.`,
+      );
+    }
+  } catch (error) {
+    const message = protocolFailureMessage(error);
+    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "run.failed",
+          run_id: runId,
+          message,
+        }),
+      );
+    }
+    if (!active?.cancelled) console.error(message);
+  } finally {
+    clearInterval(heartbeat);
+    active = null;
+    pump();
+  }
+}
+
+function parseAgentArgs(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    if (
+      !Array.isArray(parsed) ||
+      parsed.some((item) => typeof item !== "string")
+    ) {
+      throw new Error();
+    }
+    return parsed;
+  } catch {
+    fail(
+      '--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"',
+    );
+  }
+}
+
+function configuredAssessmentWorkerLimit(value) {
+  try {
+    return workspaceAssessmentWorkerLimit(value);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}