@piagent/platform 1.4.0 → 1.4.1

package/scripts/install-global.sh

@@ -4,7 +4,32 @@ set -euo pipefail
 usage() {
   cat <<'USAGE'
 Usage:
-  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>|--no-model-scope]
+  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--subagents-model-scope <scope>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>|--no-model-scope] [--default-model <model>] [-h|--help]
+
+Options:
+  --channel <stable|dev|local>    Package channel; --stable/--dev/--local are shorthands.
+  --version, --tag <tag>          Pin a release tag (pair with --resolve-tag for a SHA).
+  --resolve-tag                   Resolve the tag to a commit SHA before installing.
+  --package-source <source>       Explicit package source; overrides the channel.
+  --dry-run                       Print the planned steps without changing user config.
+  --with-mcp | --no-mcp           Install the MCP adapter (default: install).
+  --mcp-preset <preset>           MCP server set (default: core).
+  --with-subagents | --no-subagents
+                                  Install pi-subagents (default: only if already present).
+  --subagents-preset <minimal|safe|async|parallel>
+                                  Subagent runtime preset (default: safe).
+  --subagents-model-scope <none|piagent|codex|claude>
+                                  Model family the subagents run on (default: none).
+  --with-web-access | --no-web-access
+                                  Install pi-web-access for the researcher subagent (default: install).
+  --with-herdr                    Also configure Herdr integration.
+  --model-scope <full|codex|claude>
+                                  Model families to enable in Pi (default: full).
+  --no-model-scope                Leave the user's enabledModels untouched.
+  --default-model <provider/model[:thinking]>
+                                  Default model written to Pi settings
+                                  (default: openai-codex/gpt-5.5:high).
+  -h, --help                      Print this help and exit.
 
 Purpose:
   Install the piagent Pi package into the current user's global Pi settings.
@@ -74,6 +99,7 @@ RESOLVE_TAG=false
 RESOLVED_PACKAGE_TAG=""
 RESOLVED_PACKAGE_COMMIT=""
 CLI_PACKAGE_SELECTOR=""
+LOCAL_HELPER_PREFIX="${PIAGENT_LOCAL_HELPER_PREFIX:-}"
 PI_MCP_ADAPTER_SOURCE="npm:pi-mcp-adapter@2.15.0"
 PI_SUBAGENTS_SOURCE="npm:pi-subagents@0.38.0"
 PI_WEB_ACCESS_SOURCE="npm:pi-web-access@0.17.0"
@@ -181,6 +207,61 @@ run_cmd() {
   fi
 }
 
