## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The test-drive command starts an isolated instance for local
testing.
> - Source startup builds shared packages before it starts the server.
> - An interrupted build can leave an empty lock directory.
> - Later starts wait without output and fail after 60 seconds.
> - This pull request recovers abandoned locks and shows build progress.
> - Local testing can start again without manual lock removal.
## Linked Issues or Issue Description
**What happened?**
`pnpm paperclipai test-drive` stopped at “Starting Paperclip server…” in
a source checkout. A leftover plugin build lock caused a silent
60-second wait and then a timeout.
**Expected behavior**
Startup should recover an abandoned build lock. It should show when it
waits for a live build. An interrupted or failed build should not leave
partial output that the next start accepts as complete.
**Steps to reproduce**
1. Leave an empty `node_modules/.cache/paperclip-plugin-build-deps.lock`
directory after an interrupted build.
2. Make the shared or plugin SDK build output out of date.
3. Run `pnpm paperclipai test-drive --api-key placeholder --no-browser`
with a fresh data directory.
4. Observe the silent wait at server startup.
**Paperclip version or commit**
Reproduced at `2083bf6f9`.
**Deployment mode**
Local source checkout with an isolated embedded PostgreSQL instance.
Related work: #12894 added test-drive. #12898 restored its credential
inputs. Neither change handles abandoned workspace build locks. No
duplicate fix was found.
## What Changed
- Publish a lock directory with an owner record in one rename.
- Recover locks after their owner and compiler exit. Recover legacy
empty locks after two minutes.
- Keep the lock until the compiler stops on SIGINT or SIGTERM.
- Print build and lock-wait progress.
- Record source, dependency, compiler-config, and output content
fingerprints only after a successful compile. Recover partial output
even when modification times are unchanged.
- Add 12 process-level regression tests and update the development
guide.
## Verification
- `node --test scripts/__tests__/ensure-plugin-build-deps.test.mjs`: 12
tests pass.
- `pnpm exec vitest run --config cli/vitest.config.ts
cli/src/__tests__/test-drive.test.ts`: 32 tests pass.
- `pnpm --filter paperclipai typecheck`: passed.
- `pnpm --filter paperclipai build`: passed.
- Live smoke tests: fresh startup and startup with an abandoned lock
both reach ready state. The API and UI respond. The command creates the
company and CEO and enables worktree execution. Test instances stop
cleanly.
- Full repository `pnpm -r typecheck` and `pnpm build`: passed.
- Full Vitest suite coverage completed using the repository-supported
server, chat, workspace, and serialized shards. The initial local run
needed the fresh-worktree fake native-provider binary built and focused
reruns for port/socket races and load-related timeouts; all affected
tests passed on rerun. Suites skipped by fail-fast exits were run
separately and passed. The initial serial `pnpm test:run` was stopped in
favor of these shards.
- Greptile: 5/5 on commit `8b5a790c2af06a52b5dc76e5f52331966df990b8`,
with all review threads resolved.
- CI: 31 checks passed and two Storybook checks intentionally skipped.
The initial workspace and browser jobs were interrupted by runner
shutdowns; both passed on the second attempt. Build, typecheck, canary
dry run, all general and serialized tests, all browser shards, security
checks, and final verification summaries are green. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/34654730783)
## Risks
- This changes shared source-build locking for the CLI and plugin SDK
commands.
- Legacy locks have no owner identity. Recovery uses a two-minute age
threshold for empty legacy directories.
- Startup reads and hashes source and output files to verify the build
cache. Identical direct builds reuse the cache. Changed or partial
output requires a rebuild.
- A reused process ID can delay recovery. Live owner or compiler
processes keep their lock.
- No database, API, or UI contract changes.
## Model Used
OpenAI GPT-6 in Codex, with reasoning, tool use, code execution, and
process-level testing. A more specific API model identifier and
context-window size are not exposed in this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` OR (b) described the issue in-PR following the relevant issue
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Dotta