fix(cli): limit background process port scans

[catrielmuller]

Issue

No linked issue. Follow-up to an internal report that background-process port discovery could contribute to Bun memory growth.

Context

Background process support inferred listening ports by repeatedly scanning active process trees. VS Code and Agent Manager do not surface inferred ports, and even in the TUI the scan is only needed shortly after startup so users can see a detected dev-server port.

This limits the scan surface area and makes port discovery explicitly opt-in for clients that surface inferred ports.

Implementation

Port discovery now requires KILO_BACKGROUND_PROCESS_PORTS=true, and only the TUI worker sets that environment variable. Regular background-process publish/output updates no longer trigger inferred port scans.

For the TUI, inference starts shortly after launch, retries at a slower interval, and stops after startup, when a port is found, or when the process exits. The ps/lsof fallback path also has an abort timeout so stuck scan commands cannot accumulate.

Screenshots / Video

N/A - no visual changes.

How to Test

Manual/local verification

• Agent: bun test test/kilocode/background-process.test.ts from packages/opencode/ passed.
• Agent: bun run typecheck from packages/opencode/ passed.
• Agent: bun run script/check-opencode-annotations.ts --base origin/main passed.
• Agent: git diff --check passed.
• Agent: pre-push bun turbo typecheck passed after refreshing workspace links with bun install.

Reviewer test steps

1. In the TUI, start a background process that opens a local port and confirm the process detail can still report an inferred port shortly after startup.
2. In VS Code or Agent Manager, start a background process and confirm it still starts/stops normally without inferred port scanning.
3. Confirm explicit ready.port still reports that ready port for VS Code clients.

Blocked checks and substitute verification

• No blocked checks.

Checklist

• Issue linked above, or exception explained
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.

Get in Touch

Catriel Muller

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Both issues from the previous review have been addressed in the follow-up commit:

• WARNING resolved (index.ts:368): delete result.KILO_BACKGROUND_PROCESS_PORTS is now present in env(), preventing the env var from leaking into spawned child process environments.
• SUGGESTION resolved (index.ts:209): done(active) has been renamed to finished(active), eliminating the shadowing confusion with the two local done closures in connected() and waitExit().

Files Reviewed (1 file changed)

• packages/opencode/src/kilocode/background-process/index.ts - both previous issues fixed, no new issues

---

_{Reviewed by claude-4.6-sonnet-20260217 · 268,559 tokens}

_{Review guidance: REVIEW.md from base branch main}