@piagent/platform 1.44.4 → 1.46.0

package/scripts/install-global.sh

@@ -23,6 +23,9 @@ Options:
   --with-web-access | --no-web-access
                                   Install pi-web-access for the researcher subagent (default: install).
   --with-herdr                    Also configure Herdr integration.
+  --copy-login | --no-copy-login  Copy (or not) your personal pi login into Piagent's home.
+                                  Default: ask in a terminal; without one, copy only when
+                                  moving an older install out of your personal pi.
   --model-scope <full|codex|claude>
                                   Model families to enable in Pi (default: full). A member who
                                   already has a default model and model list keeps them; an
@@ -36,7 +39,13 @@ Options:
   -h, --help                      Print this help and exit.
 
 Purpose:
-  Install the piagent Pi package into the current user's global Pi settings.
+  Install Piagent into its own Pi home (~/.piagent/agent; PIAGENT_AGENT_DIR overrides).
+  Your personal `pi` (~/.pi/agent) stays stock: open Piagent with `piagent`.
+  An install from an older release that lives in ~/.pi/agent is moved out of it.
+
+  Run in a terminal, a first install asks which add-ons to install and whether
+  to use your pi login; flags answer those questions up front, and a run
+  without a terminal (CI, the dashboard updater) takes the defaults.
 
 Package source examples:
   # Recommended stable install: exact current release tag
@@ -61,7 +70,8 @@ Package source examples:
 Notes:
   - `currentRelease` in output is the version of the terminal helper executing this command.
   - Use exactly one package selector. The first CLI selector overrides environment defaults; a second selector fails closed.
-  - OAuth is intentionally not automated. Run `pi` then `/login`.
+  - OAuth is intentionally not automated. Run `piagent` then `/login`, or let the
+    installer copy the login your personal pi already has.
   - Model scope is configured with Pi's native `enabledModels` so users choose via `/model`, Ctrl+L, `/scoped-models`, and Ctrl+P.
   - Herdr integration is optional and modifies user-level Herdr/Pi config.
   - MCP is installed by default with the core preset: Context7 docs, Chrome DevTools, GitHub.
@@ -76,6 +86,21 @@ USAGE
 }
 
 PLATFORM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Piagent's own Pi home (packages/piagent-core/extensions/agent-home.js has the
+# same rule). Every `pi` call below works there, never in the personal home.
+PERSONAL_PI_DIR="${HOME}/.pi/agent"
+if [[ -n "${PIAGENT_AGENT_DIR:-}" ]]; then
+  PIAGENT_HOME="$PIAGENT_AGENT_DIR"
+elif [[ -n "${PI_CODING_AGENT_DIR:-}" && "${PI_CODING_AGENT_DIR%/}" != "$PERSONAL_PI_DIR" ]]; then
+  PIAGENT_HOME="$PI_CODING_AGENT_DIR"
+else
+  PIAGENT_HOME="${HOME}/.piagent/agent"
+fi
+export PI_CODING_AGENT_DIR="$PIAGENT_HOME"
+MCP_EXPLICIT=false
+WEB_ACCESS_EXPLICIT=false
+MODEL_SCOPE_EXPLICIT=false
+COPY_LOGIN=""
 CURRENT_RELEASE_TAG=""
 EXPECTED_PI_VERSION=""
 EXPECTED_RELEASE_COMMIT="${PIAGENT_EXPECTED_RELEASE_COMMIT:-}"
@@ -486,10 +511,12 @@ while [[ $# -gt 0 ]]; do
       ;;
     --with-mcp)
       WITH_MCP=true
+      MCP_EXPLICIT=true
       shift
       ;;
     --no-mcp)
       WITH_MCP=false
+      MCP_EXPLICIT=true
       shift
       ;;
     --mcp-preset)
@@ -520,10 +547,12 @@ while [[ $# -gt 0 ]]; do
       ;;
     --with-web-access)
       WITH_WEB_ACCESS=true
+      WEB_ACCESS_EXPLICIT=true
       shift
       ;;
     --no-web-access)
       WITH_WEB_ACCESS=false
+      WEB_ACCESS_EXPLICIT=true
       shift
       ;;
     --with-herdr)
@@ -533,6 +562,7 @@ while [[ $# -gt 0 ]]; do
     --model-scope)
       require_value "$1" "${2:-}"
       MODEL_SCOPE_PRESET="$2"
+      MODEL_SCOPE_EXPLICIT=true
       shift 2
       ;;
     --default-model)
@@ -546,6 +576,15 @@ while [[ $# -gt 0 ]]; do
       ;;
     --no-model-scope)
       CONFIGURE_MODEL_SCOPE=false
+      MODEL_SCOPE_EXPLICIT=true
+      shift
+      ;;
+    --copy-login)
+      COPY_LOGIN=true
+      shift
+      ;;
+    --no-copy-login)
+      COPY_LOGIN=false
       shift
       ;;
     -h|--help)
@@ -569,6 +608,54 @@ fi
 
 require_node_version
 
