@piagent/platform 1.4.0 → 1.5.1

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

package/scripts/traffic-snapshot.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// Archives GitHub repository traffic before GitHub discards it.
+//
+// The traffic API only serves a rolling 14-day window. Anything older is gone
+// for good -- there is no endpoint that returns it and no way to reconstruct
+// it. So the counts are merged into CSV files that keep growing, and a run that
+// happens at least every 14 days loses nothing.
+//
+// Merge rule: a row is keyed by its day and the newest fetch wins. Today's
+// bucket is still filling while the run happens, so it is always partial; the
+// next run overwrites it with the settled value. Once a day leaves the window
+// it stops being returned at all, and the stored row is final.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EXIT_USAGE = 2;
+const EXIT_FORBIDDEN = 3;
+
+const SERIES = [
+  { endpoint: "clones", file: "clones.csv", columns: ["date", "count", "uniques"] },
+  { endpoint: "views", file: "views.csv", columns: ["date", "count", "uniques"] }
+];
+// Referrers and paths are a 14-day rollup, not a daily series: the API gives no
+// per-day breakdown, so a row is only meaningful next to the day it was read.
+const ROLLUPS = [
+  { endpoint: "popular/referrers", file: "referrers.csv", key: "referrer", columns: ["snapshot_date", "referrer", "count", "uniques"] },
+  { endpoint: "popular/paths", file: "paths.csv", key: "path", columns: ["snapshot_date", "path", "title", "count", "uniques"] }
+];
+
+function fail(message, code = EXIT_USAGE) {
+  console.error(`FAIL: ${message}`);
+  process.exit(code);
+}
+
+export function parseArguments(argv) {
+  const options = { repository: "", out: "traffic", dryRun: false, today: "" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    switch (argument) {
+      case "--repository": case "--repo": {
+        options.repository = argv[index += 1] ?? "";
+        if (!/^[^/\s]+\/[^/\s]+$/.test(options.repository)) fail("--repository needs owner/name");
+        break;
+      }
+      case "--out": {
+        options.out = argv[index += 1] ?? "";
+        if (!options.out) fail("--out needs a directory");
+        break;
+      }
+      // The archive is written from a snapshot date, and a test cannot wait a
+      // day to prove the merge. Injecting it keeps the assertions exact.
+      case "--today": {
+        options.today = argv[index += 1] ?? "";
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(options.today)) fail("--today needs YYYY-MM-DD");
+        break;
+      }
+      case "--dry-run": options.dryRun = true; break;
+      case "-h": case "--help": options.help = true; break;
+      default: fail(`unknown argument: ${argument}`);
+    }
+  }
+  return options;
+}
+
+export function csvEscape(value) {
+  const text = String(value ?? "");
+  return /[",\n\r]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function parseCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quoted) {
+      if (character === '"' && text[index + 1] === '"') { field += '"'; index += 1; }
+      else if (character === '"') quoted = false;
+      else field += character;
+      continue;
+    }
+    if (character === '"') quoted = true;
+    else if (character === ",") { row.push(field); field = ""; }
+    else if (character === "\n") { row.push(field); rows.push(row); row = []; field = ""; }
+    else if (character !== "\r") field += character;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((entry) => entry.some((cell) => cell !== ""));
+}
+
+function readTable(file, columns) {
+  if (!fs.existsSync(file)) return [];
+  const rows = parseCsv(fs.readFileSync(file, "utf8"));
+  const header = rows.shift();
+  if (!header || header.join(",") !== columns.join(",")) {
+    fail(`${file} has header [${header?.join(", ") ?? "none"}], expected [${columns.join(", ")}]`);
+  }
+  return rows.map((row) => Object.fromEntries(columns.map((column, index) => [column, row[index] ?? ""])));
+}
+
+function writeTable(file, columns, rows) {
+  const lines = [columns.join(",")];
+  for (const row of rows) lines.push(columns.map((column) => csvEscape(row[column])).join(","));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${lines.join("\n")}\n`);
+}
+
+/**
+ * Existing rows plus fetched rows, keyed by `key`. The fetched value wins,
+ * because it is the newer reading of the same day. Rows outside the API window
+ * are untouched -- that is the whole point of the archive.
+ */
+export function mergeByKey(existing, fetched, key) {
+  const merged = new Map(existing.map((row) => [row[key], row]));
+  for (const row of fetched) merged.set(row[key], row);
+  return [...merged.values()].sort((a, b) => String(a[key]).localeCompare(String(b[key])));
+}
+
+/** Rollup rows for one snapshot date, replacing any earlier run on that date. */
+export function mergeRollup(existing, fetched, snapshotDate) {
+  const kept = existing.filter((row) => row.snapshot_date !== snapshotDate);
+  return [...kept, ...fetched].sort((a, b) =>
+    String(a.snapshot_date).localeCompare(String(b.snapshot_date))
+    || Number(b.count) - Number(a.count));
+}
+
+async function fetchTraffic(repository, endpoint, token) {
+  const url = `https://api.github.com/repos/${repository}/traffic/${endpoint}`;
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "user-agent": "piagent-traffic-snapshot",
+      "x-github-api-version": "2022-11-28"
+    }
+  });
+  if (response.status === 403 || response.status === 404) {
+    // The distinction matters: this is the one failure an operator cannot debug
+    // from the status code, because the traffic API answers 403 for a token
+    // that is valid but lacks push access -- which the default workflow token
+    // may or may not have, depending on repository settings.
+    fail(`the token cannot read ${endpoint} for ${repository} (HTTP ${response.status}).\n`
+      + "  Repository traffic needs push access. If this ran in GitHub Actions with the\n"
+      + "  default GITHUB_TOKEN, create a fine-grained personal access token with the\n"
+      + "  'Administration: read' permission on this repository, store it as the\n"
+      + "  TRAFFIC_TOKEN secret, and re-run. Nothing was written.", EXIT_FORBIDDEN);
+  }
+  if (!response.ok) fail(`GET ${url} returned HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function snapshot(options, token, fetcher = fetchTraffic) {
+  const today = options.today || new Date().toISOString().slice(0, 10);
+  const summary = { repository: options.repository, snapshotDate: today, files: {} };
+
+  // Read every existing file before fetching anything. A corrupt archive is a
+  // reason to stop, and stopping before the network call keeps the failure
+  // about the file rather than about whatever the API happened to answer.
+  const existing = new Map();
+  for (const target of [...SERIES, ...ROLLUPS]) {
+    existing.set(target.file, readTable(path.join(options.out, target.file), target.columns));
+  }
+
+  for (const series of SERIES) {
+    const payload = await fetcher(options.repository, series.endpoint, token);
+    const fetched = (payload[series.endpoint] ?? []).map((entry) => ({
+      date: String(entry.timestamp ?? "").slice(0, 10),
+      count: String(entry.count ?? 0),
+      uniques: String(entry.uniques ?? 0)
+    })).filter((row) => row.date);
+    const file = path.join(options.out, series.file);
+    const merged = mergeByKey(existing.get(series.file), fetched, "date");
+    if (!options.dryRun) writeTable(file, series.columns, merged);
+    summary.files[series.file] = { fetchedDays: fetched.length, totalDays: merged.length };
+  }
+
+  for (const rollup of ROLLUPS) {
+    const payload = await fetcher(options.repository, rollup.endpoint, token);
+    const fetched = (Array.isArray(payload) ? payload : []).map((entry) => ({
+      snapshot_date: today,
+      [rollup.key]: String(entry[rollup.key] ?? entry.referrer ?? entry.path ?? ""),
+      title: String(entry.title ?? ""),
+      count: String(entry.count ?? 0),
+      uniques: String(entry.uniques ?? 0)
+    }));
+    const file = path.join(options.out, rollup.file);
+    const merged = mergeRollup(existing.get(rollup.file), fetched, today);
+    if (!options.dryRun) writeTable(file, rollup.columns, merged);
+    summary.files[rollup.file] = { fetchedRows: fetched.length, totalRows: merged.length };
+  }
+
+  return summary;
+}
+
+const invokedDirectly = process.argv[1]
+  && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+
+if (invokedDirectly) {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) {
+    console.log(`Usage:
+  node scripts/traffic-snapshot.mjs --repository <owner/name> [--out <dir>] [--dry-run]
+
+Archives GitHub traffic (clones, views, referrers, paths) into growing CSV files.
+The API only keeps 14 days, so run this at least fortnightly or the gap is
+permanent. Reads the token from TRAFFIC_TOKEN, else GITHUB_TOKEN.`);
+    process.exit(0);
+  }
+  if (!options.repository) fail("--repository is required");
+  const token = process.env.TRAFFIC_TOKEN || process.env.GITHUB_TOKEN;
+  if (!token) fail("set TRAFFIC_TOKEN or GITHUB_TOKEN");
+  const summary = await snapshot(options, token);
+  console.log(JSON.stringify(summary, null, 2));
+}

package/scripts/typescript-loader.mjs

@@ -18,11 +18,27 @@ export const PINNED_EXTERNAL_TRANSFORM = Object.freeze({
 async function pinnedTransformRoot(url) {
   const configured = process.env.PIAGENT_PINNED_TS_TRANSFORM_ROOT;
   if (!configured || process.versions.node !== PINNED_EXTERNAL_TRANSFORM.nodeVersion) return false;
-  const root = await fs.realpath(configured), target = await fs.realpath(fileURLToPath(url));
+  // This asks one question: is the file being loaded inside the pinned adapter?
+  // A configured root that is absent, unreadable or not that adapter answers
+  // "no". It used to throw instead, and the throw escaped `load` on the first
+  // `.ts` file of any kind -- so a machine without pi-mcp-adapter installed
+  // could not start the gateway at all, for a reason that had nothing to do
+  // with the file it died on. Answering "no" falls back to `strip`, which is
+  // the stricter of the two modes: this can only refuse a transform, never
+  // grant one.
+  let root;
+  let metadata;
+  try {
+    root = await fs.realpath(configured);
+    metadata = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+  } catch {
+    return false;
+  }
+  if (metadata?.name !== PINNED_EXTERNAL_TRANSFORM.packageName
+    || metadata?.version !== PINNED_EXTERNAL_TRANSFORM.packageVersion) return false;
+  const target = await fs.realpath(fileURLToPath(url));
   const relative = path.relative(root, target);
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return false;
-  const metadata = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
-  return metadata.name === PINNED_EXTERNAL_TRANSFORM.packageName && metadata.version === PINNED_EXTERNAL_TRANSFORM.packageVersion;
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
 }
 
 export async function load(url, context, nextLoad) {