@agentuity/cli 0.1.32 → 0.1.34

package/src/cmd/cloud/env/import.ts

@@ -7,10 +7,8 @@ import {
 	readEnvFile,
 	writeEnvFile,
 	filterAgentuitySdkKeys,
-	mergeEnvVars,
 	splitEnvAndSecrets,
 	validateNoPublicSecrets,
-	isReservedAgentuityKey,
 } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { resolveOrgId, isOrgScope } from './org-util';
@@ -164,12 +162,9 @@ export const importSubcommand = createSubcommand({
 			let localEnvPath: string | undefined;
 			if (projectDir) {
 				localEnvPath = await findExistingEnvFile(projectDir);
-				const localEnv = await readEnvFile(localEnvPath);
-				const mergedEnv = mergeEnvVars(localEnv, filteredVars);
-
-				await writeEnvFile(localEnvPath, mergedEnv, {
-					skipKeys: Object.keys(mergedEnv).filter(isReservedAgentuityKey),
-				});
+				// writeEnvFile preserves existing keys by default, so just write the filtered vars
+				// This will merge with existing .env content, preserving AGENTUITY_SDK_KEY and other keys
+				await writeEnvFile(localEnvPath, filteredVars);
 			}
 
 			tui.success(

package/src/cmd/cloud/env/pull.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { join } from 'node:path';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectGet, orgEnvGet } from '@agentuity/server';
@@ -8,7 +7,6 @@ import {
 	readEnvFile,
 	writeEnvFile,
 	mergeEnvVars,
-	isReservedAgentuityKey,
 } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { resolveOrgId, isOrgScope } from './org-util';
@@ -93,7 +91,7 @@ export const pullSubcommand = createSubcommand({
 		const targetEnvPath = await findExistingEnvFile(projectDir);
 		const localEnv = await readEnvFile(targetEnvPath);
 
-		// Preserve local AGENTUITY_SDK_KEY before writing (since it will be skipped in the first write)
+		// Preserve local AGENTUITY_SDK_KEY
 		const localSdkKey = localEnv.AGENTUITY_SDK_KEY;
 
 		// Merge: cloud values override local if force=true, otherwise keep local
@@ -106,32 +104,25 @@ export const pullSubcommand = createSubcommand({
 			mergedEnv = mergeEnvVars(cloudEnv, localEnv);
 		}
 
-		// Write to .env (skip reserved AGENTUITY_ keys, except AGENTUITY_PUBLIC_)
+		// Determine the SDK key to use: cloud api_key is source of truth, fallback to local
+		const sdkKeyToWrite = cloudApiKey || localSdkKey;
+		if (sdkKeyToWrite) {
+			mergedEnv.AGENTUITY_SDK_KEY = sdkKeyToWrite;
+		}
+
+		// Write to .env in a single operation, preserveExisting: false since we have the full merged state
 		await writeEnvFile(targetEnvPath, mergedEnv, {
-			skipKeys: Object.keys(mergedEnv).filter(isReservedAgentuityKey),
+			preserveExisting: false,
+			addComment: (key) => {
+				if (key === 'AGENTUITY_SDK_KEY') {
+					return 'AGENTUITY_SDK_KEY is a sensitive value and should not be committed to version control.';
+				}
+				return null;
+			},
 		});
 
-		// Restore AGENTUITY_SDK_KEY to .env (cloud is source of truth, fallback to local)
-		// The key was removed by the write above since it's in skipKeys, so we need to restore it
-		const dotEnvPath = join(projectDir, '.env');
-		const dotEnv = await readEnvFile(dotEnvPath);
-
-		// Cloud is source of truth: use cloud api_key if available, otherwise fallback to local
-		// For org scope, only restore if local key exists (orgs don't have api_key)
-		const sdkKeyToWrite = cloudApiKey || localSdkKey;
-		if (sdkKeyToWrite) {
-			dotEnv.AGENTUITY_SDK_KEY = sdkKeyToWrite;
-			await writeEnvFile(dotEnvPath, dotEnv, {
-				addComment: (key) => {
-					if (key === 'AGENTUITY_SDK_KEY') {
-						return 'AGENTUITY_SDK_KEY is a sensitive value and should not be committed to version control.';
-					}
-					return null;
-				},
-			});
-			if (cloudApiKey && cloudApiKey !== localSdkKey) {
-				tui.info(`Wrote AGENTUITY_SDK_KEY to ${dotEnvPath}`);
-			}
+		if (cloudApiKey && cloudApiKey !== localSdkKey) {
+			tui.info(`Wrote AGENTUITY_SDK_KEY to ${targetEnvPath}`);
 		}
 
 		const count = Object.keys(cloudEnv).length;

package/src/cmd/cloud/env/set.ts

@@ -4,9 +4,7 @@ import * as tui from '../../../tui';
 import { projectEnvUpdate, orgEnvUpdate } from '@agentuity/server';
 import {
 	findExistingEnvFile,
-	readEnvFile,
 	writeEnvFile,
-	filterAgentuitySdkKeys,
 	looksLikeSecret,
 	isReservedAgentuityKey,
 	isPublicVarKey,
@@ -145,12 +143,8 @@ export const setSubcommand = createSubcommand({
 			let envFilePath: string | undefined;
 			if (projectDir) {
 				envFilePath = await findExistingEnvFile(projectDir);
-				const currentEnv = await readEnvFile(envFilePath);
-				currentEnv[args.key] = args.value;
-
-				// Filter out AGENTUITY_ keys before writing
-				const filteredEnv = filterAgentuitySdkKeys(currentEnv);
-				await writeEnvFile(envFilePath, filteredEnv);
+				// Write only the new key - writeEnvFile preserves existing keys by default
+				await writeEnvFile(envFilePath, { [args.key]: args.value });
 			}
 
 			const successMsg = envFilePath

package/src/cmd/cloud/region-lookup.ts

@@ -2,7 +2,7 @@ import type { Logger } from '@agentuity/core';
 import { projectGet, sandboxGet, deploymentGet, type APIClient } from '@agentuity/server';
 import { getResourceRegion, setResourceRegion } from '../../cache';
 import { getGlobalCatalystAPIClient } from '../../config';
-import type { AuthData } from '../../types';
+import type { AuthData, Config } from '../../types';
 import * as tui from '../../tui';
 import { ErrorCode } from '../../errors';
 
@@ -35,7 +35,8 @@ export async function getIdentifierRegion(
 	apiClient: APIClient,
 	profileName = 'production',
 	identifier: string,
-	orgId?: string
+	orgId?: string,
+	config?: Config | null
 ): Promise<string> {
 	const identifierType = getIdentifierType(identifier);
 
@@ -57,8 +58,14 @@ export async function getIdentifierRegion(
 		const deployment = await deploymentGet(apiClient, identifier);
 		region = deployment.cloudRegion ?? null;
 	} else {
-		// sandbox
-		const globalClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+		// sandbox - pass config to getGlobalCatalystAPIClient for proper region resolution
+		const globalClient = await getGlobalCatalystAPIClient(
+			logger,
+			auth,
+			profileName,
+			orgId,
+			config
+		);
 		const sandbox = await sandboxGet(globalClient, { sandboxId: identifier, orgId });
 		region = sandbox.region ?? null;
 	}
@@ -70,6 +77,14 @@ export async function getIdentifierRegion(
 		);
 	}
 
+	// Validate region is a non-empty string
+	if (typeof region !== 'string' || region.trim() === '') {
+		tui.fatal(
+			`Invalid region returned for ${identifierType} '${identifier}': '${region}'. Use --region flag to specify a valid region.`,
+			ErrorCode.RESOURCE_NOT_FOUND
+		);
+	}
+
 	// Cache the result
 	await setResourceRegion(identifierType, profileName, identifier, region);
 	logger.trace(`[region-lookup] Cached region for ${identifier}: ${region}`);

package/src/cmd/cloud/sandbox/exec.ts

@@ -7,8 +7,8 @@ import { getCommand } from '../../../command-prefix';
 import { sandboxExecute, executionGet, writeAndDrain } from '@agentuity/server';
 import type { Logger } from '@agentuity/core';
 
-const POLL_INTERVAL_MS = 500;
-const MAX_POLL_ATTEMPTS = 7200;
+// Server-side long-poll wait duration (max 5 minutes supported by server)
+const EXECUTION_WAIT_DURATION = '5m';
 
 const SandboxExecResponseSchema = z.object({
 	executionId: z.string().describe('Unique execution identifier'),
@@ -115,41 +115,14 @@ export const execSubcommand = createCommand({
 				}
 			}
 
-			let attempts = 0;
-			let finalExecution = execution;
-
-			while (attempts < MAX_POLL_ATTEMPTS) {
-				if (abortController.signal.aborted) {
-					throw new Error('Execution cancelled');
-				}
-
-				await sleep(POLL_INTERVAL_MS);
-				attempts++;
-
-				try {
-					const execInfo = await executionGet(client, {
-						executionId: execution.executionId,
-						orgId,
-					});
-
-					if (
-						execInfo.status === 'completed' ||
-						execInfo.status === 'failed' ||
-						execInfo.status === 'timeout' ||
-						execInfo.status === 'cancelled'
-					) {
-						finalExecution = {
-							executionId: execInfo.executionId,
-							status: execInfo.status,
-							exitCode: execInfo.exitCode,
-							durationMs: execInfo.durationMs,
-						};
-						break;
-					}
-				} catch {
-					continue;
-				}
-			}
+			// Use server-side long-polling to wait for execution completion
+			// This is more efficient than client-side polling and provides immediate
+			// error detection if the sandbox is terminated
+			const finalExecution = await executionGet(client, {
+				executionId: execution.executionId,
+				orgId,
+				wait: EXECUTION_WAIT_DURATION,
+			});
 
 			// Wait for all streams to reach EOF (Pulse blocks until true EOF)
 			await Promise.all(streamPromises);
@@ -248,8 +221,4 @@ function createCaptureStream(onChunk: (chunk: string) => void): NodeJS.WritableS
 	});
 }
 
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 export default execSubcommand;

package/src/cmd/cloud/scp/download.ts

@@ -72,7 +72,8 @@ export const downloadCommand = createSubcommand({
 			apiClient,
 			profileName,
 			identifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/scp/upload.ts

@@ -75,7 +75,8 @@ export const uploadCommand = createSubcommand({
 			apiClient,
 			profileName,
 			identifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/ssh.ts

@@ -80,7 +80,8 @@ export const sshSubcommand = createSubcommand({
 			apiClient,
 			profileName,
 			targetIdentifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/storage/create.ts

@@ -29,6 +29,9 @@ export const createSubcommand = defineSubcommand({
 		},
 	],
 	schema: {
+		options: z.object({
+			description: z.string().optional().describe('Optional description for the bucket'),
+		}),
 		response: z.object({
 			success: z.boolean().describe('Whether creation succeeded'),
 			name: z.string().describe('Created storage bucket name'),
@@ -36,7 +39,7 @@ export const createSubcommand = defineSubcommand({
 	},
 
 	async handler(ctx) {
-		const { logger, orgId, region, auth, options } = ctx;
+		const { logger, orgId, region, auth, options, opts } = ctx;
 
 		// Handle dry-run mode
 		if (isDryRunMode(options)) {
@@ -58,7 +61,9 @@ export const createSubcommand = defineSubcommand({
 			message: `Creating storage in ${region}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				return createResources(catalystClient, orgId, region!, [{ type: 's3' }]);
+				return createResources(catalystClient, orgId, region!, [
+					{ type: 's3', description: opts.description },
+				]);
 			},
 		});
 

package/src/cmd/cloud/storage/get.ts

@@ -15,6 +15,9 @@ const StorageGetResponseSchema = z.object({
 	endpoint: z.string().optional().describe('S3 endpoint URL'),
 	org_id: z.string().optional().describe('Organization ID that owns this bucket'),
 	org_name: z.string().optional().describe('Organization name that owns this bucket'),
+	bucket_type: z.string().optional().describe('Bucket type (user or snapshots)'),
+	internal: z.boolean().optional().describe('Whether this is a system-managed bucket'),
+	description: z.string().optional().describe('Optional description of the bucket'),
 });
 
 export const getSubcommand = createSubcommand({
@@ -134,6 +137,9 @@ export const getSubcommand = createSubcommand({
 			endpoint: bucket.endpoint ?? undefined,
 			org_id: bucket.org_id,
 			org_name: bucket.org_name,
+			bucket_type: bucket.bucket_type,
+			internal: bucket.internal,
+			description: bucket.description ?? undefined,
 		};
 	},
 });

package/src/cmd/cloud/storage/list.ts

@@ -20,6 +20,9 @@ const StorageListResponseSchema = z.object({
 				cloud_region: z.string().optional().describe('Cloud region where bucket is hosted'),
 				org_id: z.string().optional().describe('Organization ID that owns this bucket'),
 				org_name: z.string().optional().describe('Organization name that owns this bucket'),
+				bucket_type: z.string().optional().describe('Bucket type (user or snapshots)'),
+				internal: z.boolean().optional().describe('Whether this is a system-managed bucket'),
+				description: z.string().optional().describe('Optional description of the bucket'),
 			})
 		)
 		.optional()
@@ -241,6 +244,9 @@ export const listSubcommand = createSubcommand({
 				cloud_region: s3.cloud_region,
 				org_id: s3.org_id,
 				org_name: s3.org_name,
+				bucket_type: s3.bucket_type,
+				internal: s3.internal,
+				description: s3.description ?? undefined,
 			})),
 		};
 	},

package/src/cmd/project/auth/init.ts

@@ -12,6 +12,7 @@ import {
 	generateAuthSchemaSql,
 	getGeneratedSqlDir,
 } from './shared';
+import { readEnvFile, writeEnvFile } from '../../../env-util';
 import enquirer from 'enquirer';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -96,32 +97,23 @@ export const initSubcommand = createSubcommand({
 
 		const databaseName = dbInfo.name;
 
-		// Update .env with database URL
+		// Update .env with database URL using proper parsing
 		const envPath = path.join(projectDir, '.env');
-		let envContent = '';
-
-		if (fs.existsSync(envPath)) {
-			envContent = fs.readFileSync(envPath, 'utf-8');
-			if (!envContent.endsWith('\n') && envContent.length > 0) {
-				envContent += '\n';
-			}
-		}
+		const existingEnv = await readEnvFile(envPath);
 
 		// Check if DATABASE_URL already exists
-		const hasDatabaseUrl = envContent.match(/^DATABASE_URL=/m);
+		const hasDatabaseUrl = 'DATABASE_URL' in existingEnv;
 
 		if (dbInfo.url !== databaseUrl || !hasDatabaseUrl) {
 			if (hasDatabaseUrl) {
 				// DATABASE_URL exists, use AUTH_DATABASE_URL instead
-				envContent += `AUTH_DATABASE_URL="${dbInfo.url}"\n`;
-				fs.writeFileSync(envPath, envContent);
+				await writeEnvFile(envPath, { AUTH_DATABASE_URL: dbInfo.url });
 				tui.success('AUTH_DATABASE_URL added to .env');
 				tui.warning(
 					`DATABASE_URL already exists. Update your ${tui.bold('src/auth.ts')} to use AUTH_DATABASE_URL.`
 				);
 			} else {
-				envContent += `DATABASE_URL="${dbInfo.url}"\n`;
-				fs.writeFileSync(envPath, envContent);
+				await writeEnvFile(envPath, { DATABASE_URL: dbInfo.url });
 				tui.success('DATABASE_URL added to .env');
 			}
 		} else {
@@ -129,18 +121,14 @@ export const initSubcommand = createSubcommand({
 		}
 
 		// Add AGENTUITY_AUTH_SECRET if not present
-		// Re-read envContent to get latest state
-		envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
-		if (!envContent.endsWith('\n') && envContent.length > 0) {
-			envContent += '\n';
-		}
+		// Re-read env to get latest state
+		const currentEnv = await readEnvFile(envPath);
 
 		const hasAuthSecret =
-			envContent.match(/^AGENTUITY_AUTH_SECRET=/m) || envContent.match(/^BETTER_AUTH_SECRET=/m);
+			'AGENTUITY_AUTH_SECRET' in currentEnv || 'BETTER_AUTH_SECRET' in currentEnv;
 		if (!hasAuthSecret) {
 			const devSecret = `dev-${crypto.randomUUID()}-CHANGE-ME`;
-			envContent += `AGENTUITY_AUTH_SECRET="${devSecret}"\n`;
-			fs.writeFileSync(envPath, envContent);
+			await writeEnvFile(envPath, { AGENTUITY_AUTH_SECRET: devSecret });
 			tui.success('AGENTUITY_AUTH_SECRET added to .env (development default)');
 			tui.warning(
 				`Replace ${tui.bold('AGENTUITY_AUTH_SECRET')} with a secure value before deploying.`

package/src/config.ts

@@ -809,14 +809,16 @@ export async function getDefaultRegion(
  * @param auth - Authentication data
  * @param profileName - Profile name (default: 'production')
  * @param orgId - Optional organization ID for CLI key authentication
+ * @param config - Optional config for region preference lookup
  */
 export async function getGlobalCatalystAPIClient(
 	logger: Logger,
 	auth: AuthData,
 	profileName = 'production',
-	orgId?: string
+	orgId?: string,
+	config?: Config | null
 ) {
-	const region = await getDefaultRegion(profileName);
+	const region = await getDefaultRegion(profileName, config);
 	return getCatalystAPIClient(logger, auth, region, orgId);
 }
 
@@ -828,6 +830,12 @@ export function getIONHost(config: Config | null, region: string) {
 	if (config?.name === 'local' || region === 'local') {
 		return 'ion.agentuity.io';
 	}
+	// Validate region is a non-empty string to prevent malformed hostnames
+	if (!region || typeof region !== 'string' || region.trim() === '') {
+		throw new Error(
+			`Invalid region: '${region}'. Region must be a non-empty string. Use --region flag to specify a valid region.`
+		);
+	}
 	return `ion-${region}.agentuity.cloud`;
 }
 

package/src/env-util.ts

@@ -149,7 +149,8 @@ export async function readEnvFile(path: string): Promise<EnvVars> {
 
 /**
  * Write environment variables to an .env file
- * Optionally skip certain keys (like AGENTUITY_SDK_KEY)
+ * By default, preserves existing keys that are not in the new vars.
+ * Use preserveExisting: false to completely overwrite the file.
  */
 export async function writeEnvFile(
 	path: string,
@@ -157,20 +158,36 @@ export async function writeEnvFile(
 	options?: {
 		skipKeys?: string[];
 		addComment?: (key: string) => string | null;
+		/**
+		 * When true (default), reads existing file first and merges with new vars.
+		 * New vars take priority for matching keys, but all existing keys are preserved.
+		 * When false, completely overwrites the file with only the provided vars.
+		 */
+		preserveExisting?: boolean;
 	}
 ): Promise<void> {
 	const skipKeys = options?.skipKeys || [];
+	const preserveExisting = options?.preserveExisting ?? true;
+
+	// If preserveExisting is true, read existing file and merge
+	let finalVars = vars;
+	if (preserveExisting) {
+		const existing = await readEnvFile(path);
+		// Merge: existing as base, new vars override
+		finalVars = { ...existing, ...vars };
+	}
+
 	const lines: string[] = [];
 
 	// Sort keys for consistent output
-	const sortedKeys = Object.keys(vars).sort();
+	const sortedKeys = Object.keys(finalVars).sort();
 
 	for (const key of sortedKeys) {
 		if (skipKeys.includes(key)) {
 			continue;
 		}
 
-		const value = vars[key];
+		const value = finalVars[key];
 
 		// Add comment if provided
 		if (options?.addComment) {

package/src/types.ts

@@ -24,7 +24,10 @@ export const ConfigSchema = zod.object({
 	devmode: zod
 		.object({
 			hostname: zod.string().optional().describe('Development mode hostname'),
-			privateKey: zod.string().optional().describe('Development mode private key (base64-encoded PEM)'),
+			privateKey: zod
+				.string()
+				.optional()
+				.describe('Development mode private key (base64-encoded PEM)'),
 		})
 		.optional()
 		.describe('Development mode configuration'),

package/src/utils/installation-type.ts

@@ -2,10 +2,26 @@
  * Detects how the CLI was installed and is being run
  */
 
+import fs from 'node:fs';
 import os from 'node:os';
 
 export type InstallationType = 'global' | 'local' | 'source';
 
+/**
+ * Resolve a path to its real path (following symlinks) and normalize to POSIX separators.
+ * Returns the original path if resolution fails.
+ */
+function resolveRealPath(path: string): string {
+	if (!path) return '';
+	try {
+		// fs.realpathSync resolves symlinks (e.g., /tmp -> /private/tmp on macOS)
+		return fs.realpathSync(path).replace(/\\/g, '/');
+	} catch {
+		// If the path doesn't exist or can't be resolved, return normalized original
+		return path.replace(/\\/g, '/');
+	}
+}
+
 /**
  * Determines the installation type based on how the CLI is being executed
  *
@@ -14,34 +30,57 @@ export type InstallationType = 'global' | 'local' | 'source';
  * @returns 'source' - Running from source code (development)
  */
 export function getInstallationType(): InstallationType {
-	// Normalize paths to POSIX separators for cross-platform compatibility
+	// Bun.main already returns the resolved real path, just normalize separators
 	const mainPath = Bun.main.replace(/\\/g, '/');
-	// Bun.argv[1] contains the original invocation path (before symlink resolution)
-	const invokedPath = (Bun.argv[1] ?? '').replace(/\\/g, '/');
 
-	// Get bun's global bin directory from BUN_INSTALL or default to ~/.bun/bin
-	// Use os.homedir() as primary fallback to avoid "undefined/.bun" paths
-	const home = os.homedir() ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
-	const bunInstall = (process.env.BUN_INSTALL ?? (home ? `${home}/.bun` : '')).replace(/\\/g, '/');
-	const globalBinDir = bunInstall ? `${bunInstall}/bin/` : '';
+	// Get home directory reliably and resolve symlinks
+	// On macOS, os.homedir() returns /Users/xxx which is already real
+	const home = resolveRealPath(os.homedir() ?? process.env.HOME ?? process.env.USERPROFILE ?? '');
 
-	// Global install: invoked from bun's global bin directory (e.g., ~/.bun/bin/agentuity)
-	// This handles symlinks created by `bun add -g @agentuity/cli`
-	if (globalBinDir && invokedPath.startsWith(globalBinDir)) {
-		return 'global';
+	// Get bun install directory from BUN_INSTALL or default to ~/.bun
+	// Resolve symlinks to handle cases like BUN_INSTALL=/tmp/... on macOS where /tmp -> /private/tmp
+	const bunInstallRaw = process.env.BUN_INSTALL ?? (home ? `${home}/.bun` : '');
+	const bunInstall = resolveRealPath(bunInstallRaw);
+
+	// GLOBAL DETECTION: Check if running from bun's global install location
+	// When installed via `bun add -g`, the CLI lives at ~/.bun/node_modules/@agentuity/cli/
+	// or ~/.bun/install/global/node_modules/@agentuity/cli/
+	if (bunInstall) {
+		// Check for ~/.bun/node_modules/@agentuity/cli/ (common bun global layout)
+		if (mainPath.startsWith(`${bunInstall}/node_modules/@agentuity/cli/`)) {
+			return 'global';
+		}
+		// Check for ~/.bun/install/global/node_modules/@agentuity/cli/ (alternative layout)
+		if (mainPath.startsWith(`${bunInstall}/install/global/`)) {
+			return 'global';
+		}
+	}
+
+	// GLOBAL DETECTION: Check for legacy ~/.agentuity/ installation
+	// The install.sh script may install to ~/.agentuity/node_modules/@agentuity/cli/
+	// or create a shim at ~/.agentuity/bin/agentuity
+	if (home) {
+		const agentuityDir = resolveRealPath(`${home}/.agentuity`);
+		if (mainPath.startsWith(`${agentuityDir}/`)) {
+			return 'global';
+		}
 	}
 
-	// Also check the resolved path for explicit global install locations
-	if (mainPath.includes('/.bun/install/global/')) {
+	// GLOBAL DETECTION: Fallback check for any path containing /.bun/ before node_modules
+	// This catches edge cases where BUN_INSTALL might not match the actual path
+	if (mainPath.includes('/.bun/') && mainPath.includes('/node_modules/@agentuity/cli/')) {
 		return 'global';
 	}
 
-	// Local project install: ./node_modules/@agentuity/cli/...
+	// LOCAL DETECTION: Running from a project's node_modules
+	// This is when someone runs `bunx agentuity` or has it as a project dependency
+	// At this point, we've ruled out global installs, so any node_modules path is local
 	if (mainPath.includes('/node_modules/@agentuity/cli/')) {
 		return 'local';
 	}
 
-	// Source/development: packages/cli/bin/cli.ts or similar
+	// SOURCE DETECTION: Running from source code (development)
+	// This is when running directly from the monorepo: packages/cli/bin/cli.ts
 	return 'source';
 }