@engineeros/connector 0.15.3 → 0.16.1

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. Connector `0.15.3` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It atomically spools each completed Markdown report under `.engineeros/assessments/<run-id>` before delivery. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains the reports and reuses them after reconnect without rerunning completed agents. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, and published as canonical artifacts. The connector removes its spool only after EngineerOS acknowledges the complete bundle. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. 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 applies separate bounded structure, semantic, and corrected-response formatting repairs before failing a stage. Assessment cannot modify tracked workspace source.
+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 internal checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Reports include only material conclusions and actions; routine healthy checklist rows are not published. Capability entries state what they own, what they link to, and what they depend on. Connector `0.16.1` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It keeps one local assessment area at `.engineeros/assessment`: the initial accepted run creates `assessment.md`, later code revisions create one consolidated file under `changes/`, and in-progress reports plus resumable agent-session checkpoints stay under `.work/` until final acceptance. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains completed reports and reloads interrupted ACP or Codex sessions after reconnect when the coding agent supports session restoration. Transient ACP, app-server, provider-availability, and rate-limit failures receive two bounded attempts to continue the saved session without repeating completed inspection. A changed Git commit updates the same durable assessment, retains the prior commit in assessment history, and updates published artifacts in place. Connector reports and session checkpoints are tagged with their target commit so an earlier revision cannot leak into the update. If no assessment exists, EngineerOS creates the initial assessment identity. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, published as canonical artifacts, and archived locally. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. 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 applies separate bounded structure, semantic, and corrected-response formatting repairs before failing a stage. Assessment cannot modify tracked workspace source.
 
 Every backend `422` content-validation response is returned to the stage agent with the exact failed item. Distinct validation failures continue through correction and resubmission until the complete stage is accepted. Three repetitions of the same unresolved validation error stop the automatic loop while preserving the latest local report for retry. Authentication, cancellation, source drift, and transport failures remain operational errors rather than agent-correction prompts.
 

package/bin/engineeros-connector.mjs

@@ -21,10 +21,11 @@ import {
   applyAcceptedChange,
   enqueueWorkspaceAssessment,
   executeAssignment,
-  executeConnectedPrompt,
-  executeWorkspaceAssessment,
-  inspectCodingAgent,
-  promptStreamEvent,
+  executeConnectedPrompt,
+  executeWorkspaceAssessment,
+  inspectCodingAgent,
+  isRecoverableAssessmentAgentFailure,
+  promptStreamEvent,
   requeueInterruptedAssessment,
   stopProcess,
   submitAssessmentResultWithRetry,
@@ -33,12 +34,15 @@ import {
   workspaceAssessmentWorkerLimit,
   workspaceSnapshot,
 } from "../src/runner.mjs";
-import {
-  assessmentCheckpointPayload,
-  assessmentCompletionBundle,
-  clearAssessmentSpool,
-  loadAssessmentStageResult,
-  persistAssessmentStageResult,
+import {
+  archiveCompletedAssessment,
+  assessmentCheckpointPayload,
+  assessmentCompletionBundle,
+  assessmentRunDirectory,
+  loadAssessmentStageSession,
+  loadAssessmentStageResult,
+  persistAssessmentStageResult,
+  persistAssessmentStageSession,
   prepareLocalAssessmentAssignment,
   removeAssessmentStageResult,
 } from "../src/assessment-spool.mjs";
@@ -50,11 +54,12 @@ import {
   registeredAgents,
 } from "../src/agent-registry.mjs";
 import {
-  describeRejectedResponse,
-  describeWebSocketError,
-  protocolFailureMessage,
-  startConnectionWatchdog,
-} from "../src/connection.mjs";
+  describeRejectedResponse,
+  describeWebSocketError,
+  protocolFailureMessage,
+  sendConnectionMessage,
+  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";
@@ -250,25 +255,47 @@ process.on("SIGINT", async () => {
 
 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?.();
+async function connect() {
+  console.log(`Connecting ${config.name} to ${config.server_url}`);
+  connectionRejected = false;
+  lastConnectionError = undefined;
+  const connection = new WebSocket(config.server_url);
+  socket = connection;
+  const clearWatchdog = startConnectionWatchdog(connection, config.server_url, {
+    onTimeout: (message) => {
+      if (socket !== connection) return;
+      lastConnectionError = message;
+      console.error(message);
+      scheduleReconnect();
+    },
+  });
+  clearConnectionWatchdog = clearWatchdog;
+  connection.addEventListener("open", () => {
+    if (socket !== connection) {
+      connection.close();
+      return;
+    }
+    try {
+      if (sendConnectionMessage(socket, connection, firstMessage)) return;
+      throw new Error("The WebSocket was not open when authentication started.");
+    } catch (error) {
+      lastConnectionError = protocolFailureMessage(error);
+      console.error(
+        `Could not authenticate the WebSocket connection: ${lastConnectionError}`,
+      );
+      try {
+        connection.close();
+      } catch {
+        // The reconnect timer below owns recovery.
+      }
+      scheduleReconnect();
+    }
+  });
+  connection.addEventListener("message", async (event) => {
+    if (socket !== connection) return;
+    const message = JSON.parse(String(event.data));
+    if (message.type === "paired") {
+      clearWatchdog();
       const reusedConnector =
         existingConfig?.connector_id === message.connector.id;
       config = mergePairedConfig(
@@ -294,8 +321,8 @@ async function connect() {
       if (config.onboarding_pending) void submitWorkspaceSnapshot();
       return;
     }
-    if (message.type === "authenticated") {
-      clearConnectionWatchdog?.();
+    if (message.type === "authenticated") {
+      clearWatchdog();
       console.log("Connected and waiting for EngineerOS runs.");
       reconnectDelay = 1_000;
       startPings();
@@ -345,10 +372,10 @@ async function connect() {
       await stopProcess(active.child);
       return;
     }
-    if (message.type === "connector.revoked") {
-      stopped = true;
-      console.error("This connector was revoked in EngineerOS.");
-      socket.close();
+    if (message.type === "connector.revoked") {
+      stopped = true;
+      console.error("This connector was revoked in EngineerOS.");
+      connection.close();
       return;
     }
     if (message.type === "run.error") {
@@ -364,9 +391,10 @@ async function connect() {
       console.error(`EngineerOS: ${message.message}`);
     }
   });
-  socket.addEventListener("close", (event) => {
-    clearConnectionWatchdog?.();
-    clearInterval(pingTimer);
+  connection.addEventListener("close", (event) => {
+    clearWatchdog();
+    if (socket !== connection) return;
+    clearInterval(pingTimer);
     for (const promptState of activePrompts.values())
       void cancelPrompt(promptState);
     for (const assessmentState of activeAssessments.values()) {
@@ -382,8 +410,9 @@ async function connect() {
     if (stopped) return;
     scheduleReconnect();
   });
-  socket.addEventListener("error", (event) => {
-    lastConnectionError = describeWebSocketError(event);
+  connection.addEventListener("error", (event) => {
+    if (socket !== connection) return;
+    lastConnectionError = describeWebSocketError(event);
     console.error(
       `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
     );
@@ -662,9 +691,10 @@ async function executeAssessment(assignment, assessmentState) {
   let agentCompleted = false;
   let statusTicks = 0;
   let progress = 5;
-  let accepted = false;
-  let failureReported = false;
-  let inactivityFailure = null;
+  let accepted = false;
+  let failureReported = false;
+  let inactivityFailure = null;
+  let checkpointSessionId = null;
   let lastReportedMilestone = null;
   const creditedMilestones = new Set();
   const isActiveAssessment = () =>
@@ -724,7 +754,21 @@ async function executeAssessment(assignment, assessmentState) {
       );
     }
   }, 15_000);
-  const assessmentAgentCallbacks = {
+  const assessmentAgentCallbacks = {
+    onSession: async (sessionId) => {
+      if (!isActiveAssessment()) return;
+      checkpointSessionId = String(sessionId);
+      await persistAssessmentStageSession(
+        config.workspace,
+        assessmentId,
+        stage,
+        sessionId,
+        {
+          sourceRevision: assignment.source_revision,
+          targetHeadRevision: assignment.target_head_revision,
+        },
+      );
+    },
     onController: (controller) => {
       if (isActiveAssessment()) assessmentState.controller = controller;
     },
@@ -753,15 +797,16 @@ async function executeAssessment(assignment, assessmentState) {
       config,
       assessmentAgentCallbacks,
       {
-        draftPath: path
-          .join(
-            ".engineeros",
-            "assessments",
-            String(assessmentId),
-            candidate.report_file,
-          )
-          .split(path.sep)
-          .join("/"),
+        draftPath: path
+          .relative(
+            config.workspace,
+            path.join(
+              assessmentRunDirectory(config.workspace, assessmentId),
+              candidate.report_file,
+            ),
+          )
+          .split(path.sep)
+          .join("/"),
       },
     );
   try {
@@ -773,20 +818,37 @@ async function executeAssessment(assignment, assessmentState) {
       config.workspace,
       assignment,
     );
-    let result = await loadAssessmentStageResult(
-      config.workspace,
-      assessmentId,
-      stage,
-    );
-    if (result) {
+    let result = await loadAssessmentStageResult(
+      config.workspace,
+      assessmentId,
+      stage,
+      {
+        expectedHeadRevision: assignment.target_head_revision,
+        expectedSourceRevision: assignment.source_revision,
+      },
+    );
+    if (result) {
       attachStoredCorrection(result, preparedAssignment);
       reportProgress("Recovered completed stage report from connector storage");
-    } else {
-      result = await executeWorkspaceAssessment(
-        preparedAssignment,
-        config,
-        assessmentAgentCallbacks,
-      );
+    } else {
+      checkpointSessionId = await loadAssessmentStageSession(
+        config.workspace,
+        assessmentId,
+        stage,
+        {
+          expectedHeadRevision: assignment.target_head_revision,
+          expectedSourceRevision: assignment.source_revision,
+        },
+      );
+      if (checkpointSessionId) {
+        reportProgress("Restoring interrupted agent session");
+      }
+      result = await executeWorkspaceAssessment(
+        preparedAssignment,
+        config,
+        assessmentAgentCallbacks,
+        { previousSessionId: checkpointSessionId },
+      );
       await persistAssessmentStageResult(
         config.workspace,
         assessmentId,
@@ -837,11 +899,12 @@ async function executeAssessment(assignment, assessmentState) {
         submit: deliverResult,
         payloadFor: (candidate) =>
           stage === "synthesis"
-            ? assessmentCompletionBundle(
-                config.workspace,
-                assessmentId,
-                candidate,
-              )
+            ? assessmentCompletionBundle(
+                config.workspace,
+                assessmentId,
+                candidate,
+                { expectedSourceRevision: assignment.source_revision },
+              )
             : assessmentCheckpointPayload(candidate),
         rejectionFor: (response) =>
           describeRejectedResponse(response, "the assessment"),
@@ -883,28 +946,56 @@ async function executeAssessment(assignment, assessmentState) {
         await describeRejectedResponse(response, "the assessment"),
       );
     }
-    accepted = true;
-    if (stage === "synthesis") {
-      await clearAssessmentSpool(config.workspace, assessmentId);
-      console.log(
-        `Workspace assessment ${assessmentId} was accepted by EngineerOS.`,
-      );
+    accepted = true;
+    if (stage === "synthesis") {
+      const archivePath = await archiveCompletedAssessment(
+        config.workspace,
+        assessmentId,
+        assignment,
+        result,
+      );
+      console.log(
+        `Workspace assessment ${assessmentId} was accepted by EngineerOS and saved to ${path.relative(config.workspace, archivePath)}.`,
+      );
     } 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);
+  } catch (error) {
+    const message = inactivityFailure || protocolFailureMessage(error);
+    const resumeAttempts = Number(
+      assignment.connector_session_resume_attempts || 0,
+    );
+    const canResumeSession =
+      !inactivityFailure &&
+      checkpointSessionId &&
+      isRecoverableAssessmentAgentFailure(error) &&
+      resumeAttempts < 2;
+    if (isActiveAssessment() && canResumeSession) {
+      assessmentState.phase = "waiting";
+      assessmentState.lastMessage =
+        "Agent session interrupted; resuming checkpoint";
+      assessmentState.resumeAssignment = {
+        ...assignment,
+        connector_session_resume_attempts: resumeAttempts + 1,
+      };
+      const delayMs = 1_000 * 2 ** resumeAttempts;
+      console.warn(
+        `[assessment:${stage}] Agent session interrupted: ${message} ` +
+          `Resuming session ${checkpointSessionId} in ${Math.round(delayMs / 1_000)}s ` +
+          `(${resumeAttempts + 1}/2).`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    } else if (isActiveAssessment()) {
+      failureReported = sendAssessmentMessage({
+        type: "workspace.assessment.failed",
+        assessment_id: assessmentId,
+        stage,
+        message,
+      });
+    }
+    if (!canResumeSession) console.error(message);
   } finally {
     clearInterval(heartbeat);
     if (isActiveAssessment()) {
@@ -913,10 +1004,12 @@ async function executeAssessment(assignment, assessmentState) {
         assessments,
         assessmentState,
         { accepted, failureReported },
-      );
-      if (replayQueued) {
-        console.log(`Restarting interrupted assessment stage ${stage}.`);
-      }
+      );
+      if (replayQueued) {
+        console.log(
+          `Resuming interrupted agent session for assessment stage ${stage} from its checkpoint.`,
+        );
+      }
       pump();
     }
   }

package/package.json

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

package/src/acp-client.mjs

@@ -201,19 +201,20 @@ class AcpRuntime {
     this.clearIdleTimer();
     const initialized = await this.ready;
     let session = this.sessions.get(sessionKey);
-    if (!session) {
-      session = await this.openSession(
+    if (!session) {
+      session = await this.openSession(
         sessionKey,
         previousSessionId,
         sandbox,
         profile,
       );
-      callbacks.onEvent?.({
-        type: "agent.connected",
-        message: `Agent connected with protocol ${initialized.protocolVersion}`,
-      });
-    }
-    if (this.turns.has(session.sessionId)) {
+      callbacks.onEvent?.({
+        type: "agent.connected",
+        message: `Agent connected with protocol ${initialized.protocolVersion}`,
+      });
+    }
+    await callbacks.onSession?.(session.sessionId);
+    if (this.turns.has(session.sessionId)) {
       throw new Error(
         "The agent is already answering another prompt in this session.",
       );

package/src/assessment-spool.mjs

@@ -12,14 +12,18 @@ import path from "node:path";
 
 const LOCAL_REPORTS_MARKER = "<!-- ENGINEEROS_LOCAL_STAGE_REPORTS -->";
 
-export function assessmentRunDirectory(workspace, assessmentId) {
-  return path.join(
-    path.resolve(workspace),
-    ".engineeros",
-    "assessments",
-    String(assessmentId),
-  );
-}
+export function assessmentRunDirectory(workspace, _assessmentId) {
+  return path.join(
+    path.resolve(workspace),
+    ".engineeros",
+    "assessment",
+    ".work",
+  );
+}
+
+export function assessmentArchiveDirectory(workspace) {
+  return path.join(path.resolve(workspace), ".engineeros", "assessment");
+}
 
 export async function persistAssessmentStageResult(
   workspace,
@@ -33,12 +37,14 @@ export async function persistAssessmentStageResult(
   const basename = assessmentStageBasename(result.stage);
   const reportName = `${basename}.md`;
   const metadataName = `${basename}.result.json`;
-  const report = String(result.report_markdown).trim();
-  const metadata = {
-    stage: result.stage,
-    report_file: reportName,
-    report_sha256: sha256(report),
-    observed_head_revision: result.observed_head_revision ?? null,
+  const report = String(result.report_markdown).trim();
+  const metadata = {
+    assessment_id: assessmentId,
+    stage: result.stage,
+    report_file: reportName,
+    report_sha256: sha256(report),
+    source_revision: assignment.source_revision ?? null,
+    observed_head_revision: result.observed_head_revision ?? null,
     changed_files: result.changed_files ?? [],
     change_impact_markdown: result.change_impact_markdown ?? null,
     model: result.model ?? null,
@@ -53,23 +59,39 @@ export async function persistAssessmentStageResult(
   return { ...metadata, report_markdown: report };
 }
 
-export async function loadAssessmentStageResult(
-  workspace,
-  assessmentId,
-  stage,
-) {
+export async function loadAssessmentStageResult(
+  workspace,
+  assessmentId,
+  stage,
+  { expectedHeadRevision, expectedSourceRevision } = {},
+) {
   const directory = assessmentRunDirectory(workspace, assessmentId);
   const metadataPath = path.join(
     directory,
     `${assessmentStageBasename(stage)}.result.json`,
   );
   try {
-    const metadata = JSON.parse(await readFile(metadataPath, "utf8"));
-    if (metadata.stage !== stage) {
-      throw new Error(
-        `Assessment spool metadata does not match stage '${stage}'.`,
-      );
-    }
+    const metadata = JSON.parse(await readFile(metadataPath, "utf8"));
+    if (metadata.assessment_id !== assessmentId) {
+      return null;
+    }
+    if (metadata.stage !== stage) {
+      throw new Error(
+        `Assessment spool metadata does not match stage '${stage}'.`,
+      );
+    }
+    if (
+      expectedHeadRevision &&
+      metadata.observed_head_revision !== expectedHeadRevision
+    ) {
+      return null;
+    }
+    if (
+      expectedSourceRevision &&
+      metadata.source_revision !== expectedSourceRevision
+    ) {
+      return null;
+    }
     const expectedReportFile = `${assessmentStageBasename(stage)}.md`;
     if (metadata.report_file !== expectedReportFile) {
       throw new Error(
@@ -89,7 +111,78 @@ export async function loadAssessmentStageResult(
     if (error?.code === "ENOENT") return null;
     throw error;
   }
-}
+}
+
+export async function persistAssessmentStageSession(
+  workspace,
+  assessmentId,
+  stage,
+  sessionId,
+  { sourceRevision, targetHeadRevision } = {},
+) {
+  const normalizedSessionId = String(sessionId || "").trim();
+  if (!normalizedSessionId) {
+    throw new Error(`Assessment stage '${stage}' returned an empty session id.`);
+  }
+  const directory = assessmentRunDirectory(workspace, assessmentId);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const checkpoint = {
+    assessment_id: assessmentId,
+    stage,
+    agent_session_id: normalizedSessionId,
+    source_revision: String(sourceRevision || "").trim() || null,
+    target_head_revision: String(targetHeadRevision || "").trim() || null,
+  };
+  await atomicWrite(
+    assessmentStageSessionPath(directory, stage),
+    `${JSON.stringify(checkpoint, null, 2)}\n`,
+  );
+  return checkpoint;
+}
+
+export async function loadAssessmentStageSession(
+  workspace,
+  assessmentId,
+  stage,
+  { expectedHeadRevision, expectedSourceRevision } = {},
+) {
+  const directory = assessmentRunDirectory(workspace, assessmentId);
+  try {
+    const checkpoint = JSON.parse(
+      await readFile(assessmentStageSessionPath(directory, stage), "utf8"),
+    );
+    if (checkpoint.assessment_id !== assessmentId) {
+      return null;
+    }
+    if (checkpoint.stage !== stage) {
+      throw new Error(
+        `Assessment session checkpoint does not match stage '${stage}'.`,
+      );
+    }
+    if (
+      expectedHeadRevision &&
+      checkpoint.target_head_revision !== expectedHeadRevision
+    ) {
+      return null;
+    }
+    if (
+      expectedSourceRevision &&
+      checkpoint.source_revision !== expectedSourceRevision
+    ) {
+      return null;
+    }
+    const sessionId = String(checkpoint.agent_session_id || "").trim();
+    if (!sessionId) {
+      throw new Error(
+        `Assessment session checkpoint for '${stage}' has no session id.`,
+      );
+    }
+    return sessionId;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
 
 export async function removeAssessmentStageResult(
   workspace,
@@ -112,7 +205,11 @@ export async function removeAssessmentStageResult(
   );
 }
 
-export async function assessmentStageResults(workspace, assessmentId) {
+export async function assessmentStageResults(
+  workspace,
+  assessmentId,
+  { expectedHeadRevision, expectedSourceRevision } = {},
+) {
   const directory = assessmentRunDirectory(workspace, assessmentId);
   let entries;
   try {
@@ -128,11 +225,12 @@ export async function assessmentStageResults(workspace, assessmentId) {
         const metadata = JSON.parse(
           await readFile(path.join(directory, entry), "utf8"),
         );
-        return loadAssessmentStageResult(
-          workspace,
-          assessmentId,
-          metadata.stage,
-        );
+        return loadAssessmentStageResult(
+          workspace,
+          assessmentId,
+          metadata.stage,
+          { expectedHeadRevision, expectedSourceRevision },
+        );
       }),
   );
   return results
@@ -144,7 +242,10 @@ export async function prepareLocalAssessmentAssignment(workspace, assignment) {
   const prompt = String(assignment.prompt_markdown || "");
   if (!prompt.includes(LOCAL_REPORTS_MARKER)) return assignment;
   const reports = (
-    await assessmentStageResults(workspace, assignment.assessment_id)
+    await assessmentStageResults(workspace, assignment.assessment_id, {
+      expectedHeadRevision: assignment.target_head_revision,
+      expectedSourceRevision: assignment.source_revision,
+    })
   ).filter((result) => result.stage !== "synthesis");
   if (!reports.length) {
     throw new Error(
@@ -176,19 +277,71 @@ export async function prepareLocalAssessmentAssignment(workspace, assignment) {
   };
 }
 
-export async function assessmentCompletionBundle(
-  workspace,
-  assessmentId,
-  synthesisResult,
-) {
+export async function assessmentCompletionBundle(
+  workspace,
+  assessmentId,
+  synthesisResult,
+  { expectedSourceRevision } = {},
+) {
   const reports = (
-    await assessmentStageResults(workspace, assessmentId)
+    await assessmentStageResults(workspace, assessmentId, {
+      expectedHeadRevision: synthesisResult.observed_head_revision,
+      expectedSourceRevision,
+    })
   ).filter((result) => result.stage !== "synthesis");
   return {
     ...assessmentResultPayload(synthesisResult),
     reports: reports.map(assessmentResultPayload),
-  };
-}
+  };
+}
+
+export async function archiveCompletedAssessment(
+  workspace,
+  assessmentId,
+  assignment,
+  synthesisResult,
+) {
+  const bundle = await assessmentCompletionBundle(
+    workspace,
+    assessmentId,
+    synthesisResult,
+    { expectedSourceRevision: assignment.source_revision },
+  );
+  const archiveDirectory = assessmentArchiveDirectory(workspace);
+  const isUpdate = assignment.is_assessment_update === true;
+  const target = isUpdate
+    ? path.join(
+        archiveDirectory,
+        "changes",
+        `${assessmentChangeName(assignment, synthesisResult, assessmentId)}.md`,
+      )
+    : path.join(archiveDirectory, "assessment.md");
+  const heading = isUpdate
+    ? "# Workspace Assessment Change Log"
+    : "# Workspace Assessment";
+  const stageReports = [...bundle.reports, assessmentResultPayload(synthesisResult)]
+    .map(
+      (report) =>
+        `## ${assessmentStageTitle(report.stage, report.report_markdown)}\n\n${nestedStageReport(report.report_markdown)}`,
+    )
+    .join("\n\n");
+  const content = [
+    heading,
+    "",
+    `- Inventory revision: \`${assignment.source_revision || "not available"}\``,
+    `- Git commit: \`${synthesisResult.observed_head_revision || "not available"}\``,
+    "",
+    stageReports,
+    "",
+  ].join("\n");
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await atomicWrite(target, content);
+  await rm(assessmentRunDirectory(workspace, assessmentId), {
+    recursive: true,
+    force: true,
+  });
+  return target;
+}
 
 export function assessmentCheckpointPayload(result) {
   return {
@@ -226,14 +379,59 @@ function validateLocalAssessmentResult(assignment, result) {
   }
 }
 
-function assessmentStageBasename(stage) {
+function assessmentStageBasename(stage) {
   const slug =
     String(stage)
       .replace(/[^a-zA-Z0-9_-]+/g, "-")
       .replace(/^-+|-+$/g, "")
       .slice(0, 64) || "stage";
   return `${slug}-${sha256(String(stage)).slice(0, 12)}`;
-}
+}
+
+function assessmentStageTitle(stage, markdown) {
+  const stageKey = String(stage || "");
+  let namedStage = null;
+  let label = "";
+  if (stageKey.startsWith("capability:")) {
+    label = "Capability";
+    namedStage = String(markdown || "").match(/^### Capability:\s*(.+?)\s*$/m);
+  } else if (stageKey.startsWith("compliance:")) {
+    label = "Compliance";
+    namedStage = String(markdown || "").match(
+      /^### Compliance Framework:\s*(.+?)\s*$/m,
+    );
+  }
+  if (namedStage) {
+    return `${label} — ${namedStage[1].trim()}`;
+  }
+  return String(stage || "assessment")
+    .replace(/[:_-]+/g, " ")
+    .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+function nestedStageReport(markdown) {
+  return String(markdown || "")
+    .trim()
+    .replace(/^# Assessment Stage:[^\n]*\n+/i, "")
+    .replace(/^\s*-\s+State:\s*.*\n?/gm, "")
+    .replace(/^(#{2,5}) /gm, "#$1 ");
+}
+
+function assessmentChangeName(assignment, synthesisResult, assessmentId) {
+  const headRevision = String(synthesisResult.observed_head_revision || "")
+    .trim()
+    .toLowerCase();
+  if (/^[a-f0-9]{7,64}$/.test(headRevision)) {
+    return headRevision.slice(0, 16);
+  }
+  return sha256(
+    String(assignment.source_revision || assessmentId),
+  ).slice(0, 16);
+}
+
+function assessmentStageSessionPath(directory, stage) {
+  return path.join(directory, `${assessmentStageBasename(stage)}.session.json`);
+}
 
 function sha256(value) {
   return createHash("sha256").update(value).digest("hex");

package/src/codex-app-server.mjs

@@ -217,8 +217,9 @@ export function launchCodexAppServer({
               model: profile.model || null,
               ephemeral: false,
             });
-        threadId = threadResult.thread.id;
-        callbacks.onEvent?.({ type: "thread.started", thread_id: threadId });
+        threadId = threadResult.thread.id;
+        await callbacks.onSession?.(threadId);
+        callbacks.onEvent?.({ type: "thread.started", thread_id: threadId });
         const turnResult = await request("turn/start", {
           threadId,
           input: [{ type: "text", text: prompt }],

package/src/connection.mjs

@@ -1,13 +1,19 @@
 const PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH = 2_000;
 const TRUNCATED_FAILURE_SUFFIX = "\n… [truncated by EngineerOS connector]";
 
-export function describeWebSocketError(event) {
+export function describeWebSocketError(event) {
   return (
     event?.error?.message ||
     event?.message ||
     "The WebSocket connection failed without providing an error detail."
   );
-}
+}
+
+export function sendConnectionMessage(activeSocket, connection, message) {
+  if (activeSocket !== connection || connection.readyState !== 1) return false;
+  connection.send(JSON.stringify(message));
+  return true;
+}
 
 export function protocolFailureMessage(error) {
   const raw = error instanceof Error ? error.message : String(error ?? "");

package/src/runner.mjs

@@ -361,11 +361,12 @@ export function parseVerificationReport(
   });
 }
 
-export async function executeWorkspaceAssessment(
-  assignment,
-  config,
-  callbacks,
-) {
+export async function executeWorkspaceAssessment(
+  assignment,
+  config,
+  callbacks,
+  { previousSessionId } = {},
+) {
   const execution = workspaceAssessmentExecution(assignment);
   const assessmentAcpContext =
     config.agent_protocol === "acp"
@@ -415,13 +416,16 @@ export async function executeWorkspaceAssessment(
           assignment.target_head_revision,
         )
       : { changedFiles: [], markdown: null };
-  const prompt = changeImpact.markdown
-    ? execution.prompt.replace(
-        "<!-- ENGINEEROS_CHANGE_IMPACT -->",
-        changeImpact.markdown,
-      )
-    : execution.prompt;
-  const controller = launchAssessmentAgent(prompt);
+  const prompt = changeImpact.markdown
+    ? execution.prompt.replace(
+        "<!-- ENGINEEROS_CHANGE_IMPACT -->",
+        changeImpact.markdown,
+      )
+    : execution.prompt;
+  const controller = launchAssessmentAgent(
+    previousSessionId ? assessmentContinuationPrompt(prompt) : prompt,
+    previousSessionId,
+  );
   let completed = await controller.completed;
   const recovered = await recoverAssessmentStageOutput({
     completed,
@@ -1099,6 +1103,38 @@ export function takeWorkspaceAssessmentWave(queue, activeCount, limit) {
   return wave;
 }
 
+export function assessmentContinuationPrompt(originalPrompt) {
+  return [
+    "# Continue Interrupted EngineerOS Assessment",
+    "",
+    "Continue the existing assessment task in this agent session from its last completed step.",
+    "Do not restart repository inspection or repeat work already present in the session context.",
+    "Finish and return the complete structured Markdown report required by the original stage contract.",
+    "If the provider could not restore prior context, use the original contract below to complete only the missing work.",
+    "",
+    "## Original Stage Contract",
+    "",
+    String(originalPrompt || "").trim(),
+  ].join("\n");
+}
+
+export function isRecoverableAssessmentAgentFailure(error) {
+  const message = String(error?.message || error || "").toLowerCase();
+  return [
+    "acp connection closed",
+    "acp agent ended the task with an error",
+    "app-server connection closed",
+    "app server connection closed",
+    "connection reset",
+    "econnreset",
+    "broken pipe",
+    "service unavailable",
+    "too many requests",
+    "rate limit",
+    "overloaded",
+  ].some((fragment) => message.includes(fragment));
+}
+
 export function workspaceAssessmentWorkerLimit(value) {
   const parsed = Number(value ?? DEFAULT_ASSESSMENT_WORKERS);
   if (
@@ -1674,8 +1710,10 @@ function launchCodexProcess(
   child.stdin.end(prompt);
   let output = "";
   let buffer = "";
-  let finalMessage = "";
-  let sessionId = previousSessionId || "";
+  let finalMessage = "";
+  let sessionId = previousSessionId || "";
+  let sessionCheckpoint = Promise.resolve();
+  let sessionCheckpointError;
   child.stdout.setEncoding("utf8");
   child.stdout.on("data", (chunk) => {
     output += chunk;
@@ -1686,12 +1724,17 @@ function launchCodexProcess(
       if (!line.trim()) continue;
       try {
         const event = JSON.parse(line);
-        if (
-          event.type === "thread.started" &&
-          typeof event.thread_id === "string"
-        ) {
-          sessionId = event.thread_id;
-        }
+        if (
+          event.type === "thread.started" &&
+          typeof event.thread_id === "string"
+        ) {
+          sessionId = event.thread_id;
+          sessionCheckpoint = Promise.resolve()
+            .then(() => callbacks.onSession?.(sessionId))
+            .catch((error) => {
+              sessionCheckpointError = error;
+            });
+        }
         if (
           event.type === "item.completed" &&
           event.item?.type === "agent_message" &&
@@ -1718,17 +1761,20 @@ function launchCodexProcess(
   });
   const completed = new Promise((resolve, reject) => {
     child.once("error", reject);
-    child.once("close", (code) => {
-      if (code === 0 && sessionId)
-        resolve({ output: output.slice(-20_000), finalMessage, sessionId });
-      else if (code === 0)
-        reject(
-          new Error(
-            "Agent completed without announcing a resumable session id.",
-          ),
-        );
-      else reject(new Error(codexFailureMessage(output, code)));
-    });
+    child.once("close", (code) => {
+      void sessionCheckpoint.then(() => {
+        if (sessionCheckpointError) reject(sessionCheckpointError);
+        else if (code === 0 && sessionId)
+          resolve({ output: output.slice(-20_000), finalMessage, sessionId });
+        else if (code === 0)
+          reject(
+            new Error(
+              "Agent completed without announcing a resumable session id.",
+            ),
+          );
+        else reject(new Error(codexFailureMessage(output, code)));
+      });
+    });
   });
   return { child, completed };
 }