dsh-plugin-shop 0.8.1 → 0.8.2

package/lib/types/client/useInstall.d.ts

@@ -1,41 +1,31 @@
-/** Install driving hook for one entry: start, poll to terminal, reset. */
+/** Install driving hooks: the shared poll loop, and the tab's keyed registry. */
 import { type Dispatch, type SetStateAction } from 'react';
 import { type InstallView } from './present.ts';
+import { type KeyedFlow, type UseKeyedFlows } from './useFlows.ts';
 import type { InstallArgs, ShopInstallResult, ShopInstallStatusResult } from '../host/index.ts';
-export interface UseInstallResult {
-    view: InstallView;
-    start: (args: InstallArgs) => Promise<void>;
-    reset: () => void;
-}
-/** The poll loop shared by the install and uninstall drivers: while the view
- * is `running`, poll once per second and fold each status through the
- * reducer. A poll failure is transient — the host retains the record, so the
- * next tick finds it. The rejection handler must be present: an unhandled
- * rejection here would escape the poll loop. */
+/** The single-view poll loop: while the view is `running`, poll once per
+ * second and fold each status through the reducer. A poll failure is
+ * transient — the host retains the record, so the next tick finds it. The
+ * rejection handler must be present: an unhandled rejection here would
+ * escape the poll loop.
+ *
+ * Kept for the self-update (`useUpdateSelf`), which drives ONE flow with no
+ * identity to key it by. Everything per-plugin goes through `useKeyedFlows`,
+ * whose own loop polls every running identity from one interval. */
 export declare function usePollStatus(view: InstallView, setView: Dispatch<SetStateAction<InstallView>>, installStatus: (args: {
     installId: string;
 }) => Promise<ShopInstallStatusResult>): void;
-/** Drive one install: rejections, the polling loop at INSTALL_POLL_MS, and
- * terminal states. The interval is cleared on unmount and whenever the view
- * leaves `running`, so a done/failed/rejected install never polls again. */
-export declare function useInstall(install: (args: InstallArgs) => Promise<ShopInstallResult>, installStatus: (args: {
-    installId: string;
-}) => Promise<ShopInstallStatusResult>): UseInstallResult;
 /** One entry's install flow, as the tab hands it to a panel. */
-export interface InstallFlow {
-    view: InstallView;
-    start: (args: InstallArgs) => Promise<void>;
-    reset: () => void;
-}
-export interface UseInstallFlows {
-    /** Two panels asking for the same install identity receive one flow. */
-    flowFor: (key: string) => InstallFlow;
-}
+export type InstallFlow = KeyedFlow<InstallArgs>;
+export type UseInstallFlows = UseKeyedFlows<InstallArgs>;
 /**
  * Install flows owned by the tab and keyed by install identity. Keeping the
  * state above individual cards preserves a running operation when filtering
  * unmounts its card, and makes the shelf and Outdated panels agree.
+ *
+ * The registry itself is `useKeyedFlows`; this supplies the one thing that is
+ * install-specific — what the starting RPC's answer means.
  */
 export declare function useInstallFlows(install: (args: InstallArgs) => Promise<ShopInstallResult>, installStatus: (args: {
     installId: string;
-}) => Promise<ShopInstallStatusResult>, onSettled?: (key: string) => void): UseInstallFlows;
+}) => Promise<ShopInstallStatusResult>, onSettled?: (key: string, outcome: 'done' | 'failed') => void): UseInstallFlows;

package/lib/types/client/useUninstall.d.ts

@@ -1,21 +1,28 @@
-/** Uninstall driving hook for one entry: start, poll to terminal. Shares the
- * install view machine and poll loop; the only difference is the start
- * mapping — an uninstall business failure (not in the catalog / not
- * installed) lands in the `failed` view with the host's published detail,
- * never in the install `rejected` codes, which belong to the install gate
- * (§7.2). */
+/** Uninstall driving hook: the tab's keyed registry, one start mapping. */
 import type { ShopInstallStatusResult, ShopUninstallResult } from '../host/index.ts';
