dsh-harbor

DSH Harbor

Evidence-first governance for the DeepSeek Harness plugins already installed on your machine. Capability Inventory • Declared vs Detected • Runtime Attribution • Conflict Detection • Version Drift • Change Timeline • Upgrade Preflight

npm: @zseven-w/dsh-harbor · Current plugin release: 0.1.0-rc.3 · Tested with DSH 0.1.5-rc.2

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

Why DSH Harbor

DSH plugins run in the host's Node realm with the same local permissions as DSH itself. Harbor does not pretend this can be solved with a score or a badge: it keeps a read-only, evidence-backed ledger of what is installed, what each plugin declares, what its code and live host actually expose, where plugins collide, and what changed since the previous scan.

🔎 Capability Inventory

Harbor scans every installed third-party bundle across DSH profiles and reports a fixed 13-capability vocabulary. Source findings carry file:line evidence; manifest, filesystem, and runtime facts state their origin explicitly.

🤝 Declared vs Detected

Plugins may declare dsh.capabilities in package.json. Harbor reconciles the declaration against detection, exposes missing and unknown ids, and fails closed on malformed declarations instead of letting one bad package break the whole report.

🟢 Runtime Attribution

Inside a live DSH host, Harbor enumerates tools, providers, and routes, then attributes them only to plugins installed in the active profile. Missing host registries remain visible as coverage gaps rather than empty proof.

⚠️ Conflict Detection

The ledger finds same-profile tool names, route prefixes, provider ids, client-module ids, and order-sensitive message hooks. A quoted route used by a client does not make that client the route owner.

🧭 Two Version Axes

Cross-profile drift is local and always offline. The optional upstream check is separate, explicit, registry-aware, credential-redacted, and cached for six hours. link: and file: installs never masquerade as current registry versions.

🕰️ Change Timeline

Snapshots track additions, removals, version transitions, profile moves, capability changes, and claim changes. Even two artifacts exchanging profiles are reported as concrete per-profile transitions.

🛫 Upgrade Preflight

Before you move DSH to a new version, Harbor installs that exact version into its own cache, then import-probes every installed plugin against it in a child process, checks dsh.client.inject ids against the target's client module graph, and checks host peer ranges. The answer is per profile: boots after the upgrade, or blocked — by which plugin, with the real link-time error.

🧷 One Settings Check

The only user-settings check with a known upgrade casualty: when a built-in agent preset is renamed (code → ptc in DSH 0.1.2) the stored agent-presets.default is not migrated and every new session fails. Preflight reports the stale value against the target's preset list.

How it works

