mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 10:48:12 +02:00
a739a8dfba
## 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>