Brain

002-paperclip-phantom-workspaces

2 min read

❌ Lesson: Paperclip Creates Phantom Workspaces

Date: 2026-08-03 Severity: High — code stranded outside git Affected: All Paperclip agent work

What Happened

Paperclip has a workspace management system that overrides the agent’s configured cwd. When a project has no entry in the project_workspaces table, Paperclip automatically creates a shared_workspace at an internal path:

/root/.paperclip/instances/default/projects/{company}/{project}/_default/

This directory:

  • Has NO .git folder
  • Is invisible to normal file browsing
  • Gets ignored by the git-first policy
  • Is where agents write code that nobody can find

The agent’s adapter_config.cwd was set to /root/repos/huible, but Paperclip’s execution workspace system overrode it and ran OpenCode in the phantom _default folder instead.

Root Cause

Paperclip’s execution_workspaces table had 39 entries all pointing at the _default phantom path. The project_workspaces table had no Huible entry at all — so Paperclip fell back to creating shared workspaces dynamically.

The Fix

  1. Created project_workspaces entries for Huible pointing at /root/repos/huible
  2. Updated InvestInMe from old path /root/bhakta.us/InvestInMe → /root/repos/investinme
  3. Deleted 39 phantom execution workspaces pointing at _default folders
  4. Verified zero _default paths remain

Rule Going Forward

When configuring a new Paperclip project, ALWAYS:

  1. Create a project_workspaces entry pointing at the git repo
  2. Verify with: SELECT name, cwd FROM project_workspaces WHERE project_id = '...'
  3. Check that execution workspaces use the git path, not _default
  4. Never trust the agent adapter_config.cwd alone — the workspace table wins

Graph View