+# What personal Pi holds from an older Piagent release (packages, login).
+LEGACY_REPORT="$(node "$PLATFORM_ROOT/scripts/personal-pi-restore.mjs" --json 2>/dev/null || echo '{}')"
+legacy_field() {
+  node -e 'const r = JSON.parse(process.argv[1] || "{}"); const v = process.argv[2].split(".").reduce((o, k) => o?.[k], r); process.stdout.write(Array.isArray(v) ? v.join("\n") : String(v ?? ""));' "$LEGACY_REPORT" "$1"
+}
+LEGACY_INSTALL="$(legacy_field legacy)"
+LEGACY_SUBAGENTS=false
+if legacy_field remove | grep -q '^npm:pi-subagents@'; then LEGACY_SUBAGENTS=true; fi
+FIRST_INSTALL=true
+if [[ -f "$PIAGENT_HOME/settings.json" ]] && grep -qE '@piagent/platform|Vt-mmm/piagent' "$PIAGENT_HOME/settings.json" 2>/dev/null; then
+  FIRST_INSTALL=false
+fi
+
+# Ask, rather than decide for the member, what goes into Piagent's home: only on
+# a first install (an update keeps what is there), only in a terminal, and never
+# for a question a flag already answered.
+ask_yes_no() {
+  local question="$1" default="$2" answer hint="[Y/n]"
+  [[ "$default" == false ]] && hint="[y/N]"
+  read -r -p "$question $hint " answer </dev/tty || answer=""
+  case "$answer" in
+    [Yy]*) echo true ;;
+    [Nn]*) echo false ;;
+    *) echo "$default" ;;
+  esac
+}
+if [[ "$FIRST_INSTALL" == true && "$DRY_RUN" == false && -t 0 && -t 1 && -z "${PIAGENT_INSTALL_DEFAULTS:-}" ]]; then
+  echo "Piagent installs into its own Pi home: $PIAGENT_HOME"
+  echo "Your personal pi ($PERSONAL_PI_DIR) is not changed by these choices."
+  [[ "$MCP_EXPLICIT" == true ]] || WITH_MCP="$(ask_yes_no "Install the MCP adapter (pi-mcp-adapter, servers: $MCP_PRESET)?" "$WITH_MCP")"
+  if [[ "$SUBAGENTS_EXPLICIT" == false ]]; then
+    WITH_SUBAGENTS="$(ask_yes_no "Install pi-subagents (optional parallel helpers; company sessions use their own)?" "$LEGACY_SUBAGENTS")"
+    SUBAGENTS_EXPLICIT=true
+  fi
+  [[ "$WEB_ACCESS_EXPLICIT" == true ]] || WITH_WEB_ACCESS="$(ask_yes_no "Install pi-web-access (web search and fetch for the researcher subagent)?" "$WITH_WEB_ACCESS")"
+  [[ "$MODEL_SCOPE_EXPLICIT" == true ]] || CONFIGURE_MODEL_SCOPE="$(ask_yes_no "Set Piagent's model list and default model ($DEFAULT_MODEL)?" "$CONFIGURE_MODEL_SCOPE")"
+  if [[ -z "$COPY_LOGIN" && "$(legacy_field loginAvailable)" == true ]]; then
+    COPY_LOGIN="$(ask_yes_no "Use the login your personal pi already has (copies auth.json once)?" true)"
+  fi
+  echo
+fi
+if [[ -z "$COPY_LOGIN" ]]; then
+  COPY_LOGIN="$LEGACY_INSTALL"
+fi
+if [[ "$LEGACY_SUBAGENTS" == true && "$SUBAGENTS_EXPLICIT" == false ]]; then
+  WITH_SUBAGENTS=true
+fi
+
 # The preset is only read at the very last step, after the platform package and
 # the MCP adapter are already installed. A name with a typo therefore failed
 # after two installs had landed, leaving a half-configured machine, and the
@@ -736,10 +823,25 @@ if [[ -n "$RESOLVED_PACKAGE_COMMIT" ]]; then
 fi
 echo "  source: $PACKAGE_SOURCE"
 sync_local_helper
+echo "  home: $PIAGENT_HOME (your personal pi stays in $PERSONAL_PI_DIR)"
+run_cmd mkdir -p "$PIAGENT_HOME"
 echo "Removing previous Pi Agent Platform package registrations:"
 remove_existing_piagent_platform_sources
 run_cmd pi install "$PACKAGE_SOURCE"
 