-import type { InstallView } from './present.ts';
-export interface UseUninstallResult {
-    view: InstallView;
-    start: (args: {
-        name: string;
-    }) => Promise<void>;
-}
-/** Drive one uninstall: the host's business union, the shared polling loop,
- * and terminal states. The `rejected` install state never occurs here. */
-export declare function useUninstall(uninstall: (args: {
+import { type KeyedFlow, type UseKeyedFlows } from './useFlows.ts';
+/** One entry's uninstall flow, as the tab hands it to a panel. */
+export type UninstallFlow = KeyedFlow<{
+    name: string;
+}>;
+export type UseUninstallFlows = UseKeyedFlows<{
+    name: string;
+}>;
+/**
+ * Uninstall flows owned by the tab and keyed by install identity. Lifting the
+ * state above individual cards is what lets a completed uninstall's outcome
+ * survive the installed-projection refresh that follows it — the row backing
+ * the card disappears, but the flow keyed by identity does not.
+ *
+ * The registry itself is `useKeyedFlows`; this supplies the one thing that is
+ * uninstall-specific — what the starting RPC's answer means. An uninstall
+ * business failure (not in the catalog / not installed) lands in the `failed`
+ * view with the host's published detail, never in the install `rejected`
+ * codes: those belong to the install gate, and `ShopUninstallResult`'s
+ * failure variant has no `code` field to populate.
+ */
+export declare function useUninstallFlows(uninstall: (args: {
     name: string;
 }) => Promise<ShopUninstallResult>, installStatus: (args: {
     installId: string;
-}) => Promise<ShopInstallStatusResult>): UseUninstallResult;
+}) => Promise<ShopInstallStatusResult>, onSettled?: (key: string, outcome: 'done' | 'failed') => void): UseUninstallFlows;

package/lib/types/client/useUpdateSelf.d.ts

@@ -4,7 +4,7 @@
  * `failed` view with the host's detail, never in the install `rejected`
  * codes. */
 import type { ShopInstallStatusResult, ShopUpdateResult } from '../host/index.ts';
