paperclip-dev-workspace-run-verify-fix skill

Paperclip Dev Workspace Run / Verify / Fix

This skill is for Paperclip-specific development workspaces whose service is started through project execution workspace runtime services, typically a worktree service such as paperclip-dev.

Success means all of these are true:

detached workaround

• the service was started through the normal managed runtime path, not a

instance database

• the worktree database is a full bootstrapped isolated clone of the primary

expected URL

• /api/health returns status: ok and bootstrapStatus: ready
• the root page returns 200 and does not show the first-admin setup gate
• the board user can log in with their normal dev credentials
• the app shows populated cloned data, not only a manually copied auth user
• the main control plane shows the service as running / healthy with the

running / healthy

• the served workspace app also knows about that service and shows it as

workspace: readlink /proc//cwd resolves inside the target worktree, not a sibling workspace

• the process that owns the service port really belongs to the target

If any item fails, keep fixing. Do not mark the issue done because one probe passed.

Hard rules

repo with the real instance .env) is never a workspace repair target. Never point a worktree runtime service at it, never git worktree add into it or under /.paperclip/worktrees/, and never edit its .env while repairing a workspace. Managed workspaces run in their own folders, for example ~/.paperclip-worktrees/instances//….

• The master checkout /srv/paperclip/home/paperclipai/paperclip (the primary

alone. The service:paperclip-dev port is pinned in service config, so a sibling workspace's process can own the port and still answer health checks. Confirm the port owner's real cwd (readlink /proc//cwd) before and after every repair; the runtime row's recorded cwd and pid can be fabricated by port adoption.

• Never trust a running / healthy runtime row or a passing /api/health

database, build, or test commands.

• Read doc/DEVELOPING.md before running Paperclip CLI, dev server, worktree,

database operations. Do not use psql, raw embedded-Postgres commands, or ad hoc row copying for the normal fix path.

• Use the Paperclip CLI and API as the source of truth for worktree and

it does not prove the isolated workspace has the full bootstrapped database.

• Do not manually copy only auth rows as the final fix. That proves login, but

processes when the task is about a reusable workspace service.

• Prefer managed runtime start/stop routes over pnpm dev or detached shell

worktree.

• Avoid destructive git or database actions. Preserve user changes in the

when code changed.

• Run the smallest verification that proves the repair. Add focused tests only

commit link. Set a clear final status.

• Leave an issue comment with root cause, exact fix, verification, and any

Inputs to collect

Use environment variables when available. Do not print API keys or passwords.

• PAPERCLIPAPIURL: main control-plane API URL
• PAPERCLIPAPIKEY: agent API key
• PAPERCLIPRUNID: current run id for runtime-service mutations
• PAPERCLIPTASKID: current issue id
• PAPERCLIPCOMPANYID: company id
• PAPERCLIPAGENTID: current agent id
• execution workspace id for the worktree service
• runtime workspace command id, usually service:paperclip-dev
• expected service URL, for example http://paperclip-dev:40631
• dev credential owner, if the user supplied one; never post the password

If the execution workspace id or service command id is missing, read the issue, project, or execution-workspace API records first. Do not guess and start an unmanaged server on a random port.

Normal run sequence

Use this when the user says to start the workspace, start it again, or fix a workspace that should be freshly ready.

own words.

1. Confirm the latest issue comment and restate the success condition in your

its real cwd, and check whether any sibling workspace's runtime row also claims the same port (see "Port conflicts and workspace identity").

1. Inspect current runtime state from the main control plane.
2. Check the target port for conflicts: identify the current port owner and

through its managed control path and verify the port stays free. Do this before restarting the target; otherwise the owner can respawn and reclaim the port.

1. If another live workspace or agent run owns the port, stop that owner

is any doubt about database completeness.

1. Stop any managed instance of the target runtime service.
2. Reseed the worktree with a full clone from the primary instance when there

visibility, and port-owner identity from both the main control plane and served workspace app.

1. Start the runtime service through the managed runtime API.
2. Verify health, bootstrap state, login readiness, populated data, runtime

the narrowest repair step.

1. If a verification item fails, diagnose that exact failure and loop back to

1. Comment on the issue and set the final disposition.

Managed start / stop

Use the runtime-service endpoints on the main control plane. Include X-Paperclip-Run-Id so the mutation is associated with the current heartbeat.

curl -sS -X POST \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID/runtime-services/stop" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  --data-binary '{"workspaceCommandId":"service:paperclip-dev"}'

curl -sS -X POST \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID/runtime-services/start" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  --data-binary '{"workspaceCommandId":"service:paperclip-dev"}'

If the API returns an existing service, treat that as a candidate only. Verify its real /api/health and its port-owner identity before trusting it.

Port conflicts and workspace identity

service:paperclip-dev pins an explicit port in service config, so every workspace that realizes that service claims the same port. On start, service adoption will adopt whatever process already owns the port when its command line looks similar — and it records the requested cwd, not the owner's real cwd. Two consequences:

process exists; whichever workspace URL you open, you get that one process