dsh-home-hosted 0.3.2 → 0.4.0

package/lib/types/config.d.ts

@@ -11,5 +11,11 @@ export interface Config {
     homeHostedCommand?: string;
     /** The entry this plugin manages for the running harness. */
     defaultEntryId: string;
+    /**
+     * Extra home-hosted state roots to report as other panels. Discovery already
+     * knows the managed root, `$HHOSTED_HOME` and the `~/.home-hosted*` siblings;
+     * a panel run from a project with its own `--home` is declared here.
+     */
+    instanceRoots: string[];
 }
 export declare const Config: z<Config>;

package/lib/types/home-hosted/dsh-entry.d.ts

@@ -12,7 +12,6 @@ export declare function detectProfile(argv: readonly string[], env?: Record<stri
 export interface DshFacts {
     id: string;
     port: number | null;
-    host: string;
     profile: string | null;
     dshHome: string;
     launch: CliLaunch | null;
@@ -57,19 +56,26 @@ export declare function findDshEntry(dshHome: string): string | null;
  */
 export declare function resolveDshLaunch(options?: ResolveDshLaunchOptions): Promise<DshLaunch | null>;
 /**
- * Re-point an entry that boots a local build directly at the stable launcher.
+ * Re-point an entry at the stable launcher for the pinned image.
  *
- * Only this shape qualifies: the entry runs the same script this process does,
- * and that script is not already the launcher. An upgrade cannot repair the
- * entry it created in an earlier release otherwise — the plugin never rewrites
- * an existing entry's command.
+ * Qualifying shapes, and only these: the entry runs the script this pattern
+ * pins (a local build recorded in an earlier release), reaches that script
+ * through a package-manager shim, or names a bare `dsh`/`dsh.cmd` that a later
+ * PATH lookup would answer with a different copy. An entry that runs a
+ * *different* dsh is somebody's deliberate choice and is never touched.
+ *
+ * An entry this process was booted through is also left alone: repairing it
+ * would point it at itself, since that is already the launcher.
  */
+export declare function pinnedScriptFor(launch: DshLaunch | null): string | null;
 /**
  * Whether an entry *could* need that repair, without resolving anything.
  *
  * Resolving a local dsh walks the harness home, so the write path asks this
- * first: a global `dsh` on PATH, or an entry already on the launcher, is
- * settled here and never triggers the walk.
+ * first. Almost every shape can need one — an absolute command, an absolute
+ * first argument, a bare `dsh` — and the cheap answer is therefore "yes" here
+ * and a full comparison in `launcherRepair`, which is what decides whether
+ * anything is actually rewritten.
  */
 export declare function needsLauncherRepair(config: {
     command?: string;

package/lib/types/home-hosted/entries.d.ts

@@ -12,24 +12,10 @@ import type { EntryIntent, OnPortConflict, ServerEntry, ServerEntryPatch } from
  */
 export declare function defaultOnPortConflict(platform?: NodeJS.Platform): OnPortConflict;
 export declare function defaultIntent(id: string, platform?: NodeJS.Platform): EntryIntent;
-/**
- * The owned keys as a patch, preserving any sibling keys inside `stop`.
- *
- * `persistent` is omitted unless the panel that would parse the write knows the
- * key: an older schema drops it and warns, so writing one is noise at best.
- */
-export declare function ownedPatch(intent: EntryIntent, live?: ServerEntry | null, options?: {
-    persistent?: boolean;
-}): ServerEntryPatch;
-/**
- * Owned keys whose live value differs from the intent.
- *
- * The intent keeps what the person asked for; a key the panel cannot parse is
- * not drift, or every entry would report one on an older panel.
- */
-export declare function ownedDrift(live: ServerEntry | null, intent: EntryIntent, options?: {
-    persistent?: boolean;
-}): string[];
+/** The owned keys as a patch, preserving any sibling keys inside `stop`. */
+export declare function ownedPatch(intent: EntryIntent, live?: ServerEntry | null): ServerEntryPatch;
+/** Owned keys whose live value differs from the intent. */
+export declare function ownedDrift(live: ServerEntry | null, intent: EntryIntent): string[];
 /**
  * Only the owned keys, as they were before this plugin touched the entry.
  *

package/lib/types/home-hosted/instances-notice.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Telling the agent which home-hosted panels exist.
+ *
+ * A plugin that owns one panel must not look like the only one on the machine.
+ * When discovery finds more than one, the inventory is contributed as dynamic
+ * runtime context (`ctx.systemPrompt.context`), so every model step knows the
+ * managed panel, the others, and that this plugin cannot write to them.
+ *
+ * The contribution reads the service's cached inventory: assembly happens
+ * before a model step and must never block on the disk.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { InstanceView } from '../shared/contracts.js';
+/** The subset of `ctx.systemPrompt` this uses; absent on a host without it. */
+export interface SystemPromptLike {
+    context: (contribution: {
+        name: string;
+        order: number;
+        text: string | ((context: unknown) => string);
+    }) => () => void;
+}
+export interface InstancesNoticeDeps {
+    /** The inventory the plugin already measured; never a disk read at assembly. */
+    instances: () => readonly InstanceView[];
+    /** The `instancesNotice` setting, read per assembly. */
+    enabled: () => boolean;
+}
+/**
+ * After the first-party runtime contexts (sandbox 110, approval 115,
+ * subagent delegation 120) and before anything a repository owns.
+ */
+export declare const INSTANCES_CONTEXT_ORDER = 130;
+/** The exact text one assembly contributes, or `''` for nothing. */
+export declare function instancesContextText(instances: readonly InstanceView[], enabled: boolean): string;
+export declare function registerInstancesNotice(ctx: Context, deps: InstancesNoticeDeps): void;

package/lib/types/home-hosted/instances.d.ts

@@ -0,0 +1,34 @@
+import type { InstanceView } from '../shared/contracts.js';
+export interface InstanceDiscoveryOptions {
+    /** The state root this plugin drives. */
+    managedHome: string;
+    /** Extra roots an operator declared in the plugin row. */
+    extraRoots?: readonly string[];
+    /** Test seam: this process's `$HHOSTED_HOME`. */
+    envHome?: string | null;
+    /** Test seam: `HHOSTED_SERVER_ID`, or null when the panel does not supervise us. */
+    hostingEntryId?: string | null;
+    /** Test seam: the user's home directory. */
+    homeDir?: string;
+    /** Test seam: directory listing. */
+    listDir?: (dir: string) => string[] | null;
+    /** Test seam: whether a pid is alive. */
+    alive?: (pid: number) => boolean;
+}
+/** A path as one identity: `~` expanded, symlinks resolved (macOS `/var`). */
+export declare function canonicalPath(value: string): string;
+/** Every panel found, the managed one first and the rest by state root. */
+export declare function discoverInstances(options: InstanceDiscoveryOptions): InstanceView[];
+/**
+ * One line naming a panel, for a prompt note or a refusal. A root whose
+ * `run.json` is gone has no runtime to report — home-hosted drops a stale one —
+ * so it is never called "stopped".
+ */
+export declare function describeInstance(instance: InstanceView): string;
+/**
+ * The note the agent is given when the machine holds more than one panel.
+ *
+ * `null` for a single panel: the plugin's preference is only worth stating when
+ * there is something to prefer it over.
+ */
+export declare function instancesNoticeText(instances: readonly InstanceView[]): string | null;

package/lib/types/home-hosted/launcher.d.ts

@@ -40,6 +40,18 @@ export interface DshLauncherOptions {
     dshHome: string;
     /** Where the dsh entry is right now; recorded as the fast path. */
     resolvedEntry: string | null;
+    /**
+     * The image this plugin was installed on: the dsh a boot entry must keep
+     * running. Recorded and checked before anything else, so a copy that merely
+     * reports a higher version never wins the boot.
+     */
+    pinnedEntry?: string | null;
+    /**
+     * Adopt `pinnedEntry` even when the record already pins something else. Set
+     * only where the caller *is* the running image; a process booted through the
+     * launcher must carry the pin it started under instead of replacing it.
+     */
+    repin?: boolean;
     /** The extension the launcher must match: a `.cjs` entry gets a `.cjs` launcher. */
     entryExtension?: string | null;
     /**
@@ -53,8 +65,15 @@ export interface DshLauncherWrite {
     path: string;
     changed: boolean;
 }
-interface DshLauncherRecord {
+export interface DshLauncherRecord {
     entry: string | null;
+    /**
+     * The running image, while it still exists. A path here is an instruction:
+     * `choose()` runs this one and never sorts it against another copy.
+     */
+    pinned?: string | null;
+    /** When that image was last confirmed. */
+    pinnedAt?: number | null;
     /** Where that entry's install sat, kept across rewrites while it stays valid. */
     roots: string[];
     writtenAt: number;

package/lib/types/home-hosted/panel-control.d.ts

@@ -1,7 +1,10 @@
 import type { ChildProcess } from 'node:child_process';
 import type { PanelControlResult } from '../shared/contracts.js';
 import { run } from '../util/exec.js';
+import type { RunResult } from '../util/exec.js';
 import type { CliLaunch } from './launch.js';
+/** How the panel's CLI is run: the resolved argv plus an environment. */
+export type PanelCliExec = (args: string[], env: Record<string, string | undefined>) => Promise<RunResult>;
 export interface PanelControlDeps {
     /** The CLI to run, already resolved. */
     launch: CliLaunch | null;
@@ -11,9 +14,20 @@ export interface PanelControlDeps {
     /** Environment for the spawned CLI (absolute PATH, HOME, HHOSTED_HOME). */
     env: Record<string, string>;
     timeoutMs?: number;
+    /** Test seam: run the resolved CLI without spawning it. */
+    exec?: PanelCliExec;
 }
 /** Start the preferred CLI as a detached panel; the CLI itself does the detaching. */
 export declare function startPanel(deps: PanelControlDeps): Promise<PanelControlResult>;
+/**
+ * Stop the panel through its own CLI.
+ *
+ * The panel is the parent of every server it supervises, so this stops those
+ * too — including the dsh this plugin may be running in. That is the point of
+ * the button, not a hazard to hide: the caller's UI says so. An entry with
+ * `autostart` is started again on the next panel start; it is not restarted here.
+ */
+export declare function stopPanel(deps: PanelControlDeps): Promise<PanelControlResult>;
 export declare function takeoverHelperPath(stateDir: string): string;
 export declare function takeoverLogPath(stateDir: string): string;
 /** The generated helper's source; exported so a test can inspect it. */

package/lib/types/home-hosted/resolve.d.ts

@@ -1,13 +1,9 @@
 import type { CliStatus } from '../shared/contracts.js';
 import type { CliLaunch } from './launch.js';
 /** The range the plugin ships and is tested against. */
-export declare const EXPECTED_RANGE = "^0.6.6";
+export declare const EXPECTED_RANGE = "^0.6.7";
 /** Oldest release whose API and config schema this plugin relies on. */
 export declare const MIN_SUPPORTED_VERSION = "0.4.1";
-/** Oldest release whose config schema accepts `onPortConflict: kill`. */
-export declare const MIN_KILL_VERSION = "0.6.0";
-/** `persistent` (the nanny that keeps an entry alive across panel restarts). */
-export declare const MIN_PERSISTENT_VERSION = "0.6.3";
 export type CliPreference = 'pinned' | 'global';
 export interface CliResolution {
     launch: CliLaunch | null;

package/lib/types/home-hosted/token.d.ts

@@ -4,6 +4,8 @@ export interface EnsureTokenOptions {
     home: string;
     stateDir: string;
     exec: CliExecutor;
+    /** Which panel this credential is for; omitted is the panel the plugin manages. */
+    slot?: string;
 }
 export interface EnsureTokenResult {
     token: string | null;
@@ -15,14 +17,17 @@ export interface ReclaimTokenOptions {
     home: string;
     stateDir: string;
     exec: CliExecutor;
+    slot?: string;
 }
 export interface ReclaimTokenResult {
     token: string | null;
     detail: string;
 }
-export declare function storedTokenPath(stateDir: string): string;
-export declare function readStoredToken(stateDir: string): string | null;
-export declare function storeToken(stateDir: string, token: string): void;
+/** A stable, unguessable file name for one state root's credential. */
+export declare function tokenSlot(home: string): string;
+export declare function storedTokenPath(stateDir: string, slot?: string): string;
+export declare function readStoredToken(stateDir: string, slot?: string): string | null;
+export declare function storeToken(stateDir: string, token: string, slot?: string): void;
 export declare function generateToken(): string;
 /** Whether home-hosted already holds an API token (only its hash is on disk). */
 export declare function apiTokenEnrolled(home: string): boolean;

package/lib/types/service.d.ts

@@ -7,7 +7,7 @@
  * only when the panel is not answering.
  */
 import { Service, type Context } from '@deepseek-ai/cordis';
-import type { BootMechanism, BootStatus, HomeHostedStatus, ManagedEntryStatus, PanelControlResult, PanelStatus, RpcEndpoint, UiAction, UiResult } from './shared/contracts.js';
+import type { BootMechanism, BootStatus, HomeHostedStatus, InstanceView, ManagedEntryStatus, PanelControlResult, PanelStatus, RpcEndpoint, UiAction, UiResult } from './shared/contracts.js';
 import type { BootSpec } from './boot/types.js';
 import type { DshLaunch } from './home-hosted/dsh-entry.js';
 import type { SettingsStore } from './settings.js';
@@ -35,9 +35,17 @@ export declare class HomeHostedError extends Error {
 }
 export interface HomeHostedServiceOptions {
     home: string;
+    /** How that root was chosen: an explicit env var, an adopted legacy panel, or this instance's own. */
+    panelHomeSource?: 'env' | 'legacy' | 'instance';
     stateDir: string;
     homeHostedCommand?: string;
     defaultEntryId: string;
+    /** Other home-hosted state roots to report as panels; discovery finds the rest. */
+    instanceRoots?: readonly string[];
+    /** Test seam: this process's `$HHOSTED_HOME`; defaults to the environment. */
+    envHome?: string | null;
+    /** Test seam: where `~/.home-hosted*` siblings are looked for; defaults to the user's home. */
+    homeDir?: string;
     settings: SettingsStore;
     /** Test seam: run the home-hosted CLI without spawning it. */
     execCli?: (args: string[], env: Record<string, string | undefined>) => Promise<RunResult>;
@@ -57,9 +65,64 @@ export declare class HomeHostedService extends Service {
     private tokenDetail;
     /** When a missing managed entry was last put back, so a poll cannot become a write loop. */
     private entryRecoveryAt;
+    /** The last panel inventory, so a model-step assembly never reads the disk. */
+    private instanceCache;
     private readonly snapshotsFile;
     constructor(ctx: Context, options: HomeHostedServiceOptions);
     private resolveDsh;
+    /**
+     * The panel inventory, cached for a short while: the page polls status and
+     * the prompt provider reads it at every assembly. `refresh` (or an expired
+     * cache) re-reads the disk.
+     */
+    instances(refresh?: boolean): Promise<InstanceView[]>;
+    /**
+     * The inventory for a caller that cannot await — a prompt provider runs
+     * synchronously before a model step. Discovery is synchronous too, so this
+     * re-measures a stale cache in place and never blocks the step.
+     */
+    instancesNow(): InstanceView[];
+    private measureInstances;
+    /** The inventory as last measured, without touching the disk. */
+    instancesSnapshot(): InstanceView[];
+    /**
+     * The state root a call targets: the managed one unless it names another panel
+     * discovery reported. A caller-supplied path is never acted on directly, so a
+     * stray string cannot become a way to write anywhere on the disk.
+     */
+    private targetHome;
+    /**
+     * How a call reaches another panel. `via` names it; without one the endpoint's
+     * least invasive mechanism is used, which is the order the shared list keeps.
+     */
+    private mechanismFor;
+    /** Whether a token this plugin already holds for a panel still works. */
+    private foreignTokenWorks;
+    /**
+     * A client for another panel: the plugin's own credential for that state root,
+     * minted and enrolled the first time it is needed, proved against the panel,
+     * and replaced when the panel no longer accepts it.
+     *
+     * home-hosted keeps only a hash, so an existing token this plugin does not hold
+     * can only be replaced — which is what choosing this mechanism means.
+     */
+    private foreignClient;
+    /** Another panel's own config, refusing anything that is not a readable one. */
+    private readForeignConfig;
+    /** Another panel's entries as its config holds them: live status needs its API token. */
+    private listForeign;
+    private createForeign;
+    private updateForeign;
+    /** What a write actually left on disk, never what it was asked to write. */
+    private writtenForeignEntry;
+    private deleteForeign;
+    /**
+     * Start, stop or restart one entry through that panel's own CLI: this plugin
+     * holds no API token for a panel it does not manage, and a config edit cannot
+     * start anything. The CLI has no server restart, so a restart is a stop
+     * followed by a start — a stop that is not followed by one is reported.
+     */
+    private lifecycleForeign;
     private runtime;
     /** The entry id this very process was started as, when the panel supervises us. */
     selfEntryId(): string | null;
@@ -112,15 +175,6 @@ export declare class HomeHostedService extends Service {
     private dshCommandRepair;
     private writeOwned;
     private panelRunning;
-    /**
-     * The version whose schema will parse what we write: the answering panel, or
-     * the CLI that will parse it next. `kill` did not exist before 0.6.0, and an
-     * older panel refuses to *boot* with it — so this is checked before any write.
-     */
-    private configVersion;
-    /** Whether the panel whose schema parses our write knows `persistent`. */
-    private supportsPersistent;
-    private assertPolicySupported;
     private applyIntents;
     /**
      * Stop managing an entry: restore what it was when we only adopted it, or
@@ -131,7 +185,7 @@ export declare class HomeHostedService extends Service {
     /** Turn off the autostart intent for one entry, keeping the entry itself. */
     private pauseManagedEntry;
     /** Drive the panel's own UI through its CLI, and report what is installed. */
-    uiManage(action: UiAction, file?: string): Promise<UiResult>;
+    uiManage(action: UiAction, file?: string, target?: string): Promise<UiResult>;
     private restoreEntry;
     entriesStatus(): Promise<ManagedEntryStatus[]>;
     private ladder;
@@ -147,6 +201,15 @@ export declare class HomeHostedService extends Service {
     }>;
     /** Out-of-the-box start: run the preferred CLI's `up`, which detaches itself. */
     startPanelNow(): Promise<PanelControlResult>;
+    /**
+     * Stop the panel the plugin drives, and every server it supervises with it.
+     *
+     * Deliberately not a replacement for the takeover guard: stopping is safe to
+     * lose (an `autostart` entry comes back), while replacing is not. If this
+     * process is one of those servers the answer may never arrive, so the page
+     * treats a dropped call as "the panel is stopping" rather than a failure.
+     */
+    stopPanelNow(): Promise<PanelControlResult>;
     /**
      * Replace an answering panel with the preferred copy.
      *
@@ -179,7 +242,7 @@ export declare class HomeHostedService extends Service {
     private ensureManagedEntry;
     /** Re-assert the boot entry when the OS still has it but it stopped working. */
     private repairBootEntry;
-    status(): Promise<HomeHostedStatus>;
+    status(refresh?: boolean): Promise<HomeHostedStatus>;
     call(endpoint: RpcEndpoint, payload: unknown): Promise<unknown>;
 }
 declare module '@deepseek-ai/cordis' {

package/lib/types/shared/contracts.d.ts

@@ -21,7 +21,7 @@ export type Envelope<T> = {
     error: RpcError;
 };
 /** Endpoints the browser and the agent tools both speak. */
-export type RpcEndpoint = 'status' | 'servers.list' | 'servers.get' | 'servers.create' | 'servers.update' | 'servers.delete' | 'servers.start' | 'servers.stop' | 'servers.restart' | 'servers.freePort' | 'entries.apply' | 'entries.remove' | 'entries.restore' | 'boot.install' | 'boot.uninstall' | 'boot.verify' | 'panel.start' | 'panel.takeover' | 'panel.reclaimToken' | 'cli.installGlobal' | 'ui.manage' | 'settings.update';
+export type RpcEndpoint = 'status' | 'servers.list' | 'servers.get' | 'servers.create' | 'servers.update' | 'servers.delete' | 'servers.start' | 'servers.stop' | 'servers.restart' | 'servers.freePort' | 'entries.apply' | 'entries.remove' | 'entries.restore' | 'boot.install' | 'boot.uninstall' | 'boot.verify' | 'panel.start' | 'panel.stop' | 'panel.takeover' | 'panel.reclaimToken' | 'cli.installGlobal' | 'ui.manage' | 'settings.update';
 /** A settings write sends only the changed subtree; the host merges group by group. */
 export interface SettingsPatch {
     autostart?: Partial<PluginSettings['autostart']>;
@@ -30,36 +30,69 @@ export interface SettingsPatch {
     panel?: Partial<PluginSettings['panel']>;
     authNotice?: boolean;
     reclaimToken?: boolean;
+    instancesNotice?: boolean;
     uiStyle?: UiStyle;
     agentTools?: Partial<PluginSettings['agentTools']>;
     cli?: Partial<PluginSettings['cli']>;
 }
+/**
+ * A state root to act on instead of the panel this plugin manages. Only a panel
+ * discovery reports is accepted, and only on the endpoints {@link FOREIGN_MECHANISMS}
+ * lists.
+ */
+export interface ForeignTarget {
+    /** A discovered panel's `--home`; omitted means the panel this plugin manages. */
+    home?: string;
+    /**
+     * How to reach it; omitted means the endpoint's first mechanism. Only a value
+     * {@link FOREIGN_MECHANISMS} lists for that endpoint is accepted.
+     */
+    via?: ForeignMechanism;
+}
+/**
+ * How this plugin can act on a panel it does not manage.
+ *
+ * `file` edits that panel's `servers.config.json`, `cli` runs the home-hosted
+ * CLI against its state root, and `api` enrols a token for it and drives its own
+ * HTTP API — the only way to reach some operations, and the only one that gives
+ * live status.
+ */
+export type ForeignMechanism = 'file' | 'cli' | 'api';
+/**
+ * Which ways each endpoint has to reach another panel, least invasive first (the
+ * first entry is the default when a caller names no mechanism). A config edit
+ * needs no credential, the CLI needs none either, and `api` mints one.
+ *
+ * Anything absent here is about this machine or about the managed panel itself
+ * and is never aimed elsewhere.
+ */
+export declare const FOREIGN_MECHANISMS: Partial<Record<RpcEndpoint, readonly ForeignMechanism[]>>;
 export interface EndpointPayloads {
-    /** `refresh` is accepted and ignored: every status call re-reads live state. */
+    /** `refresh` bypasses the short panel-inventory cache; status is live either way. */
     'status': {
         refresh?: boolean;
     };
-    'servers.list': Record<string, never>;
+    'servers.list': ForeignTarget;
     'servers.get': {
         id: string;
     };
-    'servers.create': {
+    'servers.create': ForeignTarget & {
         entry: ServerEntry;
     };
-    'servers.update': {
+    'servers.update': ForeignTarget & {
         id: string;
         patch: ServerEntryPatch;
     };
-    'servers.delete': {
+    'servers.delete': ForeignTarget & {
         id: string;
     };
-    'servers.start': {
+    'servers.start': ForeignTarget & {
         id: string;
     };
-    'servers.stop': {
+    'servers.stop': ForeignTarget & {
         id: string;
     };
-    'servers.restart': {
+    'servers.restart': ForeignTarget & {
         id: string;
     };
     'servers.freePort': {
@@ -84,6 +117,11 @@ export interface EndpointPayloads {
     'boot.verify': Record<string, never>;
     /** Start the preferred CLI as a detached panel; refused while one already answers. */
     'panel.start': Record<string, never>;
+    /**
+     * Stop the answering panel through its own CLI. The servers it supervises stop
+     * with it, which can include the dsh this plugin is running in.
+     */
+    'panel.stop': Record<string, never>;
     /** Stop the answering panel and start the preferred copy instead. */
     'panel.takeover': {
         force?: boolean;
@@ -96,7 +134,7 @@ export interface EndpointPayloads {
     /** Install the pinned range as a global CLI, so the `global` preference can use it. */
     'cli.installGlobal': Record<string, never>;
     /** Drive the panel's own UI: status, update, revert, or switch to a local build. */
-    'ui.manage': {
+    'ui.manage': ForeignTarget & {
         action: UiAction;
         file?: string;
     };
@@ -237,6 +275,35 @@ export interface CliStatus {
     global?: CliCandidate | null;
     detail: string;
 }
+/**
+ * `home-hosted` is not one panel per machine: a person can install it per
+ * project, or run several panels from one install with different `--home`
+ * roots. The plugin drives exactly one of them — the root it resolved.
+ */
+export type InstanceSource = 'managed' | 'env' | 'sibling' | 'configured';
+/** One home-hosted panel: its state root, and the facts readable from it. */
+export interface InstanceView {
+    /** The state root itself: what `--home` / `$HHOSTED_HOME` names. */
+    home: string;
+    /**
+     * The panel this plugin drives. Every tool call targets it unless the call
+     * names another panel, and the plugin never writes to another one.
+     */
+    managed: boolean;
+    /** This dsh process runs as one of this panel's entries (`HHOSTED_SERVER_ID`). */
+    hosting: boolean;
+    url: string | null;
+    port: number | null;
+    pid: number | null;
+    version: string | null;
+    /** A `run.json` whose pid is still alive. */
+    running: boolean;
+    projectDir: string | null;
+    /** Entries in that panel's `servers.config.json`; `null` when it is unreadable. */
+    servers: number | null;
+    /** How discovery found this root. */
+    source: InstanceSource;
+}
 export type BootMechanism = 'systemd-user' | 'systemd-system' | 'xdg-autostart' | 'launchd-agent' | 'launchd-daemon' | 'windows-run' | 'windows-task' | 'container' | 'unsupported';
 export type BootState = 'not-installed' | 'installed-disabled' | 'enabled-running' | 'enabled-failing' | 'unsupported';
 export interface BootCandidate {
@@ -269,7 +336,7 @@ export declare const AGENT_TOOL_NAMES: readonly AgentToolName[];
  */
 export declare const MUTATING_AGENT_TOOLS: readonly AgentToolName[];
 /** The shape this release writes; a file without it was written by 0.1.x. */
-export declare const SETTINGS_VERSION = 2;
+export declare const SETTINGS_VERSION = 3;
 export type UiStyle = 'detailed' | 'compact';
 export interface PluginSettings {
     version: number;
@@ -299,6 +366,12 @@ export interface PluginSettings {
      * cleared it, or minted their own) should not keep an agent tool from working.
      */
     reclaimToken: boolean;
+    /**
+     * Tell the agent how many home-hosted panels exist on this machine, and ask
+     * the user which one to act on when there is more than one. On by default: a
+     * plugin that owns one panel must not look like the only one there is.
+     */
+    instancesNotice: boolean;
     /** `detailed` shows cards and open disclosures; `compact` folds both away. */
     uiStyle: UiStyle;
     cli: {
@@ -321,6 +394,14 @@ export interface HomeHostedStatus {
     /** The entry id this plugin manages; the page must not assume "dsh". */
     defaultEntryId: string;
     panel: PanelStatus;
+    /** The panel root this plugin instance drives, so a second install is visible. */
+    panelRoot?: string;
+    /** How that root was chosen; `legacy` means an existing `~/.home-hosted` panel was adopted. */
+    panelRootSource?: 'env' | 'legacy' | 'instance';
+    /** The OS boot artifact name this state root owns. */
+    bootUnitName?: string;
+    /** Every home-hosted panel found on this machine, the managed one first. */
+    instances?: InstanceView[];
     boot: BootStatus;
     entries: ManagedEntryStatus[];
     servers: ServerEntryView[];

package/lib/types/util/paths.d.ts

@@ -3,6 +3,27 @@ export declare function expandHome(value: string): string;
 export declare function dshHome(): string;
 /** home-hosted state root: `$HHOSTED_HOME`, else `~/.home-hosted`. */
 export declare function homeHostedHome(): string;
+/**
+ * The panel root one plugin instance drives.
+ *
+ * Two dsh installs share `~/.dsh` far more often than they should, and a shared
+ * panel root means two plugins editing one `servers.config.json` and one boot
+ * entry. So each instance normally gets its own root beside its own state.
+ *
+ * An explicit `$HHOSTED_HOME` is an instruction and always wins. So is a panel
+ * already living at the machine-wide default: an upgrade must never point a
+ * running panel somewhere else, or it would look like every server vanished.
+ */
+export declare function resolveHomeHostedHome(stateDir: string, env?: NodeJS.ProcessEnv, homeDir?: string): {
+    home: string;
+    source: 'env' | 'legacy' | 'instance';
+};
+/**
+ * The boot artifact one state root owns: the default keeps the historical name,
+ * and every other instance gets its own, so two plugins cannot overwrite one
+ * unit or delete the other's entry.
+ */
+export declare function bootUnitName(stateDir: string): string;
 /** Where this plugin keeps its own durable state (settings, snapshots, token). */
 export declare function pluginStateDir(override?: string): string;
 /** home-hosted's own tokens file, written by the panel at startup. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-home-hosted",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "DeepSeek Harness (dsh) plugin: start your dsh web server automatically at boot, and manage home-hosted's panel and servers from inside dsh.",
   "type": "module",
   "license": "MIT",
@@ -117,6 +117,6 @@
     "vitest": "^2.1.8"
   },
   "dependencies": {
-    "home-hosted": "^0.6.6"
+    "home-hosted": "^0.6.7"
   }
 }