{"record":{"id":"21ecc7520f849917","repo":"paperclipai/paperclip","slug":"in-place-workspace-realization-requires-the-codex","errorCode":null,"errorMessage":"In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.","messagePattern":"In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapters/codex-local/src/server/acp.ts","lineNumber":92,"sourceCode":"  if (raw === \"cli\") return { engine: \"cli\", explicit: true };\n  return { engine: \"acp\", explicit: false };\n}\n\nexport function resolveCodexExecutionEngine(config: Record<string, unknown>): CodexEngineSelection {\n  return normalizeEngine(config.engine);\n}\n\nexport async function resolveCodexExecutionEngineForRun(\n  input: CodexEngineResolutionInput,\n): Promise<CodexEngineSelection> {\n  const selection = normalizeEngine(input.config.engine);\n  const target = readAdapterExecutionTarget({\n    executionTarget: input.executionTarget,\n    legacyRemoteExecution: input.executionTransport?.remoteExecution,\n  });\n  if (target?.workspaceRealization?.mode === \"in_place\") {\n    if (selection.explicit && selection.engine === \"acp\") {\n      throw new Error(\"In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.\");\n    }\n    return {\n      engine: \"cli\",\n      explicit: selection.explicit,\n      ...(!selection.explicit\n        ? { fallbackReason: \"In-place workspace realization must run without ACP archive staging.\" }\n        : {}),\n    };\n  }\n  const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);\n  const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);\n  if (filesystemScope || networkScope) {\n    if (selection.explicit && selection.engine === \"acp\") {\n      throw new Error(\"Local filesystem/network confinement requires the Codex CLI engine; ACP confinement is not supported.\");\n    }\n    return {\n      engine: \"cli\",\n      explicit: selection.explicit,","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapters/codex-local/src/server/acp.ts#L74-L110","documentation":"Thrown by resolveCodexExecutionEngineForRun when the execution target's workspaceRealization.mode is 'in_place' AND the adapter config explicitly sets engine='acp'. In-place realization operates directly on the workspace directory, but the ACP lane stages work via archives — the two are incompatible, so explicitly requesting ACP under in-place realization is unsatisfiable. The function refuses rather than silently ignoring the in-place requirement.","triggerScenarios":"An execution target with workspaceRealization.mode='in_place' combined with adapter config { engine: 'acp' }. normalizeEngine marks engine explicit=true, readAdapterExecutionTarget returns the in_place target, and the explicit-acp branch throws.","commonSituations":"Pinning engine=acp for performance while the execution target is configured for in-place workspace realization; a remote/execution-target template that defaults to in_place being combined with an acp-pinned adapter config; migrating a config after workspaceRealization was added to the target schema.","solutions":["Drop engine='acp' (leave unset) so the resolver auto-falls back to CLI with a fallbackReason, preserving in-place realization.","Or set engine='cli' explicitly to match the in-place workspace mode.","If ACP is required, change the execution target's workspaceRealization.mode away from 'in_place' (use archive staging)."],"exampleFix":"// before\nconfig = { engine: \"acp\" };\nexecutionTarget.workspaceRealization.mode = \"in_place\";\n// after\nconfig = { engine: \"cli\" };\nexecutionTarget.workspaceRealization.mode = \"in_place\";","handlingStrategy":"validation","validationCode":"const target = readAdapterExecutionTarget({\n  executionTarget: input.executionTarget,\n  legacyRemoteExecution: input.executionTransport?.remoteExecution,\n});\nif (config.engine === \"acp\" && target?.workspaceRealization?.mode === \"in_place\") {\n  // pick one: in_place -> use cli; or acp -> switch workspace mode off in_place\n  config.engine = \"cli\";\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat engine=acp and workspaceRealization.mode=in_place as mutually exclusive in config validation.","Validate adapter config + execution target together at load time before run start.","Prefer leaving engine unset so the resolver can auto-fallback with a logged reason."],"tags":["codex","acp","engine-selection","workspace-realization","configuration"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}