+active_piagent_helper_prefix() {
+  if [[ -n "$LOCAL_HELPER_PREFIX" ]]; then
+    printf '%s\n' "$LOCAL_HELPER_PREFIX"
+    return 0
+  fi
+
+  local helper_command
+  helper_command="$(command -v piagent 2>/dev/null || true)"
+  [[ -n "$helper_command" ]] || return 1
+
+  node --input-type=module - "$helper_command" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+try {
+  const command = path.resolve(process.argv[2]);
+  if (path.basename(path.dirname(command)) === "bin") {
+    process.stdout.write(`${path.dirname(path.dirname(command))}\n`);
+    process.exit(0);
+  }
+  const target = fs.realpathSync(command);
+  const marker = `${path.sep}lib${path.sep}node_modules${path.sep}@piagent${path.sep}platform${path.sep}`;
+  const index = target.indexOf(marker);
+  if (index <= 0) process.exit(1);
+  process.stdout.write(`${target.slice(0, index)}\n`);
+} catch {
+  process.exit(1);
+}
+NODE
+}
+
+sync_local_helper() {
+  [[ "$RESOLVED_CHANNEL_LABEL" == "local" ]] || return 0
+
+  if ! command -v npm >/dev/null 2>&1; then
+    echo "FAIL: npm is required to synchronize the local Piagent helper and Gateway runtime." >&2
+    exit 1
+  fi
+
+  local prefix="" used_fallback=false
+  prefix="$(active_piagent_helper_prefix 2>/dev/null || true)"
+  if [[ -z "$prefix" ]]; then
+    prefix="${HOME}/.pi/npm-global"
+    used_fallback=true
+  fi
+
+  echo "Synchronizing local terminal helper and Gateway runtime:"
+  run_cmd npm install -g --ignore-scripts --prefix "$prefix" "$PLATFORM_ROOT"
+
+  if [[ "$used_fallback" == true ]]; then
+    echo "NOTE: no existing Piagent helper was found; the local helper was installed under $prefix." >&2
+    echo "NOTE: add $prefix/bin to PATH if piagent is not found after this run." >&2
+  fi
+}
+
 resolve_user_package_path() {
   local source="$1"
   local pi_agent_dir="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
@@ -285,10 +366,29 @@ verify_npm_integrity() {
     echo "FAIL: npm is required to verify package integrity for $package_spec." >&2
     exit 1
   fi
-  local actual
-  actual="$(npm view "$package_spec" dist.integrity 2>/dev/null | tr -d '\r\n')"
+  # The status is captured rather than left to `set -e`. Declaring `local actual`
+  # and assigning on the next line makes the command substitution's own status the
+  # status of the assignment, so under `pipefail` an unreachable registry -- no
+  # network, a proxy, a private registry, an npm outage -- killed the script on
+  # this line. The `FAIL:` below was never reached and npm's stderr was already
+  # discarded, so the run ended with an empty screen and exit 1, after `pi install`
+  # had already succeeded. The operator was left half-installed with no reason
+  # given. (Writing `local actual="$(...)"` also avoids the exit, but by hiding the
+  # failure inside the empty-value branch, which then reports a digest mismatch --
+  # a security message for what is usually a network problem.)
+  local actual="" status=0
+  actual="$(npm view "$package_spec" dist.integrity 2>/dev/null | tr -d '\r\n')" || status=$?
+  if [[ "$status" -ne 0 ]]; then
+    echo "FAIL: could not reach the npm registry to verify $package_spec (npm exited $status)." >&2
+    echo "      Nothing further was installed. Check network, proxy, or registry auth," >&2
+    echo "      then re-run. To see npm's own message: npm view $package_spec dist.integrity" >&2
+    exit 1
+  fi
   if [[ -z "$actual" || "$actual" != "$expected" ]]; then
     echo "FAIL: registry integrity does not match the approved digest for $package_spec." >&2
+    echo "      approved: $expected" >&2
+    echo "      registry: ${actual:-<empty>}" >&2
+    echo "      Do not proceed. The published package differs from the reviewed release." >&2
     exit 1
   fi
 }
@@ -609,6 +709,7 @@ if [[ -n "$RESOLVED_PACKAGE_COMMIT" ]]; then
   echo "  resolvedCommit: $RESOLVED_PACKAGE_COMMIT"
 fi
 echo "  source: $PACKAGE_SOURCE"
+sync_local_helper
 echo "Removing previous Pi Agent Platform package registrations:"
 remove_existing_piagent_platform_sources
 run_cmd pi install "$PACKAGE_SOURCE"

package/scripts/mcp-manage.mjs

@@ -536,7 +536,7 @@ function commandPreset(args) {
       presets: CATALOG_PRESETS,
       servers: Object.fromEntries(Object.entries(CATALOG_SERVERS).map(([name, server]) => [
         name,
-        { description: server.description, requires: CATALOG_PREREQUISITES[name] ?? [] }
+        { description: server.description, maturity: server.maturity ?? "stable", requires: CATALOG_PREREQUISITES[name] ?? [] }
       ]))
     }, null, 2)}\n`);
     return 0;
@@ -563,7 +563,9 @@ function commandPreset(args) {
   const added = [];
   const kept = [];
   const replaced = [];
-  for (const server of resolvePreset(presetName)) {
+  const resolvedPreset = resolvePreset(presetName);
+  const experimental = resolvedPreset.filter((server) => server.maturity === "experimental").map((server) => server.name);
+  for (const server of resolvedPreset) {
     if (Object.hasOwn(config.mcpServers, server.name)) {
       if (!replace) {
         kept.push(server.name);
@@ -585,6 +587,7 @@ function commandPreset(args) {
     added,
     kept,
     replaced,
+    experimental,
     serverCount: Object.keys(config.mcpServers).length
   };
 
@@ -594,11 +597,21 @@ function commandPreset(args) {
     return 0;
   }
 
+  // Warn before the write. Naming a Google preset is explicit, but it is not
+  // evidence that the operator knows the endpoint is pre-GA or that Pi OAuth
+  // has not passed a credentialed release gate yet.
+  if (experimental.length > 0) {
+    process.stderr.write(
+      `\nEXPERIMENTAL: ${experimental.join(", ")} use Google Workspace Developer Preview endpoints. `
+      + "They are not part of the default presets and have no Pi OAuth end-to-end release proof yet.\n"
+    );
+  }
+
   writeMcpConfig(file, config);
   process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 
-  // stdout stays machine-readable; the operator note goes to stderr.
-  const lines = resolvePreset(presetName).flatMap((server) => server.requires.map((item) => `  ${server.name}: ${item}`));
+  // stdout stays machine-readable; operator notes go to stderr.
+  const lines = resolvedPreset.flatMap((server) => server.requires.map((item) => `  ${server.name}: ${item}`));
   if (lines.length > 0) {
     process.stderr.write("\nServer definitions are written. Each still needs this before it can connect:\n");
     for (const line of lines) process.stderr.write(`${line}\n`);

package/scripts/pi-session-stats.sh

@@ -108,8 +108,13 @@ RPC_OUTPUT="$(
     | pi -ne --mode rpc --session "$SESSION_FILE" --offline --approve
 )"
 
-node --input-type=module - "$RPC_OUTPUT" <<'NODE'
+node --input-type=module - "$RPC_OUTPUT" "$SCRIPT_DIR/../packages/piagent-core/runtime/session/token-economics.js" <<'NODE'
+import { pathToFileURL } from "node:url";
+
 const input = process.argv[2] ?? "";
+// The token arithmetic lives in a module both this command and its test can
+// read, so the terminal cannot drift from the definition the benchmark uses.
+const { sessionTokenEconomics, formatTokenEconomics } = await import(pathToFileURL(process.argv[3]).href);
 
   const line = input
     .split(/\n+/)
@@ -126,6 +131,7 @@ const input = process.argv[2] ?? "";
   const data = response.data;
   const tokens = data.tokens ?? {};
   const context = data.contextUsage ?? {};
+  const economics = sessionTokenEconomics(tokens);
   const number = (value) => value === null || value === undefined ? "unknown" : Math.round(Number(value)).toLocaleString("en-US");
   const money = (value) => value === null || value === undefined ? "unknown" : `$${Number(value).toFixed(6)}`;
   const percent = (value) => value === null || value === undefined ? "unknown" : `${Number(value).toFixed(1)}%`;
@@ -144,7 +150,8 @@ const input = process.argv[2] ?? "";
       output: tokens.output ?? null,
       cacheRead: tokens.cacheRead ?? null,
       cacheWrite: tokens.cacheWrite ?? null,
-      total: tokens.total ?? null
+      total: tokens.total ?? null,
+      ...economics
     },
     cost: data.cost ?? null,
     contextUsage: context.tokens === undefined ? null : {
@@ -154,6 +161,7 @@ const input = process.argv[2] ?? "";
     },
     summary: {
       tokens: `${number(tokens.total)} total (${number(tokens.input)} input, ${number(tokens.output)} output, ${number(tokens.cacheRead)} cache read, ${number(tokens.cacheWrite)} cache write)`,
+      ...formatTokenEconomics(economics, number, percent),
       cost: money(data.cost),
       context: context.tokens === undefined ? "unknown" : `${number(context.tokens)} / ${number(context.contextWindow)} (${percent(context.percent)})`
     }

package/scripts/piagent-cli.mjs

@@ -24,6 +24,7 @@ const scriptByCommand = {
   "piagent-import-instructions": "scripts/import-agent-instructions.mjs",
   "piagent-auto": "scripts/pi-auto.sh",
   "piagent-context": "scripts/context-engine.mjs",
+  "piagent-explain": "scripts/explain-command.mjs",
   "piagent-webui": "scripts/piagent-webui-launcher.mjs",
   "piagent-dashboard": "scripts/piagent-dashboard.mjs"
 };
@@ -38,8 +39,20 @@ if (invokedAs === "piagent") {
   if (subcommand === "dashboard") {
     script = "scripts/piagent-dashboard.mjs";
     forwardedArgs = forwardedArgs.slice(1);
+  } else if (subcommand === "explain") {
+    script = "scripts/explain-command.mjs";
+    forwardedArgs = forwardedArgs.slice(1);
   } else if ([undefined, "help", "--help", "-h"].includes(subcommand)) {
-    console.log("Usage: piagent dashboard [open|status|stop|restart|doctor] [--no-open] [--json]");
+    // 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("");
+    console.log("Commands:");
+    console.log("  dashboard   Open and manage the local session hub");
+    console.log("  explain     Say why the guard would allow or block a shell command");
+    console.log("");
+    console.log("Run `piagent <command> --help` for that command's options.");
     process.exit(0);
   }
 }

package/scripts/piagent-dashboard.mjs

@@ -22,6 +22,8 @@ const json = args.includes("--json");
 const repair = args.includes("--repair");
 const agentDirIndex = args.indexOf("--agent-dir");
 const agentDir = agentDirIndex >= 0 ? args[agentDirIndex + 1] : undefined;
+const GATEWAY_ERROR_LOG = "gateway-stderr.log";
+const GATEWAY_ERROR_MAX_BYTES = 4_000;
 
 function output(value) {
   process.stdout.write(`${json ? JSON.stringify(value) : value}\n`);
@@ -68,6 +70,42 @@ function removeOwnedSocket(target) {
   } catch { return false; }
 }
 
+function gatewayErrorLog(state) {
+  return path.join(state.root, GATEWAY_ERROR_LOG);
+}
+
+function writeGatewayErrorLog(state, message = "") {
+  const target = gatewayErrorLog(state);
+  const descriptor = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC
+    | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+      throw new Error("gateway-error-log-invalid");
+    }
+    fs.fchmodSync(descriptor, 0o600);
+    if (message) fs.writeFileSync(descriptor, message.slice(-GATEWAY_ERROR_MAX_BYTES));
+  } finally { fs.closeSync(descriptor); }
+}
+
+function readGatewayErrorLog(state) {
+  const target = gatewayErrorLog(state);
+  try {
+    const before = fs.lstatSync(target);
+    if (!before.isFile() || before.isSymbolicLink()
+      || typeof process.getuid === "function" && before.uid !== process.getuid()) return "";
+    const descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const stat = fs.fstatSync(descriptor);
+      if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return "";
+      const length = Math.min(stat.size, GATEWAY_ERROR_MAX_BYTES);
+      const body = Buffer.alloc(length);
+      fs.readSync(descriptor, body, 0, length, Math.max(0, stat.size - length));
+      return body.toString("utf8");
+    } finally { fs.closeSync(descriptor); }
+  } catch { return ""; }
+}
+
 async function control(action, timeoutMs = 1_500) {
   const state = gatewayProfileState(agentDir);
   return await requestGatewayControl(state.controlSocket, { action }, timeoutMs);
@@ -88,6 +126,8 @@ async function ensureStarted() {
   const existing = await currentLaunchUrl();
   if (existing) return existing;
   const effectiveAgentDir = path.resolve(agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"));
+  const state = gatewayProfileState(effectiveAgentDir);
+  writeGatewayErrorLog(state);
   const child = spawn(process.execPath, [
     "--disable-warning=ExperimentalWarning",
     "--import", path.join(packageRoot, "scripts", "register-typescript-loader.mjs"),
@@ -97,14 +137,23 @@ async function ensureStarted() {
   ], { cwd: process.cwd(), env: { ...process.env,
     PIAGENT_PINNED_TS_TRANSFORM_ROOT: path.join(effectiveAgentDir, "npm", "node_modules", "pi-mcp-adapter") },
     detached: true, stdio: "ignore" });
+  let exit = null;
+  child.on("exit", (code, signal) => { exit = signal ? `signal ${signal}` : `exit code ${code}`; });
   child.unref();
   const deadline = Date.now() + 12_000;
   while (Date.now() < deadline) {
     const url = await currentLaunchUrl();
     if (url) return url;
+    // A child that has already exited is never going to publish a URL, so
+    // waiting out the rest of the deadline only delays the report.
+    if (exit !== null) break;
     await new Promise((resolve) => setTimeout(resolve, 80));
   }
-  throw new Error("gateway-start-timeout");
+  const detail = [exit && `The gateway process ended with ${exit}.`, readGatewayErrorLog(state).trim()]
+    .filter(Boolean).join("\n");
+  throw new Error(detail
+    ? `gateway-start-failed\n${detail}`
+    : "gateway-start-timeout\nThe gateway did not publish a URL within 12s and wrote nothing to stderr.");
 }
 
 async function serve() {
@@ -203,6 +252,10 @@ async function main() {
 }
 
 main().catch((error) => {
-  process.stderr.write(`Piagent dashboard failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  const message = `Piagent dashboard failed: ${error instanceof Error ? error.message : String(error)}\n`;
+  if (command === "serve") {
+    try { writeGatewayErrorLog(gatewayProfileState(agentDir), message); } catch { /* stderr still reports the failure. */ }
+  }
+  process.stderr.write(message);
   process.exitCode = 1;
 });

