@xpufx/paseo-top 0.4.4 → 0.4.5

package/package.json

@@ -2,16 +2,17 @@
   "name": "@xpufx/paseo-top",
   "private": false,
   "license": "MIT",
-  "version": "0.4.4",
-  "dependencies": {
-    "permission-audit": "*"
-  },
+  "version": "0.4.5",
   "scripts": {
     "stamp": "node -e \"import('./server/vendor/paseo-plugin-helper/version.ts').then(m => m.stampVersion({ targetFile: 'shared/version.ts' }))\"",
     "typecheck": "tsc --noEmit",
     "test": "npm run typecheck && vitest run --config client/vitest.config.ts"
   },
+  "dependencies": {
+    "@xpufx/paseo-plugin-ui": "^0.1.0"
+  },
   "devDependencies": {
+    "paseo-plugin-ui-testing": "*",
     "@getpaseo/plugin": "^0.9.0",
     "@tanstack/react-query": "^5.90.11",
     "@types/react": "^19.0.10",
@@ -26,7 +27,9 @@
   "files": [
     "paseo-plugin.json",
     "README.md",
+    "OVERVIEW.md",
     "LICENSE",
+    "screenshots",
     "index.client.tsx",
     "index.server.ts",
     "client",

package/paseo-plugin.json

@@ -1,4 +1,6 @@
 {
   "id": "top",
+  "name": "Top",
+  "description": "Live host system and workspace monitor for the Paseo composer trackbar",
   "requirements": { "paseo": ">=0.9.0" }
 }

package/server/resources.ts

@@ -29,6 +29,91 @@ import {
 } from "../shared/resources";
 import { PLUGIN_VERSION } from "../shared/version";
 
+// --- Velocity & Context Pressure helpers -------------------------------------
+
+/** Thresholds for context pressure levels. */
+const CONTEXT_NORMAL_UPPER = 60; // <60% → normal
+const CONTEXT_WARNING_UPPER = 75; // 60-74% → warning, >=75% → high
+
+/**
+ * Compute live generation velocity (tokens per second).
+ *
+ * Formula: (outputTokens + reasoningTokens) / (durationMs / 1000)
+ *
+ * Returns 0 for:
+ * - zero or missing duration (< 50 ms threshold to avoid skewed averages)
+ * - missing output tokens
+ * - interrupted/canceled turns (prevents skewed averages on partial generations)
+ */
+export function computeTokensPerSecond(
+  outputTokens: number | undefined,
+  durationMs: number | undefined,
+  outcomeKind: string,
+): number | undefined {
+  if (outputTokens == null || !Number.isFinite(outputTokens)) return undefined;
+  if (outputTokens <= 0) return 0;
+
+  const dur = durationMs ?? undefined;
+  if (dur == null || !Number.isFinite(dur) || dur < 50) return 0;
+
+  // Interrupted/canceled turns with partial data yield 0 TPS.
+  if (outcomeKind === "canceled" || outcomeKind === "failed") return 0;
+
+  const durationSec = dur / 1000;
+  const rate = outputTokens / durationSec;
+  if (!Number.isFinite(rate) || rate <= 0) return 0;
+  return Math.round(rate * 100) / 100; // round to 2dp
+}
+
+/** Context pressure level based on utilization percentage. */
+type ContextPressureLevel = "normal" | "warning" | "high";
+
+/**
+ * Classify context pressure into discrete levels:
+ * - "normal": utilization < 60%
+ * - "warning": 60–74%
+ * - "high": >= 75% (amnesia risk)
+ *
+ * Returns undefined when context window info is absent.
+ */
+export function classifyContextPressure(
+  contextUsedTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+): { level: ContextPressureLevel; pct: number } | undefined {
+  if (
+    contextUsedTokens == null ||
+    contextMaxTokens == null ||
+    contextMaxTokens <= 0
+  ) {
+    return undefined;
+  }
+
+  const pct = Math.min(100, Math.round((contextUsedTokens / contextMaxTokens) * 100));
+
+  let level: ContextPressureLevel;
+  if (pct >= CONTEXT_WARNING_UPPER) {
+    level = "high";
+  } else if (pct >= CONTEXT_NORMAL_UPPER) {
+    level = "warning";
+  } else {
+    level = "normal";
+  }
+
+  return { level, pct };
+}
+
+/** Spread context pressure fields into the telemetry object. */
+function computeContextPressure(
+  contextUsedTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+): Pick<TopTimelineTelemetryData, "contextPressureLevel" | "contextUtilizationPct"> {
+  const result = classifyContextPressure(contextUsedTokens, contextMaxTokens);
+  return {
+    contextPressureLevel: result?.level,
+    contextUtilizationPct: result?.pct,
+  };
+}
+
 export const log = createPluginLogger("top", { version: PLUGIN_VERSION });
 
 log.info("Initialized host system resources monitor", { version: PLUGIN_VERSION });
@@ -437,6 +522,10 @@ export async function handleGetSystemResources(input?: {
       .filter((state) => effectiveEnabled.has(state.id)),
     lastTurn: lastTurnTelemetry,
     liveUsage: lastLiveUsage,
+    // Velocity data from the most recent turn telemetry.
+    tokensPerSecond: lastTurnTelemetry?.tokensPerSecond,
+    contextPressureLevel: lastTurnTelemetry?.contextPressureLevel,
+    contextUtilizationPct: lastTurnTelemetry?.contextUtilizationPct,
   };
 }
 
@@ -778,6 +867,15 @@ export async function collectTurnTelemetry(
     contextUsedTokens,
     contextMaxTokens,
     costUsd,
+    // Live generation velocity: (output + reasoning) / durationSec.
+    // Guard against zero-duration, missing fields, and interrupted turns.
+    tokensPerSecond: computeTokensPerSecond(
+      outputTokens,
+      durationMs,
+      outcome.kind,
+    ),
+    // Context pressure from the most recent turn's utilization.
+    ...computeContextPressure(contextUsedTokens, contextMaxTokens),
   };
   lastTurnTelemetry = data;
   return data;

package/server/vendor/paseo-plugin-helper/custom-pills.ts

@@ -11,6 +11,9 @@ import {
   parseNumericPillValue,
   formatPillDisplay,
 } from "../../../shared/vendor/paseo-plugin-helper/custom-pills";
+import type { FeatureModule, FeatureDisposer } from "../../../shared/vendor/paseo-plugin-helper/features";
+import type { PluginRpcContract } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+
 
 
 /**
@@ -342,3 +345,70 @@ export class CustomPillPoller {
     }
   }
 }
+
+export interface CustomPillsFeatureOptions {
+  id?: string;
+  configDir?: string;
+  logger?: PluginLogger;
+  poller?: CustomPillPoller;
+  contracts?: {
+    get?: PluginRpcContract;
+    list?: PluginRpcContract;
+    run?: PluginRpcContract;
+  };
+  handlers?: {
+    get?: (input?: any) => Promise<any> | any;
+    list?: (input?: any) => Promise<any> | any;
+    run?: (input: any) => Promise<any> | any;
+  };
+  onMount?: (poller: CustomPillPoller) => void;
+  startPoller?: boolean;
+}
+
+/**
+ * Creates a reusable FeatureModule for declarative custom metric pills (#933).
+ */
+export function createCustomPillsFeature<TServerContext = any, TClientContext = any>(
+  options: CustomPillsFeatureOptions = {},
+): FeatureModule<TServerContext, TClientContext> {
+  const poller = options.poller ?? new CustomPillPoller({
+    configDir: options.configDir,
+    logger: options.logger,
+  });
+
+  const contractsRecord: Record<string, PluginRpcContract> = {};
+  if (options.contracts?.get) contractsRecord.get = options.contracts.get;
+  if (options.contracts?.list) contractsRecord.list = options.contracts.list;
+  if (options.contracts?.run) contractsRecord.run = options.contracts.run;
+
+  return {
+    id: options.id || "custom-pills",
+    contracts: contractsRecord,
+    contributeServer(server: any) {
+      if (options.startPoller !== false) {
+        void poller.start();
+      }
+      options.onMount?.(poller);
+
+      if (typeof server?.handle === "function") {
+        if (options.contracts?.get && options.handlers?.get) {
+          server.handle(options.contracts.get, options.handlers.get);
+        }
+        if (options.contracts?.list && options.handlers?.list) {
+          server.handle(options.contracts.list, options.handlers.list);
+        }
+        if (options.contracts?.run && options.handlers?.run) {
+          server.handle(options.contracts.run, options.handlers.run);
+        }
+      }
+
+      let stopped = false;
+      return () => {
+        if (stopped) return;
+        stopped = true;
+        poller.stop();
+      };
+    },
+  };
+}
+

package/server/vendor/paseo-plugin-helper/index.ts

@@ -17,4 +17,6 @@ export * from "./rpc-guard";
 export * from "./agent";
 export * from "./workspace-beacon";
 export * from "./tickets";
+export * from "./storage-guard";
+export * from "./telemetry";
 

package/server/vendor/paseo-plugin-helper/logger.ts

@@ -46,28 +46,17 @@ export function isProductionEnv(env: NodeJS.ProcessEnv = process.env): boolean {
   return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
 }
 
-/**
- * True only when `NODE_ENV` is explicitly a development value
- * (`development`/`dev`). Unset, empty, `production`, and anything else
- * (e.g. `test`) all count as quiet, so a shipped plugin defaults to info
- * without any env var set.
- */
-export function isDevelopmentEnv(env: NodeJS.ProcessEnv = process.env): boolean {
-  const nodeEnv = (env.NODE_ENV ?? "").trim().toLowerCase();
-  return nodeEnv === "development" || nodeEnv === "dev";
-}
-
 /**
  * Default rule (documented for operators):
  * explicit `PASEO_PLUGIN_LOG_LEVEL`/`PASEO_LOG_LEVEL`/`PASEO_DEBUG` always wins;
- * otherwise quiet (`info`) — including when no env var is set at all, so a
- * shipped plugin never emits debug logs by default. Debug only when `NODE_ENV`
- * is explicitly a development value (`development`/`dev`).
+ * otherwise `info` in every environment — including `NODE_ENV=development`/`dev`
+ * and when no env var is set at all. Debug requires an explicit level; the
+ * environment name alone never lifts the floor.
  */
 export function resolveDefaultMinLevel(
   env: NodeJS.ProcessEnv = process.env,
 ): LogLevel {
-  return resolveMinLevelFromEnv(env) ?? (isDevelopmentEnv(env) ? "debug" : "info");
+  return resolveMinLevelFromEnv(env) ?? "info";
 }
 
 export interface PluginLoggerOptions {
@@ -90,7 +79,7 @@ export interface PluginLoggerOptions {
 
   /**
    * Minimum log level to print. Defaults to resolveDefaultMinLevel():
-   * info unless NODE_ENV is explicitly development (or an explicit level is set).
+   * info unless an explicit level is set via the environment.
    */
   minLevel?: LogLevel;
 

package/server/vendor/paseo-plugin-helper/rpc-guard.ts

@@ -1,4 +1,4 @@
-import { withTimeout, TimeoutError } from "../../../shared/vendor/paseo-plugin-helper/async";
+import { withTimeout, isTimeoutError } from "../../../shared/vendor/paseo-plugin-helper/async";
 
 export interface RpcGuardOptions<T> {
   timeoutMs?: number;
@@ -40,7 +40,7 @@ export function guardRpcHandler<TInput, TOutput>(
         "RPC handler",
       );
     } catch (err) {
-      if (err instanceof TimeoutError) {
+      if (isTimeoutError(err)) {
         options.onTimeout?.({ timeoutMs, inflight });
       }
       throw err;

package/server/vendor/paseo-plugin-helper/storage-guard.ts

@@ -0,0 +1,294 @@
+import fs from "node:fs";
+import type { PathLike } from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { resolvePaseoHome } from "./storage";
+
+export class ScopedStorageViolationError extends Error {
+  readonly code = "ERR_SCOPED_STORAGE_VIOLATION";
+  readonly attemptedPath: string;
+  readonly allowedRoots: string[];
+
+  constructor(message: string, attemptedPath: string, allowedRoots: string[]) {
+    super(message);
+    this.name = "ScopedStorageViolationError";
+    this.attemptedPath = attemptedPath;
+    this.allowedRoots = allowedRoots;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export interface InstallStorageGuardOptions {
+  pluginId: string;
+  namespace?: string; // defaults to "plugin-data/xpufx"
+  baseDir?: string;
+  allowTmp?: boolean; // defaults to true
+  mode?: "enforce" | "warn"; // defaults to "enforce"
+  onViolation?: (violation: { path: string; operation: string; allowedRoots: string[] }) => void;
+}
+
+function resolvePathString(target: PathLike | number): string | null {
+  if (typeof target === "string") {
+    return path.resolve(target);
+  }
+  if (Buffer.isBuffer(target)) {
+    return path.resolve(target.toString("utf8"));
+  }
+  if (target instanceof URL) {
+    if (target.protocol === "file:") {
+      const pathname = decodeURIComponent(target.pathname);
+      return path.resolve(pathname);
+    }
+    return null;
+  }
+  return null;
+}
+
+function isPathWithinRoot(targetPath: string, rootDir: string): boolean {
+  const resolvedTarget = path.resolve(targetPath);
+  const resolvedRoot = path.resolve(rootDir);
+
+  if (resolvedTarget === resolvedRoot) {
+    return true;
+  }
+
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  return !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export function installStorageGuard(options: InstallStorageGuardOptions): () => void {
+  const pluginId = options.pluginId;
+  const namespace = options.namespace ?? "plugin-data/xpufx";
+  const allowTmp = options.allowTmp ?? true;
+  const mode = options.mode ?? "enforce";
+
+  const pluginStorageDir = options.baseDir
+    ? path.resolve(options.baseDir, pluginId)
+    : path.resolve(resolvePaseoHome(), namespace, pluginId);
+  const allowedRoots: string[] = [pluginStorageDir];
+
+  if (allowTmp) {
+    allowedRoots.push(path.resolve(os.tmpdir()));
+    allowedRoots.push(path.resolve(process.cwd(), ".tmp"));
+  }
+
+  function validateTarget(target: PathLike | number, operation: string): void {
+    const resolved = resolvePathString(target);
+    if (!resolved) {
+      return;
+    }
+
+    const isAllowed = allowedRoots.some((root) => isPathWithinRoot(resolved, root));
+    if (!isAllowed) {
+      options.onViolation?.({
+        path: resolved,
+        operation,
+        allowedRoots: [...allowedRoots],
+      });
+
+      const message = `Scoped storage violation: write operation '${operation}' on '${resolved}' is outside permitted scopes: [${allowedRoots.join(", ")}]`;
+
+      if (mode === "enforce") {
+        throw new ScopedStorageViolationError(message, resolved, [...allowedRoots]);
+      } else {
+        console.warn(`[WARN] ${message}`);
+      }
+    }
+  }
+
+  // Backup originals
+  const origWriteFile = fs.writeFile;
+  const origWriteFileSync = fs.writeFileSync;
+  const origAppendFile = fs.appendFile;
+  const origAppendFileSync = fs.appendFileSync;
+  const origMkdir = fs.mkdir;
+  const origMkdirSync = fs.mkdirSync;
+  const origRmdir = fs.rmdir;
+  const origRmdirSync = fs.rmdirSync;
+  const origUnlink = fs.unlink;
+  const origUnlinkSync = fs.unlinkSync;
+  const origRm = fs.rm;
+  const origRmSync = fs.rmSync;
+  const origRename = fs.rename;
+  const origRenameSync = fs.renameSync;
+  const origCopyFile = fs.copyFile;
+  const origCopyFileSync = fs.copyFileSync;
+  const origCreateWriteStream = fs.createWriteStream;
+
+  const origPromisesWriteFile = fsp.writeFile;
+  const origPromisesAppendFile = fsp.appendFile;
+  const origPromisesMkdir = fsp.mkdir;
+  const origPromisesRmdir = fsp.rmdir;
+  const origPromisesUnlink = fsp.unlink;
+  const origPromisesRm = fsp.rm;
+  const origPromisesRename = fsp.rename;
+  const origPromisesCopyFile = fsp.copyFile;
+
+  // Intercept node:fs sync & async
+  const anyFs = fs as any;
+
+  anyFs.writeFile = function (file: PathLike | number, ...args: unknown[]) {
+    validateTarget(file, "writeFile");
+    return Reflect.apply(origWriteFile, fs, [file, ...args]);
+  };
+
+  anyFs.writeFileSync = function (file: PathLike | number, ...args: unknown[]) {
+    validateTarget(file, "writeFileSync");
+    return Reflect.apply(origWriteFileSync, fs, [file, ...args]);
+  };
+
+  anyFs.appendFile = function (file: PathLike | number, ...args: unknown[]) {
+    validateTarget(file, "appendFile");
+    return Reflect.apply(origAppendFile, fs, [file, ...args]);
+  };
+
+  anyFs.appendFileSync = function (file: PathLike | number, ...args: unknown[]) {
+    validateTarget(file, "appendFileSync");
+    return Reflect.apply(origAppendFileSync, fs, [file, ...args]);
+  };
+
+  anyFs.mkdir = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "mkdir");
+    return Reflect.apply(origMkdir, fs, [pathArg, ...args]);
+  };
+
+  anyFs.mkdirSync = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "mkdirSync");
+    return Reflect.apply(origMkdirSync, fs, [pathArg, ...args]);
+  };
+
+  anyFs.rmdir = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "rmdir");
+    return Reflect.apply(origRmdir, fs, [pathArg, ...args]);
+  };
+
+  anyFs.rmdirSync = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "rmdirSync");
+    return Reflect.apply(origRmdirSync, fs, [pathArg, ...args]);
+  };
+
+  anyFs.unlink = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "unlink");
+    return Reflect.apply(origUnlink, fs, [pathArg, ...args]);
+  };
+
+  anyFs.unlinkSync = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "unlinkSync");
+    return Reflect.apply(origUnlinkSync, fs, [pathArg, ...args]);
+  };
+
+  anyFs.rm = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "rm");
+    return Reflect.apply(origRm, fs, [pathArg, ...args]);
+  };
+
+  anyFs.rmSync = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "rmSync");
+    return Reflect.apply(origRmSync, fs, [pathArg, ...args]);
+  };
+
+  anyFs.rename = function (oldPath: PathLike, newPath: PathLike, ...args: unknown[]) {
+    validateTarget(oldPath, "rename:source");
+    validateTarget(newPath, "rename:destination");
+    return Reflect.apply(origRename, fs, [oldPath, newPath, ...args]);
+  };
+
+  anyFs.renameSync = function (oldPath: PathLike, newPath: PathLike, ...args: unknown[]) {
+    validateTarget(oldPath, "renameSync:source");
+    validateTarget(newPath, "renameSync:destination");
+    return Reflect.apply(origRenameSync, fs, [oldPath, newPath, ...args]);
+  };
+
+  anyFs.copyFile = function (src: PathLike, dest: PathLike, ...args: unknown[]) {
+    validateTarget(dest, "copyFile:destination");
+    return Reflect.apply(origCopyFile, fs, [src, dest, ...args]);
+  };
+
+  anyFs.copyFileSync = function (src: PathLike, dest: PathLike, ...args: unknown[]) {
+    validateTarget(dest, "copyFileSync:destination");
+    return Reflect.apply(origCopyFileSync, fs, [src, dest, ...args]);
+  };
+
+  anyFs.createWriteStream = function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "createWriteStream");
+    return Reflect.apply(origCreateWriteStream, fs, [pathArg, ...args]);
+  };
+
+  // Intercept node:fs/promises
+  const anyFsp = fsp as any;
+
+  anyFsp.writeFile = async function (file: PathLike | number | fsp.FileHandle, ...args: unknown[]) {
+    if (typeof file === "string" || Buffer.isBuffer(file) || file instanceof URL) {
+      validateTarget(file as unknown as PathLike, "fsp.writeFile");
+    }
+    return Reflect.apply(origPromisesWriteFile, fsp, [file, ...args]);
+  };
+
+  anyFsp.appendFile = async function (file: PathLike | number | fsp.FileHandle, ...args: unknown[]) {
+    if (typeof file === "string" || Buffer.isBuffer(file) || file instanceof URL) {
+      validateTarget(file as unknown as PathLike, "fsp.appendFile");
+    }
+    return Reflect.apply(origPromisesAppendFile, fsp, [file, ...args]);
+  };
+
+  anyFsp.mkdir = async function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "fsp.mkdir");
+    return Reflect.apply(origPromisesMkdir, fsp, [pathArg, ...args]);
+  };
+
+  anyFsp.rmdir = async function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "fsp.rmdir");
+    return Reflect.apply(origPromisesRmdir, fsp, [pathArg, ...args]);
+  };
+
+  anyFsp.unlink = async function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "fsp.unlink");
+    return Reflect.apply(origPromisesUnlink, fsp, [pathArg, ...args]);
+  };
+
+  anyFsp.rm = async function (pathArg: PathLike, ...args: unknown[]) {
+    validateTarget(pathArg, "fsp.rm");
+    return Reflect.apply(origPromisesRm, fsp, [pathArg, ...args]);
+  };
+
+  anyFsp.rename = async function (oldPath: PathLike, newPath: PathLike) {
+    validateTarget(oldPath, "fsp.rename:source");
+    validateTarget(newPath, "fsp.rename:destination");
+    return Reflect.apply(origPromisesRename, fsp, [oldPath, newPath]);
+  };
+
+  anyFsp.copyFile = async function (src: PathLike, dest: PathLike, ...args: unknown[]) {
+    validateTarget(dest, "fsp.copyFile:destination");
+    return Reflect.apply(origPromisesCopyFile, fsp, [src, dest, ...args]);
+  };
+
+  return function uninstallStorageGuard(): void {
+    fs.writeFile = origWriteFile;
+    fs.writeFileSync = origWriteFileSync;
+    fs.appendFile = origAppendFile;
+    fs.appendFileSync = origAppendFileSync;
+    fs.mkdir = origMkdir;
+    fs.mkdirSync = origMkdirSync;
+    fs.rmdir = origRmdir;
+    fs.rmdirSync = origRmdirSync;
+    fs.unlink = origUnlink;
+    fs.unlinkSync = origUnlinkSync;
+    fs.rm = origRm;
+    fs.rmSync = origRmSync;
+    fs.rename = origRename;
+    fs.renameSync = origRenameSync;
+    fs.copyFile = origCopyFile;
+    fs.copyFileSync = origCopyFileSync;
+    fs.createWriteStream = origCreateWriteStream;
+
+    fsp.writeFile = origPromisesWriteFile;
+    fsp.appendFile = origPromisesAppendFile;
+    fsp.mkdir = origPromisesMkdir;
+    fsp.rmdir = origPromisesRmdir;
+    fsp.unlink = origPromisesUnlink;
+    fsp.rm = origPromisesRm;
+    fsp.rename = origPromisesRename;
+    fsp.copyFile = origPromisesCopyFile;
+  };
+}

package/server/vendor/paseo-plugin-helper/storage.ts

@@ -7,7 +7,7 @@ export interface PluginStorageOptions<T> {
   defaultData?: T;
   /**
    * Base directory override. When provided, storage is located at path.join(baseDir, pluginId).
-   * When omitted, defaults to path.join(os.homedir(), ".paseo", namespace ?? "plugin-data/xpufx", pluginId).
+   * When omitted, defaults to path.join(resolvePaseoHome(), namespace ?? "plugin-data/xpufx", pluginId).
    */
   baseDir?: string;
   /**
@@ -27,6 +27,40 @@ export interface StorageStats {
   lastModified: Date | null;
 }
 
+const AGENT_MUX_PROFILE_HOME_RE = /(?:^|[\\/])\.agent-mux[\\/]profiles[\\/]/;
+
+/**
+ * Resolve the real user home even when `HOME` points into an agent-mux profile.
+ * A profile session has `HOME=~/.agent-mux/profiles/<provider>/<profile>` while
+ * the live Paseo state stays on the host home. agent-mux exports `REAL_HOME` for
+ * every profile session, so prefer it; otherwise strip the profile prefix so
+ * paths under `~/.paseo` still resolve to the host (#1158, #973).
+ */
+export function resolveHostHome(env: NodeJS.ProcessEnv = process.env): string {
+  const home = (env.HOME || os.homedir() || "").trim();
+  if (!home || !AGENT_MUX_PROFILE_HOME_RE.test(home)) {
+    return home;
+  }
+  const realHome = (env.REAL_HOME || "").trim();
+  if (realHome) return realHome;
+  const marker = home.match(AGENT_MUX_PROFILE_HOME_RE);
+  if (marker && typeof marker.index === "number" && marker.index > 0) {
+    return home.slice(0, marker.index);
+  }
+  return home;
+}
+
+/**
+ * Resolve the canonical `~/.paseo` directory. `PASEO_HOME` is the daemon's own
+ * declaration of that root, so prefer it; otherwise anchor to the host home
+ * rather than an agent-mux profile (#1158).
+ */
+export function resolvePaseoHome(env: NodeJS.ProcessEnv = process.env): string {
+  const paseoHome = (env.PASEO_HOME || "").trim();
+  if (paseoHome) return paseoHome;
+  return path.join(resolveHostHome(env), ".paseo");
+}
+
 export const DEFAULT_NAMESPACE_README = `# Paseo Plugins Storage (xpufx)
 
 This directory is managed by \`paseo-plugin-helper\` to store persistent settings, cached metrics, and state for plugins.
@@ -60,7 +94,7 @@ export class PluginStorage<T extends Record<string, any>> {
       this.namespaceDir = options.baseDir;
       this.pluginDir = path.join(options.baseDir, pluginId);
     } else {
-      this.namespaceDir = path.join(os.homedir(), ".paseo", namespace);
+      this.namespaceDir = path.join(resolvePaseoHome(), namespace);
       this.pluginDir = path.join(this.namespaceDir, pluginId);
     }