@hienlh/ppm 0.8.14 → 0.8.15

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.8.15] - 2026-03-24
+
+### Fixed
+- **Usage polling reliability**: Replace `setInterval` with recursive `setTimeout` to prevent overlap and timer death from unhandled async rejections; wrap `pollOnce` in try/catch
+
+### Added
+- **Lowest-usage account strategy**: New `lowest-usage` routing strategy picks account with lowest 5-hour utilization, skips accounts at 100% weekly/5hr, falls back gracefully when all exhausted
+
 ## [0.8.14] - 2026-03-24
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.14",
+  "version": "0.8.15",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "start": "bun run src/index.ts start",
     "typecheck": "bunx tsc --noEmit",
     "prepublishOnly": "bun run build:web",
-    "postinstall": "echo 'postinstall done'"
+    "postinstall": "node scripts/patch-sdk.mjs"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.1",

package/scripts/patch-sdk.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Postinstall patch for @anthropic-ai/claude-agent-sdk
+ *
+ * Fixes Windows + Bun subprocess pipe issues:
+ * 1. Adding drain() handling to ProcessTransport.write()
+ * 2. Awaiting the initial prompt write in query() entry point
+ * 3. Replacing readline async iterator with manual line reader in readMessages()
+ *
+ * Bun on Windows has broken: stdin pipe backpressure, unawaited async writes,
+ * and readline.createInterface() async iterator (Symbol.asyncIterator).
+ *
+ * Tracking issues:
+ *   - TS SDK #44: https://github.com/anthropics/claude-agent-sdk-typescript/issues/44
+ *   - TS SDK #64: https://github.com/anthropics/claude-agent-sdk-typescript/issues/64
+ *
+ * Remove this patch when upstream fixes land.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const sdkPath = join(
+  import.meta.dirname,
+  "..",
+  "node_modules",
+  "@anthropic-ai",
+  "claude-agent-sdk",
+  "sdk.mjs",
+);
+
+if (!existsSync(sdkPath)) {
+  console.log("[patch-sdk] SDK not found, skipping patch");
+  process.exit(0);
+}
+
+let content = readFileSync(sdkPath, "utf8");
+let patches = 0;
+
+// ── Patch 1: ProcessTransport.write() — add drain handling ──
+
+if (content.includes("waiting for drain")) {
+  console.log("[patch-sdk] Patch 1 (drain): already applied");
+} else {
+  // Surgical approach: find the backpressure line and patch it
+  const drainPattern =
+    /if\(!this\.processStdin\.write\(([A-Za-z_$][A-Za-z0-9_$]*)\)\)([A-Za-z_$][A-Za-z0-9_$]*)\("\[ProcessTransport\] Write buffer full, data queued"\)/;
+  const drainMatch = content.match(drainPattern);
+
+  if (!drainMatch) {
+    console.warn("[patch-sdk] Patch 1 (drain): pattern not found, skipping");
+  } else {
+    const oldLine = drainMatch[0];
+    const arg = drainMatch[1];
+    const logger = drainMatch[2];
+
+    // Replace backpressure line: await drain instead of just logging
+    const newLine =
+      `if(!this.processStdin.write(${arg})){` +
+      `${logger}("[ProcessTransport] Write buffer full, waiting for drain");` +
+      `await new Promise(_dr=>this.processStdin.once("drain",_dr))}`;
+
+    content = content.replace(oldLine, newLine);
+
+    // Make the method async
+    const writeIdx = content.indexOf(newLine);
+    const oldDecl = `write(${arg}){`;
+    const declIdx = content.lastIndexOf(oldDecl, writeIdx);
+    if (declIdx >= 0) {
+      content =
+        content.substring(0, declIdx) +
+        `async write(${arg}){` +
+        content.substring(declIdx + oldDecl.length);
+    }
+
+    patches++;
+    console.log("[patch-sdk] Patch 1 (drain): applied");
+  }
+}
+
+// ── Patch 2: Await initial prompt write in query() entry point ──
+// The query() function writes the user prompt to transport.write() without
+// awaiting. Since write() is now async (returns Promise on backpressure),
+// the prompt data can be lost on Windows where pipe buffers are small.
+//
+// Pattern (minified):
+//   if(typeof Q==="string")TRANSPORT.write(SERIALIZE({type:"user",...})+"\n");
+//   else QUERY.streamInput(Q);
+//
+// We need to await the write and make the surrounding context async-compatible.
+// Since write is fire-and-forget here (the Promise is dropped), we wrap it.
+
+if (content.includes("__ppm_await_write__")) {
+  console.log("[patch-sdk] Patch 2 (await prompt): already applied");
+} else {
+  // Match: TRANSPORT.write(SERIALIZE({type:"user",...})+`\n`);
+  // Anchor on stable string literals: type:"user",session_id:"",message:{role:"user"
+  const promptWritePattern =
+    /([A-Za-z_$][A-Za-z0-9_$]*)\.write\(([A-Za-z_$][A-Za-z0-9_$]*)\(\{type:"user",session_id:"",message:\{role:"user",content:\[\{type:"text",text:([A-Za-z_$][A-Za-z0-9_$]*)\}\]\},parent_tool_use_id:null\}\)\+(?:`\n`|"\\n")\)/;
+  const promptMatch = content.match(promptWritePattern);
+
+  if (!promptMatch) {
+    console.warn(
+      "[patch-sdk] Patch 2 (await prompt): pattern not found, skipping",
+    );
+  } else {
+    const oldPromptWrite = promptMatch[0];
+    // Wrap in async IIFE — keeps query() sync so callers don't need `await query()`
+    const newPromptWrite =
+      `/*__ppm_await_write__*/(async()=>{await ${oldPromptWrite}})()`;
+
+    content = content.replace(oldPromptWrite, newPromptWrite);
+    patches++;
+    console.log("[patch-sdk] Patch 2 (await prompt): applied");
+  }
+}
+
+// ── Patch 3: Replace readline async iterator in readMessages() ──
+// Bun on Windows doesn't implement Symbol.asyncIterator for
+// readline.createInterface(), causing "undefined is not a function"
+// when the SDK does `for await (let X of readlineInterface)`.
+//
+// Replace with a manual line reader using raw stream 'data' events.
+
+if (content.includes("__ppm_manual_readline__")) {
+  console.log("[patch-sdk] Patch 3 (readline): already applied");
+} else {
+  // Match the readMessages method by anchoring on the stable error string
+  const readMsgPattern =
+    /async\s?\*\s?readMessages\(\)\{if\(!this\.processStdout\)throw Error\("ProcessTransport output stream not available"\);let ([A-Za-z_$][A-Za-z0-9_$]*)=([A-Za-z_$][A-Za-z0-9_$]*)\(\{input:this\.processStdout\}\);try\{for await\(let ([A-Za-z_$][A-Za-z0-9_$]*) of \1\)if\(\3\.trim\(\)\)try\{yield ([A-Za-z_$][A-Za-z0-9_$]*)\(\3\)\}catch\(([A-Za-z_$][A-Za-z0-9_$]*)\)\{throw ([A-Za-z_$][A-Za-z0-9_$]*)\(`Non-JSON stdout: \$\{\3\}`\),Error\(`CLI output was not valid JSON\. This may indicate an error during startup\. Output: \$\{\3\.slice\(0,200\)\}\$\{\3\.length>200\?"\.\.\.":""\}`\)\}await this\.waitForExit\(\)\}catch\(\3\)\{throw \3\}finally\{\1\.close\(\)\}\}/;
+  const readMsgMatch = content.match(readMsgPattern);
+
+  if (!readMsgMatch) {
+    console.warn(
+      "[patch-sdk] Patch 3 (readline): pattern not found, skipping",
+    );
+  } else {
+    const oldReadMsg = readMsgMatch[0];
+    const rlVar = readMsgMatch[1];     // Q (readline interface)
+    const createRL = readMsgMatch[2];   // DU (createInterface)
+    const lineVar = readMsgMatch[3];    // X (line variable)
+    const parseJSON = readMsgMatch[4];  // O1 (JSON parser)
+    const errVar = readMsgMatch[5];     // Y (error variable)
+    const logger = readMsgMatch[6];     // i0 (logger)
+
+    // Manual line reader: use stream 'data' events + buffer splitting
+    // This avoids readline's broken async iterator on Bun/Windows
+    const newReadMsg =
+      `/*__ppm_manual_readline__*/async*readMessages(){` +
+      `if(!this.processStdout)throw Error("ProcessTransport output stream not available");` +
+      // Create a manual async line iterator using stream events
+      `let _buf="";` +
+      `const _lines=[];` +
+      `let _done=false;` +
+      `let _err=null;` +
+      `let _resolve=null;` +
+      `const _notify=()=>{if(_resolve){const r=_resolve;_resolve=null;r()}};` +
+      `this.processStdout.setEncoding("utf8");` +
+      `this.processStdout.on("data",(chunk)=>{` +
+        `_buf+=chunk;` +
+        `let nl;` +
+        `while((nl=_buf.indexOf("\\n"))!==-1){` +
+          `_lines.push(_buf.slice(0,nl));` +
+          `_buf=_buf.slice(nl+1)` +
+        `}` +
+        `_notify()` +
+      `});` +
+      `this.processStdout.on("end",()=>{` +
+        `if(_buf.trim())_lines.push(_buf);` +
+        `_buf="";_done=true;_notify()` +
+      `});` +
+      `this.processStdout.on("error",(e)=>{_err=e;_done=true;_notify()});` +
+      `try{` +
+        `while(true){` +
+          `while(_lines.length>0){` +
+            `const ${lineVar}=_lines.shift();` +
+            `if(${lineVar}.trim())` +
+              `try{yield ${parseJSON}(${lineVar})}` +
+              `catch(${errVar}){` +
+                `throw ${logger}(\`Non-JSON stdout: \${${lineVar}}\`),` +
+                `Error(\`CLI output was not valid JSON. This may indicate an error during startup. Output: \${${lineVar}.slice(0,200)}\${${lineVar}.length>200?"...":""}\`)` +
+              `}` +
+          `}` +
+          `if(_err)throw _err;` +
+          `if(_done)break;` +
+          `await new Promise(r=>{_resolve=r})` +
+        `}` +
+        `await this.waitForExit()` +
+      `}catch(${lineVar}){throw ${lineVar}}}`;
+
+    content = content.replace(oldReadMsg, newReadMsg);
+    patches++;
+    console.log("[patch-sdk] Patch 3 (readline): applied");
+  }
+}
+
+if (patches > 0) {
+  writeFileSync(sdkPath, content, "utf8");
+  console.log(`[patch-sdk] Done — ${patches} patch(es) written`);
+} else {
+  console.log("[patch-sdk] No patches needed");
+}

