Introduction

After a Coding Agent starts multiple local services, it can be difficult to determine which process owns each port on the machine, why it is still running, and whether it can be safely closed. In Sessions that involve multi-service debugging or long-running background tasks, this lack of visibility can lead to port conflicts, accidental termination of other services, or leftover zombie processes. dsh-port-inspector is an auxiliary plugin for the DeepSeek Harness Web environment that addresses tracking the source of listening ports and handling them safely.

Core Features

The plugin helps developers understand the current environment by centrally displaying listening ports, applications, PIDs, and listen addresses, and by distinguishing sources from available handling actions.

  • Port Overview: Centrally view listening ports, applications, PIDs, and listen addresses across projects and the system.
  • Source Identification: Distinguish the current session, other DSH sessions, and ordinary external processes.
  • Safe Stop: Perform identity-verified stop operations for DSH-managed processes.
  • End Process: Provide direct termination capability for external processes with complete identity information.
  • Open Directory: Quickly jump to the associated project directory from port details.
  • Compose Detection: Display Compose files, services, images, containers, and port mappings.
  • Startup Chain: View the full startup relationship from the root process to the listening process.
  • Quick Filtering: Support searching, filtering, and sorting by port, application, PID, project, and session.
  • Copy Details: Copy port, process, source, and session information with one click.
  • UI Synchronization: Automatically follow DSH’s language, light/dark theme, and design style.
  • Read-Only Diagnostics: Provide a read-only port_list Tool for diagnosing port conflicts.

Installation and Enablement

Prerequisites:
* Windows operating system
* Node.js >= 22.19.0
* A runnable DeepSeek Harness (DSH)
* pnpm available in PATH
* Target DSH Profile is web

Installation Methods:

  1. Install via npm (recommended)
    dsh plugin --profile web add dsh-port-inspector@latest
  1. Download and install from GitHub Release
    gh release download --repo ianho7/dsh-port-inspector --pattern 'dsh-port-inspector-*.tgz' --output 'dsh-port-inspector-latest.tgz'
    dsh plugin --profile web add '.\dsh-port-inspector-latest.tgz'
  1. Compile from source and install
    git clone https://github.com/ianho7/dsh-port-inspector.git
    cd dsh-port-inspector
    npm install
    npm run build
    npm pack --ignore-scripts
    dsh plugin --profile web add ".\$PackageFile"

*Note: On first installation or when using `koffi`, if you encounter `ERR_PNPM_IGNORED_BUILDS`, set `allowBuilds: koffi: true` in the `pnpm-workspace.yaml` for the corresponding Profile.*

Enable:

After installation, start DSH Web:

dsh web

After the browser opens, create a new DeepSeek Harness Session, let the Agent start local services, and then open Port Inspector in the sidebar.

Typical Usage

  1. View Port Information: In the Port Inspector panel, view the port, PID, application, project, creation time, source, and handling action.
  2. Perform a Handling Action:
    • For managed resources started by DSH, choose “Stop DeepSeek Harness Task”.
    • For external processes that meet the safety conditions, choose “End This Process”.
  3. Confirm the Result: After confirmation, wait for a fresh scan, check the portReleased result reported by the interface, and confirm whether the port has actually been released.

Notes and Limitations

  • Platform Limitations: Only local Windows execution environments and TCP listening are supported.
  • Identity Verification: Verified attribution requires a PID, creation time, and a verifiable Windows parent-process chain; it must not rely solely on the command line, directory, time, or port number.
  • Lifecycle Management:
    • DeepSeek Harness-managed targets preferentially use the Job/Terminal lifecycle; if Managed shutdown fails, it does not automatically escalate to force-killing the PID.
    • For external targets, termination is permitted only after user confirmation, re-verification of identity, and explicit selection of a single PID owned by the same user.
  • Security Boundaries:
    • It does not terminate external process trees, does not automatically elevate privileges, and does not read environment secrets.
    • System processes, processes owned by other users, protected processes, targets with incomplete identity, and targets with insufficient permissions remain read-only.
  • Attribution Mechanism:
    • After installing or updating the Bundle, the target Profile must be restarted and a new task must be created to obtain source attribution.
    • Source records are retained only within the current DeepSeek Harness runtime cycle and do not retroactively attribute processes that already existed before restart.
  • Compatibility: Some Stock DeepSeek Harness versions combined with Windows ConPTY first return a LocalTerminalHandle with PID = 0; the compatibility layer waits for the PTY to publish a positive PID only when both the exact version and exact handle shape match.
  • Uninstall Behavior: Uninstalling the plugin cleans up only its own resources and does not automatically terminate user processes.

Summary

dsh-port-inspector is a port management utility focused on Windows local development. By connecting Windows listening ports and process chains with DeepSeek Harness Sessions and Tool Calls, it provides traceable and securely controllable management of development service sources. It is suitable for developers who need to distinguish same-named processes and resolve port conflicts in parallel multi-project development.