@piagent/platform 1.45.0 → 1.46.0

package/scripts/personal-pi-restore.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Takes Piagent out of the member's personal Pi (~/.pi/agent) and leaves it as
+// stock Pi. Releases before 1.46 installed Piagent, its add-ons, a model scope
+// and a subagent baseline there, so every plain `pi` loaded them. Piagent now
+// runs from its own home (~/.piagent/agent, opened with `piagent`).
+//
+//   personal-pi-restore.mjs [--apply] [--copy-login] [--json]
+//
+// Without --apply nothing changes: it reports what it would do. With --apply:
+//   - carries the member's model choices, custom models and trust decisions to
+//     Piagent's home when that home has none yet (the login only with
+//     --copy-login: credentials are copied when the member says so);
+//   - removes the Piagent package and the exact-pinned add-ons Piagent
+//     installed (pi-mcp-adapter, pi-subagents, pi-web-access) from personal Pi;
+//   - removes the subagent baseline and the model list Piagent wrote, when the
+//     list still holds only models Piagent offered.
+// Every changed file is backed up first. Sessions, the login and anything the
+// member added stay in personal Pi.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { personalPiAgentDir, piagentAgentDir } from "../packages/piagent-core/extensions/agent-home.js";
+
+const ADDONS = ["pi-mcp-adapter", "pi-subagents", "pi-web-access"];
+const MODEL_KEYS = ["defaultProvider", "defaultModel", "defaultThinkingLevel", "enabledModels"];
+const CARRIED_FILES = ["models.json", "trust.json", "piagent-model-scope.json"];
+const isPiagentSource = (source) => /(@piagent\/platform|Vt-mmm\/piagent|pi-company-platform)/.test(source);
+// Piagent always installed add-ons at an exact version; an unpinned entry is the member's own.
+const isPinnedAddon = (source) => ADDONS.some((name) => source.startsWith(`npm:${name}@`));
+
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
+const sourceOf = (entry) => (typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : "");
+
+function isLocalPiagent(agentDir, source) {
+  if (/^(npm|git|https?):/.test(source)) return false;
+  return readJson(path.join(path.resolve(agentDir, source), "package.json"))?.name === "@piagent/platform";
+}
+
+export function plan({ personalDir = personalPiAgentDir(), piagentDir = piagentAgentDir(), copyLogin = false } = {}) {
+  const settings = readJson(path.join(personalDir, "settings.json")) ?? {};
+  const packages = (Array.isArray(settings.packages) ? settings.packages : []).map(sourceOf).filter(Boolean);
+  const remove = packages.filter((source) => isPiagentSource(source) || isLocalPiagent(personalDir, source) || isPinnedAddon(source));
+  const kept = packages.filter((source) => !remove.includes(source) && ADDONS.some((name) => source.includes(name)));
+  const offered = readJson(path.join(personalDir, "piagent-model-scope.json"))?.offered;
+  const models = Array.isArray(settings.enabledModels) ? settings.enabledModels : [];
+  const piagentModelList = Array.isArray(offered) && models.length > 0 && models.every((model) => offered.includes(model));
+  const subagentConfig = path.join(personalDir, "extensions", "subagent", "config.json");
+  const target = readJson(path.join(piagentDir, "settings.json")) ?? {};
+  const carry = {
+    settings: MODEL_KEYS.filter((key) => settings[key] !== undefined && target[key] === undefined),
+    files: CARRIED_FILES.filter((name) => fs.existsSync(path.join(personalDir, name)) && !fs.existsSync(path.join(piagentDir, name))),
+    login: copyLogin && fs.existsSync(path.join(personalDir, "auth.json")) && !fs.existsSync(path.join(piagentDir, "auth.json"))
+  };
+  const cleanup = {
+    subagentsSetting: settings.subagents !== undefined && remove.some((source) => source.startsWith("npm:pi-subagents@")),
+    subagentConfig: fs.existsSync(subagentConfig) && remove.some((source) => source.startsWith("npm:pi-subagents@")),
+    enabledModels: piagentModelList,
+    modelScopeRecord: fs.existsSync(path.join(personalDir, "piagent-model-scope.json"))
+  };
+  const loginAvailable = fs.existsSync(path.join(personalDir, "auth.json")) && !fs.existsSync(path.join(piagentDir, "auth.json"));
+  const legacy = remove.some((source) => isPiagentSource(source) || isLocalPiagent(personalDir, source));
+  return { personalDir, piagentDir, legacy, remove, kept, carry, cleanup, loginAvailable };
+}
+
+function backup(file, stamp) {
+  if (!fs.existsSync(file)) return null;
+  const copy = `${file}.before-piagent-restore-${stamp}`;
+  fs.copyFileSync(file, copy);
+  fs.chmodSync(copy, 0o600);
+  return copy;
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function copyPrivate(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true, mode: 0o700 });
+  fs.copyFileSync(from, to, fs.constants.COPYFILE_EXCL);
+  fs.chmodSync(to, 0o600);
+}
+
+// `pi remove` also deletes the package's files; when Pi is missing or refuses,
+// the entry still leaves settings.json so personal Pi stops loading it.
+function removePackage(personalDir, source) {
+  const env = { ...process.env, PI_CODING_AGENT_DIR: personalDir };
+  delete env.PIAGENT_ACTIVE;
+  delete env.PIAGENT_AGENT_DIR;
+  const result = spawnSync("pi", ["remove", source], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32" });
+  if (result.status === 0) return "pi remove";
+  const file = path.join(personalDir, "settings.json"), settings = readJson(file);
+  if (settings && Array.isArray(settings.packages)) {
+    settings.packages = settings.packages.filter((entry) => sourceOf(entry) !== source);
+    writeJson(file, settings);
+  }
+  return "settings.json";
+}
+
+export function apply(options = {}, now = new Date()) {
+  const report = plan(options);
+  const { personalDir, piagentDir, carry, cleanup } = report;
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const backups = [], done = [];
+  const personalSettingsFile = path.join(personalDir, "settings.json");
+  const anything = report.remove.length || Object.values(cleanup).some(Boolean);
+  if (anything) backups.push(backup(personalSettingsFile, stamp));
+
+  // Carry first, so nothing the member chose is lost if a removal fails.
+  if (carry.settings.length) {
+    const from = readJson(personalSettingsFile) ?? {}, targetFile = path.join(piagentDir, "settings.json");
+    const target = readJson(targetFile) ?? {};
+    for (const key of carry.settings) target[key] = from[key];
+    writeJson(targetFile, target);
+    done.push(`carried ${carry.settings.join(", ")} to ${targetFile}`);
+  }
+  for (const name of carry.files) {
+    copyPrivate(path.join(personalDir, name), path.join(piagentDir, name));
+    done.push(`carried ${name} to ${piagentDir}`);
+  }
+  if (carry.login) {
+    copyPrivate(path.join(personalDir, "auth.json"), path.join(piagentDir, "auth.json"));
+    done.push(`copied the pi login to ${piagentDir} (personal pi keeps its own)`);
+  }
+
+  for (const source of report.remove) done.push(`removed ${source} from personal pi (${removePackage(personalDir, source)})`);
+
+  if (cleanup.subagentsSetting || cleanup.enabledModels) {
+    const settings = readJson(personalSettingsFile) ?? {};
+    if (cleanup.subagentsSetting) { delete settings.subagents; done.push("removed the subagents setting Piagent wrote"); }
+    if (cleanup.enabledModels) { delete settings.enabledModels; done.push("removed the model list Piagent wrote"); }
+    writeJson(personalSettingsFile, settings);
+  }
+  if (cleanup.subagentConfig) {
+    const file = path.join(personalDir, "extensions", "subagent", "config.json");
+    fs.renameSync(file, `${file}.before-piagent-restore-${stamp}`);
+    backups.push(`${file}.before-piagent-restore-${stamp}`);
+    done.push("set aside the subagent baseline Piagent wrote");
+  }
+  if (cleanup.modelScopeRecord) {
+    fs.rmSync(path.join(personalDir, "piagent-model-scope.json"), { force: true });
+    done.push("removed Piagent's model-scope record from personal pi");
+  }
+  return { ...report, done, backups: backups.filter(Boolean) };
+}
+
+function describe(report, applied) {
+  const lines = [`Personal pi: ${report.personalDir}`, `Piagent home: ${report.piagentDir}`];
+  if (applied) {
+    lines.push(...(report.done.length ? report.done.map((line) => `  ${line}`) : ["  nothing to change: personal pi has no Piagent entries"]));
+    for (const file of report.backups) lines.push(`  backup: ${file}`);
+  } else {
+    if (!report.remove.length && !Object.values(report.cleanup).some(Boolean)) lines.push("  nothing to change: personal pi has no Piagent entries");
+    for (const source of report.remove) lines.push(`  would remove ${source}`);
+    if (report.cleanup.subagentsSetting) lines.push("  would remove the subagents setting Piagent wrote");
+    if (report.cleanup.subagentConfig) lines.push("  would set aside extensions/subagent/config.json");
+    if (report.cleanup.enabledModels) lines.push("  would remove the model list Piagent wrote");
+    if (report.carry.settings.length || report.carry.files.length) lines.push(`  would carry ${[...report.carry.settings, ...report.carry.files].join(", ")} to Piagent's home`);
+    if (report.carry.login) lines.push("  would copy the pi login to Piagent's home");
+    else if (report.loginAvailable) lines.push("  login stays personal; add --copy-login to use it in Piagent too (else run `piagent`, then /login)");
+  }
+  for (const source of report.kept) lines.push(`  kept ${source} (not a version Piagent pinned; remove it with pi remove if you do not want it)`);
+  if (!applied) lines.push("Dry run. Re-run with --apply to make these changes.");
+  return lines.join("\n");
+}
+
+const real = (file) => { try { return fs.realpathSync(file); } catch { return null; } };
+const invoked = process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url));
+if (invoked) {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: piagent restore-pi [--apply] [--copy-login] [--json]\n\nTakes an older Piagent install out of your personal pi (~/.pi/agent) and leaves it stock.\nWithout --apply it only reports. --copy-login also copies your pi login into Piagent's home.");
+    process.exit(0);
+  }
+  const unknown = args.filter((value) => !["--apply", "--copy-login", "--json"].includes(value));
+  if (unknown.length) { console.error(`Unknown argument: ${unknown[0]}`); process.exit(2); }
+  const options = { copyLogin: args.includes("--copy-login") };
+  const applied = args.includes("--apply");
+  const report = applied ? apply(options) : plan(options);
+  console.log(args.includes("--json") ? JSON.stringify(report, null, 2) : describe(report, applied));
+}

