paperclipai/paperclip · error · Error

In-place workspace realization requires the Codex CLI engine

Error message

In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.

What it means

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.

Source

Thrown at packages/adapters/codex-local/src/server/acp.ts:92

  if (raw === "cli") return { engine: "cli", explicit: true };
  return { engine: "acp", explicit: false };
}

export function resolveCodexExecutionEngine(config: Record<string, unknown>): CodexEngineSelection {
  return normalizeEngine(config.engine);
}

export async function resolveCodexExecutionEngineForRun(
  input: CodexEngineResolutionInput,
): Promise<CodexEngineSelection> {
  const selection = normalizeEngine(input.config.engine);
  const target = readAdapterExecutionTarget({
    executionTarget: input.executionTarget,
    legacyRemoteExecution: input.executionTransport?.remoteExecution,
  });
  if (target?.workspaceRealization?.mode === "in_place") {
    if (selection.explicit && selection.engine === "acp") {
      throw new Error("In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.");
    }
    return {
      engine: "cli",
      explicit: selection.explicit,
      ...(!selection.explicit
        ? { fallbackReason: "In-place workspace realization must run without ACP archive staging." }
        : {}),
    };
  }
  const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
  const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
  if (filesystemScope || networkScope) {
    if (selection.explicit && selection.engine === "acp") {
      throw new Error("Local filesystem/network confinement requires the Codex CLI engine; ACP confinement is not supported.");
    }
    return {
      engine: "cli",
      explicit: selection.explicit,

View on GitHub (pinned to 67001ec6eb)

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).

Example fix

// before
config = { engine: "acp" };
executionTarget.workspaceRealization.mode = "in_place";
// after
config = { engine: "cli" };
executionTarget.workspaceRealization.mode = "in_place";

Defensive patterns

Strategy: validation

Validate before calling

const target = readAdapterExecutionTarget({
  executionTarget: input.executionTarget,
  legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
if (config.engine === "acp" && target?.workspaceRealization?.mode === "in_place") {
  // pick one: in_place -> use cli; or acp -> switch workspace mode off in_place
  config.engine = "cli";
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/21ecc7520f849917. Report an issue: GitHub.