-import type { InstallView } from './present.ts';
+import { type InstallView } from './present.ts';
 export interface UseUpdateSelfResult {
     view: InstallView;
     start: (args: {

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

@@ -0,0 +1,55 @@
+/**
+ * What a reader must do before a change the shop just made becomes visible
+ * (design 2026-09-11-activation-model §2).
+ *
+ * A dsh plugin has two halves that go live by different routes. The host half
+ * is composed by the loader. The browser half reaches a tab only through
+ * `window.__DSH_BOOT__`, which the harness composes and the webserver injects
+ * on every index request — so where that graph already holds the change, a
+ * tab predating it is stale by one RELOAD rather than by one restart.
+ *
+ * Three values, not two booleans: `needsRestart` plus `needsReload` would
+ * admit a true/true that the system cannot be in, and would make every reader
+ * re-derive the precedence.
+ *
+ * This answers about VISIBILITY, never about correctness. `live` does not
+ * claim the plugin works; tiering (§9) and harness compatibility
+ * (2026-09-01-harness-compatibility) are what speak to that.
+ */
+export type Activation = 'live' | 'reload' | 'restart';
+/**
+ * Decide what the reader must do.
+ *
+ * @param input.hostLive - whether the plugin's host half is in its intended
+ * post-change state in this process right now: the hot-mount outcome for an
+ * install or update, whether the fiber actually went away for an uninstall,
+ * and true for a toggle (the user layer is hot-reloaded).
+ * @param input.hasClientHalf - whether the package declares `dsh.client`. An
+ * unreadable manifest reports `true`; see `client-half.ts` for why.
+ * @param input.clientLive - whether THIS change's browser half is in the
+ * graph the webserver hands a reloading tab.
+ *
+ * `clientLive` is the difference between the two routes a change can take,
+ * and it is measured rather than assumed:
+ *
+ * - A change to the BOOT COMPOSITION — a toggle, an uninstall — moves an
+ *   entry the registry already enumerates, and the served graph follows it
+ *   within seconds (§2, measured 2026-09-11). `true`.
+ * - A HOT MOUNT — an install or an update — adds to the live loader entries
+ *   without entering that composition, so the graph a tab reloads into does
+ *   not contain the package. Measured 2026-09-14 against dsh 0.1.5-rc.1 in
+ *   `web-full-flow.e2e.ts`: across a reload following a hot mount the graph
+ *   is byte-identical, same `rev`, while the package's host half is live the
+ *   whole time. `false` — and a `restart` is then the only honest answer,
+ *   because there is nothing a reload could fetch.
+ *
+ * The asymmetry that decides every unknown still runs the same way: offering
+ * a step that was not needed costs the reader one action, withholding one
+ * that was needed is the defect this module exists to fix. What changed on
+ * 2026-09-14 is which step is the needed one after a hot mount.
+ */
+export declare function activationOf(input: {
+    hostLive: boolean;
+    clientLive: boolean;
+    hasClientHalf: boolean;
+}): Activation;

package/lib/types/host/client-half.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Does an installed package have a browser half? (design
+ * 2026-09-11-activation-model §3.)
+ *
+ * The harness's `ClientModuleRegistry` scans the loader's entries for
+ * packages declaring `dsh.client` and composes `window.__DSH_BOOT__` from
+ * them. That declaration is therefore the whole question: a package that
+ * declares it puts something in a browser tab, and a tab opened before the
+ * change is showing the state from before it.
+ *
+ * The read goes through `HotFs`, the same injected seam `hot.ts` uses to
+ * read the same file for `dsh.bundle.patch`, so tests never touch disk and
+ * exactly one production call site does.
+ */
+import type { HotFs } from './hot.ts';
+/**
+ * Whether `packageName`, as installed in `profileDir`, declares `dsh.client`.
+ *
+ * **An unreadable manifest answers `true`.** Offering a reload that was not
+ * needed costs the reader one keystroke; withholding one that was needed is
+ * the defect this module exists to fix, so the fallback is the safe side of
+ * a lopsided asymmetry rather than a guess.
+ *
+ * The VALUE of `dsh.client` is not inspected — an empty object is a
+ * declaration. Only a non-object (the manifest saying something else
+ * entirely) reads as no declaration.
+ */
+export declare function hasClientHalf(fs: HotFs, profileDir: string, packageName: string): boolean;

package/lib/types/host/dsh-cli.d.ts

@@ -23,6 +23,17 @@
  */
 /** The npm package the dsh CLI is published as. */
 export declare const DSH_PACKAGE = "@deepseek-ai/dsh";
+/**
+ * The command that starts `bin` through `execPath` when `bin` names a
+ * JavaScript entry, or `null` when `bin` is a program to spawn as given.
+ *
+ * Extracted from {@link dshCommand} so `prefetch.ts` can reach the same
+ * decision for pnpm without a second copy of {@link JS_ENTRY}: both need it
+ * for the same two reasons — a packaged JS entry is what a caller pinning an
+ * installation can name, and a `.mjs` test fixture is the only fake CLI that
+ * can be spawned on Windows at all.
+ */
+export declare function jsEntryCommand(bin: string, args: readonly string[], execPath: string): DshCommand | null;
 export interface DshCliFs {
     exists: (path: string) => boolean;
     read: (path: string) => string;

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

@@ -3,11 +3,17 @@
  * `dsh plugin remove` (uninstall); the only differences are the verb and the
  * post-exit manifest confirmation. */
 import type { HotRestartReason } from './hot.ts';
-export type InstallState = 'running' | 'done' | 'failed';
+import type { Activation } from './activation.ts';
+import type { Prefetcher } from './prefetch.ts';
+import { type InstallState } from '../shared/install-state.ts';
+export type { InstallState } from '../shared/install-state.ts';
 export interface InstallStatus {
     state: InstallState;
     log: string[];
-    needsRestart?: boolean;
+    /** What the reader must do for this change to be visible (design
+     * 2026-09-11-activation-model). Present only on "done". Absent means the
+     * install is still running or failed, never "nothing to do". */
+    activation?: Activation;
     restartReason?: HotRestartReason;
     detail?: string;
 }
@@ -102,6 +108,11 @@ export interface KillFns {
     killPid: (pid: number) => void;
     taskkill: (pid: number) => void;
 }
+/** The real kill. Exported for the tests that inject a RECORDING `KillFns`:
+ * a recorder that only records asserts that a kill was requested and leaves
+ * the child running, which for a `detached` fixture is an immortal node
+ * process per run — see `prefetch.test.ts`'s delegating recorder. */
+export declare const nodeKills: KillFns;
 /** Kill a child and its descendants (process group on POSIX, taskkill tree on Windows). */
 export declare function killTree(pid: number | undefined, platform: NodeJS.Platform, kills?: KillFns): void;
 /** One stream's line assembler, retaining partial UTF-8 and text lines. */
@@ -163,13 +174,16 @@ export declare function startInstall(options: {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     expectedName?: string;
+    /** The download phase, when the caller has one — see `spawnPluginCli`.
+     * An uninstall has nothing to fetch and `startUninstall` takes none. */
+    prefetcher?: Prefetcher;
     /** A further post-exit check, run only once the bundle-activation confirm
      * has passed. Returning a detail fails the install with it. The package is
      * on disk by then, so this is for facts that are unreadable until it is —
      * see `collidingEntryId`. */
     alsoConfirm?: (home: string | undefined) => string | null;
     afterDone?: (home: string | undefined) => Promise<{
-        needsRestart: boolean;
+        activation: Activation;
         restartReason?: HotRestartReason;
     } | void>;
     onStatus?: (status: InstallStatus) => void;
@@ -189,10 +203,9 @@ export declare function startUninstall(options: {
     env?: NodeJS.ProcessEnv;
     expectedName?: string;
     afterDone?: (home: string | undefined) => Promise<{
-        needsRestart: boolean;
+        activation: Activation;
         restartReason?: HotRestartReason;
     } | void>;
     onStatus?: (status: InstallStatus) => void;
     timeoutMs?: number;
 }): RunningInstall;
-export {};

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

@@ -48,12 +48,22 @@ export interface PluginHandle {
     dispose(): Promise<unknown> | void;
 }
 /**
- * Why a hot mount could not activate — a stable code the client turns into
- * copy in the reader's own dsh language. It distinguishes "restart will fix
- * it" (`timeout`, `mount-failed`) from "this package can never hot-mount"
- * (`no-patch`, `not-simple`) and "this harness cannot" (`host-unsupported`).
+ * Why a restart is needed after the hot path ran — a stable code the client
+ * turns into copy in the reader's own dsh language.
+ *
+ * Four of the five say the MOUNT could not activate, and distinguish
+ * "restart will fix it" (`timeout`, `mount-failed`) from "this package can
+ * never hot-mount" (`no-patch`, `not-simple`) and "this harness cannot"
+ * (`host-unsupported`).
+ *
+ * `client-half` is the one that does not: the mount SUCCEEDED and the host
+ * half is running, but the package declares `dsh.client` and a hot mount does
+ * not enter the composition the client registry enumerates, so no reload can
+ * fetch its browser half (measured 2026-09-14 — see `activation.ts`). It
+ * exists so the reader is not told "installed; restart dsh to activate"
+ * about a plugin that is demonstrably already running.
  */
-export type HotRestartReason = 'no-patch' | 'not-simple' | 'host-unsupported' | 'timeout' | 'mount-failed';
+export type HotRestartReason = 'no-patch' | 'not-simple' | 'host-unsupported' | 'timeout' | 'mount-failed' | 'client-half';
 export interface HotMountResult {
     ok: boolean;
     /** null exactly when ok. */
@@ -78,6 +88,7 @@ export interface HotFs {
     write: (path: string, data: string) => void;
     list: (path: string) => string[];
 }
+export declare const nodeHotFs: HotFs;
 /**
  * Parse a bundle patch into the plain insert rows a hot tree can replicate.
  *

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

@@ -5,12 +5,16 @@ import { loadCatalog, type LoadCatalogOptions } from './catalog.ts';
 import type { CatalogEntry, DeniedEntry } from './types.ts';
 import { type InstallArgs, type InstallRejectionCode } from './install.ts';
 import { type InstallStatus } from './executor.ts';
-import { hotMount, hotUnmount } from './hot.ts';
+import { hotMount, hotUnmount, type HotFs } from './hot.ts';
+import { type Activation } from './activation.ts';
 import { type RestartOutcome } from './restart.ts';
 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';
 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';
 /** One Loader inventory entry, structurally — the shop never depends on
  * cordis-plugin-loader, whose types do not reach this package's typecheck. */
@@ -59,6 +63,10 @@ export interface ShopGatewayOptions {
         mount: typeof hotMount;
         unmount: typeof hotUnmount;
     };
+    /** Test-only injection: the filesystem `packageHasClientHalf` reads
+     * `dsh.client` through; the same seam `hot.ts` reads its patch through.
+     * Production uses `nodeHotFs`. */
+    hotFs?: HotFs;
     /** Test-only injection: the Loader's boot-layer entries; production reads
      * them from `ctx.loader`. */
     loaderEntries?: () => Array<LoaderEntryLike>;
@@ -106,12 +114,18 @@ export interface ShopGatewayOptions {
     /** Test-only injection: the peer ranges the self-check judges against;
      * production reads them from the shipped package.json. */
     peerRanges?: Record<string, string>;
+    /** Test-only injection: the download phase's pump; production builds the
+     * real one. A test gateway left with the real pump spawns `pnpm store add`
+     * — a live registry request — from every install that finds a command
+     * already queued for its profile. */
+    prefetcher?: Prefetcher;
 }
 /** `shop/installStart` result (§7.3): rejections are typed wire values with an
  * author-readable `detail`, not thrown RPC errors. */
 export type ShopInstallResult = {
     ok: true;
     installId: string;
+    state: InstallState;
 } | {
     ok: false;
     code: InstallRejectionCode;
@@ -120,12 +134,30 @@ export type ShopInstallResult = {
 export interface ShopInstallStatusResult extends InstallStatus {
     found: boolean;
 }
-/** `shop/setEnabled` result (§7.3): an unknown name is a typed wire value,
- * not a thrown RPC error. */
-export interface ShopSetEnabledResult {
-    ok: boolean;
-    detail?: string;
-}
+/**
+ * `shop/setEnabled` result (§7.3): an unknown name is a typed wire value, not
+ * a thrown RPC error.
+ *
+ * A union rather than one flat shape with two optional fields, so that
+ * "`activation` is present exactly when `ok`" is something the compiler
+ * holds instead of a sentence this comment asks every reader to hold. Every
+ * `ok` answer says what the reader must do for the toggle to be visible — a
+ * toggled package with a browser half needs a reload, which this result used
+ * to be unable to say (design 2026-09-11-activation-model §6) — and every
+ * refusal carries the detail that names why.
+ *
+ * The client still defaults an absent `activation` conservatively. This type
+ * binds the process it is compiled into; the WIRE outlives it, because a tab
+ * can reach an older in-process host for as long as one reload after a shop
+ * self-update lands on disk.
+ */
+export type ShopSetEnabledResult = {
+    ok: true;
+    activation: Activation;
+} | {
+    ok: false;
+    detail: string;
+};
 /** `shop/uninstallStart` result (§7.3): a name outside the catalog or not
  * installed is a typed wire value with an author-readable `detail`, not a
  * thrown RPC error. */
@@ -139,6 +171,19 @@ export type ShopUninstallResult = {
 /** `shop/restart` result (§7.3): the restarted server's URL, or a typed
  * failure — on failure the old process is still serving. */
 export type ShopRestartResult = RestartOutcome;
+/** Why `shop/restart` would refuse, for a reason fixed for the life of this
+ * process: the platform, the supervisor (env and ppid are read once at
+ * construction), and the launch argv. Every one of them is decided before the
+ * first request arrives, which is what lets `version()` advertise it and the
+ * client name it without asking again.
+ *
+ * `restart()` carries one further refusal this deliberately omits — a running
+ * install — because that one is transient: a mount-time answer about it would
+ * be stale the moment the install finished, and a card would go on saying a
+ * 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';
 /** `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
@@ -147,16 +192,17 @@ export interface ShopVersionResult {
     installed: string;
     latest: string | null;
     outdated: boolean;
-    /** Whether `shop/restart` is usable: false when a supervisor owns this
-     * process and no `allowRestart` override is set. The client hides the
-     * restart offer on false but keeps the pending-change notice. */
-    restartSupported: boolean;
+    /** Why `shop/restart` would refuse, or null when nothing static stands in
+     * 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;
 }
 /** `shop/updateStart` result (§7.3): the self-update spawn, or a typed
  * refusal (a version that is not plain semver). */
 export type ShopUpdateResult = {
     ok: true;
     installId: string;
+    state: InstallState;
 } | {
     ok: false;
     detail: string;
@@ -219,6 +265,7 @@ export declare class ShopGateway extends TypertRemoteService {
     private readonly profileDir?;
     private readonly inventory?;
     private readonly hot?;
+    private readonly hotFs?;
     private readonly loaderEntriesInjected?;
     private readonly dshBin;
     /** The argv `shop/restart` re-spawns: the real process argv minus node and
@@ -244,10 +291,13 @@ export declare class ShopGateway extends TypertRemoteService {
     /** The release-tarball fetch for the install-time integrity check; global
      * fetch in production, a fixture response in tests. */
     private readonly fetchTarball;
+    /** 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;
     /** 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
-     * state (§8: done / needsRestart / failure detail). Oldest evicted on add. */
+     * state (§8: done / activation / failure detail). Oldest evicted on add. */
     private static readonly MAX_FINISHED_INSTALLS;
     /** How long the gateway waits after a successful restart response before
      * exiting the old process — the browser must receive the URL first. */
@@ -342,7 +392,30 @@ export declare class ShopGateway extends TypertRemoteService {
      */
     private installedSpecOf;
     private ownedEntryIdsOrNone;
-    private liveDisableIds;
+    /** Whether an installed package declares `dsh.client`. Reads through the
+     * `hotFs` option — `HotFs` is `hot.ts`'s type, but this gateway forwards
+     * the option only HERE, never into `hotMount`, which takes its own `fs`
+     * from `HotDeps`. A fixture therefore drives this read alone, which is the
+     * point: it is the only way to state what a package declared BEFORE an
+     * update overwrote its manifest. */
+    private packageHasClientHalf;
+    /**
+     * Bring every live entry the package owns down, best effort, and report
+     * whether its host half is DOWN when this returns.
+     *
+     * "Nothing matched" is down: a package with no live entry is not running,
+     * which is the ordinary case for removing a plugin that never loaded this
+     * session. Only a matched entry whose fiber outlives the retries — or
+     * whose `update` throws — leaves the plugin UP, and that is the one case
+     * an uninstall must not describe as stopped.
+     *
+     * The old spelling answered "did any update succeed", which is a different
+     * question: `update` resolving says the row was accepted, not that the
+     * instance went away. The retry loop below exists precisely because those
+     * two come apart, so reading the first as the second threw away the answer
+     * 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
@@ -370,6 +443,26 @@ export declare class ShopGateway extends TypertRemoteService {
     /** Whether the two-phase handoff can run at all here. `restart.ts` drives
      * it through `sh`, `kill -0` and `sleep`, none of which Windows has. */
     private restartPlatformSupported;
+    /** Why a restart would be refused for this process, or null when nothing
+     * 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.
+     *
+     * - `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
+     *   to take the port — dsh would simply be gone.
+     * - `systemd`: under a unit the two-phase handoff kills itself, because the
+     *   main process exiting also kills the unit's cgroup and takes the detached
+     *   helper with it; the service never comes back. Overridable, and the only
+     *   one of the three that is.
+     * - `port-zero`: the OS hands the NEW process a fresh port the browser
+     *   cannot know, so a restart would strand the client on a dead origin. */
+    private staticRestartBlock;
     private allowRestartConfigured;
     /** Browse the catalog (§7.3): cached snapshot, refreshed on demand. */
     catalog(args?: {
@@ -382,10 +475,12 @@ export declare class ShopGateway extends TypertRemoteService {
      */
     install(args: InstallArgs): Promise<ShopInstallResult>;
     /** Bound retained finished records at MAX_FINISHED_INSTALLS, evicting the
-     * oldest finished ones (insertion order, oldest first). Running records
-     * are never evicted; an id absent from the map reports `found: false`. */
+     * oldest finished ones (insertion order, oldest first). Live records —
+     * running AND queued — are never evicted; an id absent from the map reports
+     * `found: false`. */
     private evictFinishedInstalls;
-    /** Whether any command this gateway started is still running. */
+    /** Whether any command this gateway started is still running — or still
+     * waiting its turn. */
     private hasRunningCommand;
     /** Poll one install's progress (§7.2); unknown ids report `found: false`. */
     installStatus(args: {

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

@@ -56,9 +56,11 @@ export declare function nodeVersionResolver(baseUrl: string): PeerVersionResolve
  *
  * `includePrerelease` is load-bearing, not a convenience. The harness ships
  * nothing but `-rc` versions, so under strict semver `^0.1.1-rc.2` excludes
- * `0.1.2-rc.1` — the version that is installed and works — and every future
- * rc bump would raise a false alarm. With it on, the range still excludes an
- * older prerelease (`0.1.1-rc.1`) and a minor- or major-line move
+ * every later rc on the same 0.1 line — including whichever one is installed
+ * and working, named as a property because that version moves and a comment
+ * naming it goes stale in place — and every future rc bump would raise a
+ * false alarm. With it on, the range still excludes an older prerelease
+ * (`0.1.1-rc.1`) and a minor- or major-line move
  * (`0.2.0-rc.1`, `1.0.0`), which are the moves that actually break a plugin
  * path. Discrimination on both sides is the whole point: one false warning
  * teaches a reader to ignore every warning.

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

@@ -0,0 +1,67 @@
+/**
+ * The download phase that runs in front of the per-profile install mutex.
+ *
+ * `dsh plugin add` is one opaque call: it resolves, fetches, links and writes
+ * in a single pnpm invocation, so the shop cannot split it. What it can do is
+ * warm pnpm's content store first, from outside the mutex, so the serialized
+ * install is a store hit. Measured 2026-09-10: an npm or github spec warmed
+ * this way installs with `downloaded 0`. Design doc §3.
+ *
+ * Best-effort by construction. Every failure here — pnpm absent, a non-zero
+ * batch, a timeout, a store guessed wrong — leaves `dsh plugin add` to fetch
+ * what the store lacks, exactly as it does today. Nothing about whether an
+ * install SUCCEEDS may depend on this module.
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { type KillFns } from './executor.ts';
+/**
+ * Whether warming the store for `spec` can save the install any work.
+ *
+ * A raw https tarball URL cannot, measured twice on 2026-09-10: pnpm
+ * re-fetches such a URL on EVERY install even when the store already holds
+ * that exact tarball — it must read the `package.json` inside it and that
+ * read does not go through the store — and `pnpm store add` on a URL resolves
+ * no dependency closure. So a prefetch of that form is one extra full
+ * download for no measured saving. The three spec forms are indistinguishable
+ * at the `store add` boundary (all exit 0, all print `+ <spec>`), which is why
+ * this exclusion is recorded rather than left to look like an oversight.
+ * Design doc §3.
+ */
+export declare function isPrefetchableSpec(spec: string): boolean;
+/** Why no download phase happened, when one did not. The caller writes the
+ * line a user reads, so it needs the reason and not a bare `false`. */
+export type PrefetchRequest = {
+    started: true;
+} | {
+    started: false;
+    reason: 'unsupported-spec' | 'no-pnpm';
+};
+export interface Prefetcher {
+    /** Queue `spec` for this profile's next batch, starting one if none runs.
+     * `log` receives the outcome of whichever batch ends up carrying this spec —
+     * one batch serves several installs, so a batch's exit is reported to each
+     * of them. */
+    request: (args: {
+        profile: string;
+        spec: string;
+        cwd: string;
+        env?: NodeJS.ProcessEnv;
+        log?: (line: string) => void;
+    }) => PrefetchRequest;
+    /** This spec's install has settled. Kills the batch when nothing else needs it. */
+    release: (profile: string, spec: string) => void;
+}
+/** The one call this module makes on `spawn`: the argv form, whose child
+ * carries the `error`/`exit` listeners `start` needs. `typeof nodeSpawn` is an
+ * overload set that also admits two-argument forms this module never builds a
+ * command line for, and a test's recording wrapper cannot satisfy those — so
+ * the seam is named, and a caller still passes `spawn` itself. */
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export declare function createPrefetcher(options?: {
+    pnpmBin?: string;
+    spawn?: SpawnFn;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    timeoutMs?: number;
+    kills?: KillFns;
+}): Prefetcher;

package/lib/types/shared/install-state.d.ts

@@ -0,0 +1,16 @@
+/** The lifecycle of one install or uninstall command (§7.2, §7.3).
+ *
+ * Declared here rather than beside either consumer because it crosses the RPC
+ * boundary: `executor.ts` produces it, `present.ts` consumes it, and each
+ * used to spell the union itself with nothing keeping the two in agreement.
+ *
+ * `downloading` and `running` are BOTH non-terminal. Until `downloading`
+ * existed there was exactly one non-terminal state, so `!== 'running'` was a
+ * safe synonym for "finished" and three call sites wrote it that way. Ask
+ * `isTerminalInstallState` instead — the next state added must not silently
+ * reclassify a live install as finished.
+ */
+export type InstallState = 'downloading' | 'running' | 'done' | 'failed';
+/** Whether the host is done with this record: it will not change again, and a
+ * poller may stop. */
+export declare function isTerminalInstallState(state: InstallState): state is 'done' | 'failed';