+# An older release installed Piagent into personal Pi. Move it out: carry the
+# member's model choices (and the login, when agreed) to Piagent's home, then
+# leave personal Pi stock. Backups of every changed file stay beside it.
+if [[ "$LEGACY_INSTALL" == true ]]; then
+  echo "Moving the older Piagent install out of your personal pi:"
+  restore_args=("$PLATFORM_ROOT/scripts/personal-pi-restore.mjs" --apply)
+  [[ "$COPY_LOGIN" == true ]] && restore_args+=(--copy-login)
+  run_cmd node "${restore_args[@]}"
+elif [[ "$COPY_LOGIN" == true && "$(legacy_field loginAvailable)" == true ]]; then
+  echo "Copying your pi login to Piagent's home:"
+  run_cmd node -e 'const fs = require("node:fs"); fs.copyFileSync(process.argv[1], process.argv[2], fs.constants.COPYFILE_EXCL); fs.chmodSync(process.argv[2], 0o600);' "$PERSONAL_PI_DIR/auth.json" "$PIAGENT_HOME/auth.json"
+fi
+
 if [[ "$WITH_MCP" == true ]]; then
   echo "Installing Pi MCP adapter:"
   if [[ "$DRY_RUN" == false ]]; then
@@ -747,6 +849,9 @@ if [[ "$WITH_MCP" == true ]]; then
   fi
   remove_existing_npm_package_sources "pi-mcp-adapter"
   run_cmd pi install "$PI_MCP_ADAPTER_SOURCE"
+  # Pi's built-in `mcp` extension registers the same /mcp command as the
+  # adapter; Piagent's home turns the built-in off so only one loads.
+  run_cmd node -e 'const fs = require("node:fs"); const f = process.argv[1]; const s = JSON.parse(fs.readFileSync(f, "utf8")); const e = Array.isArray(s.extensions) ? s.extensions : []; if (!e.includes("-builtin:mcp")) { s.extensions = [...e, "-builtin:mcp"]; fs.writeFileSync(f, JSON.stringify(s, null, 2) + "\n"); }' "$PIAGENT_HOME/settings.json"
   if [[ "$DRY_RUN" == false ]] && command -v pi-mcp-adapter >/dev/null 2>&1; then
     pi-mcp-adapter init || true
   fi
@@ -802,10 +907,13 @@ if [[ "$DRY_RUN" == true ]]; then
   print_cmd node "$PLATFORM_ROOT/scripts/personal-pi-config.mjs" repair
 else
   node "$PLATFORM_ROOT/scripts/personal-pi-config.mjs" repair || echo "WARN: could not check the personal Pi configuration; run: node \"$PLATFORM_ROOT/scripts/personal-pi-config.mjs\" check" >&2
+  node "$PLATFORM_ROOT/scripts/personal-pi-config.mjs" repair --agent-dir "$PIAGENT_HOME" >/dev/null || true
 fi
 
 echo
-echo "Installed packages:"
+echo "Open Piagent with: piagent   (your own pi in $PERSONAL_PI_DIR stays stock)"
+echo
+echo "Installed packages in $PIAGENT_HOME:"
 if [[ "$DRY_RUN" == true ]]; then
   print_cmd pi list
 else
@@ -814,8 +922,8 @@ fi
 
 echo
 echo "Next:"
-echo "  pi"
-echo "  /login"
+echo "  piagent         # Piagent in this terminal; plain \`pi\` stays your own"
+echo "  /login          # unless the login of your pi was copied"
 echo "  /model          # or Ctrl+L: select provider/model from Pi selector"
 echo "  /scoped-models  # optional: edit Ctrl+P model cycle scope"
 if [[ "$WITH_MCP" == true ]]; then

package/scripts/model-scope-prune.mjs

@@ -10,6 +10,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
+import { piagentAgentDir } from "../packages/piagent-core/extensions/agent-home.js";
 
 // The Pi install `pi` runs from.
 export function piPackageRoot(environment = process.env) {
@@ -55,7 +56,7 @@ export function pruneSettings(settingsPath, stale) {
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)) {
   const args = process.argv.slice(2), at = args.indexOf("--settings");
-  const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(process.env.HOME ?? "", ".pi", "agent");
+  const agentDir = piagentAgentDir(process.env, process.env.HOME ?? "");
   const settingsPath = at >= 0 && args[at + 1] ? path.resolve(args[at + 1]) : path.join(agentDir, "settings.json");
   const json = args.includes("--json"), fix = args.includes("--fix");
   const out = (value, text) => process.stdout.write(json ? `${JSON.stringify(value)}\n` : `${text}\n`);

package/scripts/personal-pi-config.mjs

@@ -120,7 +120,8 @@ const invoked = process.argv[1] && real(process.argv[1]) === real(fileURLToPath(
 if (invoked) {
   const args = process.argv.slice(2), command = args[0];
   const at = args.indexOf("--agent-dir");
-  const agentDir = at >= 0 ? path.resolve(args[at + 1]) : (process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"));
+  // The member's personal pi, whatever home Piagent itself runs from.
+  const agentDir = at >= 0 ? path.resolve(args[at + 1]) : path.join(os.homedir(), ".pi", "agent");
   if (!["check", "repair"].includes(command)) { console.error("Usage: personal-pi-config.mjs check|repair [--agent-dir <dir>] [--json]"); process.exit(2); }
   const result = command === "repair" ? repair(agentDir) : inspect(agentDir);
   if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));

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"