paperclipai/paperclip · error

In-place workspace realization requires the Codex CLI…

Error message

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

What it means

Engine-capability guard for the Codex local adapter: in-place workspace realization (running directly in the source checkout) requires the Codex CLI engine; the caller explicitly pinned engine=acp, whose archive-staging model cannot support it, so the configuration is rejected rather than silently staging an archive.

Solutions

1. Use the Codex CLI engine for in-place workspace realization.
2. Use archive staging without in-place realization for ACP.

When it happens

Trigger: Thrown at packages/adapters/codex-local/src/server/acp.ts:93 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
  if (raw === "acp") return { engine: "acp", explicit: true };
  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);
  // Engine availability must never change the agent's execution or permission contract.
  if (selection.engine === "cli") return selection;
  const unavailable = (reason: string): CodexEngineSelection => ({
    ...selection,
    unavailableReason: `${reason} Repair the ACP setup, or explicitly set engine=cli to use the CLI engine.`,
  });
  const target = readAdapterExecutionTarget({
    executionTarget: input.executionTarget,
    legacyRemoteExecution: input.executionTransport?.remoteExecution,
  });
  if (target?.workspaceRealization?.mode === "in_place") {
    return unavailable("In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.");
  }
  const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
  const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
  if (filesystemScope || networkScope) {
    return unavailable("Local filesystem/network confinement requires the Codex CLI engine; ACP confinement is not supported.");
  }

  const reason = await codexAcpUnavailableReason(input);
  return reason ? unavailable(reason) : selection;
}

View on GitHub (pinned to 3f1d897a7c)