package/scripts/setup.sh

@@ -22,7 +22,7 @@ Options:
   --project-only, --no-global    Only initialize project, skip global install
   --no-project                   Skip project initialization
   --with-mcp / --no-mcp          Install/skip Pi MCP adapter during global install (default: install)
-  --mcp-preset <minimal|core|popular|all|docs|browser|github|design|design-local|web>
+  --mcp-preset <minimal|core|popular|all|docs|browser|github|design|design-local|web|documents|google|google-mail|google-all>
                                   Configure shared global MCP baseline when --with-mcp is enabled (default: core)
   --with-subagents / --no-subagents
                                   Install/skip pi-subagents during global install (default: install)
@@ -244,15 +244,11 @@ if [[ "$WITH_MCP" == false && "$MCP_PRESET_EXPLICIT" == true ]]; then
   exit 2
 fi
 
-resolve_package_source() {
-  if [[ -n "$PACKAGE_SOURCE" ]]; then
-    printf '%s\n' "$PACKAGE_SOURCE"
-    return
-  fi
-
-  if [[ "$DO_PROJECT" == true && -n "$PROJECT_PATH" && -f "$PROJECT_PATH/.pi/settings.json" ]]; then
-    local existing_source
-    existing_source="$(node --input-type=module - "$PROJECT_PATH/.pi/settings.json" <<'NODE'
+# The pin a project has committed, or empty. It is authority over that project
+# and nothing else -- one project may not decide what the machine runs.
+project_pinned_source() {
+  [[ "$DO_PROJECT" == true && -n "$PROJECT_PATH" && -f "$PROJECT_PATH/.pi/settings.json" ]] || return 0
+  node --input-type=module - "$PROJECT_PATH/.pi/settings.json" <<'NODE'
 import fs from "node:fs";
 const settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
 const source = Array.isArray(settings.packages)
@@ -260,30 +256,51 @@ const source = Array.isArray(settings.packages)
   : undefined;
 if (source) process.stdout.write(source);
 NODE
-)"
-    if [[ -n "$existing_source" ]]; then
-      printf '%s\n' "$existing_source"
-      return
-    fi
-  fi
+}
 
-  # Running from an installed package rather than a checkout. The name and
-  # version on disk are exactly what a teammate resolves from the registry, so
-  # they are a portable source; the install path is not, and project settings
-  # are meant to be committed.
-  if [[ "$PLATFORM_ROOT" == */node_modules/* ]]; then
-    local installed_name installed_version
-    installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
-    installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
-    if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
-      printf 'npm:%s@%s\n' "$installed_name" "$installed_version"
-      return
-    fi
+# Running from an installed package rather than a checkout. The name and version
+# on disk are exactly what a teammate resolves from the registry, so they are a
+# portable source; the install path is not, and project settings are meant to be
+# committed.
+running_helper_source() {
+  [[ "$PLATFORM_ROOT" == */node_modules/* ]] || return 0
+  local installed_name installed_version
+  installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
+  installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
+  if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+    printf 'npm:%s@%s' "$installed_name" "$installed_version"
   fi
+}
 
+local_path_source() {
   echo "WARN: No exact package source provided." >&2
   echo "WARN: using local platform path; do not commit project .pi/settings.json with this value for team rollout." >&2
-  printf '%s\n' "$PLATFORM_ROOT"
+  printf '%s' "$PLATFORM_ROOT"
+}
+
+# One resolved value used to serve both consumers, and the two do not want the
+# same answer. A project pin is what that project's team agreed to run; the
+# global install is what every project on this machine gets. Reading the pin
+# first meant the documented two-command install silently downgraded the
+# machine-wide package to whatever one project happened to pin -- including
+# projects the operator only meant to open once.
+resolve_global_package_source() {
+  if [[ -n "$PACKAGE_SOURCE" ]]; then printf '%s\n' "$PACKAGE_SOURCE"; return; fi
+  local helper
+  helper="$(running_helper_source)"
+  if [[ -n "$helper" ]]; then printf '%s\n' "$helper"; return; fi
+  printf '%s\n' "$(local_path_source)"
+}
+
+resolve_project_package_source() {
+  if [[ -n "$PACKAGE_SOURCE" ]]; then printf '%s\n' "$PACKAGE_SOURCE"; return; fi
+  local pinned
+  pinned="$(project_pinned_source)"
+  if [[ -n "$pinned" ]]; then printf '%s\n' "$pinned"; return; fi
+  local helper
+  helper="$(running_helper_source)"
+  if [[ -n "$helper" ]]; then printf '%s\n' "$helper"; return; fi
+  printf '%s\n' "$(local_path_source)"
 }
 
 print_cmd() {
@@ -385,22 +402,41 @@ if [[ "$DO_PROJECT" == true ]]; then
   PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
 fi
 
-PACKAGE_SOURCE="$(resolve_package_source)"
+GLOBAL_PACKAGE_SOURCE="$(resolve_global_package_source)"
+PROJECT_PACKAGE_SOURCE="$(resolve_project_package_source)"
 
 echo "Pi Agent Platform setup"
 echo "  platform: $PLATFORM_ROOT"
-echo "  packageSource: $PACKAGE_SOURCE"
+if [[ "$DO_GLOBAL" == true ]]; then
+  echo "  globalPackageSource: $GLOBAL_PACKAGE_SOURCE"
+fi
+if [[ "$DO_PROJECT" == true ]]; then
+  echo "  projectPackageSource: $PROJECT_PACKAGE_SOURCE"
+fi
 echo "  globalInstall: $DO_GLOBAL"
 echo "  projectInit: $DO_PROJECT"
 if [[ "$DO_PROJECT" == true ]]; then
   echo "  project: $PROJECT_PATH"
   echo "  profile: $PROFILE_INPUT"
 fi
+
+# The operator asked for both scopes and the project wants a different build
+# than the one about to be installed machine-wide. Neither choice is wrong, so
+# neither is overridden -- but a divergence they cannot see is how the old
+# silent downgrade went unnoticed.
+if [[ "$DO_GLOBAL" == true && "$DO_PROJECT" == true && "$GLOBAL_PACKAGE_SOURCE" != "$PROJECT_PACKAGE_SOURCE" ]]; then
+  echo
+  echo "NOTE: this project pins a different package source than the global install." >&2
+  echo "NOTE:   global:  $GLOBAL_PACKAGE_SOURCE" >&2
+  echo "NOTE:   project: $PROJECT_PACKAGE_SOURCE" >&2
+  echo "NOTE: the project keeps its pin and the machine keeps the running helper." >&2
+  echo "NOTE: pass --package-source <source> to make both the same." >&2
+fi
 echo
 
 if [[ "$DO_GLOBAL" == true ]]; then
   ensure_pi_cli
-  install_args=("$PLATFORM_ROOT/scripts/install-global.sh" "--package-source" "$PACKAGE_SOURCE")
+  install_args=("$PLATFORM_ROOT/scripts/install-global.sh" "--package-source" "$GLOBAL_PACKAGE_SOURCE")
   # The opt-out has to be passed explicitly. The installer defaults MCP on, so
   # saying nothing here would install it against the operator's choice.
   # Subagents also needs an explicit opt-out because the installer now preserves
@@ -432,7 +468,7 @@ if [[ "$DO_GLOBAL" == true ]]; then
 fi
 
 if [[ "$DO_PROJECT" == true ]]; then
-  init_args=("$PLATFORM_ROOT/scripts/init-project.sh" "$PROJECT_PATH" "--profile" "$PROFILE_INPUT" "--package-source" "$PACKAGE_SOURCE")
+  init_args=("$PLATFORM_ROOT/scripts/init-project.sh" "$PROJECT_PATH" "--profile" "$PROFILE_INPUT" "--package-source" "$PROJECT_PACKAGE_SOURCE")
   if [[ "$FORCE_PROFILE" == true ]]; then
     init_args+=("--force-profile")
   fi