Track host-owned temporary HTTP server lifecycle friction

[fitchmultz]

Summary

External testing still reports manual pkill plus fresh ports are needed for ad-hoc local fixture servers. Leaked host servers block later runs and cause recurring friction.

Current wrapper state

• TOOL_CONTRACT documents that temporary HTTP servers launched outside the tool are host-owned.
• COMMAND_REFERENCE points extension maintainers to startAgentBrowserContractFixtureServer() for deterministic localhost fixture servers instead of ad-hoc long-lived python3 -m http.server processes.
• SUPPORT_MATRIX tracks this as RQ-0115.

Ownership boundary

This native tool is intentionally a thin wrapper around upstream agent-browser. It does not allocate local ports, track arbitrary background PIDs, or clean up shell-started servers.

In-scope next action

Keep this as the local tracking link for future design work if fixture-server lifecycle becomes product scope. Any real wrapper-managed server feature needs a separate design pass with ownership, cleanup, security, and UX constraints; do not add an implicit server manager as part of routine browser navigation.

[fitchmultz]

Orchestrator triage on current main (b7cf5b3, released as 0.2.37): this is valid workflow friction, but it is outside the native browser tool’s current ownership boundary.

Evidence checked:

• docs/SUPPORT_MATRIX.md tracks RQ-0115 as host-owned/out-of-scope and docs-mitigated.
• docs/TOOL_CONTRACT.md states temporary HTTP servers launched outside the tool are host-owned; the native tool does not allocate ports, track background server PIDs, or clean them up.
• docs/COMMAND_REFERENCE.md points extension maintainers to startAgentBrowserContractFixtureServer() instead of ad-hoc long-lived python3 -m http.server processes.
• test/helpers/agent-browser-harness.ts provides the deterministic fixture-server helper for repo tests.

Fresh validation run:

• npm run verify ✅
• npm run verify -- real-upstream ✅
• Published package state: npm latest is pi-agent-browser-native@0.2.37, matching current release.

Status: blocked on product/design decision. A wrapper-managed fixture/server lifecycle feature would be new product scope and needs a separate design pass covering ownership, cleanup, port allocation, security, UX, tests, and docs. Until that decision exists, no further local code change is justified; leaked shell-started servers remain host/operator cleanup.