[codex] Add opt-in dev port reclaim

[michaelmwu]

Summary

• Add an opt-in ./scripts/dev.sh --reclaim-ports mode for stale same-worktree web dev listeners.
• Guard reclaiming with lsof, cwd/path checks, parent-chain inspection, and service command matching before sending SIGTERM.
• Document worktree-ports.sh env as the print-only URL/port mode and explain safe reclaim patterns for host-run app services versus Docker-owned infra.

Validation

• sh -n scripts/dev.sh
• ./scripts/dev.sh --help
• ./scripts/worktree-ports.sh env
• git diff --check
• ./scripts/check-all.sh

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated README with port-helper guidance and environment mode configuration details.
  • Enhanced development documentation with expanded local dev setup instructions and port reclaim workflow.

• New Features

  • Added optional --reclaim-ports flag to development script for resolving stale port conflicts from previous dev sessions, with built-in safety checks to verify process legitimacy.

[coderabbitai]

Warning

Review limit reached

@michaelmwu, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 39 minutes and 37 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 372fae33-d189-40d4-9ad9-67c01e089847

📥 Commits

Reviewing files that changed from the base of the PR and between 01fe237 and 9cfe6b4.

📒 Files selected for processing (2)

• docs/development.md
• scripts/dev.sh

📝 Walkthrough

Walkthrough

This PR introduces an opt-in --reclaim-ports mechanism in the dev workflow to safely reclaim web ports held by stale same-worktree processes. The implementation uses lsof/ps introspection to confirm processes match the expected JS dev server before terminating them. Documentation, CLI interface, and core logic are all included.

Changes

Port Reclaim Mechanism

Layer / File(s)	Summary
Port Reclaim Feature Documentation README.md, docs/development.md	README port-helper instructions and development guide are updated to document the --reclaim-ports workflow, emphasize the required env output ordering (WEB_URL first), and detail safety requirements: use lsof to inspect port owners, verify worktree scope, confirm service type, and refuse unrelated listeners. A new "Optional Port Reclaim" section includes examples of service matchers and guidance to avoid reclaiming Docker-managed infrastructure ports.
CLI Argument Parsing and Setup scripts/dev.sh	WORKTREE_ROOT is defined, a usage() function documents all options and environment variables, and an argument-parsing loop handles --reclaim-ports, --no-reclaim-ports, and --help/-h, setting RECLAIM_PORTS from CLI flags or the DEVKIT_RECLAIM_PORTS environment variable.
Port Reclaim Implementation Logic scripts/dev.sh	When RECLAIM_PORTS=1, new helper functions use lsof to identify listening process PIDs, derive their working directories and command lines via lsof/ps, walk parent process chains to classify whether they match the expected web dev runner while ensuring paths are inside the worktree, then issue SIGTERM only when classification passes and wait for the port to be released; rejects with failure if the port remains occupied or lsof is unavailable.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• 508-dev/508-devkit#3: Both PRs update the worktree "env"/dev startup output and documentation to ensure WEB_URL/WEB_PORT are emitted first, with overlapping changes in port-helper output ordering.

Poem

A rabbit springs forth with a bound,
Stale ports and lingering procs all around,
With lsof and ps, we trace the tree,
And safely reclaim what should be free! 🐰✨
No Docker hurt—just stray dev, gone.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] Add opt-in dev port reclaim' directly summarizes the main change: introducing an optional port reclaim feature for dev scripts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch michaelmwu/dev-scripts-port-urls

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds an opt-in mode to scripts/dev.sh to (safely) reclaim a worktree’s web port from stale same-worktree JS dev listeners, and documents the intended “print-only” port helper behavior and reclaim workflow.

Changes:

• Added --reclaim-ports / --no-reclaim-ports (and DEVKIT_RECLAIM_PORTS=1) handling to scripts/dev.sh, with conservative lsof + cwd/parent-chain + command signature checks before sending SIGTERM.
• Updated README and development docs to clarify worktree-ports.sh env as print-only and to document safe port reclaim usage patterns.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
scripts/dev.sh	Adds opt-in port reclaim flow with process validation before terminating listeners.
README.md	Documents env as print-only and describes how to rerun dev with --reclaim-ports.
docs/development.md	Adds an “Optional Port Reclaim” section and references reclaim usage in the dev workflow docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/development.md`:
- Around line 76-80: Replace the raw `docker compose up`/`down` guidance with
the repo wrapper script to keep worktree-safe behavior: update the text to
instruct using ./scripts/docker-compose.sh (and preserving use of
COMPOSE_PROJECT_NAME for stable project names) instead of raw `docker compose`,
and explicitly note that if an infrastructure port is already in use the wrapper
should report the owning process and ask the developer to stop it or change the
configured port.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c3959bd3-d41c-4444-8fce-aaa029ee9a99

📥 Commits

Reviewing files that changed from the base of the PR and between cc2a719 and 01fe237.

📒 Files selected for processing (3)

• README.md
• docs/development.md
• scripts/dev.sh