package/scripts/test-drain-bug.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Reproduces the stdin backpressure bug that causes SDK to hang on Windows.
+ *
+ * The issue: ProcessTransport.write() calls stdin.write() but ignores the
+ * return value (false = buffer full). Without awaiting 'drain', the subprocess
+ * may never receive the data — causing a hang.
+ *
+ * This script simulates the scenario with a slow-reading subprocess.
+ * On macOS/Linux the OS pipe buffer is larger (64KB+), so we write enough
+ * to overflow it. On Windows + Bun, even small writes can trigger this.
+ *
+ * Usage: node scripts/test-drain-bug.mjs
+ */
+
+import { spawn } from "node:child_process";
+
+// Subprocess that reads stdin slowly (simulates claude CLI processing)
+const slowReader = spawn("node", [
+  "-e",
+  `
+  // Read stdin 1 byte at a time with delays to create backpressure
+  process.stdin.setEncoding("utf8");
+  let total = 0;
+  process.stdin.on("data", (chunk) => {
+    total += chunk.length;
+    // Pause stdin to simulate slow processing (like claude thinking)
+    process.stdin.pause();
+    setTimeout(() => process.stdin.resume(), 50);
+  });
+  process.stdin.on("end", () => {
+    process.stdout.write(JSON.stringify({ received: total }));
+  });
+  `,
+]);
+
+const CHUNK = "x".repeat(1024); // 1KB chunk
+const TOTAL_WRITES = 256; // 256KB total — enough to overflow pipe buffer
+
+// ── Test 1: WITHOUT drain (current SDK behavior) ──
+console.log("=== Test 1: Write WITHOUT drain (current SDK bug) ===");
+let writesFailed = 0;
+let writesOk = 0;
+
+for (let i = 0; i < TOTAL_WRITES; i++) {
+  const ok = slowReader.stdin.write(CHUNK);
+  if (!ok) writesFailed++;
+  else writesOk++;
+}
+slowReader.stdin.end();
+
+let output = "";
+slowReader.stdout.on("data", (d) => (output += d));
+
+await new Promise((resolve) => slowReader.on("close", resolve));
+const result1 = JSON.parse(output || '{"received":0}');
+
+console.log(`  Writes OK:     ${writesOk}`);
+console.log(`  Writes FULL:   ${writesFailed} (buffer was full, SDK just logs & continues)`);
+console.log(`  Data sent:     ${TOTAL_WRITES * 1024} bytes`);
+console.log(`  Data received: ${result1.received} bytes`);
+console.log(
+  `  Lost data:     ${writesFailed > 0 ? "POSSIBLE — depends on OS buffer behavior" : "none (buffer was big enough)"}`,
+);
+
+// ── Test 2: WITH drain (patched behavior) ──
+console.log("\n=== Test 2: Write WITH drain (patched SDK) ===");
+
+const slowReader2 = spawn("node", [
+  "-e",
+  `
+  process.stdin.setEncoding("utf8");
+  let total = 0;
+  process.stdin.on("data", (chunk) => {
+    total += chunk.length;
+    process.stdin.pause();
+    setTimeout(() => process.stdin.resume(), 50);
+  });
+  process.stdin.on("end", () => {
+    process.stdout.write(JSON.stringify({ received: total }));
+  });
+  `,
+]);
+
+let drainWaits = 0;
+const start = Date.now();
+
+for (let i = 0; i < TOTAL_WRITES; i++) {
+  const ok = slowReader2.stdin.write(CHUNK);
+  if (!ok) {
+    drainWaits++;
+    await new Promise((r) => slowReader2.stdin.once("drain", r));
+  }
+}
+slowReader2.stdin.end();
+
+let output2 = "";
+slowReader2.stdout.on("data", (d) => (output2 += d));
+await new Promise((resolve) => slowReader2.on("close", resolve));
+const result2 = JSON.parse(output2 || '{"received":0}');
+const elapsed = Date.now() - start;
+
+console.log(`  Drain waits:   ${drainWaits}`);
+console.log(`  Data sent:     ${TOTAL_WRITES * 1024} bytes`);
+console.log(`  Data received: ${result2.received} bytes`);
+console.log(`  Match:         ${result2.received === TOTAL_WRITES * 1024 ? "YES — all data delivered" : "NO — data lost!"}`);
+console.log(`  Time:          ${elapsed}ms (slower due to drain waits, but reliable)`);
+
+// ── Summary ──
+console.log("\n=== Summary ===");
+if (writesFailed > 0) {
+  console.log(
+    `Buffer overflowed ${writesFailed}x in Test 1 (no drain).`,
+  );
+  console.log(
+    "On Windows + Bun, this causes the SDK subprocess to hang indefinitely.",
+  );
+  console.log(
+    "The patch adds 'await drain' to prevent data loss → fixes the hang.",
+  );
+} else {
+  console.log(
+    "Buffer did NOT overflow on this OS (macOS/Linux has large pipe buffers).",
+  );
+  console.log(
+    "On Windows + Bun, pipe buffers are smaller → overflow happens even with small prompts.",
+  );
+  console.log(
+    "The patch is still correct: it's a no-op when write() returns true.",
+  );
+}

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

