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

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 {
@@ -75,8 +78,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 +107,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 +142,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 +211,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 +226,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 +290,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;
@@ -278,6 +347,11 @@ export declare class ShopGateway extends TypertRemoteService {
     private readonly exit;
     private readonly restartExitDelayMs;
     private readonly restartParentPid;
+    /** The restart this process committed, once it has: every later
+     * `shop/restart` answers with it. A page that lost the first answer to an
+     * HMR swap asks again (client/restart-monitor.ts), and inside the exit
+     * delay that ask reaches this same process. */
+    private committedRestart;
     private readonly latestVersion;
     private readonly pinFs;
     private readonly allowRestart?;
@@ -294,6 +368,11 @@ 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;
+    /** Routes the output dsh's `pluginManager` streams to the record whose
+     * request id it carries (see the constructor). */
+    private readonly managerLogs;
     /** 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,17 +392,13 @@ 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;
-    /** Install records, running and finished; a poll finds one here or reports not found. */
+    /** 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, from the CLI and from dsh's
+     * `pluginManager` alike; 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. */
     private readonly installOrder;
@@ -347,6 +422,40 @@ 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 all of
+     * it (0.1.7 and later), else null. Never cached across calls, like
+     * `pluginPackages`, but read once per RPC, at its start, and passed down:
+     * read again after an await, a service disposed in between would let a
+     * desktop mutation past the desktop gate and onto the CLI path, which dsh
+     * refuses for that profile. Design 2026-09-26-plugin-manager-delegation,
+     * section 3.1. */
+    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 +467,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,10 +497,15 @@ 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;
+    /** Add every dependency the profile manifest holds to the `imported`
+     * record (see `importedThisProcess`): each is a package dsh's loader may
+     * have loaded in this process, at boot or by an install since. An
+     * unreadable manifest adds nothing. */
+    private recordDependenciesImported;
     private ownedEntryIdsOrNone;
     /** Whether an installed package declares `dsh.client`. Reads through the
      * `hotFs` option — `HotFs` is `hot.ts`'s type, but this gateway forwards
@@ -416,15 +531,50 @@ 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;
+    /**
+     * dsh's answer to a switch or a bundle selection, read the one way both
+     * callers need it (R32): the change, scrubbed for a desktop reader, and the
+     * detail that fails the request, or null when dsh applied it. `act` is what
+     * was asked, as "switch <name>", `request` names the request itself, as
+     * "the switch for <name>", and `stays` is the state the plugin keeps when
+     * the request does not take effect. An application this shop does not know
+     * fails rather than reading as applied: a later harness may answer
+     * something new.
+     *
+     * `overridden` fails too (R39). dsh answers it when, after it wrote the row
+     * and reloaded, the live entry still differs from the request
+     * (dsh-plugin-manager 0.1.7-rc.2, setPluginEnabled), and its README names
+     * what outranks the profile's own patch: home and invocation patches keep
+     * their higher priority. The change is saved and the plugin runs as it
+     * did, so a success would flip the client's switch over a plugin that did
+     * not change, and that switch never re-reads the live state.
+     * setBundleEnabled never answers it; a selection reads it the same way.
+     */
+    private readManagerAnswer;
     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 +597,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,12 +623,72 @@ 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
      * passing request reaches the executor.
      */
     install(args: InstallArgs): Promise<ShopInstallResult>;
+    /**
+     * What would stop the profile from starting now that `name`'s files are on
+     * disk, or null: an entry id another installed package already declares,
+     * or a bundle patch declaration this dsh cannot read. Neither is knowable
+     * before the files land. The package stays on disk either way, so each
+     * detail ends with `undo`, the sentence that says how to take the install
+     * back on the path that made it.
+     */
+    private postInstallHazard;
+    /** Remember a github entry's pinned commit: the manifest records only
+     * `github:owner/slug`, so the pins file is how `installed()` reports
+     * outdated honestly. A failed install leaves a pin behind, but the
+     * manifest presence gate keeps it invisible. */
+    private recordGithubPin;
+    /** Forget an uninstalled package's pins: its own, and its identity pin when
+     * a catalog row matched the installed spec. Both uninstall paths call this
+     * once their operation has started, so a stale pin never outlives the
+     * uninstall in the shop's cache either way. The plugin manager path tracks
+     * its record first, so a write here that throws cannot hide an operation
+     * already queued. */
+    private forgetPins;
+    /** What `managerOutcome` reads dsh's answer against. The gateway's own
+     * facts are set here once, for every operation through the service: the
+     * profile, whether it is the desktop one, and the deadline a timeout
+     * detail names. */
+    private outcomeContext;
+    /**
+     * One install-shaped operation through dsh's `pluginManager` (design
+     * 2026-09-26-plugin-manager-delegation, section 6): `installBundle(spec)`
+     * under the record's own id as its request id, so the output dsh streams
+     * for it reaches this record, in the profile's queue with the download
+     * phase the CLI path has. At the shop's deadline dsh is asked to cancel it;
+     * a service that offers no `cancelInstall` gets no deadline, and its record
+     * settles when dsh answers. `install` and `updateStart` differ only in the
+     * mechanism line and in how they read the answer.
+     */
+    private startManagerInstall;
+    /** Keep a started record where `installStatus`, the restart gate and
+     * eviction find it, then bound the finished ones. */
+    private track;
     /** Bound retained finished records at MAX_FINISHED_INSTALLS, evicting the
      * oldest finished ones (insertion order, oldest first). Live records —
      * running AND queued — are never evicted; an id absent from the map reports
@@ -534,6 +749,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/manager-runner.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One package operation through dsh's `pluginManager` service, tracked as the
+ * same `RunningInstall` the CLI executor produces: design
+ * 2026-09-26-plugin-manager-delegation, section 6. It runs in the same
+ * per-profile queue as CLI commands, so the two paths are never concurrent in
+ * one profile.
+ */
+import { type RunningInstall } from './executor.ts';
+import { type ManagerOutcome } from './plugin-manager.ts';
+import type { Prefetcher } from './prefetch.ts';
+/** The first line of every record this runner writes. The shop's log panel
+ * shows it and the 0.1.7 e2e asserts it, so a silent fall back to the CLI
+ * fails a case instead of passing it. */
+export declare const MECHANISM_PREFIX = "via dsh's plugin manager:";
+/** Routes the service's `plugin-manager/install-log` chunks to the record
+ * whose request id they carry. A chunk for any other id is dropped. dsh
+ * tags each chunk with the stream it came from; a non-string stream reads
+ * as `stdout`, matching a harness that predates the tag. */
+export declare class ManagerLogs {
+    private readonly sinks;
+    open(requestId: string, sink: (text: string, stream: string) => void): () => void;
+    chunk(requestId: unknown, text: unknown, stream?: unknown): void;
+}
+export interface ManagerOperationOptions {
+    profile: string;
+    /** The record's id, handed to the service as its request id. */
+    requestId: string;
+    /** What the mechanism line says after the prefix, e.g. `install dsh-a@1.0.0`. */
+    mechanism: string;
+    logs: ManagerLogs;
+    run: (requestId: string) => Promise<unknown>;
+    cancel?: (requestId: string) => Promise<unknown>;
+    outcome: (raw: unknown) => ManagerOutcome;
+    alsoConfirm?: () => string | null;
+    /** The download phase, as on the CLI path: `spec` is what it warms. */
+    prefetcher?: Prefetcher;
+    spec?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    /** The desktop profile, whose readers can run no `dsh plugin` command: a
+     * message the service call throws is scrubbed as dsh's answer is. */
+    desktop?: boolean;
+}
+/** What a thrown value says about itself, and total: describing an error is
+ * never itself the reason a settle fails. An `Error` gives its `message`,
+ * anything else `String(value)`. A message that is not a string, or a
+ * description that throws anywhere, reads as one fixed string: a Proxy whose
+ * getPrototypeOf trap throws defeats `instanceof` itself, a `message` getter
+ * can throw, and a null-prototype object has no conversion to a string. */
+export declare const messageOf: (error: unknown) => string;
+export declare function startManagerOperation(options: ManagerOperationOptions): RunningInstall;