DSH 任务账本 can drift from the OS processes that are actually running. This may be caused by process leaks, orphan processes, or unclear ownership. dsh-treekeeper is designed to address these issues. It reconciles the DSH task ledger with the OS process tree, identifies ownership, detects leaks, and safely governs them.

Installation and Enablement

Installing the plugin registers it in the specified DSH profile.

dsh plugin --profile web add dsh-treekeeper

You must restart DSH Web after installation for it to take effect.

Core Features

The plugin provides the following capabilities:

  • Process Sampling and Attribution: Samples the process tree of the current DSH host and attributes each process to the task that created it. It also detects duplicate commands, orphan processes, and long-running plugin child processes.
  • Session Reconciliation: Compares the task ledger with the subagent tree of the root session to identify the relationship between processes and tasks.
  • Safe Governance: Provides protected termination of entire process trees.
  • Plugin Identification: Identifies the owning plugin of a process from node_modules paths in its command line.
  • Panel Display:
    • The DSH host child-process section is collapsed by default, with the count displayed in the title.
    • The panel header displays the host type (derived from the host process executable path and command line, without relying on environment variables).
    • The desktop application’s own Electron process appears as a standalone process group in the unattributed section.
  • Finding Confidence: Finding confidence is divided into three levels (exact, indicative, and inferred) to help determine termination targets.

Configuration

Configuration applies to the current process only and reverts to defaults after restart.

Field Default Valid Values Purpose
pollMs 0 0 (sample on request) or 2000–600000 ms Background sampling interval
allowKill true Boolean Protected process-tree termination switch
extraWhitelistPids [] Array of PIDs Additional protected PIDs

Typical Usage

  • Open the panel: Click the dsh-mini-utility-dock launcher in the lower-left corner of the page to open the global panel. You can also open the panel from the session title bar and focus that session.
  • View cache: View facts already cached by the session.
  • Terminate operation: Confirm the termination target through identity verification.

Security and Boundaries

Platform and Fallback

  • Platform limitation: Windows only. On non-Windows platforms, unsupported_platform is reported.
  • CIM fallback: If CIM (Windows Management Instrumentation) is unavailable, the plugin falls back to read-only sampling; attribution and termination features are disabled.

Access Control

  • Credential reuse: DSH 0.1.0-rc.7+ reuses the signed cookie of the Connection.
  • Admission rules:
    • Host with a Connection: Determined by the Connection’s Host/Origin validation and signed cookie.
    • Host without a Connection: Determined by this plugin’s guard using the TCP peer address, Fetch Metadata, Origin, and loopback Host.
  • Remote reachability: When the host is configured with trustedHosts and listens on 0.0.0.0, a remote client with a valid browser session can invoke endpoints, including kill.
  • Write restriction: Only POST requests are accepted.

Termination Guardrails

To prevent accidental termination, termination operations include the following guardrails:

  1. Activation: The first click activates the button and remains valid for 6 seconds.
  2. Confirmation: The second click triggers a browser confirmation dialog.
  3. Snapshot: A complete snapshot no older than 15 seconds is required.
  4. Identity verification: When a request arrives, PID creation times are checked against the snapshot.
  5. Pre-execution recheck: Before termination, the system resamples and checks creation times once more.
  6. Attribution limit: Only processes whose attribution root is the DSH host can be terminated; unattributed processes are used for investigation only.
  7. Non-terminable list: Critical system processes, the current host, the startup chain, and PIDs in extraWhitelistPids cannot be terminated.
  8. Whitelist limit: Additional whitelisted PIDs only serve as attribution roots for investigation; their child processes are visible but cannot be terminated.
  9. Protected child processes: If the real-time sampled tree before termination contains any protected PID, the entire operation is rejected.

Limitations

  • PID mapping: There is no stable PID mapping between Jobs and OS processes.
  • Command-line matching: Command-line matching is only used for investigation and does not trigger automatic actions.
  • Logging: Findings and termination results are written to $DSH_HOME/treekeeper/history.l.

Summary

dsh-treekeeper is a tool focused on process-tree reconciliation and safe governance. Through strict admission validation and multiple layers of guardrails, it ensures that cleaning up leaked or orphan processes does not affect critical system services or the current task. For scenarios requiring fine-grained management of the DSH process environment, this plugin provides the necessary visibility and control capabilities.