@@ -17,6 +17,7 @@ import { getSessionMapping, setSessionMapping } from "../services/db.service.ts"
 import { accountSelector } from "../services/account-selector.service.ts";
 import { accountService } from "../services/account.service.ts";
 import { resolve } from "node:path";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 
 function getSdkSessionId(ppmId: string): string {
@@ -537,7 +538,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       const sdkId = shouldFork ? getSdkSessionId(forkSourceId!) : getSdkSessionId(sessionId);
       // Fallback cwd: SDK needs a valid working directory even when no project is selected.
       // On Windows daemons, undefined cwd can cause the subprocess to fail silently.
-      const effectiveCwd = meta.projectPath || homedir();
+      // Resolve path and validate existence — invalid cwd causes spawn to hang on Windows.
+      const rawCwd = meta.projectPath || homedir();
+      const effectiveCwd = existsSync(rawCwd) ? rawCwd : homedir();
 
       // Account-based auth injection (multi-account mode)
       // Fallback to existing env (ANTHROPIC_API_KEY) when no accounts configured.

package/src/services/account-selector.service.ts

@@ -1,7 +1,7 @@
 import { accountService, type AccountWithTokens } from "./account.service.ts";
-import { getConfigValue, setConfigValue } from "./db.service.ts";
+import { getConfigValue, setConfigValue, getLatestSnapshotForAccount } from "./db.service.ts";
 
-export type AccountStrategy = "round-robin" | "fill-first";
+export type AccountStrategy = "round-robin" | "fill-first" | "lowest-usage";
 
 const STRATEGY_CONFIG_KEY = "account_strategy";
 const MAX_RETRY_CONFIG_KEY = "account_max_retry";
@@ -68,7 +68,10 @@ class AccountSelectorService {
     }
 
     let pickedId: string;
-    if (this.getStrategy() === "fill-first") {
+    const strategy = this.getStrategy();
+    if (strategy === "lowest-usage") {
+      pickedId = this.pickLowestUsage(active);
+    } else if (strategy === "fill-first") {
       const sorted = [...active].sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt);
       pickedId = sorted[0]!.id;
     } else {
@@ -85,6 +88,33 @@ class AccountSelectorService {
     return result;
   }
 
+  /**
+   * Pick account with lowest 5-hour utilization.
+   * Skips accounts with weekly >= 100% (fully exhausted).
+   * Accounts with no usage data are treated as 0% (preferred).
+   * Falls back to round-robin if all accounts are maxed.
+   */
+  private pickLowestUsage(active: { id: string; createdAt: number }[]): string {
+    const scored = active.map((acc) => {
+      const snap = getLatestSnapshotForAccount(acc.id);
+      const fiveHour = snap?.five_hour_util ?? 0;
+      const weekly = snap?.weekly_util ?? 0;
+      // weekly >= 1.0 means fully exhausted — mark as unavailable
+      const exhausted = weekly >= 1.0 || fiveHour >= 1.0;
+      return { id: acc.id, fiveHour, weekly, exhausted };
+    });
+
+    const available = scored.filter((s) => !s.exhausted);
+    if (available.length > 0) {
+      available.sort((a, b) => a.fiveHour - b.fiveHour || a.weekly - b.weekly);
+      return available[0]!.id;
+    }
+
+    // All exhausted — fallback: pick the one with earliest reset (lowest current util)
+    scored.sort((a, b) => a.fiveHour - b.fiveHour || a.weekly - b.weekly);
+    return scored[0]!.id;
+  }
+
   /** Called when account receives 429 — apply exponential backoff */
   onRateLimit(accountId: string): void {
     const retries = (this.retryCounts.get(accountId) ?? 0) + 1;

package/src/services/claude-usage.service.ts

@@ -225,11 +225,15 @@ async function fetchLegacySingleAccount(): Promise<void> {
 }
 
 async function pollOnce(): Promise<void> {
-  const hasAccounts = accountService.list().length > 0;
-  if (hasAccounts) {
-    await fetchAllAccountUsages();
-  } else {
-    await fetchLegacySingleAccount();
+  try {
+    const hasAccounts = accountService.list().length > 0;
+    if (hasAccounts) {
+      await fetchAllAccountUsages();
+    } else {
+      await fetchLegacySingleAccount();
+    }
+  } catch (e) {
+    console.error("[usage] pollOnce error:", (e as Error).message);
   }
 }
 
@@ -285,12 +289,19 @@ export function getCachedUsage(): ClaudeUsage & { activeAccountId?: string; acti
 
 export function startUsagePolling(): void {
   if (pollTimer) return;
-  pollOnce();
-  pollTimer = setInterval(() => pollOnce(), POLL_INTERVAL);
+  // Use recursive setTimeout instead of setInterval to prevent overlap
+  // and ensure polling continues even if a single iteration errors
+  const scheduleNext = () => {
+    pollTimer = setTimeout(async () => {
+      await pollOnce();
+      scheduleNext();
+    }, POLL_INTERVAL);
+  };
+  pollOnce().then(scheduleNext);
 }
 
 export function stopUsagePolling(): void {
-  if (pollTimer) { clearInterval(pollTimer); pollTimer = null; }
+  if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
 }
 
 export function updateFromSdkEvent(_rateLimitType?: string, _utilization?: number, costUsd?: number): void {

package/test-tool.mjs

@@ -1,9 +1,10 @@
+import { tmpdir } from "node:os";
 import { ClaudeAgentSdkProvider } from "./src/providers/claude-agent-sdk.ts";
 
 // Remove CLAUDECODE to avoid nested session error
 delete process.env.CLAUDECODE;
 
-const projectPath = process.argv[2] || "/tmp";
+const projectPath = process.argv[2] || tmpdir();
 const prompt = process.argv[3] || "Run bash: echo TOOL_TEST_OK";
 
 console.log(`Testing tools with projectPath: ${projectPath}`);