package/scripts/pi-usage-history.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { piagentAgentDir } from "../packages/piagent-core/extensions/agent-home.js";
 
 const USAGE = `Usage:
   scripts/pi-usage-history.mjs [project-path] [options]
@@ -63,7 +64,7 @@ function parseArgs(argv) {
     includeSubagents: true,
     limit: 20,
     sessionsDir: process.env.PI_CODING_AGENT_SESSION_DIR
-      || path.join(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"), "sessions"),
+      || path.join(piagentAgentDir(), "sessions"),
     projectPath: undefined,
     since: undefined,
     until: undefined

package/scripts/piagent-cli.mjs

@@ -28,7 +28,8 @@ const scriptByCommand = {
   "piagent-webui": "scripts/piagent-webui-launcher.mjs",
   "piagent-dashboard": "scripts/piagent-dashboard.mjs",
   "piagent-pi-host": "scripts/pi-host.mjs",
-  "piagent-skills": "scripts/skill-sources.mjs"
+  "piagent-skills": "scripts/skill-sources.mjs",
+  "piagent-restore-pi": "scripts/personal-pi-restore.mjs"
 };
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -36,9 +37,28 @@ const invokedAs = path.basename(process.argv[1] ?? "");
 let forwardedArgs = process.argv.slice(2);
 let script = scriptByCommand[invokedAs];
 
+// Piagent's Pi lives in its own home so the member's `pi` (~/.pi/agent) stays
+// stock; Agent Watch's files stay in ~/.pi/agent. Same rule as
+// packages/piagent-core/extensions/agent-home.js, inlined because this
+// launcher runs before anything else of the package resolves.
+const personalPiDir = path.resolve(os.homedir(), ".pi", "agent");
+function piagentHome() {
+  const own = process.env.PIAGENT_AGENT_DIR?.trim();
+  if (own) return path.resolve(own);
+  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  if (configured && path.resolve(configured) !== personalPiDir) return path.resolve(configured);
+  return path.resolve(os.homedir(), ".piagent", "agent");
+}
+let terminal = false;
+
 if (invokedAs === "piagent") {
   const subcommand = forwardedArgs[0];
-  if (subcommand === "studio") {
+  if (subcommand === undefined || (subcommand.startsWith("-") && !["--help", "-h"].includes(subcommand))) {
+    // `piagent` on its own (or with Pi's flags, `piagent -c`) opens Piagent here.
+    script = "scripts/pi-host.mjs";
+    forwardedArgs = ["run", "--", ...forwardedArgs];
+    terminal = true;
+  } else if (subcommand === "studio") {
     script = "scripts/piagent-studio.mjs";
     forwardedArgs = forwardedArgs.slice(1);
   } else if (subcommand === "dashboard") {
@@ -48,6 +68,7 @@ if (invokedAs === "piagent") {
     // Pi itself, on the release Piagent is qualified on, whatever `pi` the member keeps.
     script = "scripts/pi-host.mjs";
     forwardedArgs = ["run", "--", ...forwardedArgs.slice(1)];
+    terminal = true;
   } else if (subcommand === "explain") {
     script = "scripts/explain-command.mjs";
     forwardedArgs = forwardedArgs.slice(1);
@@ -61,16 +82,18 @@ if (invokedAs === "piagent") {
     // `piagent doctor` is `piagent-doctor`: members type it both ways.
     script = scriptByCommand[`piagent-${subcommand}`];
     forwardedArgs = forwardedArgs.slice(1);
-  } else if ([undefined, "help", "--help", "-h"].includes(subcommand)) {
+  } else if (["help", "--help", "-h"].includes(subcommand)) {
     // Subcommands are listed, their flags are not. Restating them here meant a
     // second copy that drifts: this line still advertised the dashboard without
     // `--repair` after that flag shipped. Each command states its own surface.
-    console.log("Usage: piagent <command> [options]");
+    console.log("Usage: piagent [pi options]     Open Piagent in this terminal (its own Pi home, ~/.piagent/agent)");
+    console.log("       piagent <command> [options]");
     console.log("");
     console.log("Commands:");
     console.log("  dashboard   Open and manage the local session hub");
     console.log("  studio      Open the managed company agent imported by Agent Watch");
-    console.log("  pi          Run Pi on the release Piagent is qualified on (your own pi stays as it is)");
+    console.log("  pi          Same as `piagent`: Pi on the release Piagent is qualified on, in Piagent's home");
+    console.log("  restore-pi  Take an older Piagent install out of your own pi (~/.pi/agent)");
     console.log("  pi-host     Show or install the Pi host Piagent runs");
     console.log("  skills      Add, list or remove skill sources such as mattpocock/skills");
     console.log("  explain     Say why the guard would allow or block a shell command");
@@ -91,7 +114,7 @@ if (!script) {
 function benchmarkSourceRoot() {
   if (fs.existsSync(path.join(packageRoot, ".git"))) return packageRoot;
   if (process.argv.slice(2).some((value) => value === "--help" || value === "-h")) return packageRoot;
-  const agentRoot = path.resolve(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"));
+  const agentRoot = piagentHome();
   const installed = path.join(agentRoot, "git", "github.com", "Vt-mmm", "piagent");
   try {
     const helperVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
@@ -133,8 +156,9 @@ async function recordRuntime() {
     // an entrypoint that no longer exists.
     const osTemp = fs.realpathSync.native(os.tmpdir()), installRoot = fs.realpathSync.native(packageRoot);
     if (installRoot === osTemp || installRoot.startsWith(`${osTemp}${path.sep}`)) return;
-    const agentDir = path.resolve(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"));
-    if (!fs.statSync(agentDir).isDirectory()) return;
+    // Agent Watch reads the record from the personal Pi folder, not Piagent's home.
+    const agentDir = personalPiDir;
+    fs.mkdirSync(agentDir, { recursive: true, mode: 0o700 });
     const body = `${JSON.stringify({
       schema_version: 1,
       version: JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version,
@@ -151,6 +175,21 @@ async function recordRuntime() {
 }
 await recordRuntime();
 
+if (terminal) {
+  let packages = [];
+  try { packages = JSON.parse(fs.readFileSync(path.join(piagentHome(), "settings.json"), "utf8")).packages ?? []; } catch { /* not installed yet */ }
+  const isPiagent = (entry) => {
+    const source = String(typeof entry === "string" ? entry : entry?.source ?? "");
+    if (/@piagent\/platform|Vt-mmm\/piagent/.test(source)) return true;
+    try { return JSON.parse(fs.readFileSync(path.join(path.resolve(piagentHome(), source), "package.json"), "utf8")).name === "@piagent/platform"; } catch { return false; }
+  };
+  if (!packages.some(isPiagent)) {
+    console.error(`Piagent is not installed in ${piagentHome()} yet. Run: piagent-install --stable`);
+    console.error("An install from before 1.46 lives in your own pi; piagent-install moves it, or run: piagent restore-pi");
+    process.exit(1);
+  }
+}
+
 const sourceRoot = invokedAs === "piagent-benchmark" ? benchmarkSourceRoot() : packageRoot;
 const target = path.join(sourceRoot, script);
 const runner = target.endsWith(".mjs") ? process.execPath : "bash";
@@ -159,7 +198,8 @@ const runnerArgs = target.endsWith(".mjs")
   : [target];
 const child = spawn(runner, [...runnerArgs, ...forwardedArgs], {
   cwd: process.cwd(),
-  env: script === "scripts/piagent-studio.mjs" ? { PATH: "/usr/bin:/bin", HOME: os.homedir(), TERM: process.env.TERM || "xterm-256color", LANG: "en_US.UTF-8" } : process.env,
+  env: script === "scripts/piagent-studio.mjs" ? { PATH: "/usr/bin:/bin", HOME: os.homedir(), TERM: process.env.TERM || "xterm-256color", LANG: "en_US.UTF-8" }
+    : { ...process.env, PI_CODING_AGENT_DIR: piagentHome(), ...(terminal ? { PIAGENT_ACTIVE: "1" } : {}) },
   stdio: "inherit"
 });
 

package/scripts/piagent-dashboard.mjs

@@ -12,6 +12,7 @@ import { gatewayProfileState, profileRef, readGatewayDescriptor, readOrCreateCat
   removeGatewayDescriptor } from "../packages/piagent-webui/gateway/profile-state.ts";
 import { startPiagentGateway } from "../packages/piagent-webui/gateway/gateway-service.ts";
 import { agentWatchCompanyConnector } from "../packages/piagent-webui/gateway/managed-launch.ts";
+import { agentWatchControlDir, piagentAgentDir } from "../packages/piagent-core/extensions/agent-home.js";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
@@ -177,7 +178,7 @@ async function ensureStarted() {
   }
   const existing = await currentLaunchUrl() ?? await waitForRunningGateway();
   if (existing) return existing;
-  const effectiveAgentDir = path.resolve(agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"));
+  const effectiveAgentDir = path.resolve(agentDir ?? piagentAgentDir());
   const state = gatewayProfileState(effectiveAgentDir);
   writeGatewayErrorLog(state);
   const child = spawn(process.execPath, [
@@ -210,8 +211,9 @@ async function ensureStarted() {
 
 async function serve() {
   // Company sessions come from the Agent Watch binding in this Pi folder.
-  const piAgentDir = path.resolve(agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"));
-  const gateway = await startPiagentGateway({ packageRoot, expectedPiVersion, agentDir, company: agentWatchCompanyConnector(piAgentDir) });
+  // Agent Watch writes the company binding into the personal Pi folder.
+  const bindingDir = agentDir ? path.resolve(agentDir) : agentWatchControlDir();
+  const gateway = await startPiagentGateway({ packageRoot, expectedPiVersion, agentDir: agentDir ?? piagentAgentDir(), company: agentWatchCompanyConnector(bindingDir) });
   const shutdown = () => { void gateway.close(); };
   process.once("SIGINT", shutdown);
   process.once("SIGTERM", shutdown);

package/scripts/setup.sh

@@ -504,12 +504,8 @@ echo "Next:"
 if [[ "$DO_PROJECT" == true ]]; then
   echo "  cd \"$PROJECT_PATH\""
 fi
-if [[ "$PI_HOST_PRIVATE" == true ]]; then
-  echo "  piagent pi         # Pi $(node -p 'require(process.argv[1]).peerDependencies["@earendil-works/pi-coding-agent"]' "$PLATFORM_ROOT/package.json"), the release Piagent is qualified on; your own pi also loads Piagent"
-else
-  echo "  pi"
-fi
-echo "  /login             # first time only"
+echo "  piagent            # Piagent in its own Pi home; plain \`pi\` stays your own, stock"
+echo "  /login             # first time only, unless the login of your pi was copied"
 if [[ "$DO_PROJECT" == true ]]; then
   echo "  /model             # or Ctrl+L: select provider/model from Pi selector"
   echo "  /scoped-models     # optional: edit Ctrl+P model cycle scope"

package/scripts/team-doctor.sh

@@ -72,8 +72,14 @@ const installations = piagentInstallations();
 if(installations.length>1) warnings.push("Multiple Piagent installations detected. Use the pinned Watch launcher; other PATHs may run an older build: "+installations.map(i=>`${i.version} [${i.fingerprint}] ${i.root}`).join("; "));
 // Personal Pi loading Piagent twice does not start; old company providers send it to Studio outside the Harness.
 const { inspect: inspectPersonalPi } = await import(pathToFileURL(path.join(platformRoot, "scripts/personal-pi-config.mjs")).href);
-for (const finding of inspectPersonalPi(process.env.PI_CODING_AGENT_DIR || path.join(process.env.HOME || "", ".pi", "agent")).findings)
-  (finding.kind === "duplicate-extensions" ? errors : warnings).push(`personal Pi: ${finding.text} Fix: piagent-update`);
+const personalPiDir = path.join(process.env.HOME || "", ".pi", "agent");
+for (const agentDir of new Set([personalPiDir, process.env.PI_CODING_AGENT_DIR || personalPiDir]))
+  for (const finding of inspectPersonalPi(agentDir).findings)
+    (finding.kind === "duplicate-extensions" ? errors : warnings).push(`${agentDir === personalPiDir ? "personal Pi" : "Piagent home"}: ${finding.text} Fix: piagent-update`);
+// Since 1.46 Piagent runs from its own home; an older install left in personal Pi keeps loading there.
+const { plan: personalPiRestorePlan } = await import(pathToFileURL(path.join(platformRoot, "scripts/personal-pi-restore.mjs")).href);
+if (personalPiRestorePlan({ personalDir: personalPiDir }).legacy)
+  warnings.push("personal Pi still loads an older Piagent install (~/.pi/agent). Fix: piagent restore-pi --apply");
 const { verifyCapabilityLock } = await import(pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "capabilities", "capability-core.js")).href);
 
 function exists(rel) {
@@ -271,9 +277,9 @@ if (commandExists("pi")) {
   piHasMcpAdapter = combined.includes("pi-mcp-adapter");
   piHasSubagents = combined.includes("pi-subagents");
   piHasWebAccess = combined.includes("pi-web-access");
-  if (!piHasMcpAdapter) warnings.push("Pi MCP adapter not found in `pi list`; run setup with --with-mcp or `pi install npm:pi-mcp-adapter@2.15.0`");
-  if (!piHasSubagents) warnings.push("Pi subagents package not found in `pi list`; run setup with --with-subagents or `pi install npm:pi-subagents@0.38.0`");
-  if (!piHasWebAccess) warnings.push("Pi web access package not found in `pi list`; run `piagent-update --force` or `pi install npm:pi-web-access@0.17.0` so researcher subagents can browse/fetch external sources");
+  if (!piHasMcpAdapter) warnings.push("Pi MCP adapter not found in `pi list`; run `piagent-install --with-mcp` (installs into Piagent's home, not your personal pi)");
+  if (!piHasSubagents) warnings.push("Pi subagents package not found in `pi list`; run `piagent-install --with-subagents` if you want them");
+  if (!piHasWebAccess) warnings.push("Pi web access package not found in `pi list`; run `piagent-install --with-web-access` so researcher subagents can browse/fetch external sources");
 }
 
 const mcpFiles = [

package/scripts/uninstall-global.sh

@@ -9,7 +9,16 @@ set -euo pipefail
 # deleted.
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-PI_AGENT_DIR="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
+# Piagent's own Pi home (same rule as packages/piagent-core/extensions/agent-home.js).
+PERSONAL_PI_DIR="${HOME}/.pi/agent"
+if [[ -n "${PIAGENT_AGENT_DIR:-}" ]]; then
+  PI_AGENT_DIR="$PIAGENT_AGENT_DIR"
+elif [[ -n "${PI_CODING_AGENT_DIR:-}" && "${PI_CODING_AGENT_DIR%/}" != "$PERSONAL_PI_DIR" ]]; then
+  PI_AGENT_DIR="$PI_CODING_AGENT_DIR"
+else
+  PI_AGENT_DIR="${HOME}/.piagent/agent"
+fi
+export PI_CODING_AGENT_DIR="$PI_AGENT_DIR"
 GLOBAL_SETTINGS="$PI_AGENT_DIR/settings.json"
 
 APPLY=false
@@ -26,7 +35,9 @@ usage() {
 Usage:
   piagent-uninstall [--apply] [--with-addons] [--with-host] [--project <path>]
 
-Removes the Pi package this platform installed from Pi's global settings.
+Removes the Pi package this platform installed from Piagent's own Pi home
+(~/.piagent/agent). An install from before 1.46 lives in your personal pi
+(~/.pi/agent): `piagent restore-pi --apply` takes it out of there.
 
   (default)        Dry run. Reports what would be removed and exits 0.
   --apply          Perform the removal.
@@ -291,6 +302,10 @@ NODE
 fi
 
 echo
+if node "$ROOT/scripts/personal-pi-restore.mjs" --json 2>/dev/null | grep -q '"legacy": true'; then
+  echo "Your personal pi ($PERSONAL_PI_DIR) still loads an older Piagent install."
+  echo "  Take it out with: piagent restore-pi --apply"
+fi
 if [[ "$APPLY" == true ]]; then
   echo "Uninstall complete."
   echo "The npm-global helper is separate and stays until you remove it:"

package/scripts/update-global.mjs

@@ -22,6 +22,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { inspect as inspectPersonalPi } from "./personal-pi-config.mjs";
+import { personalPiAgentDir, piagentAgentDir } from "../packages/piagent-core/extensions/agent-home.js";
 import { hostPlan, installPrivateHost, privateHostRoot } from "../packages/piagent-core/managed/pi-host.mjs";
 
 const HELPER_PACKAGE = "@piagent/platform";
@@ -438,8 +439,10 @@ function main() {
     : `  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
   // The Pi package can lag the helper (installed from an older tag), and
   // personal Pi can hold conflicting Piagent or old company entries.
-  const personal = inspectPersonalPi(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"));
-  const installedPackages = personal.packages.map((item) => item.version ?? "unknown");
+  // The package lives in Piagent's home; old company entries and an older
+  // Piagent install live in the member's personal pi.
+  const personal = inspectPersonalPi(personalPiAgentDir()), own = inspectPersonalPi(piagentAgentDir());
+  const installedPackages = own.packages.map((item) => item.version ?? "unknown");
   const packageNeedsChange = options.package && (options.force || installedPackages.length !== 1 || installedPackages[0] !== targetHelper);
   console.log(`  package: ${installedPackages.join(", ") || "not installed"} -> v${targetHelper}${options.package ? packageNeedsChange ? " (reinstalled as a resolved commit)" : " (already current)" : " (skipped)"}`);
   for (const finding of personal.findings) console.log(`  personal Pi: ${finding.text}`);