@engineeros/connector 0.15.2 → 0.16.0

package/src/runner.mjs

@@ -1,2121 +1,2124 @@
-import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import {
-  lstat,
-  mkdir,
-  readFile,
-  readdir,
-  stat,
-  writeFile,
-} from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { promisify } from "node:util";
-import { deflateRaw, gzip } from "node:zlib";
-import { inspectAcpExecutionProfiles, launchAcpAgent } from "./acp-client.mjs";
-import {
-  inspectCodexExecutionProfiles,
-  launchCodexAppServer,
-} from "./codex-app-server.mjs";
-import {
-  buildAgentHarnessPrompt,
-  normalizeAgentStructuredOutput,
-} from "./agent-harness.mjs";
-
-const deflate = promisify(deflateRaw);
-const gzipBuffer = promisify(gzip);
-const MAX_ARCHIVE_BYTES = 25_000_000;
-const MAX_EVIDENCE_BYTES = 24_000_000;
-const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
-const MAX_EVIDENCE_FILES = 5_000;
-const MAX_INVENTORY_FILES = 100_000;
-const MAX_COMPRESSED_INVENTORY_BYTES = 10_000_000;
-const EVIDENCE_POLICY_VERSION = "workspace-evidence-v1";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { deflateRaw, gzip } from "node:zlib";
+import { inspectAcpExecutionProfiles, launchAcpAgent } from "./acp-client.mjs";
+import {
+  inspectCodexExecutionProfiles,
+  launchCodexAppServer,
+} from "./codex-app-server.mjs";
+import {
+  buildAgentHarnessPrompt,
+  normalizeAgentStructuredOutput,
+} from "./agent-harness.mjs";
+
+const deflate = promisify(deflateRaw);
+const gzipBuffer = promisify(gzip);
+const MAX_ARCHIVE_BYTES = 25_000_000;
+const MAX_EVIDENCE_BYTES = 24_000_000;
+const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_EVIDENCE_FILES = 5_000;
+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_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([
-  ".agents",
-  ".claude",
-  ".codex",
-  ".engineeros",
-  ".forge",
-  ".gemini",
-  ".git",
-  ".next",
-  ".pytest_cache",
-  ".ruff_cache",
-  ".venv",
-  "__pycache__",
-  "build",
-  "coverage",
-  "dist",
-  "node_modules",
-  "target",
-  "vendor",
-]);
-const EXCLUDED_PATH_PREFIXES = [".github/skills/"];
-const EXCLUDED_FILE_EXTENSIONS = new Set([
-  ".7z",
-  ".a",
-  ".bin",
-  ".class",
-  ".dll",
-  ".dylib",
-  ".exe",
-  ".gz",
-  ".jar",
-  ".lib",
-  ".o",
-  ".obj",
-  ".pyc",
-  ".pyo",
-  ".rar",
-  ".so",
-  ".tar",
-  ".tgz",
-  ".war",
-  ".zip",
-]);
-const LOCK_FILE_NAMES = new Set([
-  "cargo.lock",
-  "composer.lock",
-  "go.sum",
-  "package-lock.json",
-  "pnpm-lock.yaml",
-  "poetry.lock",
-  "uv.lock",
-  "yarn.lock",
-]);
-const ENTRYPOINT_NAMES = new Set([
-  "app.py",
-  "index.ts",
-  "index.tsx",
-  "main.py",
-  "main.ts",
-  "main.tsx",
-  "manage.py",
-  "server.py",
-]);
-const REPOSITORY_CONFIGURATION_NAMES = new Set([
-  ".dockerignore",
-  ".editorconfig",
-  ".gitattributes",
-  ".gitignore",
-  "lerna.json",
-  "makefile",
-  "nx.json",
-  "turbo.json",
-]);
-const CODE_EXTENSIONS = new Set([
-  ".c",
-  ".cpp",
-  ".cs",
-  ".go",
-  ".h",
-  ".java",
-  ".js",
-  ".jsx",
-  ".mjs",
-  ".php",
-  ".py",
-  ".rb",
-  ".rs",
-  ".sql",
-  ".ts",
-  ".tsx",
-]);
-const CODE_MARKERS = new Set([
-  "cargo.toml",
-  "composer.json",
-  "go.mod",
-  "package.json",
-  "pom.xml",
-  "pyproject.toml",
-  "requirements.txt",
-]);
-
-export async function executeAssignment(assignment, config, callbacks) {
-  const execution = connectorExecution(assignment);
-  const runWorkspace = await prepareRunWorkspace(
-    config.workspace,
-    assignment.run_id,
-    assignment.base_revision,
-  );
-  const controller = launchAgentProcess(
-    runWorkspace,
-    execution.prompt,
-    execution.sandboxMode,
-    config,
-    callbacks,
-    execution.profile,
-    undefined,
-    { runId: assignment.run_id },
-  );
-  callbacks.onProcess?.(controller.child);
-  const implementation = await controller.completed;
-  const changedFiles = await changedFilePaths(runWorkspace);
-  if (!changedFiles.length)
-    throw new Error("Agent completed without changing any files.");
-  const committed = await commitRunChange(
-    runWorkspace,
-    assignment.base_revision,
-    assignment.run_id,
-  );
-  const verificationHeading = "# Verification Report";
-  const verifier = launchAgentProcess(
-    runWorkspace,
-    buildAgentHarnessPrompt({
-      agentRole: "verification",
-      prompt: verificationPrompt(
-        assignment,
-        committed.revision,
-        committed.changedFiles,
-      ),
-      sandboxMode: "read-only",
-      requiredOutputHeading: verificationHeading,
-    }),
-    "read-only",
-    config,
-    callbacks,
-    execution.profile,
-  );
-  callbacks.onProcess?.(verifier.child);
-  const verification = await verifier.completed;
-  const verificationReport = normalizeAgentStructuredOutput(
-    verification.finalMessage,
-    verificationHeading,
-  );
-  const proofEvidence = parseVerificationReport(
-    verificationReport,
-    assignment.proof_checks,
-    config.connector_id,
-    assignment.run_id,
-  );
-  return {
-    head_revision: committed.revision,
-    repository_locator: assignment.repository_locator,
-    external_reference: `connector:${config.connector_id}/run:${assignment.run_id}`,
-    diff_patch: committed.diffPatch,
-    changed_files: committed.changedFiles,
-    proof_evidence: proofEvidence,
-    verification_report: verificationReport,
-    usage: [
-      {
-        request_type: "goal_implementation",
-        model: implementation.model,
-        ...implementation.usage,
-      },
-      {
-        request_type: "goal_verification",
-        model: verification.model,
-        ...verification.usage,
-      },
-    ].filter((entry) => entry.total_tokens > 0),
-  };
-}
-
-export async function applyAcceptedChange(
-  workspace,
-  baseRevision,
-  headRevision,
-) {
-  const current = await run("git", ["rev-parse", "HEAD"], workspace, {
-    allowFailure: true,
-  });
-  if (current.code !== 0) {
-    return {
-      applied: false,
-      reason: "The connected workspace is not a Git repository.",
-    };
-  }
-  const currentHead = current.stdout.trim();
-  const alreadyApplied = await run(
-    "git",
-    ["merge-base", "--is-ancestor", headRevision, currentHead],
-    workspace,
-    { allowFailure: true },
-  );
-  if (alreadyApplied.code === 0)
-    return { applied: true, revision: currentHead };
-  const status = await run("git", ["status", "--porcelain"], workspace);
-  if (status.stdout.trim()) {
-    return {
-      applied: false,
-      reason: `The connected workspace has uncommitted changes. Apply accepted commit ${headRevision} after preserving them.`,
-    };
-  }
-  if (currentHead !== baseRevision) {
-    return {
-      applied: false,
-      reason: `The connected branch moved from frozen base ${baseRevision} to ${currentHead}. Apply accepted commit ${headRevision} with git cherry-pick.`,
-    };
-  }
-  const applied = await run("git", ["cherry-pick", headRevision], workspace, {
-    allowFailure: true,
-  });
-  if (applied.code !== 0) {
-    await run("git", ["cherry-pick", "--abort"], workspace, {
-      allowFailure: true,
-    });
-    return {
-      applied: false,
-      reason: `The accepted commit ${headRevision} could not be applied cleanly. Apply it manually with git cherry-pick.`,
-    };
-  }
-  const integrated = await run("git", ["rev-parse", "HEAD"], workspace);
-  return { applied: true, revision: integrated.stdout.trim() };
-}
-
-async function commitRunChange(workspace, baseRevision, runId) {
-  await run("git", ["add", "-A"], workspace);
-  await run(
-    "git",
-    [
-      "-c",
-      "user.name=EngineerOS Codex",
-      "-c",
-      "user.email=codex@engineeros.local",
-      "commit",
-      "-m",
-      `EngineerOS Goal Run ${runId}`,
-    ],
-    workspace,
-  );
-  const head = await run("git", ["rev-parse", "HEAD"], workspace);
-  const revision = head.stdout.trim();
-  const diff = await run(
-    "git",
-    ["diff", "--binary", baseRevision, revision, "--"],
-    workspace,
-  );
-  const paths = await run(
-    "git",
-    ["diff", "--name-only", "-z", baseRevision, revision, "--"],
-    workspace,
-  );
-  return {
-    revision,
-    diffPatch: diff.stdout,
-    changedFiles: gitPathList(paths.stdout).sort(),
-  };
-}
-
-export function verificationPrompt(assignment, revision, changedFiles) {
-  const checks = (assignment.proof_checks ?? [])
-    .map(
-      (proof, index) =>
-        `## Proof ${index + 1}\n- Check: ${proof.check ?? ""}\n- Expected: ${proof.expected ?? ""}`,
-    )
-    .join("\n\n");
-  return `# EngineerOS Connected Verification
-
-Independently verify the frozen Goal at Git commit \`${revision}\`. Do not modify files. Run the commands or inspections needed for every Proof item, and check the Goal boundaries and constraints in the supplied packet.
-
-Changed files:
-${changedFiles.map((item) => `- \`${item}\``).join("\n")}
-
-${checks}
-
-Return structured Markdown only, with exactly one section per Proof:
-
-## Proof 1
-- Status: passed or failed
-- Exit code: integer or none
-- Evidence: concise observed output and command
-
-Do not claim a Proof passed unless you observed it directly.`;
-}
-
-export function parseVerificationReport(
-  report,
-  proofChecks,
-  connectorId,
-  runId,
-) {
-  if (!report?.trim())
-    throw new Error("Codex returned no connected verification report.");
-  return (proofChecks ?? []).map((_, index) => {
-    const start = new RegExp(`^## Proof ${index + 1}\\s*$`, "im").exec(report);
-    const tail = start ? report.slice(start.index + start[0].length) : "";
-    const section = tail.split(/^## Proof \d+\s*$/im)[0] ?? "";
-    const status =
-      /^- Status:\s*(passed|failed)\s*$/im.exec(section)?.[1] ?? "failed";
-    const exitValue =
-      /^- Exit code:\s*(\d+|none)\s*$/im.exec(section)?.[1] ?? "none";
-    const evidence = /^- Evidence:\s*(.+)$/im.exec(section)?.[1]?.trim();
-    return {
-      proof_index: index,
-      status,
-      verifier_type: "agent_reported",
-      verifier_identity: "Connected Codex CLI verifier",
-      locator: `connector:${connectorId}/run:${runId}#proof-${index + 1}`,
-      output_excerpt:
-        evidence ||
-        "The connected verifier did not provide evidence for this Proof.",
-      exit_code: exitValue === "none" ? null : Number(exitValue),
-    };
-  });
-}
-
+export const MIN_ASSESSMENT_WORKERS = 3;
+export const MAX_ASSESSMENT_WORKERS = 8;
+export const DEFAULT_ASSESSMENT_WORKERS = MIN_ASSESSMENT_WORKERS;
+const EXCLUDED_DIRECTORIES = new Set([
+  ".agents",
+  ".claude",
+  ".codex",
+  ".engineeros",
+  ".forge",
+  ".gemini",
+  ".git",
+  ".next",
+  ".pytest_cache",
+  ".ruff_cache",
+  ".venv",
+  "__pycache__",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "target",
+  "vendor",
+]);
+const EXCLUDED_PATH_PREFIXES = [".github/skills/"];
+const EXCLUDED_FILE_EXTENSIONS = new Set([
+  ".7z",
+  ".a",
+  ".bin",
+  ".class",
+  ".dll",
+  ".dylib",
+  ".exe",
+  ".gz",
+  ".jar",
+  ".lib",
+  ".o",
+  ".obj",
+  ".pyc",
+  ".pyo",
+  ".rar",
+  ".so",
+  ".tar",
+  ".tgz",
+  ".war",
+  ".zip",
+]);
+const LOCK_FILE_NAMES = new Set([
+  "cargo.lock",
+  "composer.lock",
+  "go.sum",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "poetry.lock",
+  "uv.lock",
+  "yarn.lock",
+]);
+const ENTRYPOINT_NAMES = new Set([
+  "app.py",
+  "index.ts",
+  "index.tsx",
+  "main.py",
+  "main.ts",
+  "main.tsx",
+  "manage.py",
+  "server.py",
+]);
+const REPOSITORY_CONFIGURATION_NAMES = new Set([
+  ".dockerignore",
+  ".editorconfig",
+  ".gitattributes",
+  ".gitignore",
+  "lerna.json",
+  "makefile",
+  "nx.json",
+  "turbo.json",
+]);
+const CODE_EXTENSIONS = new Set([
+  ".c",
+  ".cpp",
+  ".cs",
+  ".go",
+  ".h",
+  ".java",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".php",
+  ".py",
+  ".rb",
+  ".rs",
+  ".sql",
+  ".ts",
+  ".tsx",
+]);
+const CODE_MARKERS = new Set([
+  "cargo.toml",
+  "composer.json",
+  "go.mod",
+  "package.json",
+  "pom.xml",
+  "pyproject.toml",
+  "requirements.txt",
+]);
+
+export async function executeAssignment(assignment, config, callbacks) {
+  const execution = connectorExecution(assignment);
+  const runWorkspace = await prepareRunWorkspace(
+    config.workspace,
+    assignment.run_id,
+    assignment.base_revision,
+  );
+  const controller = launchAgentProcess(
+    runWorkspace,
+    execution.prompt,
+    execution.sandboxMode,
+    config,
+    callbacks,
+    execution.profile,
+    undefined,
+    { runId: assignment.run_id },
+  );
+  callbacks.onProcess?.(controller.child);
+  const implementation = await controller.completed;
+  const changedFiles = await changedFilePaths(runWorkspace);
+  if (!changedFiles.length)
+    throw new Error("Agent completed without changing any files.");
+  const committed = await commitRunChange(
+    runWorkspace,
+    assignment.base_revision,
+    assignment.run_id,
+  );
+  const verificationHeading = "# Verification Report";
+  const verifier = launchAgentProcess(
+    runWorkspace,
+    buildAgentHarnessPrompt({
+      agentRole: "verification",
+      prompt: verificationPrompt(
+        assignment,
+        committed.revision,
+        committed.changedFiles,
+      ),
+      sandboxMode: "read-only",
+      requiredOutputHeading: verificationHeading,
+    }),
+    "read-only",
+    config,
+    callbacks,
+    execution.profile,
+  );
+  callbacks.onProcess?.(verifier.child);
+  const verification = await verifier.completed;
+  const verificationReport = normalizeAgentStructuredOutput(
+    verification.finalMessage,
+    verificationHeading,
+  );
+  const proofEvidence = parseVerificationReport(
+    verificationReport,
+    assignment.proof_checks,
+    config.connector_id,
+    assignment.run_id,
+  );
+  return {
+    head_revision: committed.revision,
+    repository_locator: assignment.repository_locator,
+    external_reference: `connector:${config.connector_id}/run:${assignment.run_id}`,
+    diff_patch: committed.diffPatch,
+    changed_files: committed.changedFiles,
+    proof_evidence: proofEvidence,
+    verification_report: verificationReport,
+    usage: [
+      {
+        request_type: "goal_implementation",
+        model: implementation.model,
+        ...implementation.usage,
+      },
+      {
+        request_type: "goal_verification",
+        model: verification.model,
+        ...verification.usage,
+      },
+    ].filter((entry) => entry.total_tokens > 0),
+  };
+}
+
+export async function applyAcceptedChange(
+  workspace,
+  baseRevision,
+  headRevision,
+) {
+  const current = await run("git", ["rev-parse", "HEAD"], workspace, {
+    allowFailure: true,
+  });
+  if (current.code !== 0) {
+    return {
+      applied: false,
+      reason: "The connected workspace is not a Git repository.",
+    };
+  }
+  const currentHead = current.stdout.trim();
+  const alreadyApplied = await run(
+    "git",
+    ["merge-base", "--is-ancestor", headRevision, currentHead],
+    workspace,
+    { allowFailure: true },
+  );
+  if (alreadyApplied.code === 0)
+    return { applied: true, revision: currentHead };
+  const status = await run("git", ["status", "--porcelain"], workspace);
+  if (status.stdout.trim()) {
+    return {
+      applied: false,
+      reason: `The connected workspace has uncommitted changes. Apply accepted commit ${headRevision} after preserving them.`,
+    };
+  }
+  if (currentHead !== baseRevision) {
+    return {
+      applied: false,
+      reason: `The connected branch moved from frozen base ${baseRevision} to ${currentHead}. Apply accepted commit ${headRevision} with git cherry-pick.`,
+    };
+  }
+  const applied = await run("git", ["cherry-pick", headRevision], workspace, {
+    allowFailure: true,
+  });
+  if (applied.code !== 0) {
+    await run("git", ["cherry-pick", "--abort"], workspace, {
+      allowFailure: true,
+    });
+    return {
+      applied: false,
+      reason: `The accepted commit ${headRevision} could not be applied cleanly. Apply it manually with git cherry-pick.`,
+    };
+  }
+  const integrated = await run("git", ["rev-parse", "HEAD"], workspace);
+  return { applied: true, revision: integrated.stdout.trim() };
+}
+
+async function commitRunChange(workspace, baseRevision, runId) {
+  await run("git", ["add", "-A"], workspace);
+  await run(
+    "git",
+    [
+      "-c",
+      "user.name=EngineerOS Codex",
+      "-c",
+      "user.email=codex@engineeros.local",
+      "commit",
+      "-m",
+      `EngineerOS Goal Run ${runId}`,
+    ],
+    workspace,
+  );
+  const head = await run("git", ["rev-parse", "HEAD"], workspace);
+  const revision = head.stdout.trim();
+  const diff = await run(
+    "git",
+    ["diff", "--binary", baseRevision, revision, "--"],
+    workspace,
+  );
+  const paths = await run(
+    "git",
+    ["diff", "--name-only", "-z", baseRevision, revision, "--"],
+    workspace,
+  );
+  return {
+    revision,
+    diffPatch: diff.stdout,
+    changedFiles: gitPathList(paths.stdout).sort(),
+  };
+}
+
+export function verificationPrompt(assignment, revision, changedFiles) {
+  const checks = (assignment.proof_checks ?? [])
+    .map(
+      (proof, index) =>
+        `## Proof ${index + 1}\n- Check: ${proof.check ?? ""}\n- Expected: ${proof.expected ?? ""}`,
+    )
+    .join("\n\n");
+  return `# EngineerOS Connected Verification
+
+Independently verify the frozen Goal at Git commit \`${revision}\`. Do not modify files. Run the commands or inspections needed for every Proof item, and check the Goal boundaries and constraints in the supplied packet.
+
+Changed files:
+${changedFiles.map((item) => `- \`${item}\``).join("\n")}
+
+${checks}
+
+Return structured Markdown only, with exactly one section per Proof:
+
+## Proof 1
+- Status: passed or failed
+- Exit code: integer or none
+- Evidence: concise observed output and command
+
+Do not claim a Proof passed unless you observed it directly.`;
+}
+
+export function parseVerificationReport(
+  report,
+  proofChecks,
+  connectorId,
+  runId,
+) {
+  if (!report?.trim())
+    throw new Error("Codex returned no connected verification report.");
+  return (proofChecks ?? []).map((_, index) => {
+    const start = new RegExp(`^## Proof ${index + 1}\\s*$`, "im").exec(report);
+    const tail = start ? report.slice(start.index + start[0].length) : "";
+    const section = tail.split(/^## Proof \d+\s*$/im)[0] ?? "";
+    const status =
+      /^- Status:\s*(passed|failed)\s*$/im.exec(section)?.[1] ?? "failed";
+    const exitValue =
+      /^- Exit code:\s*(\d+|none)\s*$/im.exec(section)?.[1] ?? "none";
+    const evidence = /^- Evidence:\s*(.+)$/im.exec(section)?.[1]?.trim();
+    return {
+      proof_index: index,
+      status,
+      verifier_type: "agent_reported",
+      verifier_identity: "Connected Codex CLI verifier",
+      locator: `connector:${connectorId}/run:${runId}#proof-${index + 1}`,
+      output_excerpt:
+        evidence ||
+        "The connected verifier did not provide evidence for this Proof.",
+      exit_code: exitValue === "none" ? null : Number(exitValue),
+    };
+  });
+}
+
 export async function executeWorkspaceAssessment(
   assignment,
   config,
   callbacks,
+  { previousSessionId } = {},
 ) {
-  const execution = workspaceAssessmentExecution(assignment);
-  const assessmentAcpContext =
-    config.agent_protocol === "acp"
-      ? {
-          persistentAcp: true,
-          sessionKey: `assessment:${assignment.assessment_id}:${assignment.stage}`,
-        }
-      : undefined;
-  const launchAssessmentAgent = (turnPrompt, previousSessionId) => {
-    const controller = launchAgentProcess(
-      config.workspace,
-      turnPrompt,
-      execution.sandboxMode,
-      config,
-      callbacks,
-      execution.profile,
-      previousSessionId,
-      assessmentAcpContext,
-    );
-    callbacks.onController?.(controller);
-    callbacks.onProcess?.(controller.child);
-    return controller;
-  };
-  const startingRevision = await run(
-    "git",
-    ["rev-parse", "HEAD"],
-    config.workspace,
-    { allowFailure: true },
-  );
-  const startingHead =
-    startingRevision.code === 0
-      ? startingRevision.stdout.trim().slice(0, 128)
-      : null;
-  if (
-    assignment.target_head_revision &&
-    startingHead !== assignment.target_head_revision
-  ) {
-    throw new Error(
-      "This workspace is no longer at the commit inventoried by EngineerOS. Refresh the workspace inventory before assessing it.",
-    );
-  }
-  const changeImpact =
-    assignment.assessment_mode === "incremental"
-      ? await workspaceChangeImpact(
-          config.workspace,
-          assignment.base_head_revision,
-          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);
-  let completed = await controller.completed;
-  const recovered = await recoverAssessmentStageOutput({
-    completed,
-    prompt,
-    requiredOutputHeading: execution.requiredOutputHeading,
-    retry: async (correctionPrompt, previousSessionId) => {
-      callbacks.onEvent?.({
-        type: "assessment.output_correction",
-        message: "The Agent is completing the required stage report structure",
-      });
-      const correction = launchAssessmentAgent(
-        correctionPrompt,
-        previousSessionId,
-      );
-      return correction.completed;
-    },
-  });
-  completed = recovered.completed;
-  const buildResult = async (turn, report) => {
-    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 (startingHead !== endingHead) {
-      throw new Error(
-        "The Git commit changed during assessment. Refresh the workspace inventory and assess the new commit.",
-      );
-    }
-    return {
-      stage: assignment.stage,
-      report_markdown: report,
-      observed_head_revision: endingHead,
-      changed_files: changeImpact.changedFiles,
-      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);
-  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(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;
-}
-
-export async function workspaceChangeImpact(
-  workspace,
-  baseRevision,
-  targetRevision,
-) {
-  if (!baseRevision || !targetRevision) {
-    throw new Error(
-      "Incremental assessment requires both the previously assessed and current Git commits. Run a full assessment instead.",
-    );
-  }
-  const range = `${baseRevision}..${targetRevision}`;
-  const names = await run(
-    "git",
-    ["diff", "--name-status", "--find-renames", range],
-    workspace,
-    { allowFailure: true },
-  );
-  if (names.code !== 0) {
-    throw new Error(
-      "Codex could not compare the assessed and current commits. Fetch the missing Git history or run a full assessment.",
-    );
-  }
-  const committedFiles = await run(
-    "git",
-    ["-c", "core.quotepath=false", "diff", "--name-only", range],
-    workspace,
-    { allowFailure: true },
-  );
-  const workingFiles = await run(
-    "git",
-    [
-      "-c",
-      "core.quotepath=false",
-      "ls-files",
-      "--others",
-      "--modified",
-      "--deleted",
-      "--exclude-standard",
-    ],
-    workspace,
-    { allowFailure: true },
-  );
-  const status = await run("git", ["status", "--short"], workspace, {
-    allowFailure: true,
-  });
-  const stat = await run(
-    "git",
-    ["diff", "--stat", "--compact-summary", range],
-    workspace,
-    { allowFailure: true },
-  );
-  const allChangedFiles = [
-    ...new Set([
-      ...pathLines(committedFiles.stdout),
-      ...pathLines(workingFiles.stdout),
-    ]),
-  ];
-  if (allChangedFiles.length > 500) {
-    throw new Error(
-      `This change affects ${allChangedFiles.length} paths, above the 500-path incremental limit. Run a full reassessment instead.`,
-    );
-  }
-  const changedFiles = allChangedFiles;
-  if (!changedFiles.length) {
-    throw new Error(
-      "The inventoried repository changed but Git reports no assessable paths. Refresh inventory or run a full assessment.",
-    );
-  }
-  const lines = [
-    `Comparison: \`${range}\``,
-    `Changed paths: ${changedFiles.length}`,
-    "",
-    "### Name status",
-    "",
-    "```text",
-    boundedText(names.stdout, 12_000),
-    "```",
-  ];
-  if (status.stdout.trim()) {
-    lines.push(
-      "",
-      "### Working tree",
-      "",
-      "```text",
-      boundedText(status.stdout, 6_000),
-      "```",
-    );
-  }
-  if (stat.stdout.trim()) {
-    lines.push(
-      "",
-      "### Diff summary",
-      "",
-      "```text",
-      boundedText(stat.stdout, 6_000),
-      "```",
-    );
-  }
-  return { changedFiles, markdown: lines.join("\n") };
-}
-
-function pathLines(output) {
-  return String(output || "")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => line.replace(/^"|"$/g, ""));
-}
-
-function boundedText(value, maximum) {
-  const text = String(value || "").trim();
-  return text.length <= maximum
-    ? text
-    : `${text.slice(0, maximum)}\n... truncated by EngineerOS`;
-}
-
-export async function executeConnectedPrompt(assignment, config, callbacks) {
-  const execution = connectorExecution(assignment);
-  const previousSessionId = config.sessions?.[execution.sessionKey];
-  const controller = launchAgentProcess(
-    config.workspace,
-    execution.prompt,
-    execution.sandboxMode,
-    config,
-    callbacks,
-    execution.profile,
-    previousSessionId,
-    {
-      persistentAcp: true,
-      sessionKey: execution.sessionKey,
-    },
-  );
-  callbacks.onController?.(controller);
-  callbacks.onProcess?.(controller.child);
-  const completed = await controller.completed;
-  const content = sanitizeAgentResponse(completed.finalMessage).trim();
-  if (!content) {
-    throw new Error("Agent completed without returning a response.");
-  }
-  return {
-    content,
-    model: completed.model ?? config.agent_protocol ?? "coding-agent",
-    sessionId: completed.sessionId,
-    sessionKey: execution.sessionKey,
-    usage: completed.usage ?? null,
-  };
-}
-
-export async function inspectCodingAgent(config, workspace = process.cwd()) {
-  if (config.agent_protocol === "acp") {
-    if (!config.agent_command) {
-      throw new Error(
-        "ACP requires --agent-command when pairing the connector.",
-      );
-    }
-    const executionProfiles = await inspectAcpExecutionProfiles(
-      workspace,
-      config,
-    );
-    return {
-      protocol: "acp",
-      name: config.agent_name || path.basename(config.agent_command),
-      version: config.agent_version || "ACP v1",
-      executionProfiles,
-    };
-  }
-  const codex = await inspectCodexCli(workspace);
-  const modelProfiles = await inspectCodexExecutionProfiles({
-    workspace,
-    command: codex.command,
-  });
-  return {
-    protocol: "codex",
-    name: "Codex CLI",
-    version: codex.version,
-    executionProfiles: {
-      model_selection: modelProfiles.length > 0,
-      model_profiles: modelProfiles,
-      reasoning_efforts: [
-        ...new Set(modelProfiles.flatMap((model) => model.reasoning_efforts)),
-      ],
-    },
-  };
-}
-
-export async function inspectCodexCli(workspace = process.cwd()) {
-  const command =
-    process.env.CODEX_BIN ||
-    (process.platform === "win32" ? "codex.cmd" : "codex");
-  const result = await runCodexCommand(command, ["--version"], workspace);
-  if (result.code !== 0) {
-    throw new Error(
-      "Codex CLI is unavailable. Install it with `npm install -g @openai/codex@latest`, run `codex login`, then restart this connector.",
-    );
-  }
-  const version = result.stdout.trim().slice(0, 100);
-  if (!version) {
-    throw new Error(
-      "Codex CLI returned no version. Reinstall @openai/codex, then restart this connector.",
-    );
-  }
-  return { command, version };
-}
-
-export function codexFailureMessage(output, code) {
-  if (/requires a newer version of Codex/i.test(output)) {
-    return (
-      "The configured model requires a newer Codex CLI. " +
-      "Run `npm install -g @openai/codex@latest`, verify with `codex --version`, " +
-      "then restart the EngineerOS connector and retry the assessment."
-    );
-  }
-  if (/not logged in|login required|authentication required/i.test(output)) {
-    return "Codex CLI is not authenticated. Run `codex login`, then restart the EngineerOS connector.";
-  }
-  return `Codex exited with code ${code}. ${output.slice(-1_000)}`;
-}
-
-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 === "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.tool_call" || event.type === "acp.tool_call_update") {
-    return assessmentCommandMilestone(event.update?.title);
-  }
-  if (event.type === "turn.started")
-    return "Reviewing repository structure and current Git state";
-  if (event.type === "item.started") {
-    if (event.item?.type === "command_execution") {
-      return assessmentCommandMilestone(event.item.command);
-    }
-    if (event.item?.type === "mcp_tool_call")
-      return "Tracing architecture and code relationships";
-    if (event.item?.type === "web_search")
-      return "Checking an external technical reference";
-    return null;
-  }
-  if (event.type === "item.completed" && event.item?.type === "agent_message") {
-    return "Synthesizing findings and highest-return actions";
-  }
-  return null;
-}
-
-export function assessmentInactivityFailure(stage, inactiveMs) {
-  if (inactiveMs < ASSESSMENT_INACTIVITY_TIMEOUT_MS) return null;
-  return (
-    `The connected agent produced no activity for 10 minutes during ${stage}. ` +
-    "The stage was stopped instead of waiting indefinitely. Retry it after checking the agent terminal."
-  );
-}
-
-export function promptProgressMessage(event) {
-  if (!event || typeof event !== "object") return null;
-  if (event.type === "turn.started")
-    return "Reviewing the request and workspace context";
-  if (event.type === "item.started") {
-    if (event.item?.type === "command_execution") {
-      return assessmentCommandMilestone(event.item.command);
-    }
-    if (event.item?.type === "mcp_tool_call")
-      return "Checking connected project evidence";
-    if (event.item?.type === "web_search")
-      return "Checking an external technical reference";
-    return null;
-  }
-  if (event.type === "item.completed" && event.item?.type === "agent_message") {
-    return "Preparing the response";
-  }
-  if (event.type === "agent.connected") return "Agent connected";
-  if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
-    return "Agent is inspecting the workspace";
-  }
-  if (event.type === "acp.agent_message_chunk") return "Preparing the response";
-  return null;
-}
-
-export function promptStreamEvent(event) {
-  if (!event || typeof event !== "object") return null;
-  if (
-    event.type === "codex.agent_message_delta" &&
-    typeof event.delta === "string"
-  ) {
-    const delta = sanitizeAgentResponse(event.delta);
-    return delta ? { kind: "message", delta } : null;
-  }
-  if (
-    event.type === "acp.agent_message_chunk" &&
-    event.update?.content?.type === "text"
-  ) {
-    const delta = sanitizeAgentResponse(event.update.content.text);
-    return delta ? { kind: "message", delta } : null;
-  }
-  if (event.type === "acp.agent_thought_chunk") {
-    return {
-      kind: "thought",
-      message: "Agent is reasoning through the request",
-    };
-  }
-  if (event.type === "acp.permission") {
-    return {
-      kind: "permission",
-      message: event.update?.title || "Agent requested workspace permission",
-      status: event.update?.status,
-    };
-  }
-  if (event.type === "codex.usage") {
-    return { kind: "usage", message: "Agent usage updated" };
-  }
-  if (event.type === "acp.plan") {
-    return { kind: "plan", message: "Agent updated the working plan" };
-  }
-  if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
-    return {
-      kind: "tool",
-      message: event.update?.title || "Agent is inspecting the workspace",
-      status: event.update?.status,
-    };
-  }
-  if (event.type === "item.completed" && event.item?.type === "agent_message") {
-    const delta = sanitizeAgentResponse(event.item.text);
-    return delta ? { kind: "message", delta } : null;
-  }
-  const message = promptProgressMessage(event);
-  return message ? { kind: "status", message } : null;
-}
-
-function assessmentCommandMilestone(command) {
-  const value = Array.isArray(command)
-    ? command.join(" ")
-    : String(command || "");
-  const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
-  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";
-  }
-  if (
-    /\b(test|pytest|vitest|jest|ruff|eslint|tsc|build|lint)\b/.test(normalized)
-  ) {
-    return "Checking verification and delivery signals";
-  }
-  if (
-    /\b(audit|dependency|dependencies|lockfile|package-lock|pnpm-lock|requirements)\b/.test(
-      normalized,
-    )
-  ) {
-    return "Reviewing dependencies and security signals";
-  }
-  return "Tracing architecture and code relationships";
-}
-
-export function workspaceAssessmentExecution(assignment) {
-  const stage = assignment?.stage;
-  const requiredOutputHeading = String(
-    assignment?.required_output_heading || "",
-  ).trim();
-  if (!stage || !requiredOutputHeading.startsWith("# Assessment Stage: ")) {
-    throw new Error(
-      "EngineerOS assessment assignment has an unsupported stage.",
-    );
-  }
-  return {
-    ...connectorExecution(assignment, { requiredOutputHeading }),
-    requiredOutputHeading,
-  };
-}
-
-export async function recoverAssessmentStageOutput({
-  completed,
-  prompt,
-  requiredOutputHeading,
-  retry,
-}) {
-  try {
-    return {
-      completed,
-      correctionUsed: false,
-      report: normalizeAgentStructuredOutput(
-        completed.finalMessage,
-        requiredOutputHeading,
-      ),
-    };
-  } catch (error) {
-    if (!recoverableStructuredOutputFailure(error)) throw error;
-  }
-
-  const corrected = await retry(
-    assessmentStageCorrectionPrompt(prompt, requiredOutputHeading),
-    completed.sessionId,
-  );
-  try {
-    return {
-      completed: {
-        ...corrected,
-        usage: mergeTokenUsage(completed.usage, corrected.usage),
-      },
-      correctionUsed: true,
-      report: normalizeAgentStructuredOutput(
-        corrected.finalMessage,
-        requiredOutputHeading,
-      ),
-    };
-  } catch (error) {
-    throw new Error(
-      `Agent did not return the required stage report after one automatic correction attempt. ${error.message}`,
-      { cause: error },
-    );
-  }
-}
-
-export function assessmentRejectionCorrectionPrompt(
-  validationMessage,
-  requiredOutputHeading,
-) {
-  return [
-    "## Rejected Stage Output Recovery",
-    "",
-    "EngineerOS rejected the previous stage report because it was incomplete or violated the structured Markdown contract:",
-    "",
-    String(validationMessage || "The stage report was rejected.").trim(),
-    "",
-    "Treat the previous stage report as the authoritative draft.",
-    "Copy every valid section and block unchanged; repair only the incomplete or invalid entries identified by EngineerOS validation.",
-    "Do not re-inspect the repository or replace valid evidence unless the validation error requires it.",
-    "Return the entire corrected structured Markdown stage report so EngineerOS can validate it atomically, not only the repaired fragment or missing tail.",
-    `The first non-whitespace line must be exactly: ${requiredOutputHeading}`,
-    "Do not return progress commentary, an explanation of the correction, or a code fence.",
-  ].join("\n");
-}
-
-export function assessmentStageCorrectionPrompt(
-  originalPrompt,
-  requiredOutputHeading,
-) {
-  return [
-    String(originalPrompt || "").trim(),
-    "",
-    "## 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.",
-    `The first non-whitespace line of the final answer must be exactly: ${requiredOutputHeading}`,
-    "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");
-}
-
-function recoverableStructuredOutputFailure(error) {
-  const message = error instanceof Error ? error.message : "";
-  return (
-    message.startsWith("Agent completed") ||
-    message.startsWith("Agent response")
-  );
-}
-
-function mergeTokenUsage(first, second) {
-  const usages = [first, second].filter(
-    (usage) => usage && typeof usage === "object",
-  );
-  if (!usages.length) return null;
-  return Object.fromEntries(
-    [
-      "input_tokens",
-      "output_tokens",
-      "cache_read_tokens",
-      "cache_write_tokens",
-      "reasoning_tokens",
-      "total_tokens",
-    ].map((field) => [
-      field,
-      usages.reduce(
-        (total, usage) =>
-          total + (Number.isFinite(usage[field]) ? usage[field] : 0),
-        0,
-      ),
-    ]),
-  );
-}
-
-export function enqueueWorkspaceAssessment(
-  queue,
-  activeAssessment,
-  assignment,
-  { front = false } = {},
-) {
-  const matches = (candidate) =>
-    candidate?.assessment_id === assignment?.assessment_id &&
-    candidate?.stage === assignment?.stage;
-  if (
-    activeAssessment?.kind === "assessment" &&
-    activeAssessment.runId === assignment?.assessment_id &&
-    activeAssessment.stage === assignment?.stage
-  ) {
-    activeAssessment.resumeAssignment = assignment;
-    return "deferred";
-  }
-  if (queue.some(matches)) return "duplicate";
-  if (front) queue.unshift(assignment);
-  else queue.push(assignment);
-  return "queued";
-}
-
+  const execution = workspaceAssessmentExecution(assignment);
+  const assessmentAcpContext =
+    config.agent_protocol === "acp"
+      ? {
+          persistentAcp: true,
+          sessionKey: `assessment:${assignment.assessment_id}:${assignment.stage}`,
+        }
+      : undefined;
+  const launchAssessmentAgent = (turnPrompt, previousSessionId) => {
+    const controller = launchAgentProcess(
+      config.workspace,
+      turnPrompt,
+      execution.sandboxMode,
+      config,
+      callbacks,
+      execution.profile,
+      previousSessionId,
+      assessmentAcpContext,
+    );
+    callbacks.onController?.(controller);
+    callbacks.onProcess?.(controller.child);
+    return controller;
+  };
+  const startingRevision = await run(
+    "git",
+    ["rev-parse", "HEAD"],
+    config.workspace,
+    { allowFailure: true },
+  );
+  const startingHead =
+    startingRevision.code === 0
+      ? startingRevision.stdout.trim().slice(0, 128)
+      : null;
+  if (
+    assignment.target_head_revision &&
+    startingHead !== assignment.target_head_revision
+  ) {
+    throw new Error(
+      "This workspace is no longer at the commit inventoried by EngineerOS. Refresh the workspace inventory before assessing it.",
+    );
+  }
+  const changeImpact =
+    assignment.assessment_mode === "incremental"
+      ? await workspaceChangeImpact(
+          config.workspace,
+          assignment.base_head_revision,
+          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, previousSessionId);
+  let completed = await controller.completed;
+  const recovered = await recoverAssessmentStageOutput({
+    completed,
+    prompt,
+    requiredOutputHeading: execution.requiredOutputHeading,
+    retry: async (correctionPrompt, previousSessionId) => {
+      callbacks.onEvent?.({
+        type: "assessment.output_correction",
+        message: "The Agent is completing the required stage report structure",
+      });
+      const correction = launchAssessmentAgent(
+        correctionPrompt,
+        previousSessionId,
+      );
+      return correction.completed;
+    },
+  });
+  completed = recovered.completed;
+  const buildResult = async (turn, report) => {
+    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 (startingHead !== endingHead) {
+      throw new Error(
+        "The Git commit changed during assessment. Refresh the workspace inventory and assess the new commit.",
+      );
+    }
+    return {
+      stage: assignment.stage,
+      report_markdown: report,
+      observed_head_revision: endingHead,
+      changed_files: changeImpact.changedFiles,
+      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);
+  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(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;
+}
+
+export async function workspaceChangeImpact(
+  workspace,
+  baseRevision,
+  targetRevision,
+) {
+  if (!baseRevision || !targetRevision) {
+    throw new Error(
+      "Incremental assessment requires both the previously assessed and current Git commits. Run a full assessment instead.",
+    );
+  }
+  const range = `${baseRevision}..${targetRevision}`;
+  const names = await run(
+    "git",
+    ["diff", "--name-status", "--find-renames", range],
+    workspace,
+    { allowFailure: true },
+  );
+  if (names.code !== 0) {
+    throw new Error(
+      "Codex could not compare the assessed and current commits. Fetch the missing Git history or run a full assessment.",
+    );
+  }
+  const committedFiles = await run(
+    "git",
+    ["-c", "core.quotepath=false", "diff", "--name-only", range],
+    workspace,
+    { allowFailure: true },
+  );
+  const workingFiles = await run(
+    "git",
+    [
+      "-c",
+      "core.quotepath=false",
+      "ls-files",
+      "--others",
+      "--modified",
+      "--deleted",
+      "--exclude-standard",
+    ],
+    workspace,
+    { allowFailure: true },
+  );
+  const status = await run("git", ["status", "--short"], workspace, {
+    allowFailure: true,
+  });
+  const stat = await run(
+    "git",
+    ["diff", "--stat", "--compact-summary", range],
+    workspace,
+    { allowFailure: true },
+  );
+  const allChangedFiles = [
+    ...new Set([
+      ...pathLines(committedFiles.stdout),
+      ...pathLines(workingFiles.stdout),
+    ]),
+  ];
+  if (allChangedFiles.length > 500) {
+    throw new Error(
+      `This change affects ${allChangedFiles.length} paths, above the 500-path incremental limit. Run a full reassessment instead.`,
+    );
+  }
+  const changedFiles = allChangedFiles;
+  if (!changedFiles.length) {
+    throw new Error(
+      "The inventoried repository changed but Git reports no assessable paths. Refresh inventory or run a full assessment.",
+    );
+  }
+  const lines = [
+    `Comparison: \`${range}\``,
+    `Changed paths: ${changedFiles.length}`,
+    "",
+    "### Name status",
+    "",
+    "```text",
+    boundedText(names.stdout, 12_000),
+    "```",
+  ];
+  if (status.stdout.trim()) {
+    lines.push(
+      "",
+      "### Working tree",
+      "",
+      "```text",
+      boundedText(status.stdout, 6_000),
+      "```",
+    );
+  }
+  if (stat.stdout.trim()) {
+    lines.push(
+      "",
+      "### Diff summary",
+      "",
+      "```text",
+      boundedText(stat.stdout, 6_000),
+      "```",
+    );
+  }
+  return { changedFiles, markdown: lines.join("\n") };
+}
+
+function pathLines(output) {
+  return String(output || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.replace(/^"|"$/g, ""));
+}
+
+function boundedText(value, maximum) {
+  const text = String(value || "").trim();
+  return text.length <= maximum
+    ? text
+    : `${text.slice(0, maximum)}\n... truncated by EngineerOS`;
+}
+
+export async function executeConnectedPrompt(assignment, config, callbacks) {
+  const execution = connectorExecution(assignment);
+  const previousSessionId = config.sessions?.[execution.sessionKey];
+  const controller = launchAgentProcess(
+    config.workspace,
+    execution.prompt,
+    execution.sandboxMode,
+    config,
+    callbacks,
+    execution.profile,
+    previousSessionId,
+    {
+      persistentAcp: true,
+      sessionKey: execution.sessionKey,
+    },
+  );
+  callbacks.onController?.(controller);
+  callbacks.onProcess?.(controller.child);
+  const completed = await controller.completed;
+  const content = sanitizeAgentResponse(completed.finalMessage).trim();
+  if (!content) {
+    throw new Error("Agent completed without returning a response.");
+  }
+  return {
+    content,
+    model: completed.model ?? config.agent_protocol ?? "coding-agent",
+    sessionId: completed.sessionId,
+    sessionKey: execution.sessionKey,
+    usage: completed.usage ?? null,
+  };
+}
+
+export async function inspectCodingAgent(config, workspace = process.cwd()) {
+  if (config.agent_protocol === "acp") {
+    if (!config.agent_command) {
+      throw new Error(
+        "ACP requires --agent-command when pairing the connector.",
+      );
+    }
+    const executionProfiles = await inspectAcpExecutionProfiles(
+      workspace,
+      config,
+    );
+    return {
+      protocol: "acp",
+      name: config.agent_name || path.basename(config.agent_command),
+      version: config.agent_version || "ACP v1",
+      executionProfiles,
+    };
+  }
+  const codex = await inspectCodexCli(workspace);
+  const modelProfiles = await inspectCodexExecutionProfiles({
+    workspace,
+    command: codex.command,
+  });
+  return {
+    protocol: "codex",
+    name: "Codex CLI",
+    version: codex.version,
+    executionProfiles: {
+      model_selection: modelProfiles.length > 0,
+      model_profiles: modelProfiles,
+      reasoning_efforts: [
+        ...new Set(modelProfiles.flatMap((model) => model.reasoning_efforts)),
+      ],
+    },
+  };
+}
+
+export async function inspectCodexCli(workspace = process.cwd()) {
+  const command =
+    process.env.CODEX_BIN ||
+    (process.platform === "win32" ? "codex.cmd" : "codex");
+  const result = await runCodexCommand(command, ["--version"], workspace);
+  if (result.code !== 0) {
+    throw new Error(
+      "Codex CLI is unavailable. Install it with `npm install -g @openai/codex@latest`, run `codex login`, then restart this connector.",
+    );
+  }
+  const version = result.stdout.trim().slice(0, 100);
+  if (!version) {
+    throw new Error(
+      "Codex CLI returned no version. Reinstall @openai/codex, then restart this connector.",
+    );
+  }
+  return { command, version };
+}
+
+export function codexFailureMessage(output, code) {
+  if (/requires a newer version of Codex/i.test(output)) {
+    return (
+      "The configured model requires a newer Codex CLI. " +
+      "Run `npm install -g @openai/codex@latest`, verify with `codex --version`, " +
+      "then restart the EngineerOS connector and retry the assessment."
+    );
+  }
+  if (/not logged in|login required|authentication required/i.test(output)) {
+    return "Codex CLI is not authenticated. Run `codex login`, then restart the EngineerOS connector.";
+  }
+  return `Codex exited with code ${code}. ${output.slice(-1_000)}`;
+}
+
+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 === "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.tool_call" || event.type === "acp.tool_call_update") {
+    return assessmentCommandMilestone(event.update?.title);
+  }
+  if (event.type === "turn.started")
+    return "Reviewing repository structure and current Git state";
+  if (event.type === "item.started") {
+    if (event.item?.type === "command_execution") {
+      return assessmentCommandMilestone(event.item.command);
+    }
+    if (event.item?.type === "mcp_tool_call")
+      return "Tracing architecture and code relationships";
+    if (event.item?.type === "web_search")
+      return "Checking an external technical reference";
+    return null;
+  }
+  if (event.type === "item.completed" && event.item?.type === "agent_message") {
+    return "Synthesizing findings and highest-return actions";
+  }
+  return null;
+}
+
+export function assessmentInactivityFailure(stage, inactiveMs) {
+  if (inactiveMs < ASSESSMENT_INACTIVITY_TIMEOUT_MS) return null;
+  return (
+    `The connected agent produced no activity for 10 minutes during ${stage}. ` +
+    "The stage was stopped instead of waiting indefinitely. Retry it after checking the agent terminal."
+  );
+}
+
+export function promptProgressMessage(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.type === "turn.started")
+    return "Reviewing the request and workspace context";
+  if (event.type === "item.started") {
+    if (event.item?.type === "command_execution") {
+      return assessmentCommandMilestone(event.item.command);
+    }
+    if (event.item?.type === "mcp_tool_call")
+      return "Checking connected project evidence";
+    if (event.item?.type === "web_search")
+      return "Checking an external technical reference";
+    return null;
+  }
+  if (event.type === "item.completed" && event.item?.type === "agent_message") {
+    return "Preparing the response";
+  }
+  if (event.type === "agent.connected") return "Agent connected";
+  if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
+    return "Agent is inspecting the workspace";
+  }
+  if (event.type === "acp.agent_message_chunk") return "Preparing the response";
+  return null;
+}
+
+export function promptStreamEvent(event) {
+  if (!event || typeof event !== "object") return null;
+  if (
+    event.type === "codex.agent_message_delta" &&
+    typeof event.delta === "string"
+  ) {
+    const delta = sanitizeAgentResponse(event.delta);
+    return delta ? { kind: "message", delta } : null;
+  }
+  if (
+    event.type === "acp.agent_message_chunk" &&
+    event.update?.content?.type === "text"
+  ) {
+    const delta = sanitizeAgentResponse(event.update.content.text);
+    return delta ? { kind: "message", delta } : null;
+  }
+  if (event.type === "acp.agent_thought_chunk") {
+    return {
+      kind: "thought",
+      message: "Agent is reasoning through the request",
+    };
+  }
+  if (event.type === "acp.permission") {
+    return {
+      kind: "permission",
+      message: event.update?.title || "Agent requested workspace permission",
+      status: event.update?.status,
+    };
+  }
+  if (event.type === "codex.usage") {
+    return { kind: "usage", message: "Agent usage updated" };
+  }
+  if (event.type === "acp.plan") {
+    return { kind: "plan", message: "Agent updated the working plan" };
+  }
+  if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
+    return {
+      kind: "tool",
+      message: event.update?.title || "Agent is inspecting the workspace",
+      status: event.update?.status,
+    };
+  }
+  if (event.type === "item.completed" && event.item?.type === "agent_message") {
+    const delta = sanitizeAgentResponse(event.item.text);
+    return delta ? { kind: "message", delta } : null;
+  }
+  const message = promptProgressMessage(event);
+  return message ? { kind: "status", message } : null;
+}
+
+function assessmentCommandMilestone(command) {
+  const value = Array.isArray(command)
+    ? command.join(" ")
+    : String(command || "");
+  const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
+  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";
+  }
+  if (
+    /\b(test|pytest|vitest|jest|ruff|eslint|tsc|build|lint)\b/.test(normalized)
+  ) {
+    return "Checking verification and delivery signals";
+  }
+  if (
+    /\b(audit|dependency|dependencies|lockfile|package-lock|pnpm-lock|requirements)\b/.test(
+      normalized,
+    )
+  ) {
+    return "Reviewing dependencies and security signals";
+  }
+  return "Tracing architecture and code relationships";
+}
+
+export function workspaceAssessmentExecution(assignment) {
+  const stage = assignment?.stage;
+  const requiredOutputHeading = String(
+    assignment?.required_output_heading || "",
+  ).trim();
+  if (!stage || !requiredOutputHeading.startsWith("# Assessment Stage: ")) {
+    throw new Error(
+      "EngineerOS assessment assignment has an unsupported stage.",
+    );
+  }
+  return {
+    ...connectorExecution(assignment, { requiredOutputHeading }),
+    requiredOutputHeading,
+  };
+}
+
+export async function recoverAssessmentStageOutput({
+  completed,
+  prompt,
+  requiredOutputHeading,
+  retry,
+}) {
+  try {
+    return {
+      completed,
+      correctionUsed: false,
+      report: normalizeAgentStructuredOutput(
+        completed.finalMessage,
+        requiredOutputHeading,
+      ),
+    };
+  } catch (error) {
+    if (!recoverableStructuredOutputFailure(error)) throw error;
+  }
+
+  const corrected = await retry(
+    assessmentStageCorrectionPrompt(prompt, requiredOutputHeading),
+    completed.sessionId,
+  );
+  try {
+    return {
+      completed: {
+        ...corrected,
+        usage: mergeTokenUsage(completed.usage, corrected.usage),
+      },
+      correctionUsed: true,
+      report: normalizeAgentStructuredOutput(
+        corrected.finalMessage,
+        requiredOutputHeading,
+      ),
+    };
+  } catch (error) {
+    throw new Error(
+      `Agent did not return the required stage report after one automatic correction attempt. ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+export function assessmentRejectionCorrectionPrompt(
+  validationMessage,
+  requiredOutputHeading,
+) {
+  return [
+    "## Rejected Stage Output Recovery",
+    "",
+    "EngineerOS rejected the previous stage report because it was incomplete or violated the structured Markdown contract:",
+    "",
+    String(validationMessage || "The stage report was rejected.").trim(),
+    "",
+    "Treat the previous stage report as the authoritative draft.",
+    "Copy every valid section and block unchanged; repair only the incomplete or invalid entries identified by EngineerOS validation.",
+    "Do not re-inspect the repository or replace valid evidence unless the validation error requires it.",
+    "Return the entire corrected structured Markdown stage report so EngineerOS can validate it atomically, not only the repaired fragment or missing tail.",
+    `The first non-whitespace line must be exactly: ${requiredOutputHeading}`,
+    "Do not return progress commentary, an explanation of the correction, or a code fence.",
+  ].join("\n");
+}
+
+export function assessmentStageCorrectionPrompt(
+  originalPrompt,
+  requiredOutputHeading,
+) {
+  return [
+    String(originalPrompt || "").trim(),
+    "",
+    "## 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.",
+    `The first non-whitespace line of the final answer must be exactly: ${requiredOutputHeading}`,
+    "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");
+}
+
+function recoverableStructuredOutputFailure(error) {
+  const message = error instanceof Error ? error.message : "";
+  return (
+    message.startsWith("Agent completed") ||
+    message.startsWith("Agent response")
+  );
+}
+
+function mergeTokenUsage(first, second) {
+  const usages = [first, second].filter(
+    (usage) => usage && typeof usage === "object",
+  );
+  if (!usages.length) return null;
+  return Object.fromEntries(
+    [
+      "input_tokens",
+      "output_tokens",
+      "cache_read_tokens",
+      "cache_write_tokens",
+      "reasoning_tokens",
+      "total_tokens",
+    ].map((field) => [
+      field,
+      usages.reduce(
+        (total, usage) =>
+          total + (Number.isFinite(usage[field]) ? usage[field] : 0),
+        0,
+      ),
+    ]),
+  );
+}
+
+export function enqueueWorkspaceAssessment(
+  queue,
+  activeAssessment,
+  assignment,
+  { front = false } = {},
+) {
+  const matches = (candidate) =>
+    candidate?.assessment_id === assignment?.assessment_id &&
+    candidate?.stage === assignment?.stage;
+  if (
+    activeAssessment?.kind === "assessment" &&
+    activeAssessment.runId === assignment?.assessment_id &&
+    activeAssessment.stage === assignment?.stage
+  ) {
+    activeAssessment.resumeAssignment = assignment;
+    return "deferred";
+  }
+  if (queue.some(matches)) return "duplicate";
+  if (front) queue.unshift(assignment);
+  else queue.push(assignment);
+  return "queued";
+}
+
 export function takeWorkspaceAssessmentWave(queue, activeCount, limit) {
-  const available = Math.max(0, limit - activeCount);
-  if (!available || !queue.length) return [];
-  if (queue[0]?.parallelizable !== true) {
-    return activeCount === 0 ? queue.splice(0, 1) : [];
-  }
-  const wave = [];
-  while (wave.length < available && queue[0]?.parallelizable === true) {
-    wave.push(queue.shift());
-  }
-  return wave;
-}
-
-export function workspaceAssessmentWorkerLimit(
-  configuredLimit,
-  availableParallelism = os.availableParallelism(),
-) {
-  if (configuredLimit !== undefined && configuredLimit !== null) {
-    const parsed = Number(configuredLimit);
-    if (
-      !Number.isInteger(parsed) ||
-      parsed < 1 ||
-      parsed > MAX_ASSESSMENT_WORKERS
-    ) {
-      throw new Error(
-        `Assessment workers must be a whole number from 1 to ${MAX_ASSESSMENT_WORKERS}.`,
-      );
-    }
-    return parsed;
-  }
-  return Math.min(
-    MAX_AUTOMATIC_ASSESSMENT_WORKERS,
-    Math.max(1, Math.floor(Number(availableParallelism) / 2) || 1),
-  );
-}
-
-export function assessmentWorkerSnapshots(activeAssessments) {
-  return [...activeAssessments.values()].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),
-  }));
+  const available = Math.max(0, limit - activeCount);
+  if (!available || !queue.length) return [];
+  if (queue[0]?.parallelizable !== true) {
+    return activeCount === 0 ? queue.splice(0, 1) : [];
+  }
+  const wave = [];
+  while (wave.length < available && queue[0]?.parallelizable === true) {
+    wave.push(queue.shift());
+  }
+  return wave;
 }
 
-export function requeueInterruptedAssessment(
-  queue,
-  assessmentState,
-  { accepted, failureReported },
-) {
-  if (accepted || failureReported || !assessmentState?.resumeAssignment) {
-    return false;
-  }
-  return (
-    enqueueWorkspaceAssessment(queue, null, 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.",
-  );
-}
-
-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 ||
-    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.");
-  }
-  const sandboxMode = assignment?.sandbox_mode;
-  if (!new Set(["read-only", "workspace-write"]).has(sandboxMode)) {
-    throw new Error("EngineerOS assignment has an unsupported sandbox_mode.");
-  }
-  const rawProfile = assignment?.execution_profile ?? {};
-  const model =
-    typeof rawProfile.model === "string" ? rawProfile.model.trim() : "";
-  const reasoningEffort = rawProfile.reasoning_effort;
+export function workspaceAssessmentWorkerLimit(value) {
+  const parsed = Number(value ?? DEFAULT_ASSESSMENT_WORKERS);
   if (
-    reasoningEffort &&
-    !new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]).has(
-      reasoningEffort,
-    )
+    !Number.isInteger(parsed) ||
+    parsed < MIN_ASSESSMENT_WORKERS ||
+    parsed > MAX_ASSESSMENT_WORKERS
   ) {
     throw new Error(
-      "EngineerOS assignment has an unsupported reasoning effort.",
-    );
-  }
-  const agentRole = assignment?.agent_role;
-  const prompt = buildAgentHarnessPrompt({
-    agentRole,
-    agentDefinition: assignment?.agent_definition,
-    prompt: rawPrompt,
-    sandboxMode,
-    requiredOutputHeading: options.requiredOutputHeading,
-  });
-  return {
-    prompt,
-    agentRole,
-    sandboxMode,
-    sessionKey:
-      typeof assignment.session_key === "string" &&
-      assignment.session_key.trim()
-        ? assignment.session_key.trim()
-        : `project-${String(agentRole)}-${String(
-            assignment.purpose || "general",
-          )
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, "-")
-            .slice(0, 80)}`,
-    profile: {
-      ...(model ? { model } : {}),
-      ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
-    },
-  };
-}
-
-export async function stopProcess(child) {
-  if (!child || child.exitCode !== null) return;
-  if (typeof child.engineerOsCancel === "function") {
-    await child.engineerOsCancel();
-    return;
-  }
-  if (process.platform === "win32") {
-    await run(
-      "taskkill",
-      ["/pid", String(child.pid), "/t", "/f"],
-      process.cwd(),
-      { allowFailure: true },
+      `Assessment worker limit must be a whole number from ${MIN_ASSESSMENT_WORKERS} to ${MAX_ASSESSMENT_WORKERS}.`,
     );
-  } else {
-    child.kill("SIGTERM");
   }
+  return parsed;
 }
-
-export async function workspaceSnapshot(workspace) {
-  const root = path.resolve(workspace);
-  const gitFiles = await run(
-    "git",
-    ["ls-files", "-z", "-co", "--exclude-standard"],
-    root,
-    { allowFailure: true },
-  );
-  const candidates =
-    gitFiles.code === 0
-      ? gitPathList(gitFiles.stdout)
-      : await workspaceFiles(root);
-  const ignoredFiles =
-    gitFiles.code === 0
-      ? gitPathList(
-          (
-            await run(
-              "git",
-              ["ls-files", "-z", "--others", "--ignored", "--exclude-standard"],
-              root,
-              { allowFailure: true },
-            )
-          ).stdout,
-        )
-      : [];
-  const trackedFiles =
-    gitFiles.code === 0
-      ? new Set(
-          gitPathList(
-            (
-              await run("git", ["ls-files", "-z", "--cached"], root, {
-                allowFailure: true,
-              })
-            ).stdout,
-          ),
-        )
-      : new Set();
-  const modifiedFiles =
-    gitFiles.code === 0
-      ? new Set(
-          gitPathList(
-            (
-              await run("git", ["diff", "--name-only", "-z", "--"], root, {
-                allowFailure: true,
-              })
-            ).stdout,
-          ),
-        )
-      : new Set();
-  const stagedFiles =
-    gitFiles.code === 0
-      ? new Set(
-          gitPathList(
-            (
-              await run(
-                "git",
-                ["diff", "--cached", "--name-only", "-z", "--"],
-                root,
-                { allowFailure: true },
-              )
-            ).stdout,
-          ),
-        )
-      : new Set();
-  const gitStatus =
-    gitFiles.code === 0
-      ? await run(
-          "git",
-          ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
-          root,
-          { allowFailure: true },
-        )
-      : { stdout: "" };
-  const inventory = [];
-  let excludedFileCount = new Set(ignoredFiles).size;
-  const sortedCandidates = [...new Set(candidates)].sort();
-  for (let start = 0; start < sortedCandidates.length; start += 256) {
-    const batch = sortedCandidates.slice(start, start + 256);
-    const inspected = await Promise.all(
-      batch.map(async (relative) => ({
-        relative,
-        details: isShareablePath(relative)
-          ? await lstat(path.join(root, relative)).catch(() => null)
-          : null,
-      })),
-    );
-    for (const { relative, details } of inspected) {
-      if (!details?.isFile() || details.isSymbolicLink()) {
-        excludedFileCount += 1;
-        continue;
-      }
-      inventory.push({
-        path: relative,
-        size: details.size,
-        classification: evidenceClassification(relative),
-        git_state: inventoryGitState(
-          relative,
-          trackedFiles,
-          modifiedFiles,
-          stagedFiles,
-        ),
-      });
-      if (inventory.length > MAX_INVENTORY_FILES) {
-        throw new Error(
-          `Workspace contains more than ${MAX_INVENTORY_FILES.toLocaleString()} safe files. Configure repository exclusions for generated or data directories, then reconnect.`,
-        );
-      }
-    }
-  }
-  const representativeSources = representativeSourcePaths(inventory);
-  const evidenceCandidates = [...inventory].sort((left, right) => {
-    const priorityDifference =
-      evidencePriority(left, representativeSources) -
-      evidencePriority(right, representativeSources);
-    return priorityDifference || left.path.localeCompare(right.path);
-  });
-  const evidenceEntries = [];
-  let evidenceBytes = 0;
-  for (const entry of evidenceCandidates) {
-    if (
-      evidenceEntries.length >= MAX_EVIDENCE_FILES ||
-      entry.size > MAX_SHAREABLE_FILE_BYTES ||
-      evidenceBytes + entry.size > MAX_EVIDENCE_BYTES
-    ) {
-      continue;
-    }
-    evidenceEntries.push(entry);
-    evidenceBytes += entry.size;
-  }
-  const evidenceFiles = await readEvidenceFiles(root, evidenceEntries);
-  const archive = await createZip(evidenceFiles);
-  if (archive.length > MAX_ARCHIVE_BYTES) {
-    throw new Error(
-      "Prioritized workspace evidence exceeds the 25 MB archive limit. Configure repository exclusions for large source or data files, then reconnect.",
-    );
-  }
-  const inventoryJson = Buffer.from(
-    JSON.stringify({ version: 1, entries: inventory }),
-    "utf8",
-  );
-  const compressedInventory = await gzipBuffer(inventoryJson);
-  if (compressedInventory.length > MAX_COMPRESSED_INVENTORY_BYTES) {
-    throw new Error(
-      "Compressed workspace inventory exceeds 10 MB. Configure repository exclusions for generated or data directories, then reconnect.",
-    );
-  }
-  const head = await run("git", ["rev-parse", "HEAD"], root, {
-    allowFailure: true,
-  });
-  return {
-    inventory_base64: compressedInventory.toString("base64"),
-    evidence_archive_base64: archive.toString("base64"),
-    media_type: "application/zip",
-    workspace_name: path.basename(root),
-    workspace_kind: inventory.some(({ path: relative }) =>
-      isCodeBearing(relative),
-    )
-      ? "brownfield"
-      : "greenfield",
-    total_file_count: inventory.length,
-    evidence_file_count: evidenceFiles.length,
-    excluded_file_count: excludedFileCount,
-    omitted_evidence_file_count: inventory.length - evidenceFiles.length,
-    head_revision: head.code === 0 ? head.stdout.trim().slice(0, 128) : null,
-    working_tree_status_digest: sha256(gitStatus.stdout),
-    inventory_digest: sha256(inventoryJson),
-    evidence_policy_version: EVIDENCE_POLICY_VERSION,
-  };
-}
-
-function evidenceClassification(relative) {
-  const normalized = normalizePath(relative).toLowerCase();
-  const name = path.posix.basename(normalized);
-  const extension = path.posix.extname(name);
-  if (CODE_MARKERS.has(name)) return "manifest";
-  if (LOCK_FILE_NAMES.has(name)) return "lockfile";
-  if (
-    normalized.startsWith(".github/workflows/") ||
-    [
-      ".gitlab-ci.yml",
-      "azure-pipelines.yml",
-      "docker-compose.yml",
-      "docker-compose.yaml",
-      "dockerfile",
-      "jenkinsfile",
-    ].includes(name)
-  ) {
-    return "workflow";
-  }
-  if (
-    /(^|\/)(tests|__tests__)\//.test(normalized) ||
-    name.startsWith("test_") ||
-    name.includes(".test.") ||
-    name.includes(".spec.") ||
-    /^(jest|vitest|pytest|playwright|cypress)(\.|$)/.test(name)
-  ) {
-    return "test";
-  }
-  if (/(^|\/)(security|compliance|policy|policies)(\/|\.|$)/.test(normalized)) {
-    return "security_configuration";
-  }
-  if (
-    REPOSITORY_CONFIGURATION_NAMES.has(name) ||
-    /(^|\/)(eslint|ruff|mypy|tsconfig|biome|prettier)/.test(normalized)
-  ) {
-    return "repository_configuration";
-  }
-  if (ENTRYPOINT_NAMES.has(name)) return "entrypoint";
-  if (
-    /(^|\/)(api|routes|controllers)\//.test(normalized) ||
-    name.endsWith(".d.ts") ||
-    name.includes("openapi") ||
-    name.includes("swagger")
-  ) {
-    return "public_api";
-  }
-  if (
-    extension === ".md" ||
-    normalized.startsWith("docs/") ||
-    /(^|\/)(architecture|operations|runbook|deployment)(\/|\.|$)/.test(
-      normalized,
-    )
-  ) {
-    return "documentation";
-  }
-  if (CODE_EXTENSIONS.has(extension)) return "source";
-  return "other";
-}
-
-function inventoryGitState(relative, trackedFiles, modifiedFiles, stagedFiles) {
-  if (!trackedFiles.has(relative)) return "untracked";
-  const modified = modifiedFiles.has(relative);
-  const staged = stagedFiles.has(relative);
-  if (modified && staged) return "staged_and_modified";
-  if (modified) return "modified";
-  if (staged) return "staged";
-  return "clean";
-}
-
-function representativeSourcePaths(inventory) {
-  const representatives = new Set();
-  const groups = new Set();
-  for (const entry of inventory) {
-    if (entry.classification !== "source") continue;
-    const parts = entry.path.split("/");
-    const moduleName = parts.length > 1 ? parts[0] : ".";
-    const extension = path.posix.extname(entry.path).toLowerCase();
-    const group = `${moduleName}:${extension}`;
-    if (groups.has(group)) continue;
-    groups.add(group);
-    representatives.add(entry.path);
-  }
-  return representatives;
-}
-
-function evidencePriority(entry, representativeSources) {
-  const priorities = {
-    manifest: 0,
-    lockfile: 0,
-    workflow: 1,
-    security_configuration: 1,
-    repository_configuration: 1,
-    entrypoint: 2,
-    public_api: 2,
-    test: 3,
-    documentation: 4,
-  };
-  if (entry.classification in priorities)
-    return priorities[entry.classification];
-  if (
-    entry.classification === "source" &&
-    representativeSources.has(entry.path)
-  ) {
-    return 5;
-  }
-  return 6;
-}
-
-function sha256(value) {
-  return createHash("sha256").update(value).digest("hex");
-}
-
-async function readEvidenceFiles(root, entries) {
-  const files = [];
-  for (let start = 0; start < entries.length; start += 128) {
-    files.push(
-      ...(await Promise.all(
-        entries.slice(start, start + 128).map(async (entry) => ({
-          name: entry.path,
-          data: await readFile(path.join(root, entry.path)),
-        })),
-      )),
-    );
-  }
-  return files;
-}
-
-async function prepareRunWorkspace(workspace, runId, baseRevision) {
-  const source = path.resolve(workspace);
-  const root = path.join(os.homedir(), ".engineeros", "runs");
-  const target = path.join(root, runId);
-  await mkdir(root, { recursive: true });
-  const isGit =
-    (
-      await run("git", ["rev-parse", "--is-inside-work-tree"], source, {
-        allowFailure: true,
-      })
-    ).code === 0;
-  if (isGit) {
-    const exists = await stat(target).then(
-      () => true,
-      () => false,
-    );
-    if (!exists) {
-      const base = await worktreeBase(source, baseRevision);
-      await run("git", ["worktree", "add", "--detach", target, base], source);
-    }
-    return target;
-  }
-  const exists = await stat(target).then(
-    () => true,
-    () => false,
-  );
-  if (!exists) {
-    await mkdir(target, { recursive: true });
-    await copyWorkspace(source, target);
-    await run("git", ["init"], target);
-    await run("git", ["config", "user.name", "EngineerOS Connector"], target);
-    await run(
-      "git",
-      ["config", "user.email", "connector@engineeros.local"],
-      target,
-    );
-    await run("git", ["add", "-A"], target);
-    await run(
-      "git",
-      ["commit", "--allow-empty", "-m", "EngineerOS run baseline"],
-      target,
-    );
-  }
-  return target;
-}
-
-function launchCodexProcess(
-  workspace,
-  prompt,
-  sandbox,
-  callbacks,
-  profile = {},
-  previousSessionId,
-  skipGitRepoCheck = false,
-  mcpServer,
-) {
-  if (!mcpServer) {
-    return launchCodexAppServer({
-      workspace,
-      prompt,
-      sandbox,
-      profile,
-      previousSessionId,
-      callbacks,
-    });
-  }
-  const command =
-    process.env.CODEX_BIN ||
-    (process.platform === "win32" ? "codex.cmd" : "codex");
-  const args = codexExecutionArgs({
-    workspace,
-    sandbox,
-    profile,
-    previousSessionId,
-    skipGitRepoCheck,
-    mcpServer,
-  });
-  const child = spawn(command, args, {
-    cwd: workspace,
-    env: process.env,
-    shell: process.platform === "win32",
-    stdio: ["pipe", "pipe", "pipe"],
-  });
-  child.stdin.end(prompt);
-  let output = "";
-  let buffer = "";
+
+export function assessmentWorkerSnapshots(activeAssessments) {
+  return [...activeAssessments.values()].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) {
+    return false;
+  }
+  return (
+    enqueueWorkspaceAssessment(queue, null, 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.",
+  );
+}
+
+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 ||
+    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.");
+  }
+  const sandboxMode = assignment?.sandbox_mode;
+  if (!new Set(["read-only", "workspace-write"]).has(sandboxMode)) {
+    throw new Error("EngineerOS assignment has an unsupported sandbox_mode.");
+  }
+  const rawProfile = assignment?.execution_profile ?? {};
+  const model =
+    typeof rawProfile.model === "string" ? rawProfile.model.trim() : "";
+  const reasoningEffort = rawProfile.reasoning_effort;
+  if (
+    reasoningEffort &&
+    !new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]).has(
+      reasoningEffort,
+    )
+  ) {
+    throw new Error(
+      "EngineerOS assignment has an unsupported reasoning effort.",
+    );
+  }
+  const agentRole = assignment?.agent_role;
+  const prompt = buildAgentHarnessPrompt({
+    agentRole,
+    agentDefinition: assignment?.agent_definition,
+    prompt: rawPrompt,
+    sandboxMode,
+    requiredOutputHeading: options.requiredOutputHeading,
+  });
+  return {
+    prompt,
+    agentRole,
+    sandboxMode,
+    sessionKey:
+      typeof assignment.session_key === "string" &&
+      assignment.session_key.trim()
+        ? assignment.session_key.trim()
+        : `project-${String(agentRole)}-${String(
+            assignment.purpose || "general",
+          )
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .slice(0, 80)}`,
+    profile: {
+      ...(model ? { model } : {}),
+      ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+    },
+  };
+}
+
+export async function stopProcess(child) {
+  if (!child || child.exitCode !== null) return;
+  if (typeof child.engineerOsCancel === "function") {
+    await child.engineerOsCancel();
+    return;
+  }
+  if (process.platform === "win32") {
+    await run(
+      "taskkill",
+      ["/pid", String(child.pid), "/t", "/f"],
+      process.cwd(),
+      { allowFailure: true },
+    );
+  } else {
+    child.kill("SIGTERM");
+  }
+}
+
+export async function workspaceSnapshot(workspace) {
+  const root = path.resolve(workspace);
+  const gitFiles = await run(
+    "git",
+    ["ls-files", "-z", "-co", "--exclude-standard"],
+    root,
+    { allowFailure: true },
+  );
+  const candidates =
+    gitFiles.code === 0
+      ? gitPathList(gitFiles.stdout)
+      : await workspaceFiles(root);
+  const ignoredFiles =
+    gitFiles.code === 0
+      ? gitPathList(
+          (
+            await run(
+              "git",
+              ["ls-files", "-z", "--others", "--ignored", "--exclude-standard"],
+              root,
+              { allowFailure: true },
+            )
+          ).stdout,
+        )
+      : [];
+  const trackedFiles =
+    gitFiles.code === 0
+      ? new Set(
+          gitPathList(
+            (
+              await run("git", ["ls-files", "-z", "--cached"], root, {
+                allowFailure: true,
+              })
+            ).stdout,
+          ),
+        )
+      : new Set();
+  const modifiedFiles =
+    gitFiles.code === 0
+      ? new Set(
+          gitPathList(
+            (
+              await run("git", ["diff", "--name-only", "-z", "--"], root, {
+                allowFailure: true,
+              })
+            ).stdout,
+          ),
+        )
+      : new Set();
+  const stagedFiles =
+    gitFiles.code === 0
+      ? new Set(
+          gitPathList(
+            (
+              await run(
+                "git",
+                ["diff", "--cached", "--name-only", "-z", "--"],
+                root,
+                { allowFailure: true },
+              )
+            ).stdout,
+          ),
+        )
+      : new Set();
+  const gitStatus =
+    gitFiles.code === 0
+      ? await run(
+          "git",
+          ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+          root,
+          { allowFailure: true },
+        )
+      : { stdout: "" };
+  const inventory = [];
+  let excludedFileCount = new Set(ignoredFiles).size;
+  const sortedCandidates = [...new Set(candidates)].sort();
+  for (let start = 0; start < sortedCandidates.length; start += 256) {
+    const batch = sortedCandidates.slice(start, start + 256);
+    const inspected = await Promise.all(
+      batch.map(async (relative) => ({
+        relative,
+        details: isShareablePath(relative)
+          ? await lstat(path.join(root, relative)).catch(() => null)
+          : null,
+      })),
+    );
+    for (const { relative, details } of inspected) {
+      if (!details?.isFile() || details.isSymbolicLink()) {
+        excludedFileCount += 1;
+        continue;
+      }
+      inventory.push({
+        path: relative,
+        size: details.size,
+        classification: evidenceClassification(relative),
+        git_state: inventoryGitState(
+          relative,
+          trackedFiles,
+          modifiedFiles,
+          stagedFiles,
+        ),
+      });
+      if (inventory.length > MAX_INVENTORY_FILES) {
+        throw new Error(
+          `Workspace contains more than ${MAX_INVENTORY_FILES.toLocaleString()} safe files. Configure repository exclusions for generated or data directories, then reconnect.`,
+        );
+      }
+    }
+  }
+  const representativeSources = representativeSourcePaths(inventory);
+  const evidenceCandidates = [...inventory].sort((left, right) => {
+    const priorityDifference =
+      evidencePriority(left, representativeSources) -
+      evidencePriority(right, representativeSources);
+    return priorityDifference || left.path.localeCompare(right.path);
+  });
+  const evidenceEntries = [];
+  let evidenceBytes = 0;
+  for (const entry of evidenceCandidates) {
+    if (
+      evidenceEntries.length >= MAX_EVIDENCE_FILES ||
+      entry.size > MAX_SHAREABLE_FILE_BYTES ||
+      evidenceBytes + entry.size > MAX_EVIDENCE_BYTES
+    ) {
+      continue;
+    }
+    evidenceEntries.push(entry);
+    evidenceBytes += entry.size;
+  }
+  const evidenceFiles = await readEvidenceFiles(root, evidenceEntries);
+  const archive = await createZip(evidenceFiles);
+  if (archive.length > MAX_ARCHIVE_BYTES) {
+    throw new Error(
+      "Prioritized workspace evidence exceeds the 25 MB archive limit. Configure repository exclusions for large source or data files, then reconnect.",
+    );
+  }
+  const inventoryJson = Buffer.from(
+    JSON.stringify({ version: 1, entries: inventory }),
+    "utf8",
+  );
+  const compressedInventory = await gzipBuffer(inventoryJson);
+  if (compressedInventory.length > MAX_COMPRESSED_INVENTORY_BYTES) {
+    throw new Error(
+      "Compressed workspace inventory exceeds 10 MB. Configure repository exclusions for generated or data directories, then reconnect.",
+    );
+  }
+  const head = await run("git", ["rev-parse", "HEAD"], root, {
+    allowFailure: true,
+  });
+  return {
+    inventory_base64: compressedInventory.toString("base64"),
+    evidence_archive_base64: archive.toString("base64"),
+    media_type: "application/zip",
+    workspace_name: path.basename(root),
+    workspace_kind: inventory.some(({ path: relative }) =>
+      isCodeBearing(relative),
+    )
+      ? "brownfield"
+      : "greenfield",
+    total_file_count: inventory.length,
+    evidence_file_count: evidenceFiles.length,
+    excluded_file_count: excludedFileCount,
+    omitted_evidence_file_count: inventory.length - evidenceFiles.length,
+    head_revision: head.code === 0 ? head.stdout.trim().slice(0, 128) : null,
+    working_tree_status_digest: sha256(gitStatus.stdout),
+    inventory_digest: sha256(inventoryJson),
+    evidence_policy_version: EVIDENCE_POLICY_VERSION,
+  };
+}
+
+function evidenceClassification(relative) {
+  const normalized = normalizePath(relative).toLowerCase();
+  const name = path.posix.basename(normalized);
+  const extension = path.posix.extname(name);
+  if (CODE_MARKERS.has(name)) return "manifest";
+  if (LOCK_FILE_NAMES.has(name)) return "lockfile";
+  if (
+    normalized.startsWith(".github/workflows/") ||
+    [
+      ".gitlab-ci.yml",
+      "azure-pipelines.yml",
+      "docker-compose.yml",
+      "docker-compose.yaml",
+      "dockerfile",
+      "jenkinsfile",
+    ].includes(name)
+  ) {
+    return "workflow";
+  }
+  if (
+    /(^|\/)(tests|__tests__)\//.test(normalized) ||
+    name.startsWith("test_") ||
+    name.includes(".test.") ||
+    name.includes(".spec.") ||
+    /^(jest|vitest|pytest|playwright|cypress)(\.|$)/.test(name)
+  ) {
+    return "test";
+  }
+  if (/(^|\/)(security|compliance|policy|policies)(\/|\.|$)/.test(normalized)) {
+    return "security_configuration";
+  }
+  if (
+    REPOSITORY_CONFIGURATION_NAMES.has(name) ||
+    /(^|\/)(eslint|ruff|mypy|tsconfig|biome|prettier)/.test(normalized)
+  ) {
+    return "repository_configuration";
+  }
+  if (ENTRYPOINT_NAMES.has(name)) return "entrypoint";
+  if (
+    /(^|\/)(api|routes|controllers)\//.test(normalized) ||
+    name.endsWith(".d.ts") ||
+    name.includes("openapi") ||
+    name.includes("swagger")
+  ) {
+    return "public_api";
+  }
+  if (
+    extension === ".md" ||
+    normalized.startsWith("docs/") ||
+    /(^|\/)(architecture|operations|runbook|deployment)(\/|\.|$)/.test(
+      normalized,
+    )
+  ) {
+    return "documentation";
+  }
+  if (CODE_EXTENSIONS.has(extension)) return "source";
+  return "other";
+}
+
+function inventoryGitState(relative, trackedFiles, modifiedFiles, stagedFiles) {
+  if (!trackedFiles.has(relative)) return "untracked";
+  const modified = modifiedFiles.has(relative);
+  const staged = stagedFiles.has(relative);
+  if (modified && staged) return "staged_and_modified";
+  if (modified) return "modified";
+  if (staged) return "staged";
+  return "clean";
+}
+
+function representativeSourcePaths(inventory) {
+  const representatives = new Set();
+  const groups = new Set();
+  for (const entry of inventory) {
+    if (entry.classification !== "source") continue;
+    const parts = entry.path.split("/");
+    const moduleName = parts.length > 1 ? parts[0] : ".";
+    const extension = path.posix.extname(entry.path).toLowerCase();
+    const group = `${moduleName}:${extension}`;
+    if (groups.has(group)) continue;
+    groups.add(group);
+    representatives.add(entry.path);
+  }
+  return representatives;
+}
+
+function evidencePriority(entry, representativeSources) {
+  const priorities = {
+    manifest: 0,
+    lockfile: 0,
+    workflow: 1,
+    security_configuration: 1,
+    repository_configuration: 1,
+    entrypoint: 2,
+    public_api: 2,
+    test: 3,
+    documentation: 4,
+  };
+  if (entry.classification in priorities)
+    return priorities[entry.classification];
+  if (
+    entry.classification === "source" &&
+    representativeSources.has(entry.path)
+  ) {
+    return 5;
+  }
+  return 6;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+async function readEvidenceFiles(root, entries) {
+  const files = [];
+  for (let start = 0; start < entries.length; start += 128) {
+    files.push(
+      ...(await Promise.all(
+        entries.slice(start, start + 128).map(async (entry) => ({
+          name: entry.path,
+          data: await readFile(path.join(root, entry.path)),
+        })),
+      )),
+    );
+  }
+  return files;
+}
+
+async function prepareRunWorkspace(workspace, runId, baseRevision) {
+  const source = path.resolve(workspace);
+  const root = path.join(os.homedir(), ".engineeros", "runs");
+  const target = path.join(root, runId);
+  await mkdir(root, { recursive: true });
+  const isGit =
+    (
+      await run("git", ["rev-parse", "--is-inside-work-tree"], source, {
+        allowFailure: true,
+      })
+    ).code === 0;
+  if (isGit) {
+    const exists = await stat(target).then(
+      () => true,
+      () => false,
+    );
+    if (!exists) {
+      const base = await worktreeBase(source, baseRevision);
+      await run("git", ["worktree", "add", "--detach", target, base], source);
+    }
+    return target;
+  }
+  const exists = await stat(target).then(
+    () => true,
+    () => false,
+  );
+  if (!exists) {
+    await mkdir(target, { recursive: true });
+    await copyWorkspace(source, target);
+    await run("git", ["init"], target);
+    await run("git", ["config", "user.name", "EngineerOS Connector"], target);
+    await run(
+      "git",
+      ["config", "user.email", "connector@engineeros.local"],
+      target,
+    );
+    await run("git", ["add", "-A"], target);
+    await run(
+      "git",
+      ["commit", "--allow-empty", "-m", "EngineerOS run baseline"],
+      target,
+    );
+  }
+  return target;
+}
+
+function launchCodexProcess(
+  workspace,
+  prompt,
+  sandbox,
+  callbacks,
+  profile = {},
+  previousSessionId,
+  skipGitRepoCheck = false,
+  mcpServer,
+) {
+  if (!mcpServer) {
+    return launchCodexAppServer({
+      workspace,
+      prompt,
+      sandbox,
+      profile,
+      previousSessionId,
+      callbacks,
+    });
+  }
+  const command =
+    process.env.CODEX_BIN ||
+    (process.platform === "win32" ? "codex.cmd" : "codex");
+  const args = codexExecutionArgs({
+    workspace,
+    sandbox,
+    profile,
+    previousSessionId,
+    skipGitRepoCheck,
+    mcpServer,
+  });
+  const child = spawn(command, args, {
+    cwd: workspace,
+    env: process.env,
+    shell: process.platform === "win32",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stdin.end(prompt);
+  let output = "";
+  let buffer = "";
   let finalMessage = "";
   let sessionId = previousSessionId || "";
-  child.stdout.setEncoding("utf8");
-  child.stdout.on("data", (chunk) => {
-    output += chunk;
-    buffer += chunk;
-    const lines = buffer.split(/\r?\n/);
-    buffer = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-        const event = JSON.parse(line);
+  let sessionCheckpoint = Promise.resolve();
+  let sessionCheckpointError;
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    output += chunk;
+    buffer += chunk;
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
         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" &&
-          typeof event.item.text === "string"
-        ) {
-          finalMessage = event.item.text;
-        }
-        callbacks.onEvent?.(event);
-      } catch {
-        callbacks.onEvent?.({
-          type: "agent.output",
-          message: line.slice(0, 500),
-        });
-      }
-    }
-  });
-  child.stderr.setEncoding("utf8");
-  child.stderr.on("data", (chunk) => {
-    output += chunk;
-    callbacks.onEvent?.({
-      type: "agent.stderr",
-      message: chunk.trim().slice(0, 500),
-    });
-  });
-  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)));
-    });
-  });
-  return { child, completed };
-}
-
-export function codexExecutionArgs({
-  workspace,
-  sandbox,
-  profile = {},
-  previousSessionId,
-  skipGitRepoCheck = false,
-  mcpServer,
-}) {
-  const optionArgs = [
-    "--json",
-    "--config",
-    codexConfigArgument("skills.include_instructions=false"),
-  ];
-  if (skipGitRepoCheck) optionArgs.push("--skip-git-repo-check");
-  if (profile.model) optionArgs.push("--model", profile.model);
-  if (profile.reasoning_effort) {
-    optionArgs.push(
-      "--config",
-      codexConfigArgument(
-        `model_reasoning_effort=${tomlLiteralString(profile.reasoning_effort)}`,
-      ),
-    );
-  }
-  if (mcpServer) {
-    const mcpArgs = [
-      mcpServer.connectorBin,
-      "mcp",
-      "--workspace",
-      mcpServer.workspace,
-      "--run-id",
-      mcpServer.runId,
-    ];
-    optionArgs.push(
-      "--config",
-      codexConfigArgument(
-        `mcp_servers.engineeros.command=${tomlLiteralString(process.execPath)}`,
-      ),
-      "--config",
-      codexConfigArgument(
-        `mcp_servers.engineeros.args=[${mcpArgs.map(tomlLiteralString).join(",")}]`,
-      ),
-    );
-  }
-  return previousSessionId
-    ? ["exec", "resume", ...optionArgs, previousSessionId, "-"]
-    : ["exec", ...optionArgs, "--sandbox", sandbox, "-C", workspace, "-"];
-}
-
-export function sanitizeAgentResponse(value) {
-  return String(value || "").replace(
-    /^Warning: Exceeded skills context budget(?: of \d+%)?\. All skill descriptions were removed and \d+ additional skills? (?:was|were) not included in the model-visible skills list\.\s*/i,
-    "",
-  );
-}
-
-function tomlLiteralString(value) {
-  const text = String(value);
-  if (text.includes("'''")) {
-    throw new Error(
-      "Codex configuration values cannot contain three consecutive apostrophes.",
-    );
-  }
-  return `'''${text}'''`;
-}
-
-function codexConfigArgument(override) {
-  return process.platform === "win32" ? `"${override}"` : override;
-}
-
-function launchAgentProcess(
-  workspace,
-  prompt,
-  sandbox,
-  config,
-  callbacks,
-  profile = {},
-  previousSessionId,
-  mcpContext,
-) {
-  if (config.agent_protocol === "acp") {
-    return launchAcpAgent(workspace, prompt, config, callbacks, {
-      persistent: mcpContext?.persistentAcp === true,
-      sessionKey: mcpContext?.sessionKey,
-      previousSessionId,
-      sandbox,
-      profile,
-    });
-  }
-  return launchCodexProcess(
-    workspace,
-    prompt,
-    sandbox,
-    callbacks,
-    profile,
-    previousSessionId,
-    config.skip_git_repo_check === true,
-    mcpContext?.runId
-      ? {
-          connectorBin: process.argv[1],
-          workspace: config.workspace,
-          runId: mcpContext.runId,
-        }
-      : undefined,
-  );
-}
-
-function runCodexCommand(command, args, cwd) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: process.env,
-      shell: process.platform === "win32",
-      windowsHide: true,
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => (stdout += chunk));
-    child.stderr.on("data", (chunk) => (stderr += chunk));
-    child.once("error", reject);
-    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
-  });
-}
-
-async function changedFilePaths(workspace) {
-  const tracked = await run(
-    "git",
-    ["diff", "--name-only", "-z", "HEAD", "--"],
-    workspace,
-  );
-  const untracked = await run(
-    "git",
-    ["ls-files", "-z", "--others", "--exclude-standard"],
-    workspace,
-  );
-  return [
-    ...new Set([
-      ...gitPathList(tracked.stdout),
-      ...gitPathList(untracked.stdout),
-    ]),
-  ].sort();
-}
-
-async function boundedDiff(workspace, changedFiles) {
-  const tracked = await run(
-    "git",
-    ["diff", "--binary", "HEAD", "--"],
-    workspace,
-  );
-  const untracked = new Set(
-    gitPathList(
-      (
-        await run(
-          "git",
-          ["ls-files", "-z", "--others", "--exclude-standard"],
-          workspace,
-        )
-      ).stdout,
-    ),
-  );
-  const parts = [tracked.stdout];
-  for (const relative of changedFiles.filter((item) => untracked.has(item))) {
-    const generated = await run(
-      "git",
-      ["diff", "--no-index", "--binary", "--", "/dev/null", relative],
-      workspace,
-      {
-        allowFailure: true,
-      },
-    );
-    parts.push(generated.stdout);
-  }
-  const diff = parts.filter(Boolean).join("\n");
-  if (!diff.trim()) throw new Error("The run produced no bounded diff.");
-  return diff;
-}
-
-export async function repositoryArchive(workspace) {
-  const listed = await run(
-    "git",
-    ["ls-files", "-z", "-co", "--exclude-standard"],
-    workspace,
-  );
-  const files = [...new Set(gitPathList(listed.stdout))].sort();
-  return createZip(
-    await Promise.all(
-      files.map(async (relative) => ({
-        name: relative,
-        data: await readFile(path.join(workspace, relative)),
-      })),
-    ),
-  );
-}
-
-async function workspaceFiles(root, current = root) {
-  const files = [];
-  for (const entry of await readdir(current, { withFileTypes: true })) {
-    const absolute = path.join(current, entry.name);
-    const relative = normalizePath(path.relative(root, absolute));
-    if (entry.isSymbolicLink()) continue;
-    if (entry.isDirectory()) {
-      files.push(...(await workspaceFiles(root, absolute)));
-    } else if (entry.isFile()) {
-      files.push(relative);
-    }
-  }
-  return files;
-}
-
-function isShareablePath(relative) {
-  const normalized = normalizePath(relative);
-  if (
-    !normalized ||
-    normalized === ".." ||
-    normalized.startsWith("../") ||
-    path.isAbsolute(normalized)
-  ) {
-    return false;
-  }
-  const parts = normalized.split("/");
-  if (parts.some((part) => EXCLUDED_DIRECTORIES.has(part.toLowerCase()))) {
-    return false;
-  }
-  if (
-    EXCLUDED_PATH_PREFIXES.some((prefix) =>
-      normalized.toLowerCase().startsWith(prefix),
-    )
-  ) {
-    return false;
-  }
-  const name = parts.at(-1)?.toLowerCase() ?? "";
-  if (EXCLUDED_FILE_EXTENSIONS.has(path.posix.extname(name))) return false;
-  if (name === ".env.example" || name === ".env.sample") return true;
-  if (
-    name === ".env" ||
-    name.startsWith(".env.") ||
-    [".npmrc", ".netrc", "credentials", "credentials.json"].includes(name) ||
-    /\.(?:key|pem|p12|pfx)$/i.test(name)
-  ) {
-    return false;
-  }
-  return true;
-}
-
-function isCodeBearing(relative) {
-  const name = path.posix.basename(relative).toLowerCase();
-  return (
-    CODE_MARKERS.has(name) || CODE_EXTENSIONS.has(path.posix.extname(name))
-  );
-}
-
-async function worktreeBase(workspace, requested) {
-  if (!requested || requested.startsWith("greenfield:")) return "HEAD";
-  const exists = await run(
-    "git",
-    ["cat-file", "-e", `${requested}^{commit}`],
-    workspace,
-    { allowFailure: true },
-  );
-  if (exists.code !== 0) {
-    throw new Error(
-      `The frozen base revision ${requested} is not available in this repository.`,
-    );
-  }
-  return requested;
-}
-
-export async function createZip(files) {
-  const localParts = [];
-  const centralParts = [];
-  let offset = 0;
-  let total = 0;
-  for (const file of files) {
-    const name = Buffer.from(normalizePath(file.name), "utf8");
-    const data = Buffer.from(file.data);
-    total += data.length;
-    if (total > MAX_ARCHIVE_BYTES)
-      throw new Error("Repository archive exceeds the 25 MB connector limit.");
-    const compressed = await deflate(data);
-    const crc = crc32(data);
-    const local = Buffer.alloc(30);
-    local.writeUInt32LE(0x04034b50, 0);
-    local.writeUInt16LE(20, 4);
-    local.writeUInt16LE(0x0800, 6);
-    local.writeUInt16LE(8, 8);
-    local.writeUInt32LE(crc, 14);
-    local.writeUInt32LE(compressed.length, 18);
-    local.writeUInt32LE(data.length, 22);
-    local.writeUInt16LE(name.length, 26);
-    localParts.push(local, name, compressed);
-
-    const central = Buffer.alloc(46);
-    central.writeUInt32LE(0x02014b50, 0);
-    central.writeUInt16LE(20, 4);
-    central.writeUInt16LE(20, 6);
-    central.writeUInt16LE(0x0800, 8);
-    central.writeUInt16LE(8, 10);
-    central.writeUInt32LE(crc, 16);
-    central.writeUInt32LE(compressed.length, 20);
-    central.writeUInt32LE(data.length, 24);
-    central.writeUInt16LE(name.length, 28);
-    central.writeUInt32LE(offset, 42);
-    centralParts.push(central, name);
-    offset += local.length + name.length + compressed.length;
-  }
-  const central = Buffer.concat(centralParts);
-  const end = Buffer.alloc(22);
-  end.writeUInt32LE(0x06054b50, 0);
-  end.writeUInt16LE(files.length, 8);
-  end.writeUInt16LE(files.length, 10);
-  end.writeUInt32LE(central.length, 12);
-  end.writeUInt32LE(offset, 16);
-  return Buffer.concat([...localParts, central, end]);
-}
-
-async function copyWorkspace(source, target) {
-  for (const entry of await readdir(source, { withFileTypes: true })) {
-    if ([".git", ".engineeros", "node_modules"].includes(entry.name)) continue;
-    const from = path.join(source, entry.name);
-    const to = path.join(target, entry.name);
-    if (entry.isDirectory()) {
-      await mkdir(to, { recursive: true });
-      await copyWorkspace(from, to);
-    } else if (entry.isFile()) {
-      await writeFile(to, await readFile(from));
-    }
-  }
-}
-
-function normalizePath(value) {
-  return String(value ?? "")
-    .trim()
-    .replaceAll("\\", "/")
-    .replace(/^\.\//, "");
-}
-
-function gitPathList(value) {
-  return String(value ?? "")
-    .split("\0")
-    .map(normalizePath)
-    .filter(Boolean);
-}
-
-function run(command, args, cwd, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      shell: false,
-      windowsHide: true,
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => (stdout += chunk));
-    child.stderr.on("data", (chunk) => (stderr += chunk));
-    child.once("error", reject);
+        if (
+          event.type === "item.completed" &&
+          event.item?.type === "agent_message" &&
+          typeof event.item.text === "string"
+        ) {
+          finalMessage = event.item.text;
+        }
+        callbacks.onEvent?.(event);
+      } catch {
+        callbacks.onEvent?.({
+          type: "agent.output",
+          message: line.slice(0, 500),
+        });
+      }
+    }
+  });
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    output += chunk;
+    callbacks.onEvent?.({
+      type: "agent.stderr",
+      message: chunk.trim().slice(0, 500),
+    });
+  });
+  const completed = new Promise((resolve, reject) => {
+    child.once("error", reject);
     child.once("close", (code) => {
-      const result = { code: code ?? 1, stdout, stderr };
-      if (code === 0 || options.allowFailure) resolve(result);
-      else
-        reject(
-          new Error(`${command} ${args.join(" ")} failed: ${stderr || stdout}`),
-        );
+      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)));
+      });
     });
-  });
-}
-
-function crc32(buffer) {
-  let crc = 0xffffffff;
-  for (const byte of buffer) {
-    crc ^= byte;
-    for (let bit = 0; bit < 8; bit += 1)
-      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
-  }
-  return (crc ^ 0xffffffff) >>> 0;
-}
+  });
+  return { child, completed };
+}
+
+export function codexExecutionArgs({
+  workspace,
+  sandbox,
+  profile = {},
+  previousSessionId,
+  skipGitRepoCheck = false,
+  mcpServer,
+}) {
+  const optionArgs = [
+    "--json",
+    "--config",
+    codexConfigArgument("skills.include_instructions=false"),
+  ];
+  if (skipGitRepoCheck) optionArgs.push("--skip-git-repo-check");
+  if (profile.model) optionArgs.push("--model", profile.model);
+  if (profile.reasoning_effort) {
+    optionArgs.push(
+      "--config",
+      codexConfigArgument(
+        `model_reasoning_effort=${tomlLiteralString(profile.reasoning_effort)}`,
+      ),
+    );
+  }
+  if (mcpServer) {
+    const mcpArgs = [
+      mcpServer.connectorBin,
+      "mcp",
+      "--workspace",
+      mcpServer.workspace,
+      "--run-id",
+      mcpServer.runId,
+    ];
+    optionArgs.push(
+      "--config",
+      codexConfigArgument(
+        `mcp_servers.engineeros.command=${tomlLiteralString(process.execPath)}`,
+      ),
+      "--config",
+      codexConfigArgument(
+        `mcp_servers.engineeros.args=[${mcpArgs.map(tomlLiteralString).join(",")}]`,
+      ),
+    );
+  }
+  return previousSessionId
+    ? ["exec", "resume", ...optionArgs, previousSessionId, "-"]
+    : ["exec", ...optionArgs, "--sandbox", sandbox, "-C", workspace, "-"];
+}
+
+export function sanitizeAgentResponse(value) {
+  return String(value || "").replace(
+    /^Warning: Exceeded skills context budget(?: of \d+%)?\. All skill descriptions were removed and \d+ additional skills? (?:was|were) not included in the model-visible skills list\.\s*/i,
+    "",
+  );
+}
+
+function tomlLiteralString(value) {
+  const text = String(value);
+  if (text.includes("'''")) {
+    throw new Error(
+      "Codex configuration values cannot contain three consecutive apostrophes.",
+    );
+  }
+  return `'''${text}'''`;
+}
+
+function codexConfigArgument(override) {
+  return process.platform === "win32" ? `"${override}"` : override;
+}
+
+function launchAgentProcess(
+  workspace,
+  prompt,
+  sandbox,
+  config,
+  callbacks,
+  profile = {},
+  previousSessionId,
+  mcpContext,
+) {
+  if (config.agent_protocol === "acp") {
+    return launchAcpAgent(workspace, prompt, config, callbacks, {
+      persistent: mcpContext?.persistentAcp === true,
+      sessionKey: mcpContext?.sessionKey,
+      previousSessionId,
+      sandbox,
+      profile,
+    });
+  }
+  return launchCodexProcess(
+    workspace,
+    prompt,
+    sandbox,
+    callbacks,
+    profile,
+    previousSessionId,
+    config.skip_git_repo_check === true,
+    mcpContext?.runId
+      ? {
+          connectorBin: process.argv[1],
+          workspace: config.workspace,
+          runId: mcpContext.runId,
+        }
+      : undefined,
+  );
+}
+
+function runCodexCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: process.env,
+      shell: process.platform === "win32",
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+async function changedFilePaths(workspace) {
+  const tracked = await run(
+    "git",
+    ["diff", "--name-only", "-z", "HEAD", "--"],
+    workspace,
+  );
+  const untracked = await run(
+    "git",
+    ["ls-files", "-z", "--others", "--exclude-standard"],
+    workspace,
+  );
+  return [
+    ...new Set([
+      ...gitPathList(tracked.stdout),
+      ...gitPathList(untracked.stdout),
+    ]),
+  ].sort();
+}
+
+async function boundedDiff(workspace, changedFiles) {
+  const tracked = await run(
+    "git",
+    ["diff", "--binary", "HEAD", "--"],
+    workspace,
+  );
+  const untracked = new Set(
+    gitPathList(
+      (
+        await run(
+          "git",
+          ["ls-files", "-z", "--others", "--exclude-standard"],
+          workspace,
+        )
+      ).stdout,
+    ),
+  );
+  const parts = [tracked.stdout];
+  for (const relative of changedFiles.filter((item) => untracked.has(item))) {
+    const generated = await run(
+      "git",
+      ["diff", "--no-index", "--binary", "--", "/dev/null", relative],
+      workspace,
+      {
+        allowFailure: true,
+      },
+    );
+    parts.push(generated.stdout);
+  }
+  const diff = parts.filter(Boolean).join("\n");
+  if (!diff.trim()) throw new Error("The run produced no bounded diff.");
+  return diff;
+}
+
+export async function repositoryArchive(workspace) {
+  const listed = await run(
+    "git",
+    ["ls-files", "-z", "-co", "--exclude-standard"],
+    workspace,
+  );
+  const files = [...new Set(gitPathList(listed.stdout))].sort();
+  return createZip(
+    await Promise.all(
+      files.map(async (relative) => ({
+        name: relative,
+        data: await readFile(path.join(workspace, relative)),
+      })),
+    ),
+  );
+}
+
+async function workspaceFiles(root, current = root) {
+  const files = [];
+  for (const entry of await readdir(current, { withFileTypes: true })) {
+    const absolute = path.join(current, entry.name);
+    const relative = normalizePath(path.relative(root, absolute));
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      files.push(...(await workspaceFiles(root, absolute)));
+    } else if (entry.isFile()) {
+      files.push(relative);
+    }
+  }
+  return files;
+}
+
+function isShareablePath(relative) {
+  const normalized = normalizePath(relative);
+  if (
+    !normalized ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    path.isAbsolute(normalized)
+  ) {
+    return false;
+  }
+  const parts = normalized.split("/");
+  if (parts.some((part) => EXCLUDED_DIRECTORIES.has(part.toLowerCase()))) {
+    return false;
+  }
+  if (
+    EXCLUDED_PATH_PREFIXES.some((prefix) =>
+      normalized.toLowerCase().startsWith(prefix),
+    )
+  ) {
+    return false;
+  }
+  const name = parts.at(-1)?.toLowerCase() ?? "";
+  if (EXCLUDED_FILE_EXTENSIONS.has(path.posix.extname(name))) return false;
+  if (name === ".env.example" || name === ".env.sample") return true;
+  if (
+    name === ".env" ||
+    name.startsWith(".env.") ||
+    [".npmrc", ".netrc", "credentials", "credentials.json"].includes(name) ||
+    /\.(?:key|pem|p12|pfx)$/i.test(name)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function isCodeBearing(relative) {
+  const name = path.posix.basename(relative).toLowerCase();
+  return (
+    CODE_MARKERS.has(name) || CODE_EXTENSIONS.has(path.posix.extname(name))
+  );
+}
+
+async function worktreeBase(workspace, requested) {
+  if (!requested || requested.startsWith("greenfield:")) return "HEAD";
+  const exists = await run(
+    "git",
+    ["cat-file", "-e", `${requested}^{commit}`],
+    workspace,
+    { allowFailure: true },
+  );
+  if (exists.code !== 0) {
+    throw new Error(
+      `The frozen base revision ${requested} is not available in this repository.`,
+    );
+  }
+  return requested;
+}
+
+export async function createZip(files) {
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  let total = 0;
+  for (const file of files) {
+    const name = Buffer.from(normalizePath(file.name), "utf8");
+    const data = Buffer.from(file.data);
+    total += data.length;
+    if (total > MAX_ARCHIVE_BYTES)
+      throw new Error("Repository archive exceeds the 25 MB connector limit.");
+    const compressed = await deflate(data);
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    localParts.push(local, name, compressed);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(8, 10);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(compressed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt32LE(offset, 42);
+    centralParts.push(central, name);
+    offset += local.length + name.length + compressed.length;
+  }
+  const central = Buffer.concat(centralParts);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(central.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...localParts, central, end]);
+}
+
+async function copyWorkspace(source, target) {
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    if ([".git", ".engineeros", "node_modules"].includes(entry.name)) continue;
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      await mkdir(to, { recursive: true });
+      await copyWorkspace(from, to);
+    } else if (entry.isFile()) {
+      await writeFile(to, await readFile(from));
+    }
+  }
+}
+
+function normalizePath(value) {
+  return String(value ?? "")
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(/^\.\//, "");
+}
+
+function gitPathList(value) {
+  return String(value ?? "")
+    .split("\0")
+    .map(normalizePath)
+    .filter(Boolean);
+}
+
+function run(command, args, cwd, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      shell: false,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.once("error", reject);
+    child.once("close", (code) => {
+      const result = { code: code ?? 1, stdout, stderr };
+      if (code === 0 || options.allowFailure) resolve(result);
+      else
+        reject(
+          new Error(`${command} ${args.join(" ")} failed: ${stderr || stdout}`),
+        );
+    });
+  });
+}
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1)
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}