~/.dsh/profiles/*
  ├─ installed package + provenance
  │    registry artifact | link: working tree | file: snapshot
  ├─ declared
  │    package.json + cordis.patch.yml
  ├─ static
  │    bounded source scan + file:line evidence
  ├─ runtime (when loaded inside DSH)
  │    tools + providers + routes + profile-scoped attribution
  ├─ versions
  │    local cross-profile drift + opt-in registry check
  └─ snapshot
       additions + removals + version/profile/capability/claim changes

The CLI and the settings page consume the same scan core. The default path is offline. Only harbor scan --check-updates, harbor preflight, or the panel's Check for updates / Upgrade preflight actions contact a registry.

Upgrade preflight

harbor preflight --list                 # dist-tags, recent versions, locally cached host trees
harbor preflight --dsh next             # or a concrete version: --dsh 0.1.5-rc.2
harbor preflight --dsh 0.1.5-rc.2 --json

What runs, in order:

1. The target is resolved (a dist-tag needs one registry request) and @deepseek-ai/dsh@ is installed into /hosts/ with npm install -g --prefix. A completed install is reused; the global npm prefix and your profiles are never written.
2. Every installed third-party plugin's server entry is imported in a fresh node child. A module.register resolve hook rewrites @deepseek-ai/* imports to the target tree, so the plugin links against the version under evaluation while its own dependencies keep resolving from its real install. Missing packages and removed exports fail at link time and are reported verbatim — the DSH loader is fail-loud, so one such plugin blocks the whole profile.
3. dsh.client.inject / external ids are checked against the packages in the target that declare a web client module (DSH ≥ 0.1.5 skips unknown ids silently, so this never errors on its own). Host peer ranges are matched with npm's prerelease rule.
4. agent-presets.default from settings.yaml is checked against the target's built-in presets.

Verdicts distinguish an entry import failure (blocks boot) from DSH >= 0.2 rejecting host peer ranges (blocked by host, the plugin is skipped). The version gate uses the target host semver library with prereleases included; exact-version risk exemptions are not assumed. Entry imports does not verify activation, settings, tools, or devices. Unresolvable/unknown results are inconclusive. Exit code 3 means at least one plugin has not passed preflight or a known settings issue remains. Node >= 20.6 is required for the resolve hook.

Outside a profile — in CI, or for a package you have not installed — name the subjects explicitly:

harbor preflight --dsh next --plugin .                        # this repository (build it first)
harbor preflight --dsh next --pack @scope/some-plugin@1.2.3   # fetched from the registry, deps installed with scripts disabled

Contract diff between two DSH versions

harbor host-diff --from 0.1.1-rc.2 --to 0.1.5-rc.1

Installs both versions into the cache and reports what a plugin could have depended on that moved: packages added/removed, web client modules added/removed, built-in presets, and — by importing each official package's entry in a child — every export name added or removed per package. This is the machine-readable changelog the release notes do not carry; the settingsNamespace removal that broke plugins on 0.1.5 shows up here as an export removal in @deepseek-ai/dsh-settings. Exit code 3 when anything was removed.

GitHub Action

Plugin authors can run the same preflight on every pull request and every night against the next dist-tag:

- uses: actions/checkout@v4
- run: pnpm install --frozen-lockfile && pnpm run build   # the built server entry is what gets probed
- uses: ZSeven-W/dsh-harbor@v0.1.0-rc.3
  with:
    dsh: next        # version or dist-tag; default latest

The job fails with exit code 3 when the plugin would block boot, warns on stale declarations (fail-on-advisories: true turns those into failures), writes a job summary, and uploads the JSON report. The target host tree is cached per DSH version.

Ecosystem board and release watch

This repository also runs two scheduled workflows: an hourly watch on @deepseek-ai/dsh dist-tags that commits a host-diff for every tag move, and a nightly board that import-probes every npm package declaring dsh.bundle or dsh.client (about 4,500 at the time of writing) against the current next, incrementally — only plugins whose latest version changed are re-probed, and a full run happens when a DSH dist-tag moves. Results are published as a static page and a JSON index under board/. Probing executes each package's module top level in a disposable CI runner; that scan never runs on a user's machine, where preflight only touches plugins the user installed.

Evidence you can inspect

Tier · What Harbor actually knows declared · A manifest or filesystem fact, such as client injection or an on-disk realm copy. runtime · A registry entry observed in the active DSH host. static · A source behavior matched with inspectable file:line evidence. heuristic · A pattern-based inference that deserves human review.

Harbor reports facts, not a risk score. Spawning a subprocess may be the entire purpose of a plugin; the useful question is whether that capability is visible, declared, attributable, and expected.

Install into DSH

DSH is a separate package. Install the tested host version if you do not already have it:

npm install -g @deepseek-ai/dsh@latest

For local development, install the current checkout into a Web profile and restart DSH once:

dsh plugin --profile web add link:/path/to/dsh-harbor
dsh web

For a registry install, use the prerelease next tag:

dsh plugin --profile web add @zseven-w/dsh-harbor@next
dsh web

Open Settings → DSH Harbor. The panel mounts only in profiles with a Web server; the CLI remains usable in headless and CI environments.

Verify the installation

curl http://127.0.0.1:3080/_dsh/dsh-harbor/ping
pnpm --dir ~/.dsh/profiles/web exec harbor --version

A healthy ping reports four mounted Harbor routes. The package executable is profile-scoped: installing into web does not place harbor on your global shell PATH.

CLI

harbor scan
harbor scan --evidence
harbor scan --json --no-snapshot
harbor scan --json --check-updates
harbor manifest ./my-plugin
harbor preflight --dsh next

Invocation choices:

# installed in the web profile
pnpm --dir ~/.dsh/profiles/web exec harbor scan

# source checkout
node /path/to/dsh-harbor/src/cli.mjs scan

# one-off registry run after publication
pnpm dlx @zseven-w/dsh-harbor@next scan

--help and --version are side-effect free. Human-readable output strips terminal control sequences from untrusted package metadata; JSON preserves the original machine data. --no-snapshot prevents baseline writes.

Capability vocabulary

Surface · Capability ids UI and host routes · client-injection, web-routes Agent and model surface · tool-registration, llm-adapter, global-hook, mcp-server Machine and data access · subprocess, network-egress, env-read, credential-handling, foreign-config Module-realm integrity · realm-risk, realm-copy

The full, stable definitions and declaration rules live in SPEC.md and SPEC.zh.md. Authors can draft the capabilities member to merge into an existing dsh object:

harbor manifest /path/to/my-plugin

Always review the draft. Detection is deliberately conservative and pattern based; dynamic calls can be missed, and examples or dead code can look live.

Version and snapshot semantics

• Cross-profile drift compares actual installed registry artifacts. link: working trees and file: snapshots stay visible but do not define the registry baseline.
• Upstream checks read your npm registry configuration, keep cache entries isolated by registry and package name, redact credentials from errors, and return behind, current, ahead, local, or unknown.
• Snapshots live under ~/.config/dsh-harbor/ and track profile membership as well as artifact identity, so profile swaps and upgrades cannot disappear behind deduplication.

Trust model and limits

• Harbor is a read-only mirror, not a sandbox, installer gate, or policy engine.
• The default scan never contacts the network. The upstream check is the sole networked panel action.
• Source, manifest, and freshness reads are bounded, regular-file-only, and no-follow; skipped or over-limit coverage is surfaced.
• Runtime waterfall dispatch modes are not enumerable in the current host API, so Harbor marks that runtime evidence as unavailable instead of guessing.
• Static analysis can produce false positives and false negatives. Evidence is for review, not blind enforcement.

Develop and verify

pnpm install
pnpm run typecheck
pnpm test
pnpm run build:client
npm run smoke:pack

The test runner is compatible with Node 20 and Windows. CI covers Node 20/24 on Ubuntu and Windows. smoke:pack packs the real payload, installs it with plain npm in an empty directory, imports the public entry, runs the installed CLI, and checks required files and modes.

Ecosystem

• DSH Android — a live Android emulator or USB device inside a conversation
• DSH Crew — dispatch work to DSH agents from Claude Code, Codex, Antigravity, and Grok
• DSH iOS — a live iOS Simulator or USB-connected iPhone inside a conversation
• DSH Noema — durable, inspectable long-term memory for DSH
• DSH OpenPencil — inspect and edit real OpenPencil design documents inside a conversation

License

MIT — Copyright (c) 2026 ZSeven-W