dsh-home-hosted 0.3.2 → 0.4.0

package/lib/index.js

@@ -1,17 +1,28 @@
 // src/index.ts
-import path14 from "node:path";
+import path15 from "node:path";
 
 // src/config.ts
 import z from "@deepseek-ai/schemastery";
 var Config = z.object({
   stateDir: z.string().description("Plugin state directory; defaults to $DSH_HOME/dsh-home-hosted"),
   homeHostedCommand: z.string().description("home-hosted executable to put in a generated autostart entry"),
-  defaultEntryId: z.string().default("dsh").description("Server entry id used for the running harness")
+  defaultEntryId: z.string().default("dsh").description("Server entry id used for the running harness"),
+  instanceRoots: z.array(z.string()).default([]).description("Other home-hosted state roots (--home) to report as other panels")
 });
 
 // src/shared/contracts.ts
 var RPC_PATH = "/home-hosted";
 var RPC_VERSION = 1;
+var FOREIGN_MECHANISMS = {
+  "servers.list": ["file", "api"],
+  "servers.create": ["file", "api"],
+  "servers.update": ["file", "api"],
+  "servers.delete": ["file", "api"],
+  "servers.start": ["cli", "api"],
+  "servers.stop": ["cli", "api"],
+  "servers.restart": ["cli", "api"],
+  "ui.manage": ["cli"]
+};
 var ON_PORT_CONFLICT_POLICIES = ["block", "warn", "follow", "reclaim", "kill"];
 function isOnPortConflict(value) {
   return typeof value === "string" && ON_PORT_CONFLICT_POLICIES.includes(value);
@@ -30,7 +41,7 @@ var MUTATING_AGENT_TOOLS = [
   "autostart_manage",
   "ui_manage"
 ];
-var SETTINGS_VERSION = 2;
+var SETTINGS_VERSION = 3;
 var DEFAULT_SETTINGS = {
   version: SETTINGS_VERSION,
   autostart: { enabled: false, mechanism: "auto" },
@@ -41,14 +52,15 @@ var DEFAULT_SETTINGS = {
   panel: { port: null },
   authNotice: true,
   reclaimToken: true,
+  instancesNotice: true,
   uiStyle: "detailed",
   cli: { prefer: "pinned" }
 };
 
 // src/service.ts
 import { Service } from "@deepseek-ai/cordis";
-import fs13 from "node:fs";
-import path13 from "node:path";
+import fs15 from "node:fs";
+import path14 from "node:path";
 import process10 from "node:process";
 import { fileURLToPath } from "node:url";
 
@@ -1948,9 +1960,11 @@ function createBootLadder(options = {}) {
 }
 
 // src/home-hosted/config-file.ts
-import fs7 from "node:fs";
+import fs8 from "node:fs";
 
 // src/util/paths.ts
+import crypto from "node:crypto";
+import fs7 from "node:fs";
 import os3 from "node:os";
 import path6 from "node:path";
 function expandHome(value) {
@@ -1968,6 +1982,32 @@ function homeHostedHome() {
   const configured = process.env.HHOSTED_HOME?.trim();
   return configured ? path6.resolve(expandHome(configured)) : path6.join(os3.homedir(), ".home-hosted");
 }
+function resolveHomeHostedHome(stateDir, env = process.env, homeDir = os3.homedir()) {
+  const configured = env.HHOSTED_HOME?.trim();
+  if (configured)
+    return { home: path6.resolve(expandHome(configured)), source: "env" };
+  if (hasPanelState(path6.join(homeDir, ".home-hosted")))
+    return { home: path6.join(homeDir, ".home-hosted"), source: "legacy" };
+  return { home: path6.join(path6.resolve(expandHome(stateDir)), "panel"), source: "instance" };
+}
+function hasPanelState(home) {
+  return ["servers.config.json", "run.json"].some((file) => {
+    try {
+      return fs7.statSync(path6.join(home, file)).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+function bootUnitName(stateDir) {
+  if (isDefaultStateDir(stateDir))
+    return "home-hosted";
+  return `home-hosted-${crypto.createHash("sha256").update(path6.resolve(stateDir)).digest("hex").slice(0, 8)}`;
+}
+function isDefaultStateDir(stateDir) {
+  const bare = stateDir?.trim();
+  return bare === void 0 || bare.length === 0 || path6.resolve(expandHome(bare)) === path6.join(dshHome(), "dsh-home-hosted");
+}
 function pluginStateDir(override) {
   const configured = override?.trim();
   if (configured)
@@ -1989,7 +2029,7 @@ function readConfig(home) {
   const file = configFile(home);
   const raw = readJson(file);
   if (raw === null) {
-    const exists = fs7.existsSync(file);
+    const exists = fs8.existsSync(file);
     return { raw: null, exists, error: exists ? "the config file could not be parsed" : null };
   }
   if (!Array.isArray(raw.servers) && raw.servers !== void 0)
@@ -2033,12 +2073,12 @@ function removeEntry(raw, id) {
 }
 
 // src/home-hosted/dsh-entry.ts
-import fs11 from "node:fs";
+import fs12 from "node:fs";
 import path10 from "node:path";
 import process7 from "node:process";
 
 // src/home-hosted/launch.ts
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 import path7 from "node:path";
 import process4 from "node:process";
 async function which(command) {
@@ -2050,12 +2090,12 @@ async function which(command) {
   return first ?? null;
 }
 function resolveShimmedCli(absolute, nodePath = process4.execPath) {
-  if (!fs8.existsSync(absolute))
+  if (!fs9.existsSync(absolute))
     return null;
   if (/\.(?:mjs|cjs|js)$/.test(absolute))
     return { program: nodePath, args: [absolute], cliEntry: absolute, shimPath: null, source: "entry" };
   const shimTarget = /^#\s*cmd-shim-target=(.+)$/m.exec(readText(absolute) ?? "")?.[1]?.trim();
-  if (shimTarget !== void 0 && fs8.existsSync(shimTarget))
+  if (shimTarget !== void 0 && fs9.existsSync(shimTarget))
     return { program: nodePath, args: [shimTarget], cliEntry: shimTarget, shimPath: absolute, source: "shim-target" };
   return { program: absolute, args: [], cliEntry: null, shimPath: absolute, source: "shim" };
 }
@@ -2087,7 +2127,7 @@ function homeHostedEnv(facts, launch, extra = {}) {
 }
 function buildHomeHostedBootSpec(facts, launch, options) {
   const logDir = path7.join(facts.home, ".logs");
-  fs8.mkdirSync(logDir, { recursive: true });
+  fs9.mkdirSync(logDir, { recursive: true });
   const args = [...launch.args, "up", "--foreground", "--home", facts.home];
   if (facts.projectDir)
     args.push("--project", facts.projectDir);
@@ -2097,7 +2137,9 @@ function buildHomeHostedBootSpec(facts, launch, options) {
     cwd: facts.projectDir ?? facts.home,
     env: homeHostedEnv(facts, launch),
     marker: options.marker ?? "managed by dsh-home-hosted",
-    unitName: "home-hosted",
+    // One artifact per state root, so two plugin instances cannot overwrite or
+    // delete each other's entry. The default install keeps the historical name.
+    unitName: bootUnitName(options.stateDir),
     label: "home-hosted control panel",
     logDir
   };
@@ -2105,13 +2147,11 @@ function buildHomeHostedBootSpec(facts, launch, options) {
 
 // src/home-hosted/resolve.ts
 import { createRequire } from "node:module";
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 import path8 from "node:path";
 import process5 from "node:process";
-var EXPECTED_RANGE = "^0.6.6";
+var EXPECTED_RANGE = "^0.6.7";
 var MIN_SUPPORTED_VERSION = "0.4.1";
-var MIN_KILL_VERSION = "0.6.0";
-var MIN_PERSISTENT_VERSION = "0.6.3";
 function pinnedManifestPath() {
   try {
     return createRequire(import.meta.url).resolve("home-hosted/package.json");
@@ -2121,7 +2161,7 @@ function pinnedManifestPath() {
 }
 function binEntryFromManifest(manifestPath) {
   try {
-    const manifest = JSON.parse(fs9.readFileSync(manifestPath, "utf8"));
+    const manifest = JSON.parse(fs10.readFileSync(manifestPath, "utf8"));
     const declared = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.["home-hosted"] ?? Object.values(manifest.bin ?? {})[0];
     return typeof declared === "string" && declared.length > 0 ? path8.resolve(path8.dirname(manifestPath), declared) : null;
   } catch {
@@ -2204,10 +2244,10 @@ async function resolveCli(options = {}) {
   const manifest = (options.packageManifest ?? pinnedManifestPath)();
   const dependencyEntry = manifest === null ? null : binEntryFromManifest(manifest);
   let dependency = null;
-  if (dependencyEntry !== null && fs9.existsSync(dependencyEntry)) {
+  if (dependencyEntry !== null && fs10.existsSync(dependencyEntry)) {
     let version2 = null;
     try {
-      version2 = JSON.parse(fs9.readFileSync(manifest, "utf8")).version ?? null;
+      version2 = JSON.parse(fs10.readFileSync(manifest, "utf8")).version ?? null;
     } catch {
       version2 = null;
     }
@@ -2282,7 +2322,7 @@ async function resolveCli(options = {}) {
 }
 
 // src/home-hosted/launcher.ts
-import fs10 from "node:fs";
+import fs11 from "node:fs";
 import path9 from "node:path";
 import process6 from "node:process";
 function launcherDir(stateDir) {
@@ -2399,11 +2439,11 @@ process.exit(typeof result.status === 'number' ? result.status : 1)
 function writeLauncher(options) {
   const file = launcherPath(options.stateDir);
   const source = buildLauncherSource(options);
-  const previous = fs10.existsSync(file) ? fs10.readFileSync(file, "utf8") : null;
+  const previous = fs11.existsSync(file) ? fs11.readFileSync(file, "utf8") : null;
   const changed = previous !== source;
   if (changed) {
     writeFileAtomic(file, source, 493);
-    fs10.chmodSync(file, 493);
+    fs11.chmodSync(file, 493);
   }
   writeJsonAtomic(launcherRecordPath(options.stateDir), {
     entry: options.resolvedEntry,
@@ -2415,7 +2455,7 @@ function writeLauncher(options) {
 }
 async function preflightLauncher(stateDir, timeoutMs = 1e4) {
   const file = launcherPath(stateDir);
-  if (!fs10.existsSync(file))
+  if (!fs11.existsSync(file))
     return null;
   const result = process6.platform === "win32" ? await run(process6.execPath, [file, "--version"], { timeoutMs }) : await run(file, ["--version"], { timeoutMs });
   return parseVersion(result.stdout) ?? parseVersion(result.stderr);
@@ -2439,27 +2479,69 @@ import { spawnSync } from 'node:child_process'` : `const fs = require('node:fs')
 const path = require('node:path')
 const process = require('node:process')
 const { spawnSync } = require('node:child_process')`;
-  const roots = [options.resolvedEntry === null ? null : dshSearchRoot(options.resolvedEntry), ...options.searchRoots ?? []].filter((root) => typeof root === "string" && root.length > 0);
+  const searchRoots = [
+    options.resolvedEntry === null ? null : dshSearchRoot(options.resolvedEntry),
+    options.pinnedEntry === null || options.pinnedEntry === void 0 ? null : dshSearchRoot(options.pinnedEntry),
+    ...options.searchRoots ?? []
+  ].filter((root) => typeof root === "string" && root.length > 0);
   return `#!/usr/bin/env node
 // managed by dsh-home-hosted \u2014 rewritten on every plugin start; do not edit.
 ${prelude}
 
 const DSH_HOME = ${JSON.stringify(options.dshHome)}
 const RECORD = ${JSON.stringify(dshLauncherRecordPath(options.stateDir))}
-const SEARCH_ROOTS = ${JSON.stringify([...new Set(roots)])}
+const SEARCH_ROOTS = ${JSON.stringify([...new Set(searchRoots)])}
+// The image this plugin was installed on, when the record had one to carry.
+const PINNED = ${JSON.stringify(options.pinnedEntry ?? null)}
 
 function readRecord() {
   try { return JSON.parse(fs.readFileSync(RECORD, 'utf8')) } catch { return null }
 }
 
-function isEntry(file) {
+function isFile(file) {
   let stat = null
   try { stat = fs.statSync(file) } catch { return false }
-  return stat.isFile() && /\\.(?:mjs|cjs|js)$/.test(file)
+  return stat.isFile()
 }
 
-function collect(out, entry) {
-  if (typeof entry === 'string' && isEntry(entry) && !out.includes(entry)) out.push(entry)
+// One identity per file: a recorded path and a candidate reached through a
+// symlink must compare equal, or a macOS clone would look like a different copy.
+function canon(file) {
+  try { return fs.realpathSync(file) } catch { return file }
+}
+
+// Keep what can actually boot: a JavaScript entry, or a shim whose recorded
+// target is one. A bare shim found on PATH is not a script, so requiring the
+// extension would silently drop the last resort.
+//
+// Each candidate carries how it was found, which is what ordering uses:
+//   TIER_REAL   a dsh by construction (a manifest, or node_modules/dsh)
+//   TIER_PROBE  a root that merely offers a build file \u2014 any package may
+//   TIER_PATH   a dsh executable found on PATH
+const TIER_REAL = 2
+const TIER_PROBE = 1
+const TIER_PATH = 0
+
+function collect(out, entry, source, tier) {
+  const argument = typeof source === 'string' && source.length > 0 ? source : entry
+  const file = typeof entry === 'string' && isFile(entry) ? canon(entry) : null
+  if (file !== null && /\\.(?:mjs|cjs|js)$/.test(file)) {
+    if (!out.has(file) || (out.get(file) ?? 0) < tier) out.set(file, tier)
+    return
+  }
+  // Anything else is a shim: only its recorded target can boot, and a shim
+  // without one is not a candidate at all (never a second pass over itself).
+  if (typeof argument !== 'string' || !isFile(argument)) return
+  let text = ''
+  try { text = fs.readFileSync(argument, 'utf8') } catch { return }
+  const marker = 'cmd-shim-target='
+  const at = text.indexOf(marker)
+  if (at === -1) return
+  const target = text.slice(at + marker.length).split('\\n')[0].trim()
+  if (target.length === 0) return
+  const real = canon(target)
+  if (!/\\.(?:mjs|cjs|js)$/.test(real)) return
+  if (!out.has(real) || (out.get(real) ?? 0) < tier) out.set(real, tier)
 }
 
 function collectStore(root, out) {
@@ -2468,30 +2550,36 @@ function collectStore(root, out) {
   try { names = fs.readdirSync(store) } catch { return }
   for (const name of names) {
     if (!name.startsWith('dsh@') && !name.startsWith('@deepseek-ai+dsh@')) continue
-    collect(out, path.join(store, name, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'))
-    collect(out, path.join(store, name, 'node_modules', 'dsh', 'bin', 'dsh.js'))
+    collect(out, path.join(store, name, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'), null, TIER_REAL)
+    collect(out, path.join(store, name, 'node_modules', 'dsh', 'bin', 'dsh.js'), null, TIER_REAL)
   }
 }
 
 function collectRoot(root, out) {
-  collect(out, path.join(root, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'))
-  collect(out, path.join(root, 'node_modules', 'dsh', 'bin', 'dsh.js'))
+  collect(out, path.join(root, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'), null, TIER_REAL)
+  collect(out, path.join(root, 'node_modules', 'dsh', 'bin', 'dsh.js'), null, TIER_REAL)
   collectStore(root, out)
+  // A clone keeps its build output at its own root, not under node_modules.
+  for (const entry of ['lib/bin.js', 'lib/bin.mjs', 'lib/bin.cjs', 'dist/bin.js'])
+    collect(out, path.join(root, entry), null, TIER_PROBE)
 }
 
-function candidates() {
-  const out = []
+function candidates(skipPath) {
+  const out = new Map()
   const record = readRecord()
-  if (record && typeof record.entry === 'string') collect(out, record.entry)
+  if (record && typeof record.entry === 'string') collect(out, record.entry, record.entry, TIER_REAL)
   for (const root of [...(Array.isArray(record?.roots) ? record.roots : []), ...SEARCH_ROOTS]) collectRoot(root, out)
   collectRoot(DSH_HOME, out)
   let profiles = []
   try { profiles = fs.readdirSync(path.join(DSH_HOME, 'profiles')) } catch {}
   for (const name of profiles) collectRoot(path.join(DSH_HOME, 'profiles', name), out)
-  // Last resort: a dsh on the entry's own PATH.
+  // Last resort: a dsh on the entry's own PATH. It is no longer an equal
+  // candidate: a copy found there is only booted when nothing else answers.
+  if (skipPath) return out
   for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
-    collect(out, path.join(dir, 'dsh'))
-    collect(out, path.join(dir, 'dsh.cmd'))
+    const shim = path.join(dir, 'dsh')
+    collect(out, shim, shim, TIER_PATH)
+    collect(out, path.join(dir, 'dsh.cmd'), path.join(dir, 'dsh.cmd'), TIER_PATH)
   }
   return out
 }
@@ -2524,22 +2612,43 @@ function compare(a, b) {
   return left.pre < right.pre ? -1 : 1
 }
 
-// A recorded path that still exists is usually the copy to boot, but never the
-// older one: a rebuild or upgrade that landed elsewhere must win on version.
-function choose() {
-  const recorded = readRecord()?.entry ?? null
-  const found = candidates().map(entry => ({ entry, recorded: entry === recorded, version: versionOf(entry) }))
-  const known = found.filter(item => item.version !== null)
+function findPin(pin, found) {
+  if (typeof pin !== 'string' || pin.length === 0) return null
+  const real = canon(pin)
+  return found.find(item => item.entry === real)?.entry ?? null
+}
+
+// A root that only offers a build file (lib/bin.js) is a guess: any package may
+// have one. Those stay usable but never outrank a copy that is dsh by
+// construction, or a dsh executable from PATH below them.
+function bestOfTier(found, tier) {
+  const at = found.filter(item => item.tier >= tier)
+  const known = at.filter(item => item.version !== null)
   if (known.length > 0) {
-    known.sort((a, b) => (compare(b.version, a.version) || (Number(b.recorded) - Number(a.recorded))))
+    known.sort((a, b) => compare(b.version, a.version))
     return known[0].entry
   }
-  return (found.find(item => item.recorded) ?? found[0])?.entry ?? null
+  return at[0]?.entry ?? null
+}
+
+// Choose the image this plugin was installed on, and only then fall back to a
+// version sort: a higher version elsewhere is not an invitation to boot it.
+function choose() {
+  const record = readRecord()
+  const pin = typeof record?.pinned === 'string' && record.pinned.length > 0 ? record.pinned : PINNED
+  const found = [...candidates(true)].map(([entry, tier]) => ({ entry, tier, version: versionOf(entry) }))
+  const pinned = findPin(pin, found)
+  if (pinned !== null) return pinned
+  // Real dsh installs first; a bare build-file guess only when nothing else
+  // exists; PATH only when nothing local answered at all.
+  return bestOfTier(found, TIER_REAL)
+    ?? bestOfTier(found, TIER_PROBE)
+    ?? bestOfTier([...candidates(false)].map(([entry, tier]) => ({ entry, tier, version: versionOf(entry) })), TIER_PATH)
 }
 
 const entry = choose()
 if (entry === null) {
-  console.error('[dsh-home-hosted] no dsh entry found for ' + DSH_HOME + ' (recorded path, $DSH_HOME node_modules, profiles/*, PATH). Reinstall dsh, or restart: dsh web')
+  console.error('[dsh-home-hosted] no dsh entry found for ' + DSH_HOME + ' (pinned path, recorded path, $DSH_HOME node_modules, profiles/*, PATH). Reinstall dsh, or restart: dsh web')
   process.exit(1)
 }
 
@@ -2552,42 +2661,61 @@ process.exit(typeof result.status === 'number' ? result.status : 1)
 }
 function writeDshLauncher(options) {
   const file = dshLauncherPath(options.stateDir, options.entryExtension);
-  const source = buildDshLauncherSource(options);
-  const previous = fs10.existsSync(file) ? fs10.readFileSync(file, "utf8") : null;
-  const changed = previous !== source;
+  const previousRecord = readDshLauncherRecord(options.stateDir);
+  const recordedPin = existingEntry(previousRecord?.pinned);
+  const offered = existingEntry(options.pinnedEntry);
+  const pinned = options.repin === true ? offered ?? recordedPin : recordedPin ?? offered;
+  const source = buildDshLauncherSource({
+    ...options,
+    pinnedEntry: pinned === null ? options.pinnedEntry ?? null : pinned
+  });
+  const changed = (fs11.existsSync(file) ? fs11.readFileSync(file, "utf8") : null) !== source;
   if (changed) {
     writeFileAtomic(file, source, 493);
-    fs10.chmodSync(file, 493);
+    fs11.chmodSync(file, 493);
   }
-  const raw = [dshSearchRoot(options.resolvedEntry), ...options.searchRoots ?? [], ...readDshLauncherRecord(options.stateDir)?.roots ?? []];
+  const raw = [dshSearchRoot(options.resolvedEntry), dshSearchRoot(pinned), ...options.searchRoots ?? [], ...previousRecord?.roots ?? []];
   const known = raw.filter((root) => typeof root === "string" && root.length > 0 && dshRootUsable(root));
   const roots = [...new Set(known)];
   writeJsonAtomic(dshLauncherRecordPath(options.stateDir), {
     entry: options.resolvedEntry,
+    pinned,
+    pinnedAt: pinned === null ? null : pinned === recordedPin ? previousRecord?.pinnedAt ?? Date.now() : Date.now(),
     roots,
     writtenAt: Date.now()
   }, 384);
   return { path: file, changed };
 }
+function existingEntry(file) {
+  if (typeof file !== "string" || file.length === 0)
+    return null;
+  if (!fs11.existsSync(file))
+    return null;
+  try {
+    return fs11.realpathSync(file);
+  } catch {
+    return null;
+  }
+}
 function dshCandidatesUnder(root) {
   const out = [];
   for (const entry of [
     path9.join(root, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
     path9.join(root, "node_modules", "dsh", "bin", "dsh.js")
   ]) {
-    if (fs10.existsSync(entry))
+    if (fs11.existsSync(entry))
       out.push(entry);
   }
   const store = path9.join(root, "node_modules", ".pnpm");
-  if (fs10.existsSync(store)) {
-    for (const name2 of fs10.readdirSync(store)) {
+  if (fs11.existsSync(store)) {
+    for (const name2 of fs11.readdirSync(store)) {
       if (!name2.startsWith("dsh@") && !name2.startsWith("@deepseek-ai+dsh@"))
         continue;
       for (const entry of [
         path9.join(store, name2, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
         path9.join(store, name2, "node_modules", "dsh", "bin", "dsh.js")
       ]) {
-        if (fs10.existsSync(entry))
+        if (fs11.existsSync(entry))
           out.push(entry);
       }
     }
@@ -2598,12 +2726,32 @@ function dshSearchRoot(entry) {
   if (typeof entry !== "string" || entry.length === 0)
     return null;
   const parts = entry.split(path9.sep);
-  const store = parts.indexOf(".pnpm");
-  const modules = store > 0 ? store - 1 : parts.lastIndexOf("node_modules");
-  return modules > 0 ? parts.slice(0, modules).join(path9.sep) : null;
+  const store = parts.lastIndexOf(".pnpm");
+  const modules = parts.lastIndexOf("node_modules");
+  const root = store > 0 ? parts.lastIndexOf("node_modules", store) : modules;
+  if (root > 0)
+    return parts.slice(0, root).join(path9.sep);
+  return ownerRoot(entry) ?? (parts.length > 2 ? parts.slice(0, -2).join(path9.sep) : null);
+}
+function ownerRoot(entry) {
+  let dir = path9.dirname(entry);
+  for (let hop = 0; hop < 4; hop += 1) {
+    const manifestPath = path9.join(dir, "package.json");
+    const manifest = readJson(manifestPath);
+    if (manifest !== null) {
+      const declared = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.["dsh"] ?? Object.values(manifest.bin ?? {})[0];
+      if (typeof declared === "string" && path9.resolve(path9.dirname(manifestPath), declared) === entry)
+        return dir;
+    }
+    const parent = path9.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
 }
 function dshRootUsable(root) {
-  return dshCandidatesUnder(root).length > 0 || fs10.existsSync(path9.join(root, "node_modules", ".pnpm"));
+  return dshCandidatesUnder(root).length > 0 || fs11.existsSync(path9.join(root, "node_modules", ".pnpm")) || ["lib/bin.js", "lib/bin.mjs", "lib/bin.cjs", "dist/bin.js"].some((entry) => fs11.existsSync(path9.join(root, entry)));
 }
 
 // src/home-hosted/dsh-entry.ts
@@ -2638,11 +2786,11 @@ function versionOf(entry) {
   return null;
 }
 function isEntry(file) {
-  return /\.[cm]?js$/.test(file) && fs11.existsSync(file) && !fs11.statSync(file).isDirectory();
+  return /\.[cm]?js$/.test(file) && fs12.existsSync(file) && !fs12.statSync(file).isDirectory();
 }
 function realPath(file) {
   try {
-    return fs11.realpathSync(file);
+    return fs12.realpathSync(file);
   } catch {
     return file;
   }
@@ -2683,7 +2831,7 @@ function findDshEntry(dshHome2) {
 }
 function readdirNames(dir) {
   try {
-    return fs11.readdirSync(dir);
+    return fs12.readdirSync(dir);
   } catch {
     return [];
   }
@@ -2698,12 +2846,27 @@ async function resolveDshLaunch(options = {}) {
       stateDir,
       dshHome: dshHome2,
       resolvedEntry: local,
+      // The running image is the one a boot entry must keep running: a global
+      // copy that reports a higher version is not an upgrade of this install.
+      pinnedEntry: local,
+      repin: true,
       entryExtension: path10.extname(local),
       // Where this install sits, so a rebuilt/moved copy is found next boot.
       searchRoots: [dshSearchRoot(local)].filter((root) => root !== null)
     });
     return { program: process7.execPath, args: [local], cliEntry: local, shimPath: null, source: "entry", launcherPath: launcher.path };
   }
+  if (argv1 !== void 0 && argv1 !== null && realPath(argv1) === realPath(dshLauncherPath(stateDir, path10.extname(local ?? argv1)))) {
+    const pinned = readDshLauncherRecord(stateDir)?.pinned ?? null;
+    if (pinned !== null) {
+      const launcher = dshLauncherPath(stateDir, path10.extname(pinned));
+      const launch2 = resolveShimmedCli(pinned, process7.execPath);
+      const cliEntry = launch2?.cliEntry ?? pinned;
+      if (readDshLauncherRecord(stateDir)?.entry !== pinned)
+        writeDshLauncher({ stateDir, dshHome: dshHome2, resolvedEntry: cliEntry, pinnedEntry: pinned, entryExtension: path10.extname(pinned) });
+      return { program: process7.execPath, args: [launcher], cliEntry, shimPath: null, source: "entry", launcherPath: launcher };
+    }
+  }
   const installed = findDshEntry(dshHome2);
   if (installed !== null) {
     const launcher = writeDshLauncher({ stateDir, dshHome: dshHome2, resolvedEntry: installed, entryExtension: path10.extname(installed) });
@@ -2712,6 +2875,8 @@ async function resolveDshLaunch(options = {}) {
   const found = await (options.findOnPath ?? which)("dsh");
   if (found === null)
     return null;
+  if (readDshLauncherRecord(stateDir)?.pinned != null)
+    return null;
   const launch = resolveShimmedCli(found, process7.execPath);
   return launch === null ? null : { ...launch, launcherPath: null };
 }
@@ -2729,25 +2894,44 @@ function entryScript(config) {
   const rest = config.args ?? [];
   return rest.find((arg) => path10.isAbsolute(arg)) ?? program;
 }
+function pinnedScriptFor(launch) {
+  if (launch === null)
+    return null;
+  const launcher = launch.launcherPath;
+  if (launcher !== null && launcher.length > 0)
+    return launcher;
+  return launch.cliEntry ?? launch.args.find((arg) => path10.isAbsolute(arg)) ?? null;
+}
+function isBareCommand(stored) {
+  return !/[/\\]/.test(stored) && (stored === "dsh" || /^dsh\.(?:cmd|exe)$/i.test(stored));
+}
 function needsLauncherRepair(config) {
   const program = config.command;
   if (typeof program !== "string" || program.length === 0)
     return false;
   if (path10.isAbsolute(program))
     return true;
-  return (config.args ?? []).some((arg, index) => index === 0 && path10.isAbsolute(arg));
+  if (isBareCommand(program))
+    return true;
+  return (config.args ?? []).some((arg) => path10.isAbsolute(arg));
 }
 function launcherRepair(config, launch) {
-  if (launch?.launcherPath == null || launch.launcherPath.length === 0)
+  const pinned = pinnedScriptFor(launch);
+  if (pinned === null || launch === null)
     return null;
-  const launcher = launch.launcherPath;
   const stored = entryScript(config);
-  if (stored === null || stored === launcher)
+  if (stored === null || stored === pinned)
     return null;
-  if (stored !== launch.cliEntry)
-    return null;
-  const rest = (config.args ?? []).filter((arg, index) => !(index === 0 && path10.isAbsolute(arg)));
-  return { command: process7.execPath, args: [launcher, ...rest] };
+  const bare = isBareCommand(stored);
+  if (!bare) {
+    const target = resolveShimmedCli(stored, process7.execPath)?.cliEntry ?? stored;
+    if (target !== pinned && target !== launch.cliEntry)
+      return null;
+  }
+  const args = config.args ?? [];
+  const inline = bare ? -1 : args.findIndex((arg) => path10.isAbsolute(arg));
+  const rest = inline === -1 ? args : args.filter((_, index) => index !== inline);
+  return { command: process7.execPath, args: [pinned, ...rest] };
 }
 function buildDshEntry(facts) {
   const launch = facts.launch;
@@ -2758,13 +2942,11 @@ function buildDshEntry(facts) {
       "--port",
       "{port}",
       "--host",
-      "{host}",
+      "127.0.0.1",
       "--no-open",
       "--trusted-host",
       `localhost:{port}`
     );
-    if (facts.host === "0.0.0.0")
-      appArgs.push("--trusted-host", "{lanIp}:{port}");
   }
   const launcherArgs = profile === "web" ? ["web"] : ["--profile", profile];
   const generated = launch === null ? { command: "dsh", entryArgs: [] } : buildCommand(launch, facts.launcherPath ?? null);
@@ -2775,7 +2957,7 @@ function buildDshEntry(facts) {
     autostart: true,
     command: generated.command,
     args: [...generated.entryArgs, ...launcherArgs, ...appArgs],
-    bind: facts.host === "0.0.0.0" ? "lan" : "local",
+    bind: "local",
     port: facts.port,
     cwd: process7.cwd(),
     env: {},
@@ -2791,6 +2973,186 @@ function buildDshEntry(facts) {
   };
 }
 
+// src/home-hosted/instances.ts
+import fs13 from "node:fs";
+import os4 from "node:os";
+import path11 from "node:path";
+
+// src/home-hosted/runtime.ts
+import http from "node:http";
+import https from "node:https";
+import process8 from "node:process";
+function readRuntime(home) {
+  const raw = readJson(runtimeFile(home));
+  if (raw === null)
+    return null;
+  const url = typeof raw.url === "string" ? raw.url : null;
+  const pid = typeof raw.pid === "number" ? raw.pid : null;
+  if (url === null || pid === null)
+    return null;
+  return {
+    version: typeof raw.version === "string" ? raw.version : "unknown",
+    pid,
+    url: url.replace(/\/+$/, ""),
+    probeUrl: typeof raw.probeUrl === "string" ? raw.probeUrl : void 0,
+    protocol: typeof raw.protocol === "string" ? raw.protocol : void 0,
+    port: typeof raw.port === "number" ? raw.port : 0,
+    bindHost: typeof raw.bindHost === "string" ? raw.bindHost : void 0,
+    projectDir: typeof raw.projectDir === "string" ? raw.projectDir : void 0,
+    dataRoot: typeof raw.dataRoot === "string" ? raw.dataRoot : void 0,
+    configPath: typeof raw.configPath === "string" ? raw.configPath : void 0,
+    logFile: typeof raw.logFile === "string" ? raw.logFile : void 0
+  };
+}
+function pidAlive(pid) {
+  try {
+    process8.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function probePanel(url, timeoutMs = 2e3) {
+  const target = `${url.replace(/\/+$/, "")}/healthz`;
+  return await new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      resolve(value);
+    };
+    let parsed;
+    try {
+      parsed = new URL(target);
+    } catch {
+      done(false);
+      return;
+    }
+    const transport = parsed.protocol === "https:" ? https : http;
+    const request = transport.get(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: `${parsed.pathname}${parsed.search}`,
+        timeout: timeoutMs,
+        rejectUnauthorized: false
+      },
+      (response) => {
+        response.resume();
+        done(typeof response.statusCode === "number");
+      }
+    );
+    request.on("timeout", () => {
+      request.destroy();
+      done(false);
+    });
+    request.on("error", () => done(false));
+  });
+}
+
+// src/home-hosted/instances.ts
+var SIBLING_PATTERN = /^\.home-hosted(?:[._-].*)?$/;
+function canonicalPath(value) {
+  const resolved = path11.resolve(expandHome(value));
+  try {
+    return fs13.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function defaultListDir(dir) {
+  try {
+    return fs13.readdirSync(dir);
+  } catch {
+    return null;
+  }
+}
+function isStateRoot(home) {
+  try {
+    if (!fs13.statSync(home).isDirectory())
+      return false;
+  } catch {
+    return false;
+  }
+  for (const file of [configFile(home), runtimeFile(home)]) {
+    try {
+      if (fs13.statSync(file).isFile())
+        return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function viewOf(candidate, managed, envHome, hosting, alive) {
+  const runtime = readRuntime(candidate.home);
+  const read = readConfig(candidate.home);
+  return {
+    home: candidate.home,
+    managed: candidate.home === managed,
+    hosting: hosting && candidate.home === envHome,
+    url: runtime?.url ?? null,
+    port: runtime?.port ?? null,
+    pid: runtime?.pid ?? null,
+    version: runtime?.version ?? null,
+    // A `run.json` names the process that wrote it; a recycled pid is not worth
+    // chasing here, because a stale one only mislabels a panel nobody acts on.
+    running: runtime !== null && alive(runtime.pid),
+    projectDir: runtime?.projectDir ?? null,
+    servers: read.error === null ? (read.raw?.servers ?? []).length : null,
+    source: candidate.source
+  };
+}
+function discoverInstances(options) {
+  const managed = canonicalPath(options.managedHome);
+  const listDir = options.listDir ?? defaultListDir;
+  const alive = options.alive ?? pidAlive;
+  const envRaw = options.envHome?.trim();
+  const envHome = envRaw !== void 0 && envRaw.length > 0 ? canonicalPath(envRaw) : null;
+  const hostingEntryId = options.hostingEntryId?.trim() ?? "";
+  const candidates = [{ home: managed, source: "managed" }];
+  if (envHome !== null)
+    candidates.push({ home: envHome, source: "env" });
+  for (const root of options.extraRoots ?? []) {
+    if (root.trim().length > 0)
+      candidates.push({ home: canonicalPath(root), source: "configured" });
+  }
+  const homeDir = options.homeDir ?? os4.homedir();
+  for (const name2 of listDir(homeDir) ?? []) {
+    if (SIBLING_PATTERN.test(name2))
+      candidates.push({ home: canonicalPath(path11.join(homeDir, name2)), source: "sibling" });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const views = [];
+  for (const candidate of candidates) {
+    if (seen.has(candidate.home))
+      continue;
+    seen.add(candidate.home);
+    if (candidate.source !== "managed" && !isStateRoot(candidate.home))
+      continue;
+    views.push(viewOf(candidate, managed, envHome, hostingEntryId.length > 0, alive));
+  }
+  views.sort((left, right) => left.managed === right.managed ? left.home.localeCompare(right.home) : left.managed ? -1 : 1);
+  return views;
+}
+function describeInstance(instance) {
+  if (instance.url === null)
+    return `${instance.home} (no runtime)`;
+  return `${instance.home} (${instance.url}${instance.running ? "" : ", stopped"})`;
+}
+function instancesNoticeText(instances) {
+  const managed = instances.find((instance) => instance.managed);
+  const others = instances.filter((instance) => !instance.managed);
+  if (managed === void 0 || others.length === 0)
+    return null;
+  return [
+    `home-hosted: ${instances.length} panels were found on this machine, and this plugin manages only ${describeInstance(managed)}.`,
+    `Other panels: ${others.map(describeInstance).join("; ")}.`,
+    'Act on the managed panel unless the user names another; a home_hosted_* call takes "instance" to name one.',
+    "Naming another panel is allowed for methods that can reach it: the plugin asks the user how, then edits that panel's config file, runs the CLI against its state root, or \u2014 only if they choose it \u2014 mints a token for that panel and uses its API."
+  ].join(" ");
+}
+
 // src/home-hosted/entries.ts
 function defaultOnPortConflict(platform = process.platform) {
   return platform === "win32" ? "kill" : "follow";
@@ -2804,16 +3166,16 @@ function defaultIntent(id, platform = process.platform) {
     persistent: true
   };
 }
-function ownedPatch(intent, live, options = {}) {
+function ownedPatch(intent, live) {
   const stop = live?.stop ?? {};
   return {
     autostart: intent.autostart,
     onPortConflict: intent.onPortConflict,
-    ...options.persistent === false ? {} : { persistent: intent.persistent },
+    persistent: intent.persistent,
     stop: { ...stop, killPortHolders: intent.stopKillPortHolders }
   };
 }
-function ownedDrift(live, intent, options = {}) {
+function ownedDrift(live, intent) {
   if (live === null)
     return ["missing entry"];
   const drift = [];
@@ -2821,7 +3183,7 @@ function ownedDrift(live, intent, options = {}) {
     drift.push("autostart");
   if (live.onPortConflict !== intent.onPortConflict)
     drift.push("onPortConflict");
-  if (options.persistent !== false && (live.persistent ?? false) !== intent.persistent)
+  if ((live.persistent ?? false) !== intent.persistent)
     drift.push("persistent");
   const killPortHolders = live.stop?.killPortHolders;
   if (killPortHolders !== intent.stopKillPortHolders)
@@ -2854,9 +3216,9 @@ function restorePatch(live, snapshot) {
 
 // src/home-hosted/panel-control.ts
 import { spawn as spawn2 } from "node:child_process";
-import fs12 from "node:fs";
-import path11 from "node:path";
-import process8 from "node:process";
+import fs14 from "node:fs";
+import path12 from "node:path";
+import process9 from "node:process";
 function cliArgs(deps, command) {
   const args = [...deps.launch?.args ?? [], command, "--home", deps.home];
   if (deps.projectDir)
@@ -2864,10 +3226,13 @@ function cliArgs(deps, command) {
   return args;
 }
 async function runCli(deps, command) {
+  const args = cliArgs(deps, command);
+  if (deps.exec !== void 0)
+    return await deps.exec(args, deps.env);
   const launch = deps.launch;
   if (launch === null)
     return { code: null, stdout: "", stderr: "no home-hosted CLI is available" };
-  return await run(launch.program, cliArgs(deps, command), {
+  return await run(launch.program, args, {
     env: deps.env,
     timeoutMs: deps.timeoutMs ?? 9e4
   });
@@ -2881,14 +3246,22 @@ async function startPanel(deps) {
   const match = /https?:\/\/[^\s]+/.exec(result.stdout);
   return { ok: true, detail: "the panel is answering", url: match?.[0] ?? null };
 }
+async function stopPanel(deps) {
+  const result = await runCli(deps, "down");
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `the CLI exited ${String(result.code)}`;
+    return { ok: false, detail: `the panel did not stop: ${detail}` };
+  }
+  return { ok: true, detail: "the panel stopped; the servers it supervised stopped with it" };
+}
 function takeoverHelperPath(stateDir) {
-  return path11.join(launcherDir(stateDir), "panel-takeover.mjs");
+  return path12.join(launcherDir(stateDir), "panel-takeover.mjs");
 }
 function takeoverLogPath(stateDir) {
-  return path11.join(launcherDir(stateDir), "panel-takeover.log");
+  return path12.join(launcherDir(stateDir), "panel-takeover.log");
 }
 function buildTakeoverSource(deps, oldPid, marker = "managed by dsh-home-hosted") {
-  const program = deps.launch?.program ?? process8.execPath;
+  const program = deps.launch?.program ?? process9.execPath;
   const args = deps.launch === null ? [] : [...deps.launch.args, "up", "--home", deps.home, ...deps.projectDir ? ["--project", deps.projectDir] : []];
   const downArgs = [...deps.launch?.args ?? [], "down", "--home", deps.home];
   return `#!/usr/bin/env node
@@ -2943,7 +3316,7 @@ log('started with exit ' + String(result.status))
 function writeTakeoverHelper(deps, oldPid) {
   const file = takeoverHelperPath(deps.stateDir);
   writeFileAtomic(file, buildTakeoverSource(deps, oldPid), 493);
-  fs12.chmodSync(file, 493);
+  fs14.chmodSync(file, 493);
   return file;
 }
 function spawnDetached(program, args) {
@@ -2953,7 +3326,7 @@ function spawnTakeover(deps, oldPid, spawnChild = spawnDetached) {
   const helper = writeTakeoverHelper(deps, oldPid);
   let child;
   try {
-    child = spawnChild(process8.execPath, [helper]);
+    child = spawnChild(process9.execPath, [helper]);
   } catch (error) {
     return { ok: false, detail: `could not start the panel-replacement helper: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -2995,10 +3368,10 @@ var PanelClient = class {
     this.token = options.token;
     this.timeoutMs = options.timeoutMs ?? 1e4;
   }
-  async request(method, path15, body) {
+  async request(method, path16, body) {
     let response;
     try {
-      response = await fetch(`${this.baseUrl}${path15}`, {
+      response = await fetch(`${this.baseUrl}${path16}`, {
         method,
         headers: {
           authorization: `Bearer ${this.token}`,
@@ -3075,91 +3448,21 @@ async function verifyToken(baseUrl, token, timeoutMs = 5e3) {
   return await probeToken(baseUrl, token, timeoutMs) === "ok";
 }
 
-// src/home-hosted/runtime.ts
-import http from "node:http";
-import https from "node:https";
-import process9 from "node:process";
-function readRuntime(home) {
-  const raw = readJson(runtimeFile(home));
-  if (raw === null)
-    return null;
-  const url = typeof raw.url === "string" ? raw.url : null;
-  const pid = typeof raw.pid === "number" ? raw.pid : null;
-  if (url === null || pid === null)
-    return null;
-  return {
-    version: typeof raw.version === "string" ? raw.version : "unknown",
-    pid,
-    url: url.replace(/\/+$/, ""),
-    probeUrl: typeof raw.probeUrl === "string" ? raw.probeUrl : void 0,
-    protocol: typeof raw.protocol === "string" ? raw.protocol : void 0,
-    port: typeof raw.port === "number" ? raw.port : 0,
-    bindHost: typeof raw.bindHost === "string" ? raw.bindHost : void 0,
-    projectDir: typeof raw.projectDir === "string" ? raw.projectDir : void 0,
-    dataRoot: typeof raw.dataRoot === "string" ? raw.dataRoot : void 0,
-    configPath: typeof raw.configPath === "string" ? raw.configPath : void 0,
-    logFile: typeof raw.logFile === "string" ? raw.logFile : void 0
-  };
-}
-function pidAlive(pid) {
-  try {
-    process9.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function probePanel(url, timeoutMs = 2e3) {
-  const target = `${url.replace(/\/+$/, "")}/healthz`;
-  return await new Promise((resolve) => {
-    let settled = false;
-    const done = (value) => {
-      if (settled)
-        return;
-      settled = true;
-      resolve(value);
-    };
-    let parsed;
-    try {
-      parsed = new URL(target);
-    } catch {
-      done(false);
-      return;
-    }
-    const transport = parsed.protocol === "https:" ? https : http;
-    const request = transport.get(
-      {
-        hostname: parsed.hostname,
-        port: parsed.port,
-        path: `${parsed.pathname}${parsed.search}`,
-        timeout: timeoutMs,
-        rejectUnauthorized: false
-      },
-      (response) => {
-        response.resume();
-        done(typeof response.statusCode === "number");
-      }
-    );
-    request.on("timeout", () => {
-      request.destroy();
-      done(false);
-    });
-    request.on("error", () => done(false));
-  });
-}
-
 // src/home-hosted/token.ts
-import { randomBytes } from "node:crypto";
-import path12 from "node:path";
-function storedTokenPath(stateDir) {
-  return path12.join(stateDir, "panel-token");
+import { createHash, randomBytes } from "node:crypto";
+import path13 from "node:path";
+function tokenSlot(home) {
+  return createHash("sha256").update(path13.resolve(home)).digest("hex").slice(0, 16);
 }
-function readStoredToken(stateDir) {
-  const text = readText(storedTokenPath(stateDir))?.trim();
+function storedTokenPath(stateDir, slot) {
+  return slot === void 0 ? path13.join(stateDir, "panel-token") : path13.join(stateDir, "panel-tokens", `${slot}.token`);
+}
+function readStoredToken(stateDir, slot) {
+  const text = readText(storedTokenPath(stateDir, slot))?.trim();
   return text !== void 0 && text.length > 0 ? text : null;
 }
-function storeToken(stateDir, token) {
-  writeFileAtomic(storedTokenPath(stateDir), `${token}
+function storeToken(stateDir, token, slot) {
+  writeFileAtomic(storedTokenPath(stateDir, slot), `${token}
 `, 384);
 }
 function generateToken() {
@@ -3170,8 +3473,8 @@ function apiTokenEnrolled(home) {
   return secrets !== null && secrets.apiToken !== null && secrets.apiToken !== void 0;
 }
 var queue = /* @__PURE__ */ new Map();
-function serialised(stateDir, work) {
-  const key = path12.resolve(stateDir);
+function serialised(stateDir, slot, work) {
+  const key = `${path13.resolve(stateDir)}\0${slot ?? ""}`;
   const previous = queue.get(key) ?? Promise.resolve();
   const next = previous.then(work, work);
   const settled = next.then(() => void 0, () => void 0);
@@ -3182,10 +3485,10 @@ function serialised(stateDir, work) {
   return next;
 }
 async function ensureToken(options) {
-  return await serialised(options.stateDir, async () => await enrollToken(options));
+  return await serialised(options.stateDir, options.slot, async () => await enrollToken(options));
 }
 async function reclaimToken(options) {
-  return await serialised(options.stateDir, async () => await enrollFreshToken(options));
+  return await serialised(options.stateDir, options.slot, async () => await enrollFreshToken(options));
 }
 async function runCli2(exec, args, env) {
   try {
@@ -3201,7 +3504,7 @@ async function runCli2(exec, args, env) {
   }
 }
 async function enrollToken(options) {
-  const stored = readStoredToken(options.stateDir);
+  const stored = readStoredToken(options.stateDir, options.slot);
   if (stored !== null)
     return { token: stored, enrolled: false, detail: "using the stored panel token" };
   if (apiTokenEnrolled(options.home)) {
@@ -3220,7 +3523,7 @@ async function enrollToken(options) {
       detail: `could not enrol an API token: ${enrolled.failure ?? "the CLI did not answer"}`
     };
   }
-  storeToken(options.stateDir, token);
+  storeToken(options.stateDir, token, options.slot);
   return { token, enrolled: true, detail: "enrolled a new panel API token" };
 }
 async function enrollFreshToken(options) {
@@ -3232,7 +3535,7 @@ async function enrollFreshToken(options) {
       detail: `could not enrol a fresh API token: ${enrolled.failure ?? "the CLI did not answer"}; the previously stored token was kept`
     };
   }
-  storeToken(options.stateDir, token);
+  storeToken(options.stateDir, token, options.slot);
   return { token, detail: "enrolled a fresh panel API token" };
 }
 
@@ -3240,9 +3543,10 @@ async function enrollFreshToken(options) {
 var ENTRY_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
 var TOKEN_PROBE_TIMEOUT_MS = 3e3;
 var ENTRY_RECOVERY_INTERVAL_MS = 3e4;
+var INSTANCES_CACHE_MS = 1e4;
 function pluginRoot() {
   try {
-    return path13.dirname(path13.dirname(fileURLToPath(import.meta.url)));
+    return path14.dirname(path14.dirname(fileURLToPath(import.meta.url)));
   } catch {
     return null;
   }
@@ -3254,11 +3558,14 @@ var HomeHostedError = class extends Error {
     this.name = "HomeHostedError";
   }
 };
+function foreignView(entry) {
+  return { id: entry.id, status: "unknown", pid: null, url: null, config: entry };
+}
 var HomeHostedService = class extends Service {
   constructor(ctx, options) {
     super(ctx, "homeHosted");
     this.options = options;
-    this.snapshotsFile = path13.join(options.stateDir, "snapshots.json");
+    this.snapshotsFile = path14.join(options.stateDir, "snapshots.json");
   }
   clientCache = null;
   /** The last token this service proved against a panel, so a poll does not re-probe it. */
@@ -3266,6 +3573,8 @@ var HomeHostedService = class extends Service {
   tokenDetail = "";
   /** When a missing managed entry was last put back, so a poll cannot become a write loop. */
   entryRecoveryAt = 0;
+  /** The last panel inventory, so a model-step assembly never reads the disk. */
+  instanceCache = null;
   snapshotsFile;
   async resolveDsh(dshHome2) {
     return await (this.options.resolveDsh ?? ((options) => resolveDshLaunch(options)))({
@@ -3274,6 +3583,185 @@ var HomeHostedService = class extends Service {
     });
   }
   // -------------------------------------------------------------------------
+  // Panels on this machine
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async instances(refresh = false) {
+    if (refresh || this.instanceCache === null || Date.now() - this.instanceCache.at >= INSTANCES_CACHE_MS)
+      return this.measureInstances();
+    return this.instanceCache.list;
+  }
+  /**
+   * 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() {
+    if (this.instanceCache !== null && Date.now() - this.instanceCache.at < INSTANCES_CACHE_MS)
+      return this.instanceCache.list;
+    return this.measureInstances();
+  }
+  measureInstances() {
+    const now = Date.now();
+    try {
+      this.instanceCache = {
+        at: now,
+        list: discoverInstances({
+          managedHome: this.options.home,
+          extraRoots: this.options.instanceRoots,
+          envHome: this.options.envHome === void 0 ? process10.env.HHOSTED_HOME ?? null : this.options.envHome,
+          homeDir: this.options.homeDir,
+          hostingEntryId: this.selfEntryId()
+        })
+      };
+    } catch {
+      this.instanceCache = { at: now, list: [] };
+    }
+    return this.instanceCache.list;
+  }
+  /** The inventory as last measured, without touching the disk. */
+  instancesSnapshot() {
+    return this.instanceCache?.list ?? [];
+  }
+  // -------------------------------------------------------------------------
+  // Acting on another panel
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async targetHome(requested) {
+    if (requested === void 0 || requested === null || requested === "")
+      return { home: this.options.home, foreign: false };
+    if (typeof requested !== "string")
+      throw new HomeHostedError("a panel target must be a state root path", "INSTANCE_INVALID");
+    if (requested.trim().length === 0)
+      return { home: this.options.home, foreign: false };
+    const home = canonicalPath(requested);
+    if (home === canonicalPath(this.options.home))
+      return { home: this.options.home, foreign: false };
+    const instances = await this.instances();
+    if (!instances.some((instance) => instance.home === home && !instance.managed))
+      throw new HomeHostedError(`"${requested}" is not a home-hosted panel this machine reports`, "INSTANCE_UNKNOWN");
+    return { home, foreign: true };
+  }
+  /**
+   * 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.
+   */
+  mechanismFor(endpoint, requested) {
+    const allowed = FOREIGN_MECHANISMS[endpoint];
+    if (allowed === void 0)
+      throw new HomeHostedError(`"${endpoint}" cannot be aimed at another panel`, "INSTANCE_UNSUPPORTED");
+    if (requested === void 0 || requested === null)
+      return allowed[0];
+    if (typeof requested === "string" && allowed.includes(requested))
+      return requested;
+    throw new HomeHostedError(
+      `"${String(requested)}" is not a way to reach another panel for ${endpoint}; use one of ${allowed.join(", ")}`,
+      "MECHANISM_UNSUPPORTED"
+    );
+  }
+  /** Whether a token this plugin already holds for a panel still works. */
+  async foreignTokenWorks(home) {
+    const runtime = readRuntime(home);
+    if (runtime === null || runtime.url.length === 0)
+      return false;
+    const stored = readStoredToken(this.options.stateDir, tokenSlot(home));
+    return stored !== null && await verifyToken(runtime.url, stored);
+  }
+  /**
+   * 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.
+   */
+  async foreignClient(home) {
+    const runtime = readRuntime(home);
+    if (runtime === null || runtime.url.length === 0)
+      throw new HomeHostedError(`no panel is running at ${home}, so its API cannot be used`, "PANEL_UNAVAILABLE");
+    const slot = tokenSlot(home);
+    const exec = async (args, env) => await this.cliExec(args, env);
+    const stored = readStoredToken(this.options.stateDir, slot);
+    if (stored !== null && await verifyToken(runtime.url, stored))
+      return new PanelClient({ baseUrl: runtime.url, token: stored });
+    const enrolled = stored !== null || apiTokenEnrolled(home) ? await reclaimToken({ home, stateDir: this.options.stateDir, exec, slot }) : await ensureToken({ home, stateDir: this.options.stateDir, exec, slot });
+    if (enrolled.token === null)
+      throw new HomeHostedError(enrolled.detail, "TOKEN_UNAVAILABLE");
+    return new PanelClient({ baseUrl: runtime.url, token: enrolled.token });
+  }
+  /** Another panel's own config, refusing anything that is not a readable one. */
+  readForeignConfig(home) {
+    const read = readConfig(home);
+    if (read.error !== null || read.raw === null)
+      throw new HomeHostedError(read.error ?? `no servers config in ${home}`, "CONFIG_UNREADABLE");
+    return read.raw;
+  }
+  /** Another panel's entries as its config holds them: live status needs its API token. */
+  listForeign(home) {
+    return (this.readForeignConfig(home).servers ?? []).map((entry) => foreignView(entry));
+  }
+  createForeign(home, entry) {
+    const raw = this.readForeignConfig(home);
+    if (findEntry(raw, entry.id) !== null)
+      throw new HomeHostedError(`"${entry.id}" already exists in ${home}/servers.config.json`, "DUPLICATE_SERVER");
+    writeConfig(home, upsertEntry(raw, { ...entry, autostart: false }), this.writtenBy(home));
+    const added = this.readForeignConfig(home);
+    writeConfig(home, patchEntry(added, entry.id, { autostart: entry.autostart === true }), this.writtenBy(home));
+    return this.writtenForeignEntry(home, entry.id);
+  }
+  updateForeign(home, id, patch) {
+    const raw = this.readForeignConfig(home);
+    if (findEntry(raw, id) === null)
+      throw new HomeHostedError(`no server "${id}" exists in ${home}/servers.config.json`, "UNKNOWN_SERVER");
+    const next = patchEntry(raw, id, { ...patch, id });
+    writeConfig(home, next, this.writtenBy(home));
+    return this.writtenForeignEntry(home, id);
+  }
+  /** What a write actually left on disk, never what it was asked to write. */
+  writtenForeignEntry(home, id) {
+    const entry = findEntry(this.readForeignConfig(home), id);
+    if (entry === null)
+      throw new HomeHostedError(`the write to ${home}/servers.config.json did not take`, "FOREIGN_WRITE_LOST");
+    return foreignView(entry);
+  }
+  deleteForeign(home, id) {
+    const raw = this.readForeignConfig(home);
+    if (findEntry(raw, id) === null)
+      throw new HomeHostedError(`no server "${id}" exists in ${home}/servers.config.json`, "UNKNOWN_SERVER");
+    writeConfig(home, removeEntry(raw, id), this.writtenBy(home));
+    return { id, home, via: "file" };
+  }
+  /**
+   * 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.
+   */
+  async lifecycleForeign(home, action, id) {
+    const once = async (command) => {
+      const result = await this.cliExec([command, id, "--home", home], { ...process10.env, HHOSTED_HOME: home });
+      if (result.code !== 0) {
+        const output = [result.stderr, result.stdout, result.error].filter((part) => typeof part === "string" && part.trim().length > 0).join("\n").trim();
+        throw new HomeHostedError(output.length > 0 ? output : `home-hosted ${command} ${id} exited ${String(result.code)}`, "CLI_FAILED");
+      }
+    };
+    if (action === "restart") {
+      await once("stop");
+      await once("start");
+    } else {
+      await once(action);
+    }
+    return { home, id, action, via: "cli" };
+  }
+  // -------------------------------------------------------------------------
   // Facts
   // -------------------------------------------------------------------------
   runtime() {
@@ -3285,14 +3773,13 @@ var HomeHostedService = class extends Service {
     return id !== void 0 && id.length > 0 ? id : null;
   }
   /** What the config's `meta.writtenBy` names: the panel release when we can read it. */
-  writtenBy() {
-    return this.runtime()?.version ?? "dsh-home-hosted";
+  writtenBy(home = this.options.home) {
+    return readRuntime(home)?.version ?? "dsh-home-hosted";
   }
   webServer() {
     const service = this.ctx.get("webServer");
     const port = typeof service?.port === "number" ? service.port : null;
-    const host = typeof service?.host === "string" ? service.host : "127.0.0.1";
-    return { port, host };
+    return { port };
   }
   cliCache = null;
   /**
@@ -3329,7 +3816,8 @@ var HomeHostedService = class extends Service {
       home: this.options.home,
       projectDir,
       stateDir: this.options.stateDir,
-      env: launch === null ? {} : homeHostedEnv({ home: this.options.home, projectDir }, launch)
+      env: launch === null ? {} : homeHostedEnv({ home: this.options.home, projectDir }, launch),
+      exec: this.options.execCli
     };
   }
   async cliExec(args, env) {
@@ -3520,11 +4008,10 @@ var HomeHostedService = class extends Service {
       return null;
     const harnessHome = process10.env.DSH_HOME ?? dshHome();
     const dsh = await this.resolveDsh(harnessHome);
-    const { port, host } = this.webServer();
+    const { port } = this.webServer();
     const generated = buildDshEntry({
       id: intent.id,
       port,
-      host,
       profile: detectProfile(process10.argv, process10.env),
       dshHome: harnessHome,
       launch: dsh,
@@ -3552,7 +4039,7 @@ var HomeHostedService = class extends Service {
       snapshots[intent.id] = live === null ? { id: intent.id } : snapshotOwned(live.config);
       this.saveSnapshots(snapshots);
     }
-    const patch = ownedPatch(intent, live?.config ?? null, { persistent: await this.supportsPersistent() });
+    const patch = ownedPatch(intent, live?.config ?? null);
     const repair = intent.id === this.options.defaultEntryId ? await this.dshCommandRepair(live?.config ?? null) : null;
     const client = await this.tryClient();
     if (client !== null) {
@@ -3593,35 +4080,6 @@ var HomeHostedService = class extends Service {
     const runtime = this.runtime();
     return runtime !== null && (pidAlive(runtime.pid) || await probePanel(runtime.url));
   }
-  /**
-   * 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.
-   */
-  async configVersion() {
-    const runtime = this.runtime();
-    if (runtime !== null && runtime.version !== null && (pidAlive(runtime.pid) || await probePanel(runtime.url)))
-      return runtime.version;
-    const { resolution } = await this.cli();
-    return resolution.status.version;
-  }
-  /** Whether the panel whose schema parses our write knows `persistent`. */
-  async supportsPersistent() {
-    const version = await this.configVersion();
-    return version !== null && compareVersions(version, MIN_PERSISTENT_VERSION) >= 0;
-  }
-  async assertPolicySupported(intent) {
-    if (intent.onPortConflict !== "kill")
-      return;
-    const version = await this.configVersion();
-    if (version === null || compareVersions(version, MIN_KILL_VERSION) >= 0)
-      return;
-    const { resolution } = await this.cli();
-    throw new HomeHostedError(
-      `the home-hosted that would parse this config is ${version}, which has no "kill" policy (added in ${MIN_KILL_VERSION}); replace it with ${resolution.status.version ?? "the pinned copy"} from this page, or set the entry's on-port-conflict policy to block`,
-      "KILL_UNSUPPORTED"
-    );
-  }
   async applyIntents(intents) {
     for (const raw of intents) {
       if (!ENTRY_ID_PATTERN.test(raw.id))
@@ -3640,7 +4098,6 @@ var HomeHostedService = class extends Service {
         stopKillPortHolders: raw.stopKillPortHolders ?? fallback.stopKillPortHolders,
         persistent: raw.persistent ?? fallback.persistent
       };
-      await this.assertPolicySupported(intent);
       await this.writeOwned(intent);
       const current = this.options.settings.get();
       const entries = current.entries.filter((entry) => entry.id !== intent.id);
@@ -3705,21 +4162,22 @@ var HomeHostedService = class extends Service {
     return await this.entriesStatus();
   }
   /** Drive the panel's own UI through its CLI, and report what is installed. */
-  async uiManage(action, file) {
+  async uiManage(action, file, target) {
+    const home = target ?? this.options.home;
     const cli = action === "status" ? null : await this.cli();
     const runUi = async (args) => {
       const launch = cli?.resolution.launch ?? null;
       if (launch === null)
         throw new HomeHostedError(cli?.resolution.status.detail ?? "no home-hosted CLI could be resolved", "CLI_NOT_FOUND");
-      const result = await run(launch.program, [...launch.args, ...args, "--home", this.options.home], {
-        env: { ...process10.env, HHOSTED_HOME: this.options.home },
+      const result = await run(launch.program, [...launch.args, ...args, "--home", home], {
+        env: { ...process10.env, HHOSTED_HOME: home },
         timeoutMs: 3e5
       });
       const output = [result.error, result.stdout, result.stderr].filter((part) => typeof part === "string" && part.trim().length > 0).join("\n").trim();
       return { code: result.code, output };
     };
     const active = () => {
-      const meta = readJson(path13.join(this.options.home, ".ui", "ui.json"));
+      const meta = readJson(path14.join(home, ".ui", "ui.json"));
       return meta === null ? null : { name: meta.name ?? null, version: meta.version ?? null, repo: meta.repo ?? null, tag: meta.tag ?? null };
     };
     switch (action) {
@@ -3738,7 +4196,7 @@ var HomeHostedService = class extends Service {
       case "switch": {
         if (file === void 0 || file.trim().length === 0)
           throw new HomeHostedError("switching the UI needs the zip to install", "UI_FILE_REQUIRED");
-        if (!fs13.existsSync(file))
+        if (!fs15.existsSync(file))
           throw new HomeHostedError(`no file at ${file}`, "UI_FILE_MISSING");
         const result = await runUi(["ui-switch", "--file", file, "--yes"]);
         return { ok: result.code === 0, detail: result.code === 0 ? "the UI was replaced" : "the switch did not run", ui: active(), output: result.output };
@@ -3777,7 +4235,6 @@ var HomeHostedService = class extends Service {
     const settings = this.options.settings.get();
     const live = await this.liveEntries();
     const snapshots = this.snapshots();
-    const persistent = await this.supportsPersistent();
     const ids = /* @__PURE__ */ new Set([this.options.defaultEntryId, ...settings.entries.map((entry) => entry.id)]);
     return [...ids].map((id) => {
       const intent = this.options.settings.intentFor(id);
@@ -3786,7 +4243,7 @@ var HomeHostedService = class extends Service {
         intent,
         exists: entry !== null,
         managed: snapshots[id] !== void 0,
-        drift: entry === null ? ["missing entry"] : ownedDrift(entry.config, intent, { persistent }),
+        drift: entry === null ? ["missing entry"] : ownedDrift(entry.config, intent),
         live: entry?.view ?? null,
         snapshot: snapshots[id] ?? null
       };
@@ -3912,6 +4369,28 @@ var HomeHostedService = class extends Service {
     this.clientCache = null;
     return result;
   }
+  /**
+   * 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.
+   */
+  async stopPanelNow() {
+    const { resolution } = await this.cli();
+    const runtime = this.runtime();
+    if (runtime === null || !await probePanel(runtime.url)) {
+      return { ok: true, detail: "no panel is answering, so there was nothing to stop" };
+    }
+    const deps = await this.panelControlDeps();
+    if (deps.launch === null)
+      throw new HomeHostedError(resolution.status.detail, "CLI_NOT_FOUND");
+    const result = await stopPanel(deps);
+    this.clientCache = null;
+    this.tokenProof = null;
+    return result;
+  }
   /**
    * Replace an answering panel with the preferred copy.
    *
@@ -3992,7 +4471,7 @@ var HomeHostedService = class extends Service {
     if (status.state !== "enabled-failing" && status.state !== "installed-disabled")
       return;
     const fileBacked = status.mechanism === "systemd-user" || status.mechanism === "systemd-system" || status.mechanism === "xdg-autostart" || status.mechanism === "launchd-agent" || status.mechanism === "launchd-daemon";
-    if (fileBacked && (status.unitPath === null || !fs13.existsSync(status.unitPath)))
+    if (fileBacked && (status.unitPath === null || !fs15.existsSync(status.unitPath)))
       return;
     try {
       await this.installBoot();
@@ -4002,7 +4481,7 @@ var HomeHostedService = class extends Service {
   // -------------------------------------------------------------------------
   // Status
   // -------------------------------------------------------------------------
-  async status() {
+  async status(refresh = false) {
     const client = await this.tryClient();
     const panel = await this.panelStatus();
     const { resolution, launcher, launcherVersion } = await this.cli();
@@ -4030,6 +4509,10 @@ var HomeHostedService = class extends Service {
     return {
       defaultEntryId: this.options.defaultEntryId,
       panel,
+      panelRoot: this.options.home,
+      panelRootSource: this.options.panelHomeSource ?? "instance",
+      bootUnitName: bootUnitName(this.options.stateDir),
+      instances: await this.instances(refresh),
       boot: await this.bootStatus(),
       // A deleted managed entry is put back here as well as at startup: whoever
       // deleted it is looking at the page that reports it missing.
@@ -4045,28 +4528,54 @@ var HomeHostedService = class extends Service {
   // -------------------------------------------------------------------------
   async call(endpoint, payload) {
     const input = payload ?? {};
+    if (typeof input.home === "string" && input.home.trim().length > 0 && FOREIGN_MECHANISMS[endpoint] === void 0) {
+      throw new HomeHostedError(
+        `"${endpoint}" is about the panel this plugin manages and cannot be aimed at another one`,
+        "INSTANCE_UNSUPPORTED"
+      );
+    }
     switch (endpoint) {
       case "status":
-        return await this.status();
+        return await this.status(input.refresh === true);
       case "settings.update": {
         const patch = input.patch ?? {};
         this.options.settings.update(patch);
         return await this.status();
       }
-      case "servers.list":
-        return await (await this.requireClient()).listServers();
+      case "servers.list": {
+        const target = await this.targetHome(input.home);
+        if (!target.foreign)
+          return await (await this.requireClient()).listServers();
+        const via = this.mechanismFor("servers.list", input.via);
+        if (via === "api" || input.via === void 0 && await this.foreignTokenWorks(target.home))
+          return await (await this.foreignClient(target.home)).listServers();
+        return this.listForeign(target.home);
+      }
       case "servers.get":
         return await (await this.requireClient()).getServer(String(input.id));
       case "servers.create": {
         const entry = input.entry;
         if (typeof entry?.id !== "string" || !ENTRY_ID_PATTERN.test(entry.id))
           throw new HomeHostedError("a server entry needs an id matching ^[a-z0-9][a-z0-9_-]*$", "INVALID_ID");
-        return await (await this.requireClient()).createServer(entry);
+        const target = await this.targetHome(input.home);
+        if (!target.foreign)
+          return await (await this.requireClient()).createServer(entry);
+        return this.mechanismFor("servers.create", input.via) === "api" ? await (await this.foreignClient(target.home)).createServer(entry) : this.createForeign(target.home, entry);
+      }
+      case "servers.update": {
+        const target = await this.targetHome(input.home);
+        const id = String(input.id);
+        const patch = input.patch ?? {};
+        if (!target.foreign)
+          return await (await this.requireClient()).updateServer(id, patch);
+        return this.mechanismFor("servers.update", input.via) === "api" ? await (await this.foreignClient(target.home)).updateServer(id, patch) : this.updateForeign(target.home, id, patch);
       }
-      case "servers.update":
-        return await (await this.requireClient()).updateServer(String(input.id), input.patch ?? {});
       case "servers.delete": {
         const id = String(input.id);
+        const target = await this.targetHome(input.home);
+        if (target.foreign) {
+          return this.mechanismFor("servers.delete", input.via) === "api" ? await (await this.foreignClient(target.home)).deleteServer(id).then(() => ({ id, home: target.home, via: "api" })) : this.deleteForeign(target.home, id);
+        }
         if (id === this.selfEntryId()) {
           throw new HomeHostedError(
             `"${id}" is the entry this very process runs as, and deleting it stops this session; pause it (autostart off) or restore it instead`,
@@ -4076,15 +4585,45 @@ var HomeHostedService = class extends Service {
         await (await this.requireClient()).deleteServer(id);
         return { id };
       }
-      case "servers.start":
-        await (await this.requireClient()).startServer(String(input.id));
+      case "servers.start": {
+        const target = await this.targetHome(input.home);
+        const id = String(input.id);
+        if (target.foreign) {
+          if (this.mechanismFor("servers.start", input.via) === "api") {
+            await (await this.foreignClient(target.home)).startServer(id);
+            return { home: target.home, id, action: "start", via: "api" };
+          }
+          return await this.lifecycleForeign(target.home, "start", id);
+        }
+        await (await this.requireClient()).startServer(id);
         return await this.entriesStatus();
-      case "servers.stop":
-        await (await this.requireClient()).stopServer(String(input.id));
+      }
+      case "servers.stop": {
+        const target = await this.targetHome(input.home);
+        const id = String(input.id);
+        if (target.foreign) {
+          if (this.mechanismFor("servers.stop", input.via) === "api") {
+            await (await this.foreignClient(target.home)).stopServer(id);
+            return { home: target.home, id, action: "stop", via: "api" };
+          }
+          return await this.lifecycleForeign(target.home, "stop", id);
+        }
+        await (await this.requireClient()).stopServer(id);
         return await this.entriesStatus();
-      case "servers.restart":
-        await (await this.requireClient()).restartServer(String(input.id));
+      }
+      case "servers.restart": {
+        const target = await this.targetHome(input.home);
+        const id = String(input.id);
+        if (target.foreign) {
+          if (this.mechanismFor("servers.restart", input.via) === "api") {
+            await (await this.foreignClient(target.home)).restartServer(id);
+            return { home: target.home, id, action: "restart", via: "api" };
+          }
+          return await this.lifecycleForeign(target.home, "restart", id);
+        }
+        await (await this.requireClient()).restartServer(id);
         return await this.entriesStatus();
+      }
       case "servers.freePort":
         return await (await this.requireClient()).freePort(String(input.id));
       case "entries.apply": {
@@ -4095,8 +4634,16 @@ var HomeHostedService = class extends Service {
         return await this.removeManagedEntry(String(input.id));
       case "entries.restore":
         return await this.restoreEntry(String(input.id));
-      case "ui.manage":
-        return await this.uiManage(input.action, typeof input.file === "string" ? input.file : void 0);
+      case "ui.manage": {
+        const target = await this.targetHome(input.home);
+        if (target.foreign)
+          this.mechanismFor("ui.manage", input.via);
+        return await this.uiManage(
+          input.action,
+          typeof input.file === "string" ? input.file : void 0,
+          target.foreign ? target.home : void 0
+        );
+      }
       case "boot.install":
         return await this.installBoot(input.mechanism);
       case "boot.uninstall":
@@ -4105,6 +4652,8 @@ var HomeHostedService = class extends Service {
         return await this.bootStatus();
       case "panel.start":
         return await this.startPanelNow();
+      case "panel.stop":
+        return await this.stopPanelNow();
       case "panel.takeover":
         return await this.takeoverPanel(input.force === true);
       case "panel.reclaimToken":
@@ -4174,6 +4723,24 @@ function registerRpc(ctx, service) {
   });
 }
 
+// src/home-hosted/instances-notice.ts
+var INSTANCES_CONTEXT_ORDER = 130;
+function instancesContextText(instances, enabled) {
+  return enabled ? instancesNoticeText(instances) ?? "" : "";
+}
+function registerInstancesNotice(ctx, deps) {
+  ctx.inject(["systemPrompt"], (scoped) => {
+    const prompt = scoped.systemPrompt;
+    if (typeof prompt?.context !== "function")
+      return;
+    scoped.effect(() => prompt.context({
+      name: "dsh-home-hosted:instances",
+      order: INSTANCES_CONTEXT_ORDER,
+      text: () => instancesContextText(deps.instances(), deps.enabled())
+    }), "dsh-home-hosted: instance notice");
+  });
+}
+
 // src/home-hosted/web-notice.ts
 var STOCK_UNAUTHORIZED = "dsh web authentication required; reopen the URL printed by dsh web.";
 function authNoticeBody(logUrl) {
@@ -4273,6 +4840,7 @@ var LEGACY_TOOL_NAMES = {
 function isLegacyDefaultAllowlist(names) {
   return names.length === 2 && names.includes("status") && names.includes("servers_list");
 }
+var PRE_MERGE_SETTINGS_VERSION = 2;
 var BOOT_MECHANISMS = ["auto", "systemd-user", "systemd-system", "launchd-agent", "launchd-daemon", "xdg-autostart", "windows-run", "windows-task", "container", "unsupported"];
 function isBootMechanism(value) {
   return typeof value === "string" && BOOT_MECHANISMS.includes(value);
@@ -4280,7 +4848,7 @@ function isBootMechanism(value) {
 function normalize(raw, fallbackEntryId) {
   const entries = Array.isArray(raw?.entries) ? raw.entries.map((intent) => normalizeIntent(intent, fallbackEntryId)) : [];
   const declared = Array.isArray(raw?.agentTools?.allow) ? raw.agentTools.allow : null;
-  const legacyFile = (typeof raw?.version === "number" ? raw.version : 1) < SETTINGS_VERSION;
+  const legacyFile = (typeof raw?.version === "number" ? raw.version : 1) < PRE_MERGE_SETTINGS_VERSION;
   const migrated = declared === null ? null : [...new Set(declared.map((name2) => legacyFile ? LEGACY_TOOL_NAMES[name2] ?? name2 : name2).filter(knownTool))];
   const choseNothing = legacyFile && declared !== null && migrated !== null && isLegacyDefaultAllowlist(declared);
   const allow = migrated === null || choseNothing ? [...DEFAULT_SETTINGS.agentTools.allow] : migrated;
@@ -4304,6 +4872,8 @@ function normalize(raw, fallbackEntryId) {
     authNotice: raw?.authNotice === void 0 ? DEFAULT_SETTINGS.authNotice : raw.authNotice === true,
     // Absent means on: a stale token is a fault to repair, not a setting to opt into.
     reclaimToken: raw?.reclaimToken === void 0 ? DEFAULT_SETTINGS.reclaimToken : raw.reclaimToken === true,
+    // Absent means on: a plugin that owns one panel should say so by default.
+    instancesNotice: raw?.instancesNotice === void 0 ? DEFAULT_SETTINGS.instancesNotice : raw.instancesNotice === true,
     uiStyle: raw?.uiStyle === "compact" ? "compact" : "detailed",
     agentTools: {
       // Absent means the default (on), and so does the pair the previous
@@ -4342,6 +4912,7 @@ var SettingsStore = class {
       panel: { ...this.current.panel, ...patch.panel ?? {} },
       authNotice: patch.authNotice ?? this.current.authNotice,
       reclaimToken: patch.reclaimToken ?? this.current.reclaimToken,
+      instancesNotice: patch.instancesNotice ?? this.current.instancesNotice,
       uiStyle: patch.uiStyle ?? this.current.uiStyle,
       agentTools: { ...this.current.agentTools, ...patch.agentTools ?? {} },
       cli: { ...this.current.cli, ...patch.cli ?? {} }
@@ -4373,6 +4944,10 @@ function sandboxMode(ctx, exec) {
     return null;
   }
 }
+function withTarget(payload, home, via) {
+  const target = via === null ? { home } : { home, via };
+  return typeof payload === "object" && payload !== null ? { ...payload, ...target } : target;
+}
 function stringArg(input, key) {
   const value = input[key];
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
@@ -4381,20 +4956,62 @@ function jsonArg(input, key) {
   const value = input[key];
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
+function jsonArgError(input, key, purpose) {
+  const value = input[key];
+  const received = value === void 0 ? "missing" : Array.isArray(value) ? "array" : typeof value;
+  return new Error(`${key} must be a JSON object ${purpose} (received: ${received})`);
+}
+var INSTANCE_PARAM = {
+  type: "string",
+  description: "Home-hosted panel to act on: a state root (--home) or URL reported by home_hosted_status. Omit for the panel this plugin manages; naming another panel asks the user how to reach it before it changes anything."
+};
+var ENTRY_FIELDS = {
+  id: { type: "string", required: true, description: "Entry id, ^[a-z0-9][a-z0-9_-]*$" },
+  command: { type: "string", description: "Executable to run" },
+  args: { type: "array", items: { type: "string" }, description: "Arguments" },
+  cwd: { type: "string", description: "Working directory" },
+  label: { type: "string", description: "Human label" },
+  enabled: { type: "boolean", description: "Whether the entry may run" },
+  autostart: { type: "boolean", description: "Start it when the panel starts" },
+  // The panel's schema is `1..65535 | null`, and a patch that clears a port sends it.
+  port: { oneOf: [{ type: "number" }, { type: "null" }], description: "Port the panel tracks for this entry, or null" },
+  bind: { type: "string", description: "Bind host or local/lan" },
+  onPortConflict: { type: "string", enum: [...ON_PORT_CONFLICT_POLICIES], description: "Policy when the port is taken" },
+  stop: { type: "object", additionalProperties: true, description: "Stop policy, e.g. killPortHolders" },
+  health: { type: "object", additionalProperties: true, description: "Health check block" },
+  restart: { type: "object", additionalProperties: true, description: "Restart policy block" },
+  env: { type: "object", additionalProperties: true, description: "Environment variables" },
+  dataEnvs: { type: "object", additionalProperties: true, description: "Environment entries the panel fills in" }
+};
+var ENTRY_PARAM = {
+  type: "object",
+  additionalProperties: true,
+  description: "A home-hosted server entry: at least id and command",
+  properties: ENTRY_FIELDS
+};
+var PATCH_PARAM = {
+  type: "object",
+  additionalProperties: true,
+  description: "Fields to change on an existing entry; only the given keys are touched",
+  // The same fields, none required and without `id`: the entry patched is the one
+  // the `id` argument names, and the panel rejects a patch that carries an id.
+  properties: Object.fromEntries(Object.entries(ENTRY_FIELDS).filter(([key]) => key !== "id"))
+};
 var TOOL_SPECS = {
   status: {
-    description: "Report the home-hosted panel state, its boot-autostart entry, and the entries this plugin manages.",
-    parameters: {},
+    description: "Report the home-hosted panel state, every home-hosted panel found on this machine, its boot-autostart entry, and the entries this plugin manages. This describes the managed panel only; its payload lists the others.",
+    parameters: { instance: INSTANCE_PARAM },
     run: () => ({ endpoint: "status", payload: {} })
   },
   servers_list: {
-    description: "List every server home-hosted supervises, with status, pid and url.",
-    parameters: {},
+    description: "List every server home-hosted supervises, with status, pid and url. A named panel is read from its config file, or through its API when this plugin already holds a token for that panel; naming the API mechanism mints one.",
+    parameters: { instance: INSTANCE_PARAM },
     run: () => ({ endpoint: "servers.list", payload: {} })
   },
   servers_lifecycle: {
-    description: "Start, stop or restart a server supervised by home-hosted. Restarting the entry this session runs as ends the session.",
+    description: "Start, stop or restart a server supervised by home-hosted. Restarting the entry this session runs as ends the session. A named panel is driven through the home-hosted CLI aimed at its state root, or through its API, and a CLI restart is a stop then a start.",
     parameters: {
+      instance: INSTANCE_PARAM,
       action: { type: "string", required: true, description: "start, stop or restart" },
       id: { type: "string", required: true, description: "Server entry id" }
     },
@@ -4409,27 +5026,31 @@ var TOOL_SPECS = {
     }
   },
   servers_edit: {
-    description: "Create, update or delete a home-hosted server entry. Delete is refused for the entry this session runs as.",
+    description: "Create, update or delete a home-hosted server entry. Delete is refused for the entry this session runs as. A named panel is edited through its servers.config.json, or through its API with a token this plugin mints.",
     parameters: {
+      instance: INSTANCE_PARAM,
       action: { type: "string", required: true, description: "create, update or delete" },
       id: { type: "string", description: "Server entry id (update, delete)" },
-      entry: { type: "json", description: "A full home-hosted server entry, including its id and command (create)" },
-      patch: { type: "json", description: "Fields to change (update)" }
+      entry: ENTRY_PARAM,
+      patch: PATCH_PARAM
     },
     run: (input) => {
       const action = stringArg(input, "action");
       if (action === "create") {
         const entry = jsonArg(input, "entry");
         if (entry === null)
-          throw new Error("entry is required to create a server");
+          throw jsonArgError(input, "entry", "to create a server");
         return { endpoint: "servers.create", payload: { entry } };
       }
       if (action === "update") {
         const id = stringArg(input, "id");
         const patch = jsonArg(input, "patch");
-        if (id === null || patch === null)
-          throw new Error("id and patch are required to update a server");
-        return { endpoint: "servers.update", payload: { id, patch } };
+        if (id === null)
+          throw new Error("id is required to update a server");
+        if (patch === null)
+          throw jsonArgError(input, "patch", "to update a server");
+        const { id: _key, ...fields } = patch;
+        return { endpoint: "servers.update", payload: { id, patch: fields } };
       }
       if (action === "delete") {
         const id = stringArg(input, "id");
@@ -4441,8 +5062,9 @@ var TOOL_SPECS = {
     }
   },
   autostart_manage: {
-    description: "Install or remove the OS entry that starts home-hosted at boot or login.",
+    description: "Install or remove the OS entry that starts home-hosted at boot or login. The entry is machine-wide and always starts the panel this plugin manages.",
     parameters: {
+      instance: INSTANCE_PARAM,
       action: { type: "string", required: true, description: "install or uninstall" },
       mechanism: { type: "string", description: "Explicit mechanism, e.g. launchd-daemon or systemd-system; omit to use the plugin setting" }
     },
@@ -4455,8 +5077,9 @@ var TOOL_SPECS = {
     }
   },
   ui_manage: {
-    description: "Inspect or change the home-hosted panel's own web UI: status, update, revert to stock, or switch to a local zip.",
+    description: "Inspect or change the home-hosted panel's own web UI: status, update, revert to stock, or switch to a local zip. A named panel's UI is driven through the home-hosted CLI aimed at its state root.",
     parameters: {
+      instance: INSTANCE_PARAM,
       action: { type: "string", required: true, description: "status, update, revert or switch" },
       file: { type: "string", description: "Absolute path to a UI zip (switch)" }
     },
@@ -4475,6 +5098,198 @@ function toolNameFor(name2) {
 var READ_ONLY_ACTIONS = {
   ui_manage: (input) => stringArg(input, "action") === "status"
 };
+var CANCEL_LABEL = "Cancel";
+var NO_ANSWERER_CODES = /* @__PURE__ */ new Set(["NO_PROVIDER", "DELEGATED_CALLER", "CALLER_NOT_LIVE"]);
+var MECHANISM_WORDING = {
+  file: { option: "Edit its config file", phrase: "by editing its servers.config.json" },
+  cli: { option: "Run the home-hosted CLI", phrase: "by running the home-hosted CLI against its state root" },
+  api: { option: "Generate a token and use its API", phrase: "by enrolling a token for it and using its API" }
+};
+var NO_FOREIGN_REASON = {
+  "status": "home_hosted_status describes the panel this plugin manages, and it already lists every panel found on the machine.",
+  "boot.install": "the OS boot entry starts the panel this plugin manages; it is one machine-wide entry and cannot be aimed at another panel.",
+  "boot.uninstall": "the OS boot entry is one machine-wide entry and belongs to the panel this plugin manages."
+};
+async function inventoryOf(service) {
+  const reader = service.instances;
+  if (typeof reader !== "function")
+    return [];
+  try {
+    return await reader.call(service);
+  } catch {
+    return [];
+  }
+}
+function matchInstance(instances, wanted) {
+  const target = wanted.trim();
+  if (target.length === 0)
+    return null;
+  const asPath = canonicalPath(target);
+  return instances.find(
+    (instance) => instance.home === asPath || instance.url === target || instance.projectDir !== null && instance.projectDir === target
+  ) ?? null;
+}
+function inventoryText(instances) {
+  return instances.map((instance) => `${instance.managed ? "managed: " : ""}${describeInstance(instance)}`).join("; ");
+}
+function refusalForUnknownPanel(instances, wanted) {
+  return `refused: no home-hosted panel at "${wanted}" was found on this machine. Panels found: ${inventoryText(instances)}. Ask the user which panel they mean, or read home_hosted_status for the inventory.`;
+}
+function refusalForUnreachablePanel(instances, target, endpoint) {
+  const reason = NO_FOREIGN_REASON[endpoint] ?? `this plugin has no way to change another panel's state for ${endpoint}`;
+  return `refused: ${describeInstance(target)} is another home-hosted panel, and ${reason} Panels found: ${inventoryText(instances)}.`;
+}
+function answerOf(answer2, id) {
+  const item = (Array.isArray(answer2?.answers) ? answer2.answers : []).find((entry) => entry.id === id);
+  return {
+    selected: Array.isArray(item?.selected) ? item.selected : [],
+    custom: typeof item?.custom === "string" && item.custom.trim().length > 0 ? item.custom.trim() : null
+  };
+}
+async function planTarget(service, settings, endpoint, requested, mutating) {
+  const instances = await inventoryOf(service);
+  if (instances.length === 0) {
+    return requested === null ? { ok: true, home: null, ask: null } : { ok: false, text: `refused: this host could not list the home-hosted panels on this machine, so "${requested}" cannot be checked; ask the user, or call without instance to act on the panel this plugin manages.` };
+  }
+  const managed = instances.find((instance) => instance.managed);
+  const mechanisms = FOREIGN_MECHANISMS[endpoint];
+  if (requested !== null) {
+    const target = matchInstance(instances, requested);
+    if (target === null)
+      return { ok: false, text: refusalForUnknownPanel(instances, requested) };
+    if (target.managed)
+      return { ok: true, home: null, ask: null };
+    if (mechanisms === void 0)
+      return { ok: false, text: refusalForUnreachablePanel(instances, target, endpoint) };
+    return mutating ? { ok: true, home: target.home, ask: "foreign", mechanisms } : { ok: true, home: target.home, ask: null };
+  }
+  if (!mutating || !settings.get().instancesNotice || managed === void 0 || mechanisms === void 0 || instances.length < 2)
+    return { ok: true, home: null, ask: null };
+  return { ok: true, home: null, ask: "which", mechanisms };
+}
+async function ask(ctx, exec, questions, item) {
+  try {
+    const answer2 = await questions.ask({
+      questions: [{ id: item.id, header: "home-hosted", question: item.question, detail: item.detail, options: item.options }],
+      agent: exec?.agent,
+      signal: exec?.signal
+    });
+    const { selected, custom } = answerOf(answer2, item.id);
+    return { ok: true, selected, custom };
+  } catch (error) {
+    return { ok: false, code: errorCode(error), error };
+  }
+}
+async function askForeignPanel(ctx, exec, instances, target, mechanisms) {
+  const questions = ctx.get("userQuestions");
+  const first = mechanisms[0];
+  if (typeof questions?.ask !== "function")
+    return { ok: true, home: target.home, via: first };
+  const answer2 = await ask(ctx, exec, questions, {
+    id: "home-hosted-foreign-panel",
+    question: `${target.home} is not a panel this plugin manages. How should it be changed?`,
+    detail: inventoryText(instances),
+    options: [
+      ...mechanisms.map((mechanism) => ({
+        label: MECHANISM_WORDING[mechanism].option,
+        description: `${MECHANISM_WORDING[mechanism].phrase}${mechanism === "api" ? "; that mints a token for it, replacing any it had" : "; this plugin holds no API token for that panel"}`
+      })),
+      { label: CANCEL_LABEL, description: "Change nothing; say which panel you meant instead." }
+    ]
+  });
+  if (!answer2.ok) {
+    if (answer2.code === "ASK_ABORTED")
+      return { ok: false, text: "cancelled: the user dismissed the panel question to speak instead; stop and wait for their message." };
+    if (answer2.code !== null && NO_ANSWERER_CODES.has(answer2.code))
+      return { ok: true, home: target.home, via: first };
+    return { ok: false, text: `refused: the panel question could not be asked (${messageOf(answer2.error)}); ask the user before changing another panel.` };
+  }
+  if (answer2.selected.includes(CANCEL_LABEL))
+    return { ok: false, text: `cancelled: the user did not confirm changing ${target.home}; ask which panel they meant.` };
+  const chosen = answer2.selected.find((label) => label !== CANCEL_LABEL);
+  if (chosen !== void 0) {
+    const mechanism = mechanisms.find((candidate) => MECHANISM_WORDING[candidate].option === chosen);
+    if (mechanism !== void 0)
+      return { ok: true, home: target.home, via: mechanism };
+  }
+  if (chosen === void 0 && answer2.custom !== null) {
+    const mechanism = mechanisms.find((candidate) => matchesMechanism(answer2.custom, candidate));
+    if (mechanism !== void 0)
+      return { ok: true, home: target.home, via: mechanism };
+  }
+  return { ok: false, text: `cancelled: the user did not confirm changing ${target.home}; ask which panel they meant.` };
+}
+function matchesMechanism(text, mechanism) {
+  const value = text.toLowerCase();
+  if (mechanism === "file")
+    return /file|config/.test(value);
+  if (mechanism === "cli")
+    return /cli|command|terminal/.test(value);
+  return /api|token/.test(value);
+}
+async function askWhichPanel(ctx, exec, instances, managed, others, mechanisms) {
+  const questions = ctx.get("userQuestions");
+  if (typeof questions?.ask !== "function")
+    return { ok: true, home: null, via: null };
+  const answer2 = await ask(ctx, exec, questions, {
+    id: "home-hosted-instance",
+    question: `${instances.length} home-hosted panels were found on this machine. Act on the panel this plugin manages?`,
+    detail: inventoryText(instances),
+    options: [
+      { label: managed.home, description: `managed by this plugin${managed.url === null ? "" : ` \xB7 ${managed.url}`}` },
+      ...others.map((instance) => ({
+        label: instance.home,
+        description: `not managed by this plugin${instance.url === null ? "" : ` \xB7 ${instance.url}`} \xB7 ${mechanisms.map((candidate) => MECHANISM_WORDING[candidate].phrase).join(", or ")}`
+      })),
+      { label: CANCEL_LABEL, description: "Do nothing; say which panel you meant instead." }
+    ]
+  });
+  if (!answer2.ok) {
+    if (answer2.code === "ASK_ABORTED")
+      return { ok: false, text: "cancelled: the user dismissed the panel question to speak instead; stop and wait for their message." };
+    if (answer2.code !== null && NO_ANSWERER_CODES.has(answer2.code))
+      return { ok: true, home: null, via: null };
+    return { ok: false, text: `refused: the panel question could not be asked (${messageOf(answer2.error)}); ask the user which panel they mean before acting.` };
+  }
+  if (answer2.selected.includes(CANCEL_LABEL))
+    return { ok: false, text: "cancelled: the user chose not to pick a panel; ask them which one they mean." };
+  const chosen = answer2.selected.find((label) => label !== CANCEL_LABEL);
+  if (chosen !== void 0) {
+    const instance = matchInstance(instances, chosen);
+    if (instance === null)
+      return { ok: false, text: `cancelled: the answer "${chosen}" names no panel; ask the user which panel they mean.` };
+    return instance.managed ? { ok: true, home: null, via: null } : { ok: true, home: instance.home, via: null };
+  }
+  if (answer2.custom !== null) {
+    const instance = matchInstance(instances, answer2.custom);
+    if (instance?.managed === true)
+      return { ok: true, home: null, via: null };
+    if (instance !== null)
+      return { ok: true, home: instance.home, via: null };
+    return { ok: false, text: `cancelled: the user answered "${answer2.custom}", which names no panel; ask them which panel they mean.` };
+  }
+  return { ok: false, text: "cancelled: the panel question was not answered; ask the user which panel they mean before acting." };
+}
+async function confirmPlan(ctx, exec, service, plan) {
+  if (plan.ask === null)
+    return { ok: true, home: plan.home, via: null };
+  const instances = await inventoryOf(service);
+  const managed = instances.find((instance) => instance.managed);
+  if (plan.ask === "foreign") {
+    const target = instances.find((instance) => instance.home === plan.home);
+    return target === void 0 ? { ok: false, text: refusalForUnknownPanel(instances, plan.home) } : await askForeignPanel(ctx, exec, instances, target, plan.mechanisms);
+  }
+  if (managed === void 0)
+    return { ok: true, home: null, via: null };
+  const others = instances.filter((instance) => !instance.managed);
+  const picked = await askWhichPanel(ctx, exec, instances, managed, others, plan.mechanisms);
+  if (!picked.ok || picked.home === null)
+    return picked;
+  const chosen = instances.find((instance) => instance.home === picked.home);
+  if (chosen === void 0 || chosen.managed)
+    return picked;
+  return await askForeignPanel(ctx, exec, instances, chosen, plan.mechanisms);
+}
 var TOKEN_REFUSAL_CODES = /* @__PURE__ */ new Set([
   "AUTH_REQUIRED",
   "AUTH_UNARMED",
@@ -4531,8 +5346,17 @@ function registerOne(ctx, service, settings, name2) {
     },
     async execute(args, exec) {
       const input = args ?? {};
+      let request;
+      try {
+        request = spec.run(input);
+      } catch (error) {
+        return failureText(error);
+      }
       const mode = sandboxMode(ctx, exec);
       const mutating = mutatingTool && !(READ_ONLY_ACTIONS[name2]?.(input) ?? false);
+      const plan = await planTarget(service, settings, request.endpoint, stringArg(input, "instance"), mutating);
+      if (!plan.ok)
+        return plan.text;
       if (mutating && mode !== "danger-full-access") {
         const remedy = "Set the session to Full access (danger-full-access), or use a session where approvals can be answered.";
         const approval = ctx.get("approval");
@@ -4546,16 +5370,17 @@ function registerOne(ctx, service, settings, name2) {
         if (outcome !== "allowed-once")
           return `refused: approval answered "${outcome}" (session sandbox: ${mode ?? "unknown"}). ${remedy}`;
       }
-      let request;
-      try {
-        request = spec.run(input);
-      } catch (error) {
-        return failureText(error);
-      }
+      const target = await confirmPlan(ctx, exec, service, plan);
+      if (!target.ok)
+        return target.text;
+      const payload = target.home === null ? request.payload : withTarget(request.payload, target.home, target.via ?? FOREIGN_MECHANISMS[request.endpoint]?.[0] ?? null);
+      const landing = target.home === null ? "" : `
+
+home-hosted: ${plan.ask === null ? "read from" : "acted on"} ${target.home}, not the panel this plugin manages${target.via === null ? "" : `, ${MECHANISM_WORDING[target.via].phrase}`}.`;
       try {
-        return JSON.stringify(await service.call(request.endpoint, request.payload), null, 2);
+        return `${JSON.stringify(await service.call(request.endpoint, payload), null, 2)}${landing}`;
       } catch (error) {
-        if (!settings.get().reclaimToken || !await tokenRefused(service, error))
+        if (target.home !== null || !settings.get().reclaimToken || !await tokenRefused(service, error))
           return failureText(error);
         try {
           await service.call("panel.reclaimToken", {});
@@ -4563,7 +5388,7 @@ function registerOne(ctx, service, settings, name2) {
           return `${failureText(error)} (token reclaim failed: ${messageOf(reclaimError)})`;
         }
         try {
-          return JSON.stringify(await service.call(request.endpoint, request.payload), null, 2);
+          return `${JSON.stringify(await service.call(request.endpoint, payload), null, 2)}${landing}`;
         } catch (retryError) {
           return failureText(retryError);
         }
@@ -4606,21 +5431,31 @@ function apply(ctx, config) {
   const resolved = {
     stateDir: config?.stateDir,
     homeHostedCommand: config?.homeHostedCommand,
-    defaultEntryId: config?.defaultEntryId ?? "dsh"
+    defaultEntryId: config?.defaultEntryId ?? "dsh",
+    instanceRoots: config?.instanceRoots ?? []
   };
   const stateDir = pluginStateDir(resolved.stateDir);
   ensureDir(stateDir, 448);
-  const settings = new SettingsStore(path14.join(stateDir, "settings.json"), resolved.defaultEntryId);
+  const panel = resolveHomeHostedHome(stateDir);
+  const settings = new SettingsStore(path15.join(stateDir, "settings.json"), resolved.defaultEntryId);
   const service = new HomeHostedService(ctx, {
-    home: homeHostedHome(),
+    home: panel.home,
+    panelHomeSource: panel.source,
     stateDir,
     homeHostedCommand: resolved.homeHostedCommand,
     defaultEntryId: resolved.defaultEntryId,
+    instanceRoots: resolved.instanceRoots,
     settings
   });
   registerRpc(ctx, service);
   registerAgentTools(ctx, service, settings);
+  registerInstancesNotice(ctx, {
+    instances: () => service.instancesNow(),
+    enabled: () => settings.get().instancesNotice
+  });
   registerAuthNotice(ctx, () => settings.get().authNotice ? service.panelLogUrl() : null);
+  void service.instances().catch(() => {
+  });
   ctx.effect(() => {
     const timer = setTimeout(() => {
       void service.reconcile().catch(() => {