dsh-plugin-shop 0.8.3 → 0.8.4-beta.0

package/lib/types/host/index.d.ts

@@ -12,10 +12,13 @@ import { type RepoPinFs } from './repo-pins.ts';
 import { type InstallState } from '../shared/install-state.ts';
 import { type Prefetcher } from './prefetch.ts';
 import { type PeerResolver, type PeerVersionResolver } from './peers.ts';
+import { type HarnessVerdict } from './compatibility.ts';
+import { type RunningHarness } from './harness.ts';
 export type { InstallArgs, InstallRejectionCode } from './install.ts';
 export type { HotRestartReason } from './hot.ts';
 export type { Activation } from './activation.ts';
 export type { CatalogEntry } from './types.ts';
+export type { HarnessVerdict } from './compatibility.ts';
 /** One Loader inventory entry, structurally — the shop never depends on
  * cordis-plugin-loader, whose types do not reach this package's typecheck. */
 export interface InventoryEntry {
@@ -36,6 +39,21 @@ export interface LoaderEntryLike {
         disabled: boolean | null;
     }, create?: boolean, force?: boolean): Promise<void>;
 }
+/** The slice of dsh 0.1.7's `pluginManager` service this gateway calls,
+ * structurally: the build compiles against the 0.1.1-rc.2 harness floor,
+ * where the package does not exist. `setBundleEnabled` is what dsh's own
+ * Plugins page calls for its bundle switch, and it answers with the saved
+ * change and how it applied (design 2026-09-26-plugin-manager-delegation,
+ * section 2). */
+export interface BundleSelector {
+    setBundleEnabled(name: string, enabled: boolean): Promise<{
+        application?: unknown;
+        error?: {
+            code?: unknown;
+            diagnostic?: unknown;
+        };
+    }>;
+}
 /** Test-only injection points; production callers pass nothing. */
 export interface ShopGatewayOptions {
     catalogUrl?: string;
@@ -75,8 +93,25 @@ export interface ShopGatewayOptions {
      * defaults to the real `process.argv` minus node and the script path. */
     restartArgv?: string[];
     /** The JS entry `shop/restart` re-runs; defaults to `process.argv[1]`, the
-     * script this dsh was started with. */
+     * script this dsh was started with. It is also what identifies the running
+     * harness for the `dsh.compatibility` verdict: the package that owns this
+     * script, through symlinks, is the dsh actually running, and its own
+     * app-boot supplies the profile templates (`harness.ts`). A script owned by
+     * anything else — a test runner, another host — leaves both halves of that
+     * verdict silent. The tests about where the running version comes from pass
+     * a fixture install here, which is the production path; the rest inject
+     * `readHarness`. */
     restartScript?: string;
+    /** Test-only injection: how the running harness is read from
+     * `restartScript`; production uses `readRunningHarness`. It exists because
+     * an in-process test cannot import a module from another Windows drive
+     * under vitest's module runner, and a Windows runner has the checkout on D:
+     * and the temp dir, where every fixture harness lives, on C:. The read's
+     * import of the fixture's app-boot fails there, and the table reads empty.
+     * Production passes nothing, so the running dsh is read as before. Read
+     * once and kept either way (see `harnessRead`), so like the default it
+     * must never reject. */
+    readHarness?: (script: string | undefined) => Promise<RunningHarness>;
     /** Test-only injection: the exit the restart calls after the response is
      * delivered. Production uses `process.exit`. */
     exit?: (code?: number) => void;
@@ -87,6 +122,9 @@ export interface ShopGatewayOptions {
     /** Test-only injection: the shop's latest-version lookup; production
      * fetches the npm packument. */
     fetchLatestVersion?: () => Promise<string | null>;
+    /** Test-only injection: the version of the code this process loaded;
+     * production reads it once, when own-version.ts is first evaluated. */
+    runningVersion?: string;
     /** How long the gateway waits after a successful restart response before
      * exiting the old process; test-only shortening, production uses 2s. */
     restartExitDelayMs?: number;
@@ -119,6 +157,11 @@ export interface ShopGatewayOptions {
      * — a live registry request — from every install that finds a command
      * already queued for its profile. */
     prefetcher?: Prefetcher;
+    /** Test-only injection: the record of packages this process may already
+     * have imported. Production shares one module-scope set across every
+     * gateway in the process (see `importedThisProcess`), which a test file
+     * building many gateways would otherwise share as well. */
+    importedModules?: Set<string>;
 }
 /** `shop/installStart` result (§7.3): rejections are typed wire values with an
  * author-readable `detail`, not thrown RPC errors. */
@@ -183,12 +226,14 @@ export type ShopRestartResult = RestartOutcome;
  * restart was impossible after it had become possible. Static here, dynamic
  * there; the split is the whole reason this is a separate predicate rather
  * than a cache of `restart()`'s answer. */
-export type RestartBlockedReason = 'windows' | 'systemd' | 'port-zero';
+export type RestartBlockedReason = 'desktop' | 'windows' | 'systemd' | 'port-zero';
 /** `shop/version` result (§7.3): the RUNNING shop version (from the shipped
  * package.json, not the manifest's range), the npm latest when the check
  * could answer (`null` = no answer — advisory, never an error), and the
  * comparison verdict. */
 export interface ShopVersionResult {
+    /** The version of the code this process is running, read when it loaded.
+     * Not the file on disk now: a self-update rewrites that in place. */
     installed: string;
     latest: string | null;
     outdated: boolean;
@@ -196,6 +241,17 @@ export interface ShopVersionResult {
      * its way. The client drops the restart offer on a reason and renders that
      * reason's own copy, keeping the pending-change notice either way. */
     restartBlocked: RestartBlockedReason | null;
+    /**
+     * The version the profile has installed when it is not the one running —
+     * an update that landed and waits for a restart — or null when the running
+     * code is what is installed, or the installed copy could not be read.
+     *
+     * This host always sends it. Absent, it comes from a host older than the
+     * field, and the client reads that as a restart still pending: a client
+     * newer than its host exists only because the disk holds a newer shop than
+     * the process running (design §7.3, 2026-09-27 amendment).
+     */
+    pendingVersion?: string | null;
 }
 /** `shop/updateStart` result (§7.3): the self-update spawn, or a typed
  * refusal (a version that is not plain semver). */
@@ -249,16 +305,44 @@ export interface ShopCatalogResult {
      * or the sidecar could not be fetched/verified (§5). */
     stars: Record<string, number>;
     /** Install identity (`npm:<name>` / `github:<repo>#<subdir>`) → the declared
-     * peers this installation does not provide. A key is absent when the plugin
-     * runs here or when no verdict could be formed; same-named entries stay
-     * independent. */
+     * peers node resolution cannot find from the profile. This is the HOST half
+     * of the verdict only: a module the browser's module table serves — a
+     * platform seed word such as `react` — has no package on disk and is still
+     * listed here, so the client removes every name its live module table
+     * provides before anything renders (`client/module-table.ts`), and renders
+     * no peer verdict at all on a page that offers no usable table. A key is
+     * absent when the plugin runs here or when no verdict could be formed;
+     * same-named entries stay independent. */
     incompatible: Record<string, string[]>;
+    /** Install identity → what the entry's author declared in
+     * `dsh.compatibility` that this installation does not meet (design
+     * 2026-09-01-harness-compatibility §8.2), and what the running dsh itself
+     * will refuse the install on (`peers`, from dsh 0.1.7; design
+     * 2026-09-26-dsh-017-readiness, B1). A key is absent when nothing was
+     * declared or every declared half is met, and dsh refuses nothing. A half that cannot be judged —
+     * the running version unreadable, a range semver cannot parse — is left out
+     * while the other is still judged, so an unknown never reads as an
+     * accusation; same-named entries stay independent. A process not started
+     * by dsh's CLI judges neither half: nothing then says which harness runs
+     * (`harness.ts`). */
+    incompatibleHarness: Record<string, HarnessVerdict>;
 }
 /** Remote-only service exposing the shop Remote methods of §7.3.
  *
  * @typert service shop */
 export declare class ShopGateway extends TypertRemoteService {
     private readonly options;
+    /** The context this gateway was built with: the shop's own fiber. Inside an
+     * RPC method `this.ctx` is NOT that — cordis hands a service out with `ctx`
+     * rebound to the context that looked it up, so a call arriving over the
+     * wire sees the caller's, the typert gateway's (measured on 0.1.5-rc.3 and
+     * 0.1.7-rc.2). Anything whose PARENT matters is registered from here. The
+     * hot tree above all: registered from the gateway's context it was owned by
+     * the gateway's fiber rather than the shop's, was listed under the gateway's
+     * loader entry, and — the part a reader saw — sat where dsh's client
+     * registry never composed it, so a hot-installed browser half needed a
+     * restart that a reload now does (design 2026-09-26-dsh-017-readiness). */
+    private readonly home;
     /** The profile dsh installs into; discovered from this module's own
      * location when the caller does not supply one. */
     private readonly profile;
@@ -294,6 +378,8 @@ export declare class ShopGateway extends TypertRemoteService {
     /** One pump for the whole gateway: batching is per profile and lives inside
      * it, so a second instance would race the first for the same store. */
     private readonly prefetcher;
+    /** What this process may already have imported (see `importedThisProcess`). */
+    private readonly imported;
     /** The install gate runs against the last loaded snapshot, never a fresh
      * fetch per request (§7.2: the Host's cached snapshot is the truth). */
     /** Finished install records retained, so a poll sees the true terminal
@@ -313,16 +399,11 @@ export declare class ShopGateway extends TypertRemoteService {
     /** The user's own `registry=` from `~/.npmrc`, read at most once per
      * gateway. A wrapper distinguishes a genuine `null` from an unread value. */
     private npmRegistryCache;
-    /** The incompatibility map already computed for `lastSnapshot`, keyed by
-     * that snapshot's own object identity. Design §3 asks for the verdict
-     * once per loaded snapshot, not once per RPC call: `loadCatalog` serves
-     * the same snapshot from its on-disk cache for minutes at a time, so
-     * without this, reopening the tab within that window would re-walk
-     * `node_modules` for every distinct peer name again — and Node only
-     * caches a SUCCESSFUL resolution, so a genuinely missing peer pays a full
-     * failed walk on every single call. Recomputed only when `catalog()`
-     * loads a snapshot that is not this exact object. */
-    private incompatibleCache;
+    /** The harness this process runs, read at most once per gateway: which dsh
+     * is running cannot change while it runs, and the read imports a module. A
+     * promise, so concurrent first calls share one read; `readRunningHarness`
+     * never rejects, so there is no failure to retry. */
+    private harnessRead;
     /** Install records, running and finished; a poll finds one here or reports not found. */
     private readonly installs;
     /** Every install id in insertion order, oldest first; finished-record eviction walks this from the front. */
@@ -347,6 +428,38 @@ export declare class ShopGateway extends TypertRemoteService {
      * stays lazy so `setEnabled` works in tests via the `profileDir` option
      * without requiring a real profile above this module. */
     private profileDirResolved;
+    /** Where every "what can this installation's plugins import?" question
+     * resolves from: the profile's own Loader root, which is where the harness
+     * resolves plugins from. One definition for the peer presence check and the
+     * load-time self-check, so neither can drift onto a different notion of
+     * "the installation". NOT where the running harness is read from: a copy
+     * of `@deepseek-ai/dsh` a plugin's dependencies hoist into the profile is
+     * importable from here and is not what runs (`harness.ts`). Throws when no
+     * profile directory can be discovered and none is given. */
+    private profileAnchor;
+    /** dsh's `pluginPackages` service, when the running harness provides one
+     * (0.1.7 and later), else null. Read on each use, like `pluginInventory`.
+     * It is how such a harness serves its own packages to plugins, which no
+     * walk of the profile's disk can see (design
+     * 2026-09-01-harness-compatibility §11). */
+    private harnessPackages;
+    /** dsh's `pluginManager` service, when the running harness provides one
+     * (0.1.7 and later), else null. Read on each use, like `pluginPackages`.
+     * It is the only way back for a bundle its Plugins page deselected: the
+     * 0.1.7 CLI does not select an installed package again on `add`, while
+     * 0.1.5's does (both measured 2026-09-27). */
+    private pluginManager;
+    /** "Does this installation provide `spec`?", asked from `anchor`: the
+     * harness's own resolution in front of the walk where the harness has one,
+     * the walk alone where it has not. */
+    private peerResolver;
+    /** `peerResolver`'s twin for the versions the load-time self-check reads. */
+    private peerVersionResolver;
+    /** `profileDirResolved`, or null when no profile directory can be
+     * discovered — for the reads that answer "cannot tell" rather than fail. */
+    private profileDirOrNone;
+    /** The harness this process runs, read once (see `harnessRead`). */
+    private runningHarness;
     /** The inventory, through the wire remote: an envelope `{ ok, value }` or
      * `{ ok: false, error }`. Each row is re-validated before trust (same
      * discipline as the rowConfig cast). */
@@ -358,8 +471,9 @@ export declare class ShopGateway extends TypertRemoteService {
      * down. A disable can land while the entry's init is still in flight: the
      * options flip but the finishing init brings the fiber up anyway, and a
      * plain re-update no-ops on the empty diff (dsh-market themes.ts:74-93).
-     * For an update swap this sequencing is mandatory, not defensive: two live
-     * instances of a service-providing plugin would collide at provision. */
+     * The uninstall path is the one caller: an update used to swap its running
+     * instance for a hot mount through here, and no longer mounts at all
+     * (design 2026-09-26-market-borrowings §1). */
     /** The package's owned entry ids, or none when its bundle patch cannot be
      * read. For the paths where a live disable is an optimization and the
      * operation must succeed regardless; `setEnabled` reports the failure
@@ -387,8 +501,8 @@ export declare class ShopGateway extends TypertRemoteService {
      * Through `ownDependencySpec` for the reason spelled out there: a bare index
      * read answers for `Object.prototype`, and `constructor` is a legal npm
      * name. The cost on this path is behavioural twice over — the gate would
-     * weigh a function as the installed spec, and a phantom `isUpdate` would run
-     * `liveDisableIds` against something absent.
+     * weigh a function as the installed spec, and a phantom `isUpdate` would
+     * refuse a hot mount to a package this process never imported.
      */
     private installedSpecOf;
     private ownedEntryIdsOrNone;
@@ -416,15 +530,30 @@ export declare class ShopGateway extends TypertRemoteService {
      * the loop was computing.
      */
     private liveEntriesDown;
-    /** Enable or disable one installed plugin, hot (§8): a disable writes the
-     * row to the user layer, an enable drops it again so the bundle default
-     * rules — the CLI's watchUserPatches applies either through HMR. The shop's
-     * own row and the framework's bundles are never toggleable: disabling the
-     * host chain would break HMR itself. */
+    /** Enable or disable one installed plugin, hot (§8): the write sets the
+     * `disabled` key of each owned entry's row in the user layer and changes
+     * nothing else there (design 2026-09-26-market-borrowings §2) — the CLI's
+     * watchUserPatches applies it through HMR. The shop's own row and the
+     * framework's bundles are never toggleable: disabling the host chain would
+     * break HMR itself. */
     setEnabled(args: {
         name: string;
         enabled: boolean;
     }): Promise<ShopSetEnabledResult>;
+    /**
+     * `setEnabled` for an installed package whose bundle the profile does not
+     * select.
+     *
+     * Switching it off writes the plugin-level rows and nothing else: none of
+     * it runs, and the rows keep it off if dsh selects the bundle again.
+     * Switching it on selects the bundle through dsh's own `pluginManager`, the
+     * writer behind the switch that deselected it, and then clears the
+     * plugin-level rows as an ordinary enable does. A harness without that
+     * service gets the way back in words instead. `dsh plugin add <name>` is
+     * not printed: it selects the bundle again only on 0.1.5, and it lets pnpm
+     * float a registry package to `latest`.
+     */
+    private setDeselectedEnabled;
     private rowConfig;
     /** The user's own registry, read once. The self-update check and catalog
      * race share this preference so neither path repeatedly touches ~/.npmrc. */
@@ -447,11 +576,16 @@ export declare class ShopGateway extends TypertRemoteService {
      * static does. One ordered list, read by `restart()` before it commits and
      * by `version()` so the client can say the same thing up front.
      *
-     * The order is the order the refusals were written in and is load-bearing
-     * for the copy a reader sees: Windows first, because the platform check has
-     * no override and reporting the systemd one there sends a Windows user to
-     * set `allowRestart: true`, which this gate would still refuse.
+     * The order is load-bearing for the copy a reader sees. The desktop
+     * profile first: dsh itself refuses to launch it, so no platform,
+     * supervisor or port could make a restart possible there. Then Windows,
+     * because the platform check has no override and reporting the systemd one
+     * there sends a Windows user to set `allowRestart: true`, which this gate
+     * would still refuse.
      *
+     * - `desktop`: dsh's CLI refuses `--profile desktop` ("managed exclusively
+     *   by the Electron application"), so the relaunch would exit at once and
+     *   leave nothing on the port; the app restarts it.
      * - `windows`: the handoff helper is a POSIX shell one-liner (restart.ts)
      *   and there is no `sh` on Windows. That spawn fails ASYNCHRONOUSLY, so
      *   committing would answer `ok: true`, exit this process, and leave nothing
@@ -468,6 +602,26 @@ export declare class ShopGateway extends TypertRemoteService {
     catalog(args?: {
         refresh?: boolean;
     }): Promise<ShopCatalogResult>;
+    /**
+     * The installs the running dsh will refuse on their harness peers
+     * (`peerVerdictsOf`), judged against the exemptions this profile holds —
+     * read on every call like the other verdicts, because recording one is
+     * exactly the event that must clear a card: the reader runs the command
+     * the card shows, presses Refresh, and the install is allowed. Empty when
+     * the running dsh has no such check (before 0.1.7) or no profile was
+     * found, and when either read throws: a refusal nobody could establish is
+     * never shown, least of all as a disabled button.
+     */
+    private refusedByHarness;
+    /**
+     * The bundles the profile at `profileDir` composes, or null when its
+     * manifest cannot be read — which is no verdict on the profile half rather
+     * than an accusation. `dsh.profile.bundles` is the same list
+     * `discoverProfile` uses to recognize a profile directory, read through the
+     * harness's own parser so a profile this shop was booted inside is read the
+     * way dsh reads it.
+     */
+    private runningProfileBundles;
     /**
      * Install one cataloged version into the profile (§7.2). The rejection
      * paths run against this Host's snapshot before anything is spawned; only a
@@ -534,6 +688,21 @@ export declare class ShopGateway extends TypertRemoteService {
      * and the client shows the version alone. `installed` is the RUNNING
      * version (own-version.ts), not the manifest's range spec. */
     version(): Promise<ShopVersionResult>;
+    /**
+     * The version of the shop the profile has installed, when it is not the
+     * one this process runs; null when they match or the copy cannot be read.
+     *
+     * Read from the profile's own copy — the directory `dsh plugin add` writes
+     * and the next boot loads — rather than from the file beside this module.
+     * For the hoisted install those are one directory, but a `link:` install
+     * runs from its link target, which an update replaces in the profile and
+     * never touches at the target, so reading beside the module would never see
+     * the update land.
+     *
+     * Unreadable is null, never a throw: the version check is advisory, and a
+     * missing field would tell the client this host predates it.
+     */
+    private pendingVersion;
     /** Update the shop itself to a published version (§7.3): the explicit pin
      * is the only install form that bypasses pnpm's release cooldown. The
      * version is re-validated as plain semver at the boundary — the spec

package/lib/types/host/install.d.ts

@@ -1,7 +1,7 @@
 /** Install gate: the gate rejection paths of §7.2, as a pure function. */
 import type { CatalogSnapshot } from './catalog.ts';
 import type { CatalogEntry } from './types.ts';
-export type InstallRejectionCode = 'not-in-catalog' | 'denied' | 'version-mismatch' | 'needs-acknowledgement' | 'tarball-integrity' | 'ambiguous-identity' | 'name-taken';
+export type InstallRejectionCode = 'not-in-catalog' | 'denied' | 'version-mismatch' | 'needs-acknowledgement' | 'tarball-integrity' | 'ambiguous-identity' | 'name-taken' | 'desktop-profile';
 export interface InstallArgs {
     name: string;
     version: string;

package/lib/types/host/peers.d.ts

@@ -7,12 +7,151 @@ import { type EntryIdentity } from '../shared/identity.ts';
  * drive every verdict and exactly one call site touches the filesystem. */
 export type PeerResolver = (spec: string) => boolean;
 /**
- * The production resolver: the same question the harness's own
- * ClientModuleRegistry asks, through a require anchored at the profile. Asking
- * what the loader asks is what keeps this verdict and the runtime's behaviour
- * from drifting apart.
+ * The two filesystem reads the package lookup makes. Injected so fixtures can
+ * drive every branch of the walk — including a permission failure, which a
+ * real directory cannot stage when the suite runs as root — while
+ * `NODE_LOOKUP_FS` below stays the one place this module touches the disk.
+ */
+export interface PackageLookupFs {
+    /** `statSync`'s contract: follows symlinks, and throws an errno error
+     * (`code` set) for a path it cannot stat. */
+    stat(path: string): {
+        isDirectory(): boolean;
+        isFile(): boolean;
+    };
+    /** `readFileSync(path, 'utf8')`'s contract: throws for a file it cannot read. */
+    readFile(path: string): string;
+}
+/**
+ * The directory `spec` is installed at as seen from `fromDir`, or null when
+ * it is not installed there: the walk's match (`findPackageDir`), and only
+ * when that directory holds a `package.json` that stats as a FILE. Anything
+ * else is ABSENT — a match with no manifest, a manifest that is not a file,
+ * one whose stat fails — because the loader matches that directory and the
+ * import fails there. The case this exists for: an uninstall that stops
+ * part-way (on Windows a locked file is enough) can leave
+ * `<profile>/node_modules/L/` holding nothing but a nested `node_modules/`,
+ * and a plugin declaring L then fails with ERR_MODULE_NOT_FOUND; while any
+ * directory counted as present, the badge naming L disappeared. The lookup
+ * before that one, `require.resolve('<spec>/package.json')`, required the
+ * manifest too.
+ *
+ * The manifest is stat-ed and never read here: presence is the file, and
+ * what it says is the version resolver's question. So a manifest that exists
+ * but cannot be read or parsed is a present package with no readable version.
+ *
+ * One edge is knowingly given up: a directory holding `index.js` and no
+ * manifest DOES import — Node's legacy main resolution tries `index.js` in a
+ * match without a manifest — but reads absent here. No package manager
+ * installs that shape.
+ *
+ * Throws only for a `spec` that is not a bare package name. This one lookup
+ * is behind the presence resolver, the version resolver, and the running
+ * harness's own `@deepseek-ai/dsh-app-boot` (`harness.ts`).
+ */
+export declare function packageDirectory(fromDir: string, spec: string, fs?: PackageLookupFs): string | null;
+/** `nodeResolver` over an injected filesystem, walking up from `fromDir` —
+ * the seam fixtures drive the lookup through. */
+export declare function packageResolver(fromDir: string, fs: PackageLookupFs): PeerResolver;
+/**
+ * The production resolver, anchored at the profile. A peer is present when
+ * the first ancestor `node_modules/<spec>` that is a directory holds a
+ * `package.json` file — the directory the ESM resolver that loads plugins'
+ * host halves matches for a bare package, and a manifest in it
+ * (`findPackageDir`, `packageDirectory`). From `<profile>/cordis.yml` the
+ * walk reads `<profile>/node_modules`, then `$DSH_HOME/profiles/node_modules`
+ * — the link farm dsh-app-boot's `healProfilesModuleFallback` keeps, pointing
+ * into the global dsh install, on 0.1.5; 0.1.7 keeps none, and on a harness
+ * that serves its packages another way `harnessPackageResolver` asks it in
+ * front of this walk — and so on up to the root, past any candidate
+ * it cannot stat, as Node's reader walks past one (measured on Node 26.6.0
+ * with a looping link in front of a real copy: the import loads the copy).
+ * The one shape where this and the loader knowingly disagree is a directory
+ * holding `index.js` and no manifest, which imports and reads absent here;
+ * no package manager installs it (`packageDirectory`).
+ *
+ * It used to ask `require.resolve('<spec>/package.json')`, a question that
+ * answered wrongly twice:
+ *
+ *  - Under a packaged dsh executable (`process.pkg`) the link farm holds ESM
+ *    proxy packages instead of symlinks, and a proxy's `exports` leaves
+ *    `./package.json` out on purpose, so resolving it threw
+ *    ERR_PACKAGE_PATH_NOT_EXPORTED for every proxied peer. Presence read that
+ *    as present; the version resolver below could read nothing. Reproduced:
+ *    a proxy at `0.2.0-rc.1` against a declared `^0.1.1-rc.2` gave presence
+ *    true, version null, mismatches `[]` — the load-time self-check could
+ *    never fire under a packaged dsh.
+ *  - Node caches a SUCCESSFUL CJS resolution for the life of the process
+ *    (`Module._pathCache`, keyed on request + lookup paths) and hands the
+ *    cached filename back without looking at the disk; a failure is not
+ *    cached. Measured on Node 26.6.0 in one process: absent → false,
+ *    installed → true, uninstalled → STILL true. A peer the reader removed
+ *    left every plugin declaring it unflagged until dsh restarted.
+ *
+ * So nothing is cached and `exports` is never consulted: every call stats
+ * afresh, and a package with a manifest is present whatever its `exports`
+ * says. `stat` follows symlinks, so a link to nothing reads absent — which
+ * matters, because the link farm adds links and never prunes them: 29 of its
+ * 511 dangled on the machine this was measured on, after upgrades.
+ *
+ * The global folders — `NODE_PATH`, `~/.node_modules`, `~/.node_libraries`,
+ * `$PREFIX/lib/node` — are deliberately not searched: the ESM resolver that
+ * loads plugin host code does not search them either. That is not academic.
+ * pnpm's bin shims export `NODE_PATH` (this repo's own `node_modules/.bin/
+ * vitest` points it into the virtual store), and under one the old lookup
+ * found harness packages from any anchor at all, a temp directory included.
+ *
+ * It throws only for a `spec` that is not a bare package name, and
+ * `incompatibilityMap` turns the throw into no verdict: a hostile name is not
+ * a fact about this installation, and false is an accusation. Nothing on the
+ * filesystem makes it throw. It used to throw on a stat failure other than
+ * ENOENT or ENOTDIR as well, reasoning that such a candidate "may hold the
+ * package" — but the loader never asks what a candidate it cannot stat holds;
+ * it walks on (`findPackageDir`), so the throw silenced true badges and
+ * established nothing.
  */
 export declare function nodeResolver(baseUrl: string): PeerResolver;
+/**
+ * The one method of dsh's `pluginPackages` service the peer check reads: the
+ * harness's own answer to "which package does this import reach?".
+ *
+ * dsh 0.1.7 stopped mirroring its installation into
+ * `$DSH_HOME/profiles/node_modules`. It serves those packages to every
+ * profile through Node's module hooks instead — its runtime resolution
+ * routes a plugin's bare import of any package in the installation's
+ * dependency closure to the package that declares it — so the walk
+ * `nodeResolver` makes, which reads the disk around the profile, finds none
+ * of them. Measured on 0.1.7-rc.2 against the live catalog, the walk read
+ * `@deepseek-ai/dsh-tools` as missing for 1,038 entries, and the shop badged
+ * 2,214 where 0.1.5-rc.3 badges 570 (design
+ * 2026-09-01-harness-compatibility §11). `packageOf` answers from that
+ * resolution for the importer `parentURL` names; 0.1.5 has no such service.
+ *
+ * Typed loosely because the answer crosses in from the harness: only a
+ * string `manifestPath` is used.
+ */
+export interface HarnessPackageLookup {
+    packageOf(specifier: string, parentURL: string): {
+        manifestPath?: unknown;
+    } | undefined;
+}
+/**
+ * Presence on a harness that serves its packages through its runtime
+ * resolution (`HarnessPackageLookup`): present when the harness reaches a
+ * package for `spec` from `parentURL`, the profile anchor, and otherwise
+ * whatever `walk` answers — `nodeResolver` over the same anchor, in
+ * production. Asking the harness first asks the loader's own question, since
+ * a plugin's import goes through the same resolution. The walk stays behind
+ * it because either answer can only clear a badge, never raise one, and a
+ * false badge is the failure this module exists to avoid.
+ *
+ * Throws, which `incompatibilityMap` turns into no verdict for the entries
+ * declaring `spec`, for a name that is not a bare package name and for
+ * anything the service throws. A harness that cannot answer is silence:
+ * falling back to the walk alone would read every package it serves as
+ * missing.
+ */
+export declare function harnessPackageResolver(walk: PeerResolver, lookup: HarnessPackageLookup, parentURL: string, fs?: PackageLookupFs): PeerResolver;
 /**
  * Package name → the peer names that did not resolve. A key is present only
  * when at least one peer is missing, so an absent key means "runs here, or we
@@ -41,15 +180,47 @@ export interface PeerVersionMismatch {
     /** The version the installation actually provides. */
     found: string;
 }
+/** `nodeVersionResolver` over an injected filesystem, walking up from
+ * `fromDir` — the seam fixtures drive the lookup through. */
+export declare function packageVersionResolver(fromDir: string, fs: PackageLookupFs): PeerVersionResolver;
 /**
- * The production resolver: `nodeResolver`'s own resolution, kept this time
- * instead of collapsed to a boolean. Anything that leaves no version to read
- * answers null — a peer that is absent, one that restricts `./package.json`
- * in its exports, an unreadable or malformed manifest, a manifest with no
- * `version`. Absence is deliberately NOT reported as a version violation:
- * `incompatibilityMap` is what covers a missing peer.
+ * The production version resolver: `nodeResolver`'s lookup, then the matched
+ * directory's own `package.json`, read directly. Reading it directly is the
+ * fix, not a shortcut: resolving `<spec>/package.json` is what an exports map
+ * can refuse, and a packaged dsh's module proxy refuses it by construction
+ * while carrying the proxied package's version in exactly that file (see
+ * `nodeResolver`).
+ *
+ * The directory is the one the presence resolver finds present — the walk's
+ * first directory match, holding a `package.json` file (`packageDirectory`;
+ * `findPackageDir` cites Node's reader) — so the two never disagree about
+ * which copy is installed: a candidate nobody can stat is walked past to the
+ * copy further up, whose version is then the answer, exactly as the loader
+ * imports that copy (measured on Node 26.6.0 with a looping link in front of
+ * it); a match without a manifest is absent, and shadows every copy above
+ * it. An `index.js`-only directory, which the loader would import, has no
+ * manifest to read a version from either way.
+ *
+ * Anything that leaves no version to read answers null: a spec that is not a
+ * bare package name, a peer that is absent, a manifest that is unreadable or
+ * malformed, a `version` that is not a non-empty string. Absence is
+ * deliberately NOT reported as a version violation: `incompatibilityMap` is
+ * what covers a missing peer.
  */
 export declare function nodeVersionResolver(baseUrl: string): PeerVersionResolver;
+/**
+ * `harnessPackageResolver`'s twin for versions: read afresh from the manifest
+ * of the package the harness reaches for `spec` — the copy a plugin's import
+ * loads, which the walk cannot see on dsh 0.1.7 — and `walk`'s answer only
+ * when the harness reaches none. A manifest the harness names but nobody can
+ * read or parse answers null, never the walk's version: the walk may match
+ * another copy, and the version must describe the copy presence found (see
+ * `nodeVersionResolver`).
+ *
+ * Null for a name that is not a bare package name and for a service that
+ * throws, as null is already this resolver's no-verdict signal.
+ */
+export declare function harnessPackageVersionResolver(walk: PeerVersionResolver, lookup: HarnessPackageLookup, parentURL: string, fs?: PackageLookupFs): PeerVersionResolver;
 /**
  * The declared peers whose provided version is outside the declared range,
  * ordered by peer name. Pure: the module graph arrives through `resolve`.