@hienlh/ppm 0.9.80 → 0.9.82

package/src/providers/claude-agent-sdk.ts

@@ -109,6 +109,7 @@ interface StreamingSession {
  */
 interface PendingApproval {
   resolve: (result: { approved: boolean; data?: unknown }) => void;
+  sessionId: string;
 }
 
 /**
@@ -360,7 +361,13 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     this.closeStreamingSession(sessionId);
     this.activeSessions.delete(sessionId);
     this.messageCount.delete(sessionId);
-    this.pendingApprovals.delete(sessionId);
+    // Resolve and clean up all pending approvals for this session
+    for (const [reqId, pending] of this.pendingApprovals) {
+      if (pending.sessionId === sessionId) {
+        pending.resolve({ approved: false });
+        this.pendingApprovals.delete(reqId);
+      }
+    }
     this.forkSources.delete(sessionId);
 
     // Best-effort: delete JSONL from ~/.claude/projects/
@@ -472,10 +479,32 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   }
 
   async *sendMessage(
-    sessionId: string,
+    _sessionId: string,
     message: string,
     opts?: import("./provider.interface.ts").SendMessageOpts & { forkSession?: boolean; priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }> },
   ): AsyncIterable<ChatEvent> {
+    // SDK requires valid UUID session IDs. Short/random IDs can leak from
+    // tab derivation or URL parsing — migrate to a real UUID early.
+    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    let sessionId = _sessionId;
+    if (!UUID_RE.test(sessionId)) {
+      const newId = crypto.randomUUID();
+      console.warn(`[sdk] session=${sessionId} is not a valid UUID — migrating to ${newId}`);
+      // Migrate internal maps
+      const oldMeta = this.activeSessions.get(sessionId);
+      if (oldMeta) {
+        this.activeSessions.delete(sessionId);
+        oldMeta.id = newId;
+        this.activeSessions.set(newId, oldMeta);
+      }
+      const oldCount = this.messageCount.get(sessionId);
+      if (oldCount != null) { this.messageCount.set(newId, oldCount); this.messageCount.delete(sessionId); }
+      const oldStream = this.streamingSessions.get(sessionId);
+      if (oldStream) { this.streamingSessions.set(newId, oldStream); this.streamingSessions.delete(sessionId); }
+      yield { type: "session_migrated" as const, oldSessionId: sessionId, newSessionId: newId };
+      sessionId = newId;
+    }
+
     // Follow-up: push into existing streaming session, yield nothing
     const existingStream = this.streamingSessions.get(sessionId);
     if (existingStream) {
@@ -543,15 +572,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
      */
     const waitForApproval = (toolName: string, input: unknown): Promise<{ approved: boolean; data?: unknown }> => {
       const requestId = crypto.randomUUID();
-      const APPROVAL_TIMEOUT_MS = 5 * 60_000;
+      // No timeout — approval waits indefinitely until user responds or session cleanup resolves it.
       const promise = new Promise<{ approved: boolean; data?: unknown }>((resolve) => {
-        this.pendingApprovals.set(requestId, { resolve });
-        setTimeout(() => {
-          if (this.pendingApprovals.has(requestId)) {
-            this.pendingApprovals.delete(requestId);
-            resolve({ approved: false });
-          }
-        }, APPROVAL_TIMEOUT_MS);
+        this.pendingApprovals.set(requestId, { resolve, sessionId });
       });
       approvalEvents.push({ type: "approval_request", requestId, tool: toolName, input });
       approvalNotify?.();
@@ -609,7 +632,6 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       PreToolUse: [{
         matcher: ".*",  // Match all tools — our hook checks internally
         hooks: [preToolUseHook],
-        timeout: 300,  // 5min for user approval
       }],
     };
 
@@ -617,6 +639,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     let resultSubtype: string | undefined;
     let resultNumTurns: number | undefined;
     let resultContextWindowPct: number | undefined;
+    let lastAssistantUuid: string | undefined;
     let yieldedDone = false;
     try {
       // Session ID is the canonical ID for both PPM and SDK (no dual-ID mapping).
@@ -977,6 +1000,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         // Partial assistant message — streaming text deltas
         if ((msg as any).type === "partial" || (msg as any).type === "stream_event") {
           const partial = msg as any;
+          // Track assistant UUID from top-level messages (not subagent children)
+          if (!parentId && partial.uuid) lastAssistantUuid = partial.uuid;
           // Handle stream_event (raw API events) for text deltas
           if ((msg as any).type === "stream_event") {
             const event = partial.event;
@@ -1014,6 +1039,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
 
         // Full assistant message
         if (msg.type === "assistant") {
+          // Track assistant UUID from top-level messages (not subagent children)
+          if (!parentId && (msg as any).uuid) lastAssistantUuid = (msg as any).uuid;
           // SDK assistant messages can carry an error field for auth/billing/rate-limit failures
           let assistantError = (msg as any).error as string | undefined;
 
@@ -1361,6 +1388,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             resultSubtype: resultSubtype as any,
             numTurns: resultNumTurns,
             contextWindowPct: resultContextWindowPct,
+            lastMessageUuid: lastAssistantUuid,
           };
 
           // Reset per-turn state for next turn
@@ -1370,6 +1398,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           resultSubtype = undefined;
           resultNumTurns = undefined;
           resultContextWindowPct = undefined;
+          lastAssistantUuid = undefined;
           sdkEventCount = 0;
           continue; // Wait for next turn from generator
         }
@@ -1438,6 +1467,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         resultSubtype: resultSubtype as any,
         numTurns: resultNumTurns,
         contextWindowPct: resultContextWindowPct,
+        lastMessageUuid: lastAssistantUuid,
       };
     }
   }
@@ -1551,6 +1581,7 @@ function parseSessionMessage(msg: { uuid: string; type: string; message: unknown
     content: textContent,
     events: events.length > 0 ? events : undefined,
     timestamp: new Date().toISOString(),
+    sdkUuid: msg.uuid,
   };
 }
 

package/src/server/index.ts

@@ -29,10 +29,10 @@ async function setupLogFile() {
   (globalThis as any).__PPM_LOG_SETUP__ = true;
 
   const { resolve } = await import("node:path");
-  const { homedir } = await import("node:os");
   const { appendFileSync, mkdirSync, existsSync } = await import("node:fs");
+  const { getPpmDir } = await import("../services/ppm-dir.ts");
 
-  const ppmDir = process.env.PPM_HOME || resolve(homedir(), ".ppm");
+  const ppmDir = getPpmDir();
   if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
   const logPath = resolve(ppmDir, "ppm.log");
 
@@ -104,9 +104,9 @@ app.get("/api/info", (c) => c.json(ok({
 // Public: recent logs for bug reports (last 30 lines)
 app.get("/api/logs/recent", async (c) => {
   const { resolve } = await import("node:path");
-  const { homedir } = await import("node:os");
   const { existsSync, readFileSync } = await import("node:fs");
-  const logFile = resolve(homedir(), ".ppm", "ppm.log");
+  const { getPpmDir } = await import("../services/ppm-dir.ts");
+  const logFile = resolve(getPpmDir(), "ppm.log");
   if (!existsSync(logFile)) return c.json(ok({ logs: "" }));
   const content = readFileSync(logFile, "utf-8");
   const lines = content.split("\n").slice(-30).join("\n").trim();
@@ -234,12 +234,12 @@ export async function startServer(options: {
 
   {
     const { resolve } = await import("node:path");
-    const { homedir } = await import("node:os");
     const { writeFileSync, readFileSync, mkdirSync, existsSync, openSync } = await import("node:fs");
     const { isCompiledBinary } = await import("../services/autostart-generator.ts");
     const { writeCmd, acquireLock, releaseLock } = await import("../services/supervisor-state.ts");
+    const { getPpmDir } = await import("../services/ppm-dir.ts");
 
-    const ppmDir = process.env.PPM_HOME || resolve(homedir(), ".ppm");
+    const ppmDir = getPpmDir();
     if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
     const pidFile = resolve(ppmDir, "ppm.pid");
     const statusFile = resolve(ppmDir, "status.json");
@@ -490,9 +490,9 @@ if (process.argv.includes("__serve__")) {
   // Also write server version to status.json so supervisor heartbeat reports the actual running version.
   try {
     const { resolve: r } = await import("node:path");
-    const { homedir: h } = await import("node:os");
     const { readFileSync: rf, writeFileSync: wf, renameSync: rn } = await import("node:fs");
-    const statusFile = r(h(), ".ppm", "status.json");
+    const { getPpmDir: gd } = await import("../services/ppm-dir.ts");
+    const statusFile = r(gd(), "status.json");
     const status = JSON.parse(rf(statusFile, "utf-8"));
     // Write running server version — source of truth for heartbeat
     status.serverVersion = VERSION;

package/src/server/routes/chat.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { chatService } from "../../services/chat.service.ts";
 import { providerRegistry } from "../../providers/registry.ts";
 import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sdk";
-import { listSlashItems } from "../../services/slash-items.service.ts";
+import { listSlashItems, searchSlashItems } from "../../services/slash-items.service.ts";
 import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.service.ts";
 import { getSessionLog } from "../../services/session-log.service.ts";
 import { getSessionProjectPath, setSessionMetadata, setSessionTitle, getPinnedSessionIds, pinSession, unpinSession, deleteSessionMapping, deleteSessionMetadata, deleteSessionTitle } from "../../services/db.service.ts";
@@ -19,7 +19,9 @@ export const chatRoutes = new Hono<Env>();
 chatRoutes.get("/slash-items", (c) => {
   try {
     const projectPath = c.get("projectPath");
-    const items = listSlashItems(projectPath);
+    const q = c.req.query("q");
+    let items = listSlashItems(projectPath);
+    if (q) items = searchSlashItems(items, q);
     return c.json(ok(items));
   } catch (e) {
     return c.json(err((e as Error).message), 500);

package/src/server/routes/upgrade.ts

@@ -1,6 +1,5 @@
 import { Hono } from "hono";
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import { readFileSync, existsSync } from "node:fs";
 import { VERSION } from "../../version.ts";
 import {
@@ -10,8 +9,7 @@ import {
   signalSupervisorUpgrade,
 } from "../../services/upgrade.service.ts";
 import { ok, err } from "../../types/api.ts";
-
-const STATUS_FILE = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"), "status.json");
+import { getPpmDir } from "../../services/ppm-dir.ts";
 
 export const upgradeRoutes = new Hono();
 
@@ -19,8 +17,8 @@ export const upgradeRoutes = new Hono();
 upgradeRoutes.get("/", (c) => {
   let availableVersion: string | null = null;
   try {
-    if (existsSync(STATUS_FILE)) {
-      const data = JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+    if (existsSync(resolve(getPpmDir(), "status.json"))) {
+      const data = JSON.parse(readFileSync(resolve(getPpmDir(), "status.json"), "utf-8"));
       const candidate = data.availableVersion ?? null;
       // Only report if actually newer than current version
       if (candidate && compareSemver(VERSION, candidate) < 0) {

package/src/server/ws/chat.ts

@@ -85,6 +85,21 @@ function bufferAndBroadcast(sessionId: string, event: unknown): void {
     if (entry.turnEvents.length < MAX_TURN_EVENTS) {
       entry.turnEvents.push({ ...(event as Record<string, unknown>) });
     }
+    // Enrich: embed tool_result onto matching tool_use for reconnect reliability.
+    // Reconnecting clients may miss separate tool_result events — this ensures
+    // the tool_use event itself carries the result as a fallback.
+    if (evType === "tool_result") {
+      const toolUseId = (event as any)?.toolUseId;
+      if (toolUseId) {
+        for (let i = entry.turnEvents.length - 1; i >= 0; i--) {
+          const buffered = entry.turnEvents[i] as any;
+          if (buffered.type === "tool_use" && buffered.toolUseId === toolUseId) {
+            buffered.result = { output: (event as any).output, isError: (event as any).isError };
+            break;
+          }
+        }
+      }
+    }
   }
   broadcast(sessionId, event);
 }
@@ -567,6 +582,22 @@ export const chatWebSocket = {
         entry.permissionMode = parsed.permissionMode;
       }
 
+      // Intercept PPM-handled built-in commands (e.g. /skills, /version)
+      const content = parsed.content.trim();
+      const slashMatch = content.match(/^\/(\S+)/);
+      if (slashMatch) {
+        const { isPpmHandled, executeBuiltin } = await import("../../services/slash-discovery/index.ts");
+        const cmdName = slashMatch[1]!;
+        if (isPpmHandled(cmdName)) {
+          const response = executeBuiltin(cmdName, entry.projectPath ?? "");
+          if (response) {
+            broadcast(sessionId, { type: "text", content: response });
+            broadcast(sessionId, { type: "done", resultSubtype: "builtin", numTurns: 0 });
+            return;
+          }
+        }
+      }
+
       const provider = providerRegistry.get(providerId);
 
       if (!entry.isStreamingActive) {

package/src/services/cloud-ws.service.ts

@@ -4,7 +4,7 @@
  */
 import { appendFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { homedir } from "node:os";
+import { getPpmDir } from "./ppm-dir.ts";
 
 // ─── Types (must match Cloud's ws-types.ts) ─────────
 interface WsMessage {
@@ -152,7 +152,9 @@ function doConnect(): void {
   sock.onopen = () => {
     if (ws !== sock) return; // stale — newer connection replaced us
     reconnecting = false;
-    reconnectAttempt = 0;
+    // Don't reset reconnectAttempt here — only after auth succeeds.
+    // Resetting on open causes tight reconnect loops when the server
+    // keeps closing immediately after connect (backoff never builds up).
     log("INFO", "Cloud WS connected, sending auth");
 
     // Send auth as first message — server must process this before any other msg
@@ -170,6 +172,7 @@ function doConnect(): void {
     setTimeout(() => {
       if (ws !== sock) return; // replaced during delay
       connected = true;
+      reconnectAttempt = 0; // Auth succeeded — reset backoff
 
       // Flush queued messages
       while (outboundQueue.length > 0 && connected) {
@@ -234,6 +237,6 @@ function scheduleReconnect(source = "unknown"): void {
 
 function log(level: string, msg: string): void {
   const ts = new Date().toISOString();
-  const logFile = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"), "ppm.log");
+  const logFile = resolve(getPpmDir(), "ppm.log");
   try { appendFileSync(logFile, `[${ts}] [${level}] [cloud-ws] ${msg}\n`); } catch {}
 }

package/src/services/cloud.service.ts

@@ -1,14 +1,14 @@
 import { resolve } from "node:path";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { VERSION } from "../version.ts";
 import { configService } from "./config.service.ts";
+import { getPpmDir } from "./ppm-dir.ts";
 
-const PPM_DIR = resolve(homedir(), ".ppm");
-const AUTH_FILE = resolve(PPM_DIR, "cloud-auth.json");
-const DEVICE_FILE = resolve(PPM_DIR, "cloud-device.json");
-const MACHINE_ID_FILE = resolve(PPM_DIR, "machine-id");
+const authFile = () => resolve(getPpmDir(), "cloud-auth.json");
+const deviceFile = () => resolve(getPpmDir(), "cloud-device.json");
+const machineIdFile = () => resolve(getPpmDir(), "machine-id");
 
 const DEFAULT_CLOUD_URL = "https://ppm.hienle.tech";
 const HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
@@ -47,12 +47,12 @@ interface DeviceInfo {
 
 /** Get or generate a stable machine ID (random UUID, persists across reboots) */
 export function getMachineId(): string {
-  if (existsSync(MACHINE_ID_FILE)) {
-    return readFileSync(MACHINE_ID_FILE, "utf-8").trim();
+  if (existsSync(machineIdFile())) {
+    return readFileSync(machineIdFile(), "utf-8").trim();
   }
   const id = randomBytes(16).toString("hex");
   ensurePpmDir();
-  writeFileSync(MACHINE_ID_FILE, id);
+  writeFileSync(machineIdFile(), id);
   return id;
 }
 
@@ -61,8 +61,8 @@ export function getMachineId(): string {
 /** Read saved cloud auth credentials */
 export function getCloudAuth(): CloudAuth | null {
   try {
-    if (!existsSync(AUTH_FILE)) return null;
-    return JSON.parse(readFileSync(AUTH_FILE, "utf-8"));
+    if (!existsSync(authFile())) return null;
+    return JSON.parse(readFileSync(authFile(), "utf-8"));
   } catch {
     return null;
   }
@@ -71,13 +71,13 @@ export function getCloudAuth(): CloudAuth | null {
 /** Save cloud auth credentials (restricted permissions) */
 export function saveCloudAuth(auth: CloudAuth): void {
   ensurePpmDir();
-  writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2));
-  try { chmodSync(AUTH_FILE, 0o600); } catch {}
+  writeFileSync(authFile(), JSON.stringify(auth, null, 2));
+  try { chmodSync(authFile(), 0o600); } catch {}
 }
 
 /** Remove cloud auth credentials */
 export function removeCloudAuth(): void {
-  try { if (existsSync(AUTH_FILE)) unlinkSync(AUTH_FILE); } catch {}
+  try { if (existsSync(authFile())) unlinkSync(authFile()); } catch {}
 }
 
 // ─── Device ─────────────────────────────────────────────────────────────
@@ -85,8 +85,8 @@ export function removeCloudAuth(): void {
 /** Read saved cloud device info */
 export function getCloudDevice(): CloudDevice | null {
   try {
-    if (!existsSync(DEVICE_FILE)) return null;
-    return JSON.parse(readFileSync(DEVICE_FILE, "utf-8"));
+    if (!existsSync(deviceFile())) return null;
+    return JSON.parse(readFileSync(deviceFile(), "utf-8"));
   } catch {
     return null;
   }
@@ -95,13 +95,13 @@ export function getCloudDevice(): CloudDevice | null {
 /** Save cloud device info (restricted permissions) */
 export function saveCloudDevice(device: CloudDevice): void {
   ensurePpmDir();
-  writeFileSync(DEVICE_FILE, JSON.stringify(device, null, 2));
-  try { chmodSync(DEVICE_FILE, 0o600); } catch {}
+  writeFileSync(deviceFile(), JSON.stringify(device, null, 2));
+  try { chmodSync(deviceFile(), 0o600); } catch {}
 }
 
 /** Remove cloud device info */
 export function removeCloudDevice(): void {
-  try { if (existsSync(DEVICE_FILE)) unlinkSync(DEVICE_FILE); } catch {}
+  try { if (existsSync(deviceFile())) unlinkSync(deviceFile()); } catch {}
 }
 
 // ─── API Client ─────────────────────────────────────────────────────────
@@ -398,7 +398,8 @@ export function stopHeartbeat(): void {
 // ─── Helpers ────────────────────────────────────────────────────────────
 
 function ensurePpmDir(): void {
-  if (!existsSync(PPM_DIR)) mkdirSync(PPM_DIR, { recursive: true });
+  const dir = getPpmDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
 function openBrowser(url: string): void {

package/src/services/cloudflared.service.ts

@@ -1,10 +1,10 @@
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import { existsSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
+import { getPpmDir } from "./ppm-dir.ts";
 
-const CLOUDFLARED_DIR = resolve(homedir(), ".ppm", "bin");
 const isWindows = process.platform === "win32";
-const CLOUDFLARED_PATH = resolve(CLOUDFLARED_DIR, isWindows ? "cloudflared.exe" : "cloudflared");
+const cloudflaredDir = () => resolve(getPpmDir(), "bin");
+const cloudflaredPath = () => resolve(cloudflaredDir(), isWindows ? "cloudflared.exe" : "cloudflared");
 
 const OS_MAP: Record<string, string> = { darwin: "darwin", linux: "linux", win32: "windows" };
 const ARCH_MAP: Record<string, string> = { x64: "amd64", arm64: "arm64" };
@@ -67,40 +67,40 @@ async function extractTgz(tgzPath: string, destDir: string): Promise<void> {
  * Downloads from GitHub releases if missing. Returns path to binary.
  */
 export async function ensureCloudflared(): Promise<string> {
-  if (existsSync(CLOUDFLARED_PATH)) return CLOUDFLARED_PATH;
+  if (existsSync(cloudflaredPath())) return cloudflaredPath();
 
-  if (!existsSync(CLOUDFLARED_DIR)) {
-    mkdirSync(CLOUDFLARED_DIR, { recursive: true });
+  if (!existsSync(cloudflaredDir())) {
+    mkdirSync(cloudflaredDir(), { recursive: true });
   }
 
   const url = getDownloadUrl();
   const isTgz = url.endsWith(".tgz");
   const isExe = url.endsWith(".exe");
-  const tmpPath = resolve(CLOUDFLARED_DIR, isTgz ? "cloudflared.tgz" : isExe ? "cloudflared.exe.tmp" : "cloudflared.tmp");
+  const tmpPath = resolve(cloudflaredDir(), isTgz ? "cloudflared.tgz" : isExe ? "cloudflared.exe.tmp" : "cloudflared.tmp");
 
   try {
     const data = await downloadWithProgress(url);
     await Bun.write(tmpPath, data);
 
     if (isTgz) {
-      await extractTgz(tmpPath, CLOUDFLARED_DIR);
+      await extractTgz(tmpPath, cloudflaredDir());
       unlinkSync(tmpPath);
     } else {
-      renameSync(tmpPath, CLOUDFLARED_PATH);
+      renameSync(tmpPath, cloudflaredPath());
     }
     if (!isWindows) {
-      chmodSync(CLOUDFLARED_PATH, 0o755);
+      chmodSync(cloudflaredPath(), 0o755);
     }
   } catch (err) {
     try { unlinkSync(tmpPath); } catch {}
-    try { unlinkSync(CLOUDFLARED_PATH); } catch {}
+    try { unlinkSync(cloudflaredPath()); } catch {}
     throw err;
   }
 
-  return CLOUDFLARED_PATH;
+  return cloudflaredPath();
 }
 
 /** Get path where cloudflared binary is/will be stored */
 export function getCloudflaredPath(): string {
-  return CLOUDFLARED_PATH;
+  return cloudflaredPath();
 }

package/src/services/config.service.ts

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync, renameSync } from "node:fs";
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import type { PpmConfig, ProjectConfig } from "../types/config.ts";
 import { DEFAULT_CONFIG, sanitizeConfig } from "../types/config.ts";
@@ -14,8 +13,7 @@ import {
   getDb,
   getDbFilePath,
 } from "./db.service.ts";
-
-const PPM_DIR = resolve(homedir(), ".ppm");
+import { getPpmDir } from "./ppm-dir.ts";
 
 /** Top-level config keys stored in the config table (not projects) */
 const CONFIG_TABLE_KEYS: (keyof PpmConfig)[] = [
@@ -148,8 +146,8 @@ class ConfigService {
 
   private migrateYamlIfNeeded(): void {
     const yamlPaths = [
-      resolve(PPM_DIR, "config.yaml"),
-      resolve(PPM_DIR, "config.dev.yaml"),
+      resolve(getPpmDir(), "config.yaml"),
+      resolve(getPpmDir(), "config.dev.yaml"),
     ];
     for (const yamlPath of yamlPaths) {
       if (!existsSync(yamlPath)) continue;
@@ -187,7 +185,7 @@ class ConfigService {
   }
 
   private migrateSessionMapIfNeeded(): void {
-    const mapPath = resolve(PPM_DIR, "session-map.json");
+    const mapPath = resolve(getPpmDir(), "session-map.json");
     if (!existsSync(mapPath)) return;
     try {
       const { setSessionMetadata } = require("./db.service.ts");
@@ -202,7 +200,7 @@ class ConfigService {
   }
 
   private migratePushSubsIfNeeded(): void {
-    const subsPath = resolve(PPM_DIR, "push-subscriptions.json");
+    const subsPath = resolve(getPpmDir(), "push-subscriptions.json");
     if (!existsSync(subsPath)) return;
     try {
       const { upsertPushSubscription } = require("./db.service.ts");

package/src/services/db.service.ts

@@ -1,10 +1,8 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import { mkdirSync, existsSync } from "node:fs";
 import { encrypt, decrypt } from "../lib/account-crypto.ts";
-
-const PPM_DIR = process.env.PPM_HOME || resolve(homedir(), ".ppm");
+import { getPpmDir } from "./ppm-dir.ts";
 const CURRENT_SCHEMA_VERSION = 15;
 
 let db: Database | null = null;
@@ -17,14 +15,15 @@ export function setDbProfile(profile: string | null): void {
 }
 
 function getDbPath(): string {
-  if (dbProfile) return resolve(PPM_DIR, `ppm.${dbProfile}.db`);
-  return resolve(PPM_DIR, "ppm.db");
+  if (dbProfile) return resolve(getPpmDir(), `ppm.${dbProfile}.db`);
+  return resolve(getPpmDir(), "ppm.db");
 }
 
 /** Get or create the singleton DB instance (lazy init) */
 export function getDb(): Database {
   if (db) return db;
-  if (!existsSync(PPM_DIR)) mkdirSync(PPM_DIR, { recursive: true });
+  const ppmDir = getPpmDir();
+  if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
   db = new Database(getDbPath());
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");

package/src/services/extension-rpc-handlers.ts

@@ -156,8 +156,8 @@ export function registerVscodeCompatHandlers(rpc: RpcChannel): void {
     const { resolve, relative } = await import("node:path");
     const resolved = resolve(filePath);
     // Allow: CWD (project root) and ~/.ppm/extensions/ (extension storage)
-    const { homedir } = await import("node:os");
-    const allowedRoots = [resolve(process.cwd()), resolve(homedir(), ".ppm", "extensions")];
+    const { getPpmDir } = await import("./ppm-dir.ts");
+    const allowedRoots = [resolve(process.cwd()), resolve(getPpmDir(), "extensions")];
     const isSafe = allowedRoots.some((root) => {
       const rel = relative(root, resolved);
       return !rel.startsWith("..") && !rel.startsWith("/");

package/src/services/extension.service.ts

@@ -1,5 +1,4 @@
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import type { ExtensionManifest, ExtensionInfo, RpcMessage } from "../types/extension.ts";
 import { getExtensions, getExtensionById, insertExtension, getExtensionStorage, setExtensionStorageValue } from "./db.service.ts";
@@ -8,9 +7,7 @@ import { RpcChannel } from "./extension-rpc.ts";
 import { parseManifest, discoverManifests } from "./extension-manifest.ts";
 import { installExtension, removeExtension, devLinkExtension, ensureExtensionsDir } from "./extension-installer.ts";
 import { registerVscodeCompatHandlers } from "./extension-rpc-handlers.ts";
-
-const PPM_DIR = process.env.PPM_HOME || resolve(homedir(), ".ppm");
-const EXTENSIONS_DIR = resolve(PPM_DIR, "extensions");
+import { getPpmDir } from "./ppm-dir.ts";
 
 class ExtensionService {
   private worker: Worker | null = null;
@@ -67,15 +64,15 @@ class ExtensionService {
   }
 
   async discover(): Promise<ExtensionManifest[]> {
-    ensureExtensionsDir(EXTENSIONS_DIR);
-    return discoverManifests(EXTENSIONS_DIR);
+    ensureExtensionsDir(resolve(getPpmDir(), "extensions"));
+    return discoverManifests(resolve(getPpmDir(), "extensions"));
   }
 
   async install(name: string): Promise<ExtensionManifest> {
     if (this.installing.has(name)) throw new Error(`Already installing ${name}`);
     this.installing.add(name);
     try {
-      return await installExtension(name, EXTENSIONS_DIR);
+      return await installExtension(name, resolve(getPpmDir(), "extensions"));
     } finally {
       this.installing.delete(name);
     }
@@ -83,7 +80,7 @@ class ExtensionService {
 
   async remove(id: string): Promise<void> {
     if (this.activatedIds.has(id)) await this.deactivate(id);
-    await removeExtension(id, EXTENSIONS_DIR);
+    await removeExtension(id, resolve(getPpmDir(), "extensions"));
     contributionRegistry.unregister(id);
   }
 
@@ -95,7 +92,7 @@ class ExtensionService {
     if (!row.enabled) throw new Error(`Extension ${id} is disabled`);
 
     const manifest: ExtensionManifest = JSON.parse(row.manifest);
-    const extDir = resolve(EXTENSIONS_DIR, "node_modules", id);
+    const extDir = resolve(resolve(getPpmDir(), "extensions"), "node_modules", id);
     const entryPath = resolve(extDir, manifest.main);
     if (!existsSync(entryPath)) throw new Error(`Entry point not found: ${entryPath}`);
 
@@ -176,7 +173,7 @@ class ExtensionService {
   }
 
   async devLink(localPath: string): Promise<ExtensionManifest> {
-    const manifest = devLinkExtension(localPath, EXTENSIONS_DIR);
+    const manifest = devLinkExtension(localPath, resolve(getPpmDir(), "extensions"));
     // Auto-activate after dev-link (DB record is created with enabled=1)
     if (!this.activatedIds.has(manifest.id)) {
       try { await this.activate(manifest.id); } catch (e) {
@@ -187,7 +184,7 @@ class ExtensionService {
   }
 
   async startup(): Promise<void> {
-    ensureExtensionsDir(EXTENSIONS_DIR);
+    ensureExtensionsDir(resolve(getPpmDir(), "extensions"));
     const manifests = await this.discover();
     for (const m of manifests) {
       if (!getExtensionById(m.id)) {
@@ -214,7 +211,7 @@ class ExtensionService {
   }
 
   isActivated(id: string): boolean { return this.activatedIds.has(id); }
-  getExtensionsDir(): string { return EXTENSIONS_DIR; }
+  getExtensionsDir(): string { return resolve(getPpmDir(), "extensions"); }
 
   /** Push current contributions to all connected browser clients */
   private broadcastContributions(): void {