@engineeros/connector 0.15.0 → 0.15.2

package/README.md

@@ -47,7 +47,9 @@ 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.0` uses half of the locally available CPU parallelism by default, capped at eight assessment workers, and supports an explicit `--assessment-workers` override from 1 to 32. 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 gives an incomplete report one bounded correction turn instead of repeatedly restarting it. 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 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.1` uses half of the locally available CPU parallelism by default, capped at eight assessment workers, and supports an explicit `--assessment-workers` override from 1 to 32. 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.
+
+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.
 
 Override the automatic assessment worker count when pairing (saved for that workspace) or starting the connector (for that process only):
 

package/bin/engineeros-connector.mjs

@@ -13,6 +13,7 @@ import {
 } from "../src/config.mjs";
 import {
   ASSESSMENT_RESULT_TIMEOUT_MS,
+  attachAssessmentRejectionCorrection,
   assessmentWorkerSnapshots,
   assessmentInactivityFailure,
   assessmentProgressMessage,
@@ -26,6 +27,7 @@ import {
   requeueInterruptedAssessment,
   stopProcess,
   submitAssessmentResultWithRetry,
+  submitAssessmentWithValidationRepair,
   takeWorkspaceAssessmentWave,
   workspaceAssessmentWorkerLimit,
   workspaceSnapshot,
@@ -720,6 +722,46 @@ async function executeAssessment(assignment, assessmentState) {
       );
     }
   }, 15_000);
+  const assessmentAgentCallbacks = {
+    onController: (controller) => {
+      if (isActiveAssessment()) assessmentState.controller = controller;
+    },
+    onProcess: (child) => {
+      if (isActiveAssessment()) {
+        assessmentState.child = child;
+        agentProcessStarted = true;
+        if (assessmentState.phase !== "correcting") {
+          assessmentState.phase = "running";
+          reportProgress("Connected agent process started");
+        }
+        assessmentState.lastActivityAt = Date.now();
+      }
+    },
+    onEvent: (event) => {
+      assessmentState.lastActivityAt = Date.now();
+      assessmentState.eventCount += 1;
+      const message = assessmentProgressMessage(event);
+      if (message) reportProgress(message);
+    },
+  };
+  const attachStoredCorrection = (candidate, preparedAssignment) =>
+    attachAssessmentRejectionCorrection(
+      candidate,
+      preparedAssignment,
+      config,
+      assessmentAgentCallbacks,
+      {
+        draftPath: path
+          .join(
+            ".engineeros",
+            "assessments",
+            String(assessmentId),
+            candidate.report_file,
+          )
+          .split(path.sep)
+          .join("/"),
+      },
+    );
   try {
     if (assignment.assessment_mode === "incremental") {
       progress = 15;
@@ -735,28 +777,14 @@ async function executeAssessment(assignment, assessmentState) {
       stage,
     );
     if (result) {
+      attachStoredCorrection(result, preparedAssignment);
       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);
-        },
-      });
+      result = await executeWorkspaceAssessment(
+        preparedAssignment,
+        config,
+        assessmentAgentCallbacks,
+      );
       await persistAssessmentStageResult(
         config.workspace,
         assessmentId,
@@ -801,44 +829,53 @@ async function executeAssessment(assignment, assessmentState) {
           );
         },
       });
-    const deliveryPayload =
-      stage === "synthesis"
-        ? await assessmentCompletionBundle(
+    const repairedDelivery = await submitAssessmentWithValidationRepair(
+      result,
+      {
+        submit: deliverResult,
+        payloadFor: (candidate) =>
+          stage === "synthesis"
+            ? assessmentCompletionBundle(
+                config.workspace,
+                assessmentId,
+                candidate,
+              )
+            : assessmentCheckpointPayload(candidate),
+        rejectionFor: (response) =>
+          describeRejectedResponse(response, "the assessment"),
+        correct: async (candidate, rejection) => {
+          agentCompleted = false;
+          assessmentState.phase = "correcting";
+          assessmentState.lastMessage = "Correcting a rejected stage result";
+          if (!candidate.correctAfterRejection) {
+            throw new Error(
+              `${rejection} The connector could not start the required agent correction.`,
+            );
+          }
+          return candidate.correctAfterRejection(rejection);
+        },
+        onCorrected: async (candidate) => {
+          await removeAssessmentStageResult(
             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),
-      );
-    }
+            stage,
+          );
+          const persisted = await persistAssessmentStageResult(
+            config.workspace,
+            assessmentId,
+            preparedAssignment,
+            candidate,
+          );
+          attachStoredCorrection(persisted, preparedAssignment);
+          agentCompleted = true;
+          assessmentState.phase = "delivering";
+          assessmentState.lastMessage = "Delivering corrected stage result";
+          return persisted;
+        },
+      },
+    );
+    result = repairedDelivery.result;
+    const response = repairedDelivery.response;
     if (!response.ok) {
       throw new Error(
         await describeRejectedResponse(response, "the assessment"),

package/package.json

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

package/src/assessment-spool.mjs

@@ -43,6 +43,7 @@ export async function persistAssessmentStageResult(
     change_impact_markdown: result.change_impact_markdown ?? null,
     model: result.model ?? null,
     usage: result.usage ?? null,
+    agent_session_id: result.agent_session_id ?? null,
   };
   await atomicWrite(path.join(directory, reportName), `${report}\n`);
   await atomicWrite(

package/src/runner.mjs

@@ -33,6 +33,7 @@ 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_RESULT_TIMEOUT_MS = 120_000;
+export const MAX_REPEATED_ASSESSMENT_VALIDATION_FAILURES = 3;
 export const MAX_ASSESSMENT_WORKERS = 32;
 export const MAX_AUTOMATIC_ASSESSMENT_WORKERS = 8;
 const EXCLUDED_DIRECTORIES = new Set([
@@ -462,39 +463,116 @@ export async function executeWorkspaceAssessment(
       change_impact_markdown: changeImpact.markdown,
       model: turn.model ?? config.agent_protocol ?? "coding-agent",
       usage: turn.usage ?? null,
+      agent_session_id: turn.sessionId ?? null,
     };
   };
   const result = await buildResult(completed, recovered.report);
-  if (!recovered.correctionUsed) {
-    Object.defineProperty(result, "correctAfterRejection", {
-      enumerable: false,
-      value: async (validationMessage) => {
-        callbacks.onEvent?.({
-          type: "assessment.output_correction",
-          message: "The Agent is correcting the rejected stage report",
-        });
-        const correction = launchAssessmentAgent(
-          assessmentRejectionCorrectionPrompt(
-            validationMessage,
-            execution.requiredOutputHeading,
-          ),
-          completed.sessionId,
-        );
-        const corrected = await correction.completed;
-        const correctedReport = normalizeAgentStructuredOutput(
-          corrected.finalMessage,
-          execution.requiredOutputHeading,
+  attachAssessmentRejectionCorrection(result, assignment, config, callbacks, {
+    previousSessionId: completed.sessionId,
+    buildResult,
+  });
+  return result;
+}
+
+export function attachAssessmentRejectionCorrection(
+  result,
+  assignment,
+  config,
+  callbacks,
+  { previousSessionId = result.agent_session_id, draftPath, buildResult } = {},
+) {
+  const execution = workspaceAssessmentExecution(assignment);
+  const assessmentAcpContext =
+    config.agent_protocol === "acp"
+      ? {
+          persistentAcp: true,
+          sessionKey: `assessment:${assignment.assessment_id}:${assignment.stage}`,
+        }
+      : undefined;
+  Object.defineProperty(result, "correctAfterRejection", {
+    enumerable: false,
+    value: async (validationMessage) => {
+      callbacks.onEvent?.({
+        type: "assessment.output_correction",
+        message: "The Agent is correcting the rejected stage report",
+      });
+      const draftInstruction = draftPath
+        ? [
+            "",
+            `The authoritative draft is stored at \`${draftPath}\`. Read that file before making the requested correction.`,
+          ].join("\n")
+        : "";
+      const correctionPrompt = `${assessmentRejectionCorrectionPrompt(validationMessage, execution.requiredOutputHeading)}${draftInstruction}`;
+      const launchCorrection = (prompt, sessionId) => {
+        const controller = launchAgentProcess(
+          config.workspace,
+          prompt,
+          execution.sandboxMode,
+          config,
+          callbacks,
+          execution.profile,
+          sessionId,
+          assessmentAcpContext,
         );
+        callbacks.onController?.(controller);
+        callbacks.onProcess?.(controller.child);
+        return controller;
+      };
+      let corrected = await launchCorrection(
+        correctionPrompt,
+        previousSessionId,
+      ).completed;
+      const recovered = await recoverAssessmentStageOutput({
+        completed: corrected,
+        prompt: correctionPrompt,
+        requiredOutputHeading: execution.requiredOutputHeading,
+        retry: async (formatPrompt, sessionId) => {
+          callbacks.onEvent?.({
+            type: "assessment.output_correction",
+            message: "The Agent is formatting the corrected stage report",
+          });
+          return launchCorrection(formatPrompt, sessionId).completed;
+        },
+      });
+      corrected = recovered.completed;
+      const correctedReport = recovered.report;
+      if (buildResult) {
         return buildResult(
           {
             ...corrected,
-            usage: mergeTokenUsage(completed.usage, corrected.usage),
+            usage: mergeTokenUsage(result.usage, corrected.usage),
           },
           correctedReport,
         );
-      },
-    });
-  }
+      }
+      const endingRevision = await run(
+        "git",
+        ["rev-parse", "HEAD"],
+        config.workspace,
+        { allowFailure: true },
+      );
+      const endingHead =
+        endingRevision.code === 0
+          ? endingRevision.stdout.trim().slice(0, 128)
+          : null;
+      if (
+        assignment.target_head_revision &&
+        endingHead !== assignment.target_head_revision
+      ) {
+        throw new Error(
+          "The Git commit changed before assessment correction. Refresh the workspace inventory and assess the new commit.",
+        );
+      }
+      return {
+        ...result,
+        report_markdown: correctedReport,
+        observed_head_revision: endingHead,
+        model: corrected.model ?? result.model,
+        usage: mergeTokenUsage(result.usage, corrected.usage),
+        agent_session_id: corrected.sessionId ?? previousSessionId ?? null,
+      };
+    },
+  });
   return result;
 }
 
@@ -1112,6 +1190,36 @@ export async function submitAssessmentResultWithRetry(
   );
 }
 
+export async function submitAssessmentWithValidationRepair(
+  initialResult,
+  {
+    submit,
+    payloadFor,
+    rejectionFor,
+    correct,
+    onCorrected = async () => {},
+    maxRepeatedFailures = MAX_REPEATED_ASSESSMENT_VALIDATION_FAILURES,
+  },
+) {
+  let result = initialResult;
+  let response = await submit(await payloadFor(result));
+  const rejectionCounts = new Map();
+  while (response.status === 422) {
+    const rejection = await rejectionFor(response);
+    const rejectionCount = (rejectionCounts.get(rejection) || 0) + 1;
+    rejectionCounts.set(rejection, rejectionCount);
+    if (rejectionCount > maxRepeatedFailures) {
+      throw new Error(
+        `${rejection} The Agent repeated this unresolved validation failure ${maxRepeatedFailures} times; the connector retained the latest local report for retry.`,
+      );
+    }
+    result = await correct(result, rejection);
+    result = (await onCorrected(result, rejection)) || result;
+    response = await submit(await payloadFor(result));
+  }
+  return { result, response };
+}
+
 function isTransientAssessmentResultResponse(response) {
   return (
     response.status === 408 ||