DSH plugin conflicts: shadowed tools and safe mode

DeepSeek Harness plugin conflicts look like a broken plugin but are usually two plugins present with one shadowing the other. The tell is simple: works alone, fails in combination, works again when separated. Conflicts split into shadowed tools, duplicate dependencies and contended permissions, with only remove, replace or isolate as resolutions — the hard part is identifying the pair.

Three classes of DeepSeek Harness plugin conflict

Bottom line: shadowing shows replaced behavior, dependency duplication shows "each works alone but not together," and contention shows permission or directory errors. Different signatures, different tests.

Option A: bisect the DSH plugin set (most reliable)

Bottom line: halve the enabled set repeatedly. Diagnostics drop from exponential to logarithmic cost, and it is the preferred method.

1. Freeze the scene: record the installed list and versions (export or screenshot from DSH Plugin Hub) so you can restore it.
2. Disable half and observe:
   • the symptom disappears, the cause is in the disabled half;
   • it persists, the cause is in the enabled half.
3. Repeat on the suspicious half, halving each round. Three or four rounds usually isolate a single plugin.
4. Verify alone: install just that plugin plus the ones you always need and see whether the symptom returns. If it does, find its pair.
5. Restore the environment from step 1 rather than leaving a half-configured state.

Option B: isolate with a profile (does not disturb your setup)

Bottom line: create a minimal profile with only the suspects. You leave your daily environment alone and still get a decisive reproduction result.

1. Create a clean profile (use --profile; confirm the flag with dsh --help).
2. Install only the two or three suspicious DSH plugin packages, with the data directory pointed at a temporary location for full isolation.
3. Observe:
   • reproduces, the problem is confined to those plugins — continue bisecting within them;
   • does not reproduce, your existing configuration is involved — go back to Option A in your daily profile.
4. Both results are useful because either one at least halves the search space.
5. Delete the temporary profile afterwards.

Option C: read load order and registration logs (for shadowing)

Bottom line: shadowing does not need bisection. Who registered first, who overrode whom, and whether duplicate registration was reported points directly at the relationship.

1. Read startup or load output: plugin load order is usually visible, and later registrations override earlier ones — that explains changed behavior.
2. Find duplicate registration warnings: duplicate tool names usually produce warnings or errors. This log evidence is stronger than probing.
3. Reproduce with the minimal pair to confirm a single override relationship without third-party noise.
4. Write down the conclusion: who shadows whom, which action is affected, what the symptom looks like.
5. Consider versions as the cause: two versions of the same DSH plugin coexisting produces the same "duplicate registration" pattern; pinning resolves it (see pinning DSH plugin versions).

Building a minimal repro for DSH plugin conflicts

Bottom line: the goal is a minimal plugin set plus stable steps. A conflict you cannot reproduce is a fix you cannot verify.

1. Shrink the set from everything down to the smallest combination that reproduces (usually two or three plugins).
2. Fix the steps: what you install, what action you take, what appears. Three lines is enough.
3. Remove environment variables from the equation by reproducing with a clean data directory.
4. Record versions for every plugin in the minimal set — changing versions may make it disappear, which is also a fix direction.
5. Verify the fix by re-running the same steps; installing things back is not proof.

Three resolutions for DSH plugin conflicts

Bottom line: ask whether you truly need both plugins at once. If not, remove one. If yes, replace or isolate.

1. Uninstall or disable one: simplest, appropriate when one was a trial or has been superseded.
2. Replace it: the same need often has several implementations; find candidates in DSH Plugin Hub that avoid the conflicting approach.
3. Isolate into separate profiles: keep both but never together, accepting the extra switching step.
4. Avoid relying on lucky load order — the next upgrade reorders things and the conflict returns.

DSH plugin troubleshooting for conflicts

Bottom line: the core of conflict diagnosis is controlling variables — freeze the list, bisect, minimize the repro. Do those three and no conflict stays hidden.

1. Record before touching anything; an accurate installed list is the starting point.
2. Bisect instead of uninstalling everything — faster and less destructive.
3. Prefer registration logs over probing when available.
4. Separate conflict from failure: a plugin that fails on its own is a broken plugin or a missing prerequisite.
5. Versions can be the conflict source: two copies of one plugin can masquerade as a conflict.
6. Repair status, stated honestly: this is a methodology article based on the official repository's plugin registration and profile mechanics plus general diagnostic practice. The three-way classification is our synthesis, not an official taxonomy, and message wording varies by version — trust your own logs.

Sources: apps/cli/README.md, docs/user/develop/basic/publish.md, plugin permission boundary.