@piagent/platform 1.3.1 → 1.4.1

package/scripts/piagent-dashboard.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { requestGatewayControl } from "../packages/piagent-webui/gateway/control-socket.ts";
+import { installedPiHostRoot } from "../packages/piagent-webui/gateway/pi-host.ts";
+import { gatewayProfileState, profileRef, readGatewayDescriptor, readOrCreateCatalogKey,
+  removeGatewayDescriptor } from "../packages/piagent-webui/gateway/profile-state.ts";
+import { startPiagentGateway } from "../packages/piagent-webui/gateway/gateway-service.ts";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const expectedPiVersion = packageJson.peerDependencies["@earendil-works/pi-coding-agent"];
+const args = process.argv.slice(2);
+const command = ["--help", "-h"].includes(args[0]) ? args.shift()
+  : args[0] && !args[0].startsWith("-") ? args.shift() : "open";
+const noOpen = args.includes("--no-open");
+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`);
+}
+
+function openBrowser(url) {
+  if (noOpen) return;
+  const opener = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  const result = spawnSync(opener[0], opener[1], { stdio: "ignore" });
+  if (result.status !== 0) process.stderr.write(`Dashboard is ready at ${url}\n`);
+}
+
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return !(error && typeof error === "object" && "code" in error && error.code === "ESRCH"); }
+}
+
+function ownerOnlyDirectory(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    return stat.isDirectory() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0
+      && (typeof process.getuid !== "function" || stat.uid === process.getuid());
+  } catch { return false; }
+}
+
+function removeOwnedRegularFile(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink()
+      || typeof process.getuid === "function" && stat.uid !== process.getuid()) return false;
+    fs.unlinkSync(target); return true;
+  } catch { return false; }
+}
+
+function removeOwnedSocket(target) {
+  if (process.platform === "win32") return false;
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isSocket() || stat.isSymbolicLink()
+      || typeof process.getuid === "function" && stat.uid !== process.getuid()) return false;
+    fs.unlinkSync(target); return true;
+  } 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);
+}
+
+async function currentLaunchUrl() {
+  try {
+    const response = await control("issue-launch-url");
+    if (response.ok && response.value && typeof response.value === "object"
+      && typeof response.value.launchUrl === "string") return response.value.launchUrl;
+  } catch {
+    // Gateway is not ready yet.
+  }
+  return null;
+}
+
+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"),
+    fileURLToPath(import.meta.url),
+    "serve",
+    ...(agentDir ? ["--agent-dir", agentDir] : [])
+  ], { 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));
+  }
+  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() {
+  const gateway = await startPiagentGateway({ packageRoot, expectedPiVersion, agentDir });
+  const shutdown = () => { void gateway.close(); };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  await gateway.wait();
+}
+
+async function main() {
+  if (command === "serve") return await serve();
+  if (["help", "--help", "-h"].includes(command)) {
+    output("Usage: piagent dashboard [open|status|stop|restart|doctor] [--no-open] [--json] [--repair]");
+    return;
+  }
+  if (command === "open" || command === "start") {
+    const launchUrl = await ensureStarted();
+    output(json ? { state: "running", launchUrl } : launchUrl);
+    openBrowser(launchUrl);
+    return;
+  }
+  if (command === "status") {
+    try {
+      const response = await control("health");
+      if (!response.ok) throw new Error(response.error);
+      output(json ? { state: "running", gateway: response.value } : "Piagent Gateway is running.");
+    } catch {
+      const descriptor = readGatewayDescriptor(gatewayProfileState(agentDir));
+      output(json ? { state: "stopped", staleDescriptor: Boolean(descriptor) } : "Piagent Gateway is stopped.");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (command === "stop") {
+    try {
+      const response = await control("stop");
+      if (!response.ok) throw new Error(response.error);
+      output(json ? { state: "stopping" } : "Piagent Gateway is stopping.");
+    } catch {
+      output(json ? { state: "stopped" } : "Piagent Gateway is already stopped.");
+    }
+    return;
+  }
+  if (command === "restart") {
+    try { await control("stop"); } catch { /* already stopped */ }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    const launchUrl = await ensureStarted();
+    output(json ? { state: "running", launchUrl } : launchUrl);
+    openBrowser(launchUrl);
+    return;
+  }
+  if (command === "doctor") {
+    const state = gatewayProfileState(agentDir);
+    const key = readOrCreateCatalogKey(state), descriptor = readGatewayDescriptor(state);
+    let actual = null;
+    try {
+      const hostRoot = installedPiHostRoot();
+      actual = JSON.parse(fs.readFileSync(path.join(hostRoot, "package.json"), "utf8")).version;
+    } catch { /* reported as a failed check below */ }
+    let health = null;
+    try {
+      const response = await control("health", 1_000);
+      health = response.ok ? "ready" : "unavailable";
+    } catch { health = "unavailable"; }
+    const staleDescriptor = Boolean(descriptor && !processAlive(descriptor.pid));
+    const invalidDescriptor = fs.existsSync(state.descriptorFile) && !descriptor;
+    const repairs = [];
+    if (repair && staleDescriptor && descriptor) {
+      removeGatewayDescriptor(state, descriptor.gatewayInstanceRef); repairs.push("stale-descriptor-removed");
+    } else if (repair && invalidDescriptor && removeOwnedRegularFile(state.descriptorFile)) repairs.push("invalid-descriptor-removed");
+    if (repair && health !== "ready" && removeOwnedSocket(state.controlSocket)) repairs.push("stale-control-socket-removed");
+    const checks = {
+      piHostVersion: actual === expectedPiVersion,
+      clientBuild: fs.existsSync(path.join(packageRoot, "packages", "piagent-webui", "dist", "client", "index.html")),
+      profileStateOwnerOnly: ownerOnlyDirectory(state.root),
+      descriptor: !invalidDescriptor && !staleDescriptor,
+      gatewayHealth: descriptor ? health === "ready" : true
+    };
+    const result = {
+      ok: Object.values(checks).every(Boolean),
+      expectedPiVersion,
+      actualPiVersion: actual,
+      profileRef: profileRef(state, key),
+      gateway: descriptor ? health === "ready" ? "ready" : staleDescriptor ? "stale" : "unavailable" : "not-registered",
+      checks,
+      repaired: repairs
+    };
+    output(json ? result : result.ok ? "Piagent Gateway doctor passed." : repair && repairs.length
+      ? "Piagent Gateway doctor repaired stale local state; run doctor again."
+      : "Piagent Gateway doctor found a version, build, ownership, or lifecycle mismatch.");
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  throw new Error(`unknown-dashboard-command:${command}`);
+}
+
+main().catch((error) => {
+  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/piagent-webui-launcher.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+function help() {
+  return [
+    "Usage: piagent-webui [--session <opaque-session-ref>] [--no-open]",
+    "",
+    "Opens a WebUI already owned by the current Pi process.",
+    "Start it first with /piagent-webui inside the Pi terminal.",
+    "This command never creates a second Pi runtime."
+  ].join("\n");
+}
+
+function parse(argv) {
+  let session = null, open = true;
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--help" || value === "-h") return { help: true, session, open };
+    if (value === "--no-open") { open = false; continue; }
+    if (value === "--session" && typeof argv[index + 1] === "string" && REF.test(argv[index + 1])) { session = argv[index += 1]; continue; }
+    throw new Error(`Unknown or invalid option: ${value}`);
+  }
+  return { help: false, session, open };
+}
+
+function launcherDirectory(start) {
+  let current = path.resolve(start);
+  while (true) {
+    const candidate = path.join(current, ".pi", "piagent-state", "webui-launcher");
+    try { if (fs.lstatSync(candidate).isDirectory()) return candidate; } catch { /* keep walking */ }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readDescriptor(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8_192 || process.platform !== "win32" && (stat.mode & 0o077) !== 0) {
+    throw new Error("WebUI launcher descriptor is unsafe");
+  }
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  const temporary = fs.realpathSync(os.tmpdir());
+  const socket = path.resolve(String(value.controlSocket ?? ""));
+  const canonicalSocket = fs.realpathSync(socket);
+  if (value.schemaVersion !== 1 || !REF.test(String(value.sessionRef ?? "")) || !REF.test(String(value.projectRef ?? ""))
+    || typeof value.controlToken !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value.controlToken)
+    || path.relative(temporary, canonicalSocket).startsWith("..") || path.isAbsolute(path.relative(temporary, canonicalSocket))) {
+    throw new Error("WebUI launcher descriptor is invalid");
+  }
+  return { ...value, controlSocket: socket };
+}
+
+function requestLaunch(descriptor) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(descriptor.controlSocket);
+    let bytes = Buffer.alloc(0), settled = false;
+    const fail = (error) => { if (!settled) { settled = true; socket.destroy(); reject(error); } };
+    socket.setTimeout(2_000, () => fail(new Error("WebUI sidecar did not respond")));
+    socket.once("error", () => fail(new Error("WebUI sidecar is not running; use /piagent-webui in Pi")));
+    socket.once("connect", () => socket.write(`${JSON.stringify({ action: "launch", token: descriptor.controlToken })}\n`));
+    socket.on("data", (chunk) => {
+      if (settled) return;
+      bytes = Buffer.concat([bytes, chunk]);
+      if (bytes.length > 8_192) { fail(new Error("WebUI sidecar response exceeded its limit")); return; }
+      const newline = bytes.indexOf(10);
+      if (newline < 0) return;
+      try {
+        const response = JSON.parse(bytes.subarray(0, newline).toString("utf8"));
+        if (!response.ok || typeof response.launchUrl !== "string" || !/^http:\/\/127\.0\.0\.1:\d+\/#bootstrap=/.test(response.launchUrl)) {
+          fail(new Error("WebUI sidecar rejected the launch request")); return;
+        }
+        settled = true; socket.end(); resolve(response.launchUrl);
+      } catch { fail(new Error("WebUI sidecar returned an invalid response")); }
+    });
+  });
+}
+
+function openUrl(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
+  if (!command) return false;
+  const child = spawn(command, [url], { detached: true, stdio: "ignore" });
+  child.unref(); return true;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let options;
+  try { options = parse(argv); }
+  catch (error) { process.stderr.write(`${error.message}\n${help()}\n`); return 2; }
+  if (options.help) { process.stdout.write(`${help()}\n`); return 0; }
+  const directory = launcherDirectory(process.cwd());
+  if (!directory) { process.stderr.write("No running Piagent WebUI was found. Run /piagent-webui inside the Pi terminal first.\n"); return 1; }
+  let descriptors;
+  try {
+    descriptors = fs.readdirSync(directory).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+      .map((name) => readDescriptor(path.join(directory, name)))
+      .filter((value) => !options.session || value.sessionRef === options.session);
+  } catch (error) { process.stderr.write(`${error instanceof Error ? error.message : "WebUI launcher state is unavailable"}\n`); return 1; }
+  if (descriptors.length !== 1) {
+    process.stderr.write(descriptors.length === 0
+      ? "No matching running WebUI session was found.\n"
+      : "More than one WebUI session is running; pass --session <opaque-session-ref>.\n");
+    return 1;
+  }
+  try {
+    const url = await requestLaunch(descriptors[0]);
+    if (!options.open || !openUrl(url)) process.stdout.write(`${url}\n`);
+    else process.stdout.write(`Opened Piagent WebUI for ${descriptors[0].sessionRef}.\n`);
+    return 0;
+  } catch (error) { process.stderr.write(`${error instanceof Error ? error.message : "WebUI could not be opened"}\n`); return 1; }
+}
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(new URL(import.meta.url))) process.exit(await main());
+
+export { help, main, parse, readDescriptor, requestLaunch };

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