@engineeros/connector 0.14.2 → 0.14.4

package/README.md

@@ -47,7 +47,7 @@ npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engi
 
 The connector uploads a bounded ZIP snapshot for a safe file inventory, then stays online for deep assessments, rescans, and Goal Runs. Inventory never executes repository code. It excludes known secrets, dependency directories, build output, compiled binaries, files larger than 5 MB, agent-tool caches, Git metadata, and connector state before upload.
 
-From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 baseline checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Every domain uses a detailed structured-Markdown contract. EngineerOS stores each completed stage, resumes unfinished work after a connector restart, retry, or temporary connection loss, and then synthesizes the selected results into System State. Connector `0.14.2` runs native Codex stages concurrently and runs ACP agents such as OpenCode one stage at a time because every ACP stage owns a separate local process. It also throttles repetitive progress transitions so long assessments do not saturate the backend with database writes. Capability detail and project-specific compliance controls fan out after their catalogs, and final synthesis waits for every selected result. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. Each result, live output, validation correction, and retry remains independently durable. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and gives an incomplete report one bounded correction turn instead of repeatedly restarting it. Assessment cannot modify the workspace.
+From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 baseline checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Every domain uses a detailed structured-Markdown contract. EngineerOS stores each completed stage, resumes unfinished work after a connector restart, retry, or temporary connection loss, and then synthesizes the selected results into System State. Connector `0.14.4` runs up to three independent assessment stages for every supported coding-agent protocol, including ACP agents such as OpenCode. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; workers no longer compete to send individual WebSocket progress heartbeats. Live output remains coalesced separately because it is durable report content. Capability detail and project-specific compliance controls fan out after their catalogs, and final synthesis waits for every selected result. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. Each result, live output, validation correction, and retry remains independently durable. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and gives an incomplete report one bounded correction turn instead of repeatedly restarting it. Assessment cannot modify the workspace.
 
 After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
 

package/bin/engineeros-connector.mjs

@@ -12,6 +12,9 @@ import {
   workspaceUrl,
 } from "../src/config.mjs";
 import {
+  ASSESSMENT_OUTPUT_FLUSH_INTERVAL_MS,
+  ASSESSMENT_RESULT_TIMEOUT_MS,
+  assessmentWorkerSnapshots,
   assessmentInactivityFailure,
   assessmentProgressMessage,
   assessmentStreamDelta,
@@ -20,15 +23,14 @@ import {
   executeAssignment,
   executeConnectedPrompt,
   executeWorkspaceAssessment,
-  inspectCodingAgent,
-  promptStreamEvent,
-  requeueInterruptedAssessment,
-  shouldReportAssessmentProgress,
-  stopProcess,
-  submitAssessmentResultWithRetry,
-  takeWorkspaceAssessmentWave,
-  workspaceAssessmentWorkerLimit,
-  workspaceSnapshot,
+  inspectCodingAgent,
+  promptStreamEvent,
+  requeueInterruptedAssessment,
+  stopProcess,
+  submitAssessmentResultWithRetry,
+  takeWorkspaceAssessmentWave,
+  workspaceAssessmentWorkerLimit,
+  workspaceSnapshot,
 } from "../src/runner.mjs";
 import { disposeAcpRuntimes } from "../src/acp-client.mjs";
 import {
@@ -199,15 +201,13 @@ firstMessage.capabilities = capabilities;
 
 let stopped = false;
 let active = null;
-const activeAssessments = new Map();
-const ASSESSMENT_WORKER_LIMIT = workspaceAssessmentWorkerLimit(
-  codingAgent.protocol,
-);
-if (ASSESSMENT_WORKER_LIMIT === 1) {
-  console.log(
-    "ACP assessments run one stage at a time to keep the local agent and EngineerOS responsive.",
-  );
-}
+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();
@@ -354,11 +354,11 @@ async function connect() {
   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);
-    }
+    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(
@@ -421,7 +421,7 @@ async function submitWorkspaceSnapshot() {
       `Inventoried ${snapshot.total_file_count.toLocaleString()} safe file(s).`,
     );
     console.log(
-      `Uploaded ${snapshot.evidence_file_count.toLocaleString()} prioritized source file(s).`,
+      `Uploaded ${snapshot.evidence_file_count.toLocaleString()} prioritized source file(s).`,
     );
     console.log(
       `Excluded ${snapshot.excluded_file_count.toLocaleString()} sensitive or generated file(s).`,
@@ -453,16 +453,29 @@ async function submitWorkspaceSnapshot() {
 
 function startPings() {
   clearInterval(pingTimer);
-  pingTimer = setInterval(() => {
-    if (socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "ping",
-          active_run_id: active?.kind === "goal" ? active.runId : null,
-        }),
-      );
+  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.
     }
-  }, 10_000);
+    scheduleReconnect();
+  }
 }
 
 function sendPromptEvent(promptId, event) {
@@ -491,13 +504,20 @@ function pump() {
       kind: "assessment",
       key: assessmentKey,
       runId: assessment.assessment_id,
-      stage: assessment.stage,
-      child: null,
-      resumeAssignment: null,
-    };
+      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;
@@ -610,12 +630,9 @@ 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 = Date.now();
-  let lastAgentActivityAt = stageStartedAt;
-  let lastAgentStatus = "Starting the connected agent";
-  let agentEventCount = 0;
-  let agentProcessStarted = false;
-  let agentCompleted = false;
+  const stageStartedAt = assessmentState.startedAt;
+  let agentProcessStarted = false;
+  let agentCompleted = false;
   let statusTicks = 0;
   let progress = 5;
   let outputBuffer = "";
@@ -623,31 +640,28 @@ async function executeAssessment(assignment, assessmentState) {
   let outputTimer;
   let accepted = false;
   let failureReported = false;
-  let inactivityFailure = null;
-  let lastReportedMilestone = null;
-  let lastProgressMessage = null;
-  let lastProgressPercent = -1;
-  let lastProgressSentAt = 0;
-  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 } = {}) => {
+  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) {
@@ -656,38 +670,11 @@ async function executeAssessment(assignment, assessmentState) {
         creditedMilestones.add(message);
         progress = Math.min(90, progress + 10);
       }
-      lastAgentStatus = message;
       console.log(`[assessment:${stage}] ${message}.`);
     }
-    const boundedMessage = String(message).slice(0, 500);
-    const now = Date.now();
-    if (
-      !shouldReportAssessmentProgress(
-        {
-          message: boundedMessage,
-          progressPercent: progress,
-          lastMessage: lastProgressMessage,
-          lastProgressPercent,
-          lastSentAt: lastProgressSentAt,
-        },
-        { now },
-      )
-    ) {
-      return;
-    }
-    if (
-      sendAssessmentMessage({
-        type: "workspace.assessment.progress",
-        assessment_id: assessmentId,
-        stage,
-        progress_percent: progress,
-        message: boundedMessage,
-      })
-    ) {
-      lastProgressMessage = boundedMessage;
-      lastProgressPercent = progress;
-      lastProgressSentAt = now;
-    }
+    const boundedMessage = String(message).slice(0, 500);
+    assessmentState.progressPercent = progress;
+    assessmentState.lastMessage = boundedMessage;
   };
   const flushOutput = () => {
     if (outputTimer) clearTimeout(outputTimer);
@@ -700,14 +687,14 @@ async function executeAssessment(assignment, assessmentState) {
       !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),
-      });
+    }
+    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) => {
@@ -719,16 +706,19 @@ async function executeAssessment(assignment, assessmentState) {
     if (outputBuffer.length >= 50_000) {
       flushOutput();
     } else if (!outputTimer) {
-      outputTimer = setTimeout(flushOutput, 500);
+      outputTimer = setTimeout(
+        flushOutput,
+        ASSESSMENT_OUTPUT_FLUSH_INTERVAL_MS,
+      );
     }
   };
   reportProgress(`Starting ${stage} assessment stage`);
   const heartbeat = setInterval(() => {
     const now = Date.now();
-    const inactiveMs = now - lastAgentActivityAt;
-    const nextInactivityFailure = agentProcessStarted && !agentCompleted
-      ? assessmentInactivityFailure(stage, inactiveMs)
-      : null;
+    const inactiveMs = now - assessmentState.lastActivityAt;
+    const nextInactivityFailure = agentProcessStarted && !agentCompleted
+      ? assessmentInactivityFailure(stage, inactiveMs)
+      : null;
     if (!inactivityFailure && nextInactivityFailure) {
       inactivityFailure = nextInactivityFailure;
       console.error(`[assessment:${stage}] ${inactivityFailure}`);
@@ -736,42 +726,45 @@ async function executeAssessment(assignment, assessmentState) {
       return;
     }
     if (inactivityFailure) return;
-    reportProgress("Assessment in progress", { milestone: false });
     statusTicks += 1;
     if (statusTicks % 2 === 0) {
       console.log(
         `[assessment:${stage}] ${formatAssessmentDuration(now - stageStartedAt)} elapsed · ` +
-          `${lastAgentStatus} · last agent activity ${formatAssessmentDuration(inactiveMs)} ago ` +
-          `(${agentEventCount.toLocaleString()} events).`,
+          `${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");
+    if (assignment.assessment_mode === "incremental") {
+      progress = 15;
+      reportProgress("Calculating changed files and affected behavior");
     }
-    let result = await executeWorkspaceAssessment(assignment, config, {
+    let result = await executeWorkspaceAssessment(assignment, config, {
       onProcess: (child) => {
         if (isActiveAssessment()) {
           assessmentState.child = child;
           agentProcessStarted = true;
-          lastAgentActivityAt = Date.now();
+          assessmentState.phase = "running";
+          assessmentState.lastActivityAt = Date.now();
           reportProgress("Connected agent process started");
         }
       },
       onEvent: (event) => {
-        lastAgentActivityAt = Date.now();
-        agentEventCount += 1;
+        assessmentState.lastActivityAt = Date.now();
+        assessmentState.eventCount += 1;
         reportOutput(assessmentStreamDelta(event));
         const message = assessmentProgressMessage(event);
-        if (message) reportProgress(message);
-      },
-    });
-    agentCompleted = true;
-    flushOutput();
-    const submitResult = (payload) =>
-      fetch(
+        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,
@@ -779,38 +772,42 @@ async function executeAssessment(assignment, assessmentState) {
         ),
         {
           method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${config.token}`,
-          },
-          body: JSON.stringify(payload),
-          signal: AbortSignal.timeout(30_000),
-        },
-      );
-    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;
-      result = await result.correctAfterRejection(rejection);
-      agentCompleted = true;
-      flushOutput();
-      response = await deliverResult(result);
+          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(
@@ -822,14 +819,14 @@ async function executeAssessment(assignment, assessmentState) {
   } catch (error) {
     flushOutput();
     const message = inactivityFailure || protocolFailureMessage(error);
-    if (isActiveAssessment()) {
-      failureReported = sendAssessmentMessage({
-        type: "workspace.assessment.failed",
-        assessment_id: assessmentId,
-        stage,
-        message,
-      });
-    }
+    if (isActiveAssessment()) {
+      failureReported = sendAssessmentMessage({
+        type: "workspace.assessment.failed",
+        assessment_id: assessmentId,
+        stage,
+        message,
+      });
+    }
     console.error(message);
   } finally {
     if (outputTimer) clearTimeout(outputTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",

package/src/runner.mjs

@@ -32,6 +32,9 @@ const MAX_INVENTORY_FILES = 100_000;
 const MAX_COMPRESSED_INVENTORY_BYTES = 10_000_000;
 const EVIDENCE_POLICY_VERSION = "workspace-evidence-v1";
 export const ASSESSMENT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1_000;
+export const ASSESSMENT_OUTPUT_FLUSH_INTERVAL_MS = 15_000;
+export const ASSESSMENT_RESULT_TIMEOUT_MS = 120_000;
+export const MAX_ASSESSMENT_WORKERS = 3;
 const EXCLUDED_DIRECTORIES = new Set([
   ".agents",
   ".claude",
@@ -697,16 +700,16 @@ export function codexFailureMessage(output, code) {
 
 export function assessmentProgressMessage(event) {
   if (!event || typeof event !== "object") return null;
-  if (event.type === "assessment.output_correction")
-    return "Completing the required stage report structure";
-  if (event.type === "agent.connected")
-    return "Connected agent is ready to inspect the workspace";
+  if (event.type === "assessment.output_correction")
+    return "Completing the required stage report structure";
+  if (event.type === "agent.connected")
+    return "Connected agent is ready to inspect the workspace";
   if (event.type === "acp.plan")
     return "Organizing the repository assessment plan";
-  if (event.type === "acp.agent_thought_chunk")
-    return "Reasoning through the current implementation";
-  if (event.type === "acp.agent_message_chunk")
-    return "Drafting the stage report";
+  if (event.type === "acp.agent_thought_chunk")
+    return "Reasoning through the current implementation";
+  if (event.type === "acp.agent_message_chunk")
+    return "Drafting the stage report";
   if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
     return assessmentCommandMilestone(event.update?.title);
   }
@@ -824,7 +827,7 @@ function assessmentCommandMilestone(command) {
     ? command.join(" ")
     : String(command || "");
   const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
-  if (!normalized) return "Inspecting workspace source";
+  if (!normalized) return "Inspecting workspace source";
   if (/\bgit\s+(status|log|diff|show|rev-parse)\b/.test(normalized)) {
     return "Comparing Git history and workspace changes";
   }
@@ -930,9 +933,9 @@ export function assessmentStageCorrectionPrompt(
     "## Incomplete Stage Output Recovery",
     "",
     "The previous turn ended without a complete stage deliverable. Return the entire structured Markdown stage report now.",
-    "Use repository context already inspected in the previous turn when it is available; inspect only what remains necessary.",
+    "Use repository context already inspected in the previous turn when it is available; inspect only what remains necessary.",
     `The first non-whitespace line of the final answer must be exactly: ${requiredOutputHeading}`,
-    "Follow every section, inspection, and completeness rule in the Assignment.",
+    "Follow every section, inspection, and completeness rule in the Assignment.",
     "Do not return progress commentary, an explanation of the correction, or a code fence.",
   ].join("\n");
 }
@@ -992,7 +995,7 @@ export function enqueueWorkspaceAssessment(
   return "queued";
 }
 
-export function takeWorkspaceAssessmentWave(queue, activeCount, limit = 3) {
+export function takeWorkspaceAssessmentWave(queue, activeCount, limit = 3) {
   const available = Math.max(0, limit - activeCount);
   if (!available || !queue.length) return [];
   if (queue[0]?.parallelizable !== true) {
@@ -1005,36 +1008,37 @@ export function takeWorkspaceAssessmentWave(queue, activeCount, limit = 3) {
   ) {
     wave.push(queue.shift());
   }
-  return wave;
-}
-
-export function workspaceAssessmentWorkerLimit(protocol) {
-  return protocol === "acp" ? 1 : 3;
-}
-
-export function shouldReportAssessmentProgress(
-  {
-    message,
-    progressPercent,
-    lastMessage,
-    lastProgressPercent,
-    lastSentAt,
-  },
-  { now = Date.now(), minimumIntervalMs = 2_000 } = {},
-) {
-  if (!message) return false;
-  if (message === lastMessage && progressPercent <= lastProgressPercent) {
-    return false;
-  }
-  return (
-    progressPercent > lastProgressPercent ||
-    now - lastSentAt >= minimumIntervalMs
-  );
-}
-
-export function requeueInterruptedAssessment(
-  queue,
-  assessmentState,
+  return wave;
+}
+
+export function workspaceAssessmentWorkerLimit() {
+  return MAX_ASSESSMENT_WORKERS;
+}
+
+export function assessmentWorkerSnapshots(activeAssessments) {
+  return [...activeAssessments.values()]
+    .slice(0, MAX_ASSESSMENT_WORKERS)
+    .map((state) => ({
+      assessment_id: String(state.runId),
+      stage: String(state.stage).slice(0, 96),
+      phase: state.phase,
+      progress_percent: Math.max(
+        0,
+        Math.min(95, Number(state.progressPercent) || 0),
+      ),
+      message: String(state.lastMessage || "Assessment worker is starting").slice(
+        0,
+        500,
+      ),
+      started_at: new Date(state.startedAt).toISOString(),
+      last_activity_at: new Date(state.lastActivityAt).toISOString(),
+      event_count: Math.max(0, Number(state.eventCount) || 0),
+    }));
+}
+
+export function requeueInterruptedAssessment(
+  queue,
+  assessmentState,
   { accepted, failureReported },
 ) {
   if (accepted || failureReported || !assessmentState?.resumeAssignment) {
@@ -1047,52 +1051,52 @@ export function requeueInterruptedAssessment(
       assessmentState.resumeAssignment,
       { front: true },
     ) === "queued"
-  );
-}
-
-export async function submitAssessmentResultWithRetry(
-  payload,
-  submit,
-  {
-    isActive = () => true,
-    onRetry = () => {},
-    wait = (milliseconds) =>
-      new Promise((resolve) => setTimeout(resolve, milliseconds)),
-    initialDelayMs = 1_000,
-    maxDelayMs = 30_000,
-  } = {},
-) {
-  let retryDelayMs = initialDelayMs;
-  while (isActive()) {
-    let retryFailure;
-    try {
-      const response = await submit(payload);
-      if (!isTransientAssessmentResultResponse(response)) return response;
-      await response.body?.cancel?.();
-      retryFailure = new Error(
-        `EngineerOS temporarily rejected the completed assessment result (${response.status}).`,
-      );
-    } catch (error) {
-      retryFailure = error;
-    }
-    if (!isActive()) break;
-    onRetry(retryFailure, retryDelayMs);
-    await wait(retryDelayMs);
-    retryDelayMs = Math.min(maxDelayMs, retryDelayMs * 2);
-  }
-  throw new Error("Assessment result delivery stopped before EngineerOS accepted it.");
-}
-
-function isTransientAssessmentResultResponse(response) {
-  return (
-    response.status === 408 ||
-    response.status === 425 ||
-    response.status === 429 ||
-    response.status >= 500
-  );
-}
-
-export function connectorExecution(assignment, options = {}) {
+  );
+}
+
+export async function submitAssessmentResultWithRetry(
+  payload,
+  submit,
+  {
+    isActive = () => true,
+    onRetry = () => {},
+    wait = (milliseconds) =>
+      new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    initialDelayMs = 1_000,
+    maxDelayMs = 30_000,
+  } = {},
+) {
+  let retryDelayMs = initialDelayMs;
+  while (isActive()) {
+    let retryFailure;
+    try {
+      const response = await submit(payload);
+      if (!isTransientAssessmentResultResponse(response)) return response;
+      await response.body?.cancel?.();
+      retryFailure = new Error(
+        `EngineerOS temporarily rejected the completed assessment result (${response.status}).`,
+      );
+    } catch (error) {
+      retryFailure = error;
+    }
+    if (!isActive()) break;
+    onRetry(retryFailure, retryDelayMs);
+    await wait(retryDelayMs);
+    retryDelayMs = Math.min(maxDelayMs, retryDelayMs * 2);
+  }
+  throw new Error("Assessment result delivery stopped before EngineerOS accepted it.");
+}
+
+function isTransientAssessmentResultResponse(response) {
+  return (
+    response.status === 408 ||
+    response.status === 425 ||
+    response.status === 429 ||
+    response.status >= 500
+  );
+}
+
+export function connectorExecution(assignment, options = {}) {
   const rawPrompt = assignment?.prompt_markdown;
   if (typeof rawPrompt !== "string" || !rawPrompt.trim()) {
     throw new Error("EngineerOS assignment is missing prompt_markdown.");