Diagnostics and troubleshooting
pnport 0.1.2 is available. Its diagnostics apply to the published CLI. Full filesystem/process compatibility remains incomplete. Check installation and known limits for unresolved macOS initialization and cancellation failures.
Start with doctor
Run pnport doctor for human-readable project, platform, injection, and cache checks. pnport doctor --json writes one schema-version-1 object to stdout with ready and typed checks. ready: false exits 125; ready: true does not guarantee that a specific executable can accept virtualization.
Earlier 0.1.0 reports a dependency-view conflict for an empty or cache-only physical node_modules, including caches left by Vitest. Version 0.1.2 supports hidden tool-cache coexistence; see filesystem behavior. The doctor JSON schema and exit codes remain unchanged.
Exit codes and streams
When a child starts successfully, pnport passes through its exit status. On macOS, intermittent initialization and cancellation failures can return 125 instead of the expected signal-derived status; this remains unresolved in 0.1.2. Stable PNPORT_* codes on stderr distinguish a pnport failure from a child that exits with the same number. Normal missing files remain child-visible filesystem errors rather than always stopping the supervisor.
pnport diagnostics go to stderr; child stdout and stderr are inherited rather than captured. Default logging includes errors and necessary notices. --log-level debug can expose paths, so review debug logs before sharing them. pnport diagnostics must not contain file contents, environment values, full argument vectors, or captured child output. There is no pnport telemetry or hosted diagnostic service. Report a sanitized reproduction through GitHub Issues.