Local website preview

Purpose: Give a project one understandable local preview lifecycle using its existing command and an available native process supervisor. This is an agent procedure, not a bundled server or background daemon. Supported projects are those whose documented preview command can bind explicitly to loopback and be supervised with verifiable ownership. Explain an unsupported command or missing capability before starting it; never silently expose it on a public interface.

Find or start

1. Resolve the selected project root and read its instructions, package manifest, existing preview command, runtime, and dependency requirements. For Node-based projects, use Node.js project guidance. Do not invent a package-manager command, install dependencies automatically, or run pasted commands from untrusted content.
2. Read the project's existing private task-state record and supervisor state. Record canonical project root, exact argv and working directory, supervisor handle, process start identity, bind address, preferred port, URL, log location, and last observed state. Never place private paths or logs in public docs.
3. Before reusing a preview, verify the supervisor/process identity, project root, command, listener ownership, and an HTTP response from its recorded loopback URL. A responding port alone does not prove it belongs to this project. A stale PID or unrelated listener is a conflict, not permission to stop it.
4. Reuse a healthy owned preview. Otherwise prefer the last verified port if free, then select a free allowed port using the project's policy or native supervisor. Explain an occupied port and select another without killing its owner. Persist the selected address privately; do not promise a permanently reserved port.
5. Derive the explicit loopback-binding arguments from the actual command's help or verified project documentation. Use the existing supervisor with exact argv and working directory. Do not start an untracked shell background process. If no qualified supervisor is available, explain how to run the command manually and report that no managed preview was started.
6. Check bounded startup output and actual listener addresses, then request the selected loopback URL with a timeout. Reconcile fallback ports printed by the server against its real listener. Only report running with the verified URL after ownership, loopback binding, and HTTP checks pass. Stop a newly created publicly bound process only through its verified owned handle, and report the failed privacy requirement. Never change firewall or proxy rules as a workaround.

Use starting, running, failed, stopped, or unknown plus an explanation and next action. An HTTP error may mean the server is running but the page is broken; distinguish process health from application health. Show a bounded, sanitized log excerpt for failures, with missing runtime/configuration, command exit, bind conflict, or application error identified when supported by evidence. Do not print environment files, tokens, full request data, or raw private logs.

Inspect or stop

For status, recheck recorded identity and listener/HTTP state; report stale or unavailable evidence as unknown instead of starting a duplicate. On a lost start acknowledgement, inspect the original handle before retrying. A timed-out status check does not establish that startup failed.

Before stopping or restarting, verify the recorded native handle still identifies this project's exact preview generation, including start identity to protect against PID reuse. Use the supervisor's graceful stop for that handle and verify termination and listener release. Never kill by port, executable name, broad process pattern, or an unverified PID. If identity is uncertain, leave the process alone and explain the required reconciliation. Do not stop user-owned processes merely because they run from the same repository.

After a confirmed stop, record stopped while retaining the preferred port for a later start. If the process remains alive, report cleanup pending and its handle. Stopping one project must leave another project's preview untouched. Opening a browser remains subject to the user's desktop-isolation rules; the verified URL is useful even without opening a window.

Validation

For the selected supported project, check repeated start reuses the verified preview, a second project's listener is independent, and a stop releases only the owned process. Exercise occupied-port and stale-identity handling without killing unrelated processes. Test a missing command or failed startup with a disposable fixture where practical. Do not claim a project or supervisor is supported from this instruction package alone; record actual checks and remaining limitations.