@engineeros/connector 0.9.2 → 0.10.2

package/src/runner.mjs

@@ -1,1324 +1,1368 @@
-import { spawn } from "node:child_process";
-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 } from "node:zlib";
-import { launchAcpAgent } from "./acp-client.mjs";
-import {
-  buildAgentHarnessPrompt,
-  normalizeAgentStructuredOutput,
-} from "./agent-harness.mjs";
-
-const deflate = promisify(deflateRaw);
-const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
-const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
-const MAX_WORKSPACE_FILES = 5_000;
-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 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);
-  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,
-  };
-}
-
-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,
-) {
-  const execution = workspaceAssessmentExecution(assignment);
-  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 = launchAgentProcess(
-    config.workspace,
-    prompt,
-    execution.sandboxMode,
-    config,
-    callbacks,
-    execution.profile,
-  );
-  callbacks.onProcess?.(controller.child);
-  const completed = await controller.completed;
-  const report = normalizeAgentStructuredOutput(
-    completed.finalMessage,
-    execution.requiredOutputHeading,
-  );
-  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 {
-    report_markdown: report,
-    observed_head_revision: endingHead,
-    changed_files: changeImpact.changedFiles,
-    change_impact_markdown: changeImpact.markdown,
-  };
-}
-
-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 = 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,
-  };
-}
-
-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.",
-      );
-    }
-    return {
-      protocol: "acp",
-      name: config.agent_name || path.basename(config.agent_command),
-      version: config.agent_version || "ACP v1",
-    };
-  }
-  const codex = await inspectCodexCli(workspace);
-  return { protocol: "codex", name: "Codex CLI", version: codex.version };
-}
-
-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 === "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 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 === "acp.agent_message_chunk" &&
-    event.update?.content?.type === "text"
-  ) {
-    return { kind: "message", delta: event.update.content.text };
-  }
-  if (event.type === "acp.agent_thought_chunk") {
-    return {
-      kind: "thought",
-      message: "Agent is reasoning through the request",
-    };
-  }
-  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") {
-    return { kind: "message", delta: event.item.text };
-  }
-  const message = promptProgressMessage(event);
-  return message ? { kind: "status", message } : null;
-}
-
-export function assessmentStreamDelta(event) {
-  const streamEvent = promptStreamEvent(event);
-  if (streamEvent?.kind !== "message" || !streamEvent.delta) return null;
-  return event.type === "item.completed"
-    ? `${streamEvent.delta.trim()}\n\n`
-    : streamEvent.delta;
-}
-
-function assessmentCommandMilestone(command) {
-  const value = Array.isArray(command)
-    ? command.join(" ")
-    : String(command || "");
-  const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
-  if (!normalized) return "Inspecting repository evidence";
-  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 requiredOutputHeading =
-    assignment?.assessment_mode === "incremental"
-      ? "# Workspace Assessment Delta"
-      : "# Workspace Assessment";
-  return {
-    ...connectorExecution(assignment, { requiredOutputHeading }),
-    requiredOutputHeading,
-  };
-}
-
-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(["low", "medium", "high", "xhigh"]).has(reasoningEffort)
-  ) {
-    throw new Error(
-      "EngineerOS assignment has an unsupported reasoning effort.",
-    );
-  }
-  const agentRole = assignment?.agent_role;
-  const prompt = buildAgentHarnessPrompt({
-    agentRole,
-    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;
-  await child.engineerOsCancel?.();
-  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", "-co", "--exclude-standard"],
-    root,
-    { allowFailure: true },
-  );
-  const candidates =
-    gitFiles.code === 0
-      ? gitFiles.stdout.split(/\r?\n/).map(normalizePath).filter(Boolean)
-      : await workspaceFiles(root);
-  const files = [];
-  let excludedFileCount = 0;
-  let totalBytes = 0;
-  for (const relative of [...new Set(candidates)].sort()) {
-    if (!isShareablePath(relative)) {
-      excludedFileCount += 1;
-      continue;
-    }
-    const absolute = path.join(root, relative);
-    const details = await lstat(absolute).catch(() => null);
-    if (!details?.isFile() || details.isSymbolicLink()) {
-      excludedFileCount += 1;
-      continue;
-    }
-    if (details.size > MAX_SHAREABLE_FILE_BYTES) {
-      excludedFileCount += 1;
-      continue;
-    }
-    totalBytes += details.size;
-    if (totalBytes > MAX_ARCHIVE_BYTES) {
-      throw new Error(
-        "Shareable workspace files exceed 25 MB. Exclude large generated or data files before onboarding.",
-      );
-    }
-    files.push({ name: relative, data: await readFile(absolute) });
-    if (files.length > MAX_WORKSPACE_FILES) {
-      throw new Error(
-        `Workspace exceeds the ${MAX_WORKSPACE_FILES.toLocaleString()}-file onboarding limit. Exclude generated files first.`,
-      );
-    }
-  }
-  const archive = await createZip(files);
-  const head = await run("git", ["rev-parse", "HEAD"], root, {
-    allowFailure: true,
-  });
-  return {
-    archive_base64: archive.toString("base64"),
-    media_type: "application/zip",
-    workspace_name: path.basename(root),
-    workspace_kind: files.some(({ name }) => isCodeBearing(name))
-      ? "brownfield"
-      : "greenfield",
-    file_count: files.length,
-    excluded_file_count: excludedFileCount,
-    head_revision: head.code === 0 ? head.stdout.trim().slice(0, 128) : null,
-  };
-}
-
-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,
-) {
-  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);
-        if (
-          event.type === "thread.started" &&
-          typeof event.thread_id === "string"
-        ) {
-          sessionId = event.thread_id;
-        }
-        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"];
-  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, "-"];
-}
-
-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
-      ? {
-          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()) {
-      if (!EXCLUDED_DIRECTORIES.has(entry.name.toLowerCase())) {
-        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;
-}
+import { spawn } from "node:child_process";
+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 } from "node:zlib";
+import { launchAcpAgent } from "./acp-client.mjs";
+import { launchCodexAppServer } from "./codex-app-server.mjs";
+import {
+  buildAgentHarnessPrompt,
+  normalizeAgentStructuredOutput,
+} from "./agent-harness.mjs";
+
+const deflate = promisify(deflateRaw);
+const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
+const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_WORKSPACE_FILES = 5_000;
+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 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);
+  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,
+  };
+}
+
+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,
+) {
+  const execution = workspaceAssessmentExecution(assignment);
+  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 = launchAgentProcess(
+    config.workspace,
+    prompt,
+    execution.sandboxMode,
+    config,
+    callbacks,
+    execution.profile,
+  );
+  callbacks.onProcess?.(controller.child);
+  const completed = await controller.completed;
+  const report = normalizeAgentStructuredOutput(
+    completed.finalMessage,
+    execution.requiredOutputHeading,
+  );
+  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 {
+    report_markdown: report,
+    observed_head_revision: endingHead,
+    changed_files: changeImpact.changedFiles,
+    change_impact_markdown: changeImpact.markdown,
+  };
+}
+
+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,
+  };
+}
+
+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.",
+      );
+    }
+    return {
+      protocol: "acp",
+      name: config.agent_name || path.basename(config.agent_command),
+      version: config.agent_version || "ACP v1",
+    };
+  }
+  const codex = await inspectCodexCli(workspace);
+  return { protocol: "codex", name: "Codex CLI", version: codex.version };
+}
+
+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 === "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 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;
+}
+
+export function assessmentStreamDelta(event) {
+  const streamEvent = promptStreamEvent(event);
+  if (streamEvent?.kind !== "message" || !streamEvent.delta) return null;
+  return event.type === "item.completed"
+    ? `${streamEvent.delta.trim()}\n\n`
+    : streamEvent.delta;
+}
+
+function assessmentCommandMilestone(command) {
+  const value = Array.isArray(command)
+    ? command.join(" ")
+    : String(command || "");
+  const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
+  if (!normalized) return "Inspecting repository evidence";
+  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 requiredOutputHeading =
+    assignment?.assessment_mode === "incremental"
+      ? "# Workspace Assessment Delta"
+      : "# Workspace Assessment";
+  return {
+    ...connectorExecution(assignment, { requiredOutputHeading }),
+    requiredOutputHeading,
+  };
+}
+
+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(["low", "medium", "high", "xhigh"]).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;
+  await child.engineerOsCancel?.();
+  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", "-co", "--exclude-standard"],
+    root,
+    { allowFailure: true },
+  );
+  const candidates =
+    gitFiles.code === 0
+      ? gitFiles.stdout.split(/\r?\n/).map(normalizePath).filter(Boolean)
+      : await workspaceFiles(root);
+  const files = [];
+  let excludedFileCount = 0;
+  let totalBytes = 0;
+  for (const relative of [...new Set(candidates)].sort()) {
+    if (!isShareablePath(relative)) {
+      excludedFileCount += 1;
+      continue;
+    }
+    const absolute = path.join(root, relative);
+    const details = await lstat(absolute).catch(() => null);
+    if (!details?.isFile() || details.isSymbolicLink()) {
+      excludedFileCount += 1;
+      continue;
+    }
+    if (details.size > MAX_SHAREABLE_FILE_BYTES) {
+      excludedFileCount += 1;
+      continue;
+    }
+    totalBytes += details.size;
+    if (totalBytes > MAX_ARCHIVE_BYTES) {
+      throw new Error(
+        "Shareable workspace files exceed 25 MB. Exclude large generated or data files before onboarding.",
+      );
+    }
+    files.push({ name: relative, data: await readFile(absolute) });
+    if (files.length > MAX_WORKSPACE_FILES) {
+      throw new Error(
+        `Workspace exceeds the ${MAX_WORKSPACE_FILES.toLocaleString()}-file onboarding limit. Exclude generated files first.`,
+      );
+    }
+  }
+  const archive = await createZip(files);
+  const head = await run("git", ["rev-parse", "HEAD"], root, {
+    allowFailure: true,
+  });
+  return {
+    archive_base64: archive.toString("base64"),
+    media_type: "application/zip",
+    workspace_name: path.basename(root),
+    workspace_kind: files.some(({ name }) => isCodeBearing(name))
+      ? "brownfield"
+      : "greenfield",
+    file_count: files.length,
+    excluded_file_count: excludedFileCount,
+    head_revision: head.code === 0 ? head.stdout.trim().slice(0, 128) : null,
+  };
+}
+
+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);
+        if (
+          event.type === "thread.started" &&
+          typeof event.thread_id === "string"
+        ) {
+          sessionId = event.thread_id;
+        }
+        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,
+      "",
+    )
+    .trimStart();
+}
+
+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()) {
+      if (!EXCLUDED_DIRECTORIES.has(entry.name.toLowerCase())) {
+        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;
+}