## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Isolated development workspaces need a repeatable run, verify, and
repair procedure
> - Port conflicts can be caused by another live Paperclip run that
keeps respawning and reclaiming a configured port
> - Restarting the target service alone does not resolve that class of
conflict
> - This pull request teaches the workspace-repair skill to identify the
owner, guard the master checkout, and stop the conflicting run before
repair
> - The benefit is safer recovery guidance that addresses the actual
port owner instead of creating restart loops
## Linked Issues or Issue Description
### What happened?
The workspace repair procedure could recommend restarting a managed
service while a separate live run still owned and reclaimed the
configured port.
### Expected behavior
The procedure identifies the owning process/run, protects the live
master checkout, and stops the conflicting owner before restarting the
intended service.
### Steps to reproduce
1. Start two managed workspace runs configured for the same fixed port.
2. Restart only the target workspace service.
3. Observe the sibling run reclaiming the port and the repair failing to
hold.
### Paperclip version or commit
`origin/master` at `02e2dd271`
### Deployment mode
Local dev; built from source; not adapter-specific; not
database-related.
## What Changed
- Expand the port-conflict diagnosis to distinguish dead owners from
live respawning runs.
- Add master-checkout safety checks before killing or restarting
processes.
- Document owner-first recovery and explicit verification of final port
ownership.
- Tighten the success checklist so a repaired workspace must prove
health and correct ownership.
## Verification
- Reviewed the rendered Markdown diff and command sequence for
consistent owner-first recovery.
- No executable code changes are included in this documentation-only PR.
## Risks
- Low risk: documentation and agent procedure only.
- Process termination guidance remains intentionally guarded by owner
identification and master-worktree checks.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, GPT-5.3 Codex, reasoning with repository tool use and
code execution; context-window size was not exposed by the runtime. The
original change also credits Claude Fable 5 in the commit trailer.
## 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
#` / `Refs #` 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: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
a739a8dfba