@hienlh/ppm 0.9.19 → 0.9.21

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

@@ -784,6 +784,41 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             continue;
           }
 
+          // Intercept SDK's internal api_retry with 401 — the SDK will retry up to 10 times
+          // with exponential backoff using the same expired token, wasting 2+ minutes.
+          // Instead, refresh the OAuth token immediately and restart the query.
+          if (subtype === "api_retry" && (msg as any).error_status === 401 && account && !authRetried) {
+            authRetried = true;
+            try {
+              await accountService.refreshAccessToken(account.id, false);
+              const refreshedAccount = accountService.getWithTokens(account.id);
+              if (refreshedAccount) {
+                const label = refreshedAccount.label ?? refreshedAccount.email ?? "Unknown";
+                console.log(`[sdk] session=${sessionId} intercepted api_retry 401 — refreshing token for ${account.id} (${label})`);
+                yield { type: "account_retry" as const, reason: "Token refreshed", accountId: refreshedAccount.id, accountLabel: label };
+                const retryEnv = this.buildQueryEnv(meta.projectPath, refreshedAccount);
+                streamCtrl.done();
+                q.close();
+                const { generator: earlyAuthGen, controller: earlyAuthCtrl } = createMessageChannel();
+                const currentSdkId = getSessionMapping(sessionId);
+                const canResume = currentSdkId && currentSdkId !== sessionId;
+                if (!canResume) earlyAuthCtrl.push(firstMsg);
+                const retryOpts = { ...queryOptions, sessionId: undefined, resume: canResume ? currentSdkId : undefined, env: retryEnv };
+                const rq = query({
+                  prompt: earlyAuthGen,
+                  options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
+                });
+                this.streamingSessions.set(sessionId, { meta, query: rq, controller: earlyAuthCtrl });
+                this.activeQueries.set(sessionId, rq);
+                eventSource = rq;
+                continue retryLoop;
+              }
+            } catch (refreshErr) {
+              console.error(`[sdk] session=${sessionId} early OAuth refresh failed:`, refreshErr);
+              accountSelector.onAuthError(account.id);
+            }
+          }
+
           // Yield system events so streaming loop can transition phases
           // (e.g. connecting → thinking when hooks/init arrive)
           yield { type: "system" as any, subtype } as any;
@@ -912,11 +947,16 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                   yield { type: "account_retry" as const, reason: "Token refreshed", accountId: refreshedAccount.id, accountLabel: label };
                   const retryEnv = this.buildQueryEnv(meta.projectPath, refreshedAccount);
                   // Close failed query and old channel, create new channel + query with refreshed token.
-                  // Resume existing SDK session so conversation context is preserved.
+                  // Re-resolve sdkId: the init event may have mapped ppmId → real SDK session_id
+                  // after sdkId was originally resolved. Using the stale value would try to
+                  // resume a non-existent session, causing the SDK to hang forever.
                   streamCtrl.done();
                   q.close();
                   const { generator: authRetryGen, controller: authRetryCtrl } = createMessageChannel();
-                  const retryOpts = { ...queryOptions, sessionId: undefined, resume: sdkId, env: retryEnv };
+                  const currentSdkId = getSessionMapping(sessionId);
+                  const canResume = currentSdkId && currentSdkId !== sessionId;
+                  if (!canResume) authRetryCtrl.push(firstMsg);
+                  const retryOpts = { ...queryOptions, sessionId: undefined, resume: canResume ? currentSdkId : undefined, env: retryEnv };
                   const rq = query({
                     prompt: authRetryGen,
                     options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
@@ -963,12 +1003,15 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               yield { type: "error", message: `Rate limited. Auto-retrying in ${backoff / 1000}s... (${rateLimitRetryCount}/${MAX_RATE_LIMIT_RETRIES})` };
               await new Promise((r) => setTimeout(r, backoff));
               // Close failed query and recreate with (potentially new) account env.
-              // Resume existing SDK session so conversation context is preserved.
+              // Re-resolve sdkId to pick up init-event mapping (see auth retry comment).
               streamCtrl.done();
               q.close();
               const rlRetryEnv = this.buildQueryEnv(meta.projectPath, account);
               const { generator: rlRetryGen, controller: rlRetryCtrl } = createMessageChannel();
-              const retryOpts = { ...queryOptions, sessionId: undefined, resume: sdkId, env: rlRetryEnv };
+              const rlCurrentSdkId = getSessionMapping(sessionId);
+              const rlCanResume = rlCurrentSdkId && rlCurrentSdkId !== sessionId;
+              if (!rlCanResume) rlRetryCtrl.push(firstMsg);
+              const retryOpts = { ...queryOptions, sessionId: undefined, resume: rlCanResume ? rlCurrentSdkId : undefined, env: rlRetryEnv };
               const rq = query({
                 prompt: rlRetryGen,
                 options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
@@ -1059,12 +1102,15 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                 }
                 yield { type: "error", message: `Rate limited. Auto-retrying in ${backoff / 1000}s... (${rateLimitRetryCount}/${MAX_RATE_LIMIT_RETRIES})` };
                 await new Promise((r) => setTimeout(r, backoff));
-                // Resume existing SDK session so conversation context is preserved.
+                // Re-resolve sdkId to pick up init-event mapping (see auth retry comment).
                 streamCtrl.done();
                 q.close();
                 const rlRetryEnv = this.buildQueryEnv(meta.projectPath, account);
                 const { generator: rlRetryGen, controller: rlRetryCtrl } = createMessageChannel();
-                const retryOpts = { ...queryOptions, sessionId: undefined, resume: sdkId, env: rlRetryEnv };
+                const rlCurrentSdkId2 = getSessionMapping(sessionId);
+                const rlCanResume2 = rlCurrentSdkId2 && rlCurrentSdkId2 !== sessionId;
+                if (!rlCanResume2) rlRetryCtrl.push(firstMsg);
+                const retryOpts = { ...queryOptions, sessionId: undefined, resume: rlCanResume2 ? rlCurrentSdkId2 : undefined, env: rlRetryEnv };
                 const rq = query({
                   prompt: rlRetryGen,
                   options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,
@@ -1087,12 +1133,15 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                     const label = refreshedAccount.label ?? refreshedAccount.email ?? "Unknown";
                     console.log(`[sdk] 401 in result on account ${account.id} (${label}) — token refreshed, retrying`);
                     yield { type: "account_retry" as const, reason: "Token refreshed", accountId: refreshedAccount.id, accountLabel: label };
-                    // Resume existing SDK session so conversation context is preserved.
+                    // Re-resolve sdkId to pick up init-event mapping (see auth retry comment).
                     streamCtrl.done();
                     q.close();
                     const retryEnv = this.buildQueryEnv(meta.projectPath, refreshedAccount);
                     const { generator: authRetryGen2, controller: authRetryCtrl2 } = createMessageChannel();
-                    const retryOpts = { ...queryOptions, sessionId: undefined, resume: sdkId, env: retryEnv };
+                    const authCurrentSdkId2 = getSessionMapping(sessionId);
+                    const authCanResume2 = authCurrentSdkId2 && authCurrentSdkId2 !== sessionId;
+                    if (!authCanResume2) authRetryCtrl2.push(firstMsg);
+                    const retryOpts = { ...queryOptions, sessionId: undefined, resume: authCanResume2 ? authCurrentSdkId2 : undefined, env: retryEnv };
                     const rq = query({
                       prompt: authRetryGen2,
                       options: { ...retryOpts, ...(permissionHooks && { hooks: permissionHooks }), canUseTool } as any,

package/src/web/app.tsx

@@ -10,11 +10,9 @@ import { ProjectBottomSheet } from "@/components/layout/project-bottom-sheet";
 import { LoginScreen } from "@/components/auth/login-screen";
 import { useProjectStore, resolveOrder } from "@/stores/project-store";
 import { useTabStore } from "@/stores/tab-store";
-import { usePanelStore } from "@/stores/panel-store";
 import {
   fetchWorkspaceFromServer,
   resolveWorkspaceConflict,
-  savePanelLayout,
 } from "@/stores/panel-utils";
 import {
   useSettingsStore,
@@ -160,21 +158,26 @@ export function App() {
       }
       if (!target) return;
 
-      useProjectStore.getState().setActiveProject(target);
-
-      // Fetch server workspace + compare with localStorage (latest-wins)
+      // Fetch server workspace BEFORE activating project.
+      // setActiveProject triggers switchProject which creates an empty layout
+      // with a new timestamp if localStorage is empty (new tunnel/device).
+      // By pre-populating localStorage, switchProject picks up the server data.
       const serverLayout = await fetchWorkspaceFromServer(target.name);
       if (serverLayout) {
         const localRaw = localStorage.getItem(`ppm-panels-${target.name}`);
         const localLayout = localRaw ? JSON.parse(localRaw) : null;
         const resolved = resolveWorkspaceConflict(localLayout, serverLayout);
         if (resolved && resolved === serverLayout) {
-          // Server wins — overwrite localStorage and reload panels
-          savePanelLayout(target.name, resolved);
-          usePanelStore.getState().reloadProject(target.name);
+          // Server wins — write directly to localStorage (no server sync needed)
+          localStorage.setItem(
+            `ppm-panels-${target.name}`,
+            JSON.stringify(serverLayout),
+          );
         }
       }
 
+      useProjectStore.getState().setActiveProject(target);
+
       // Auto-open target tab from URL (type-based)
       queueMicrotask(() => {
         if (urlState.tabType) {

package/test-session-ops.mjs

@@ -0,0 +1,444 @@
+/**
+ * Test script: Advanced Session Operations
+ * Tests: listSessions, getSessionMessages, forkSession (mid-message), deleteSession, resumeSessionAt
+ *
+ * Usage: bun test-session-ops.mjs [test-name]
+ * Tests: list | messages | fork-mid | delete | resume-at | compact-summary | all
+ */
+import {
+  query,
+  listSessions,
+  getSessionMessages,
+  getSessionInfo,
+  forkSession,
+  renameSession,
+  tagSession,
+} from "@anthropic-ai/claude-agent-sdk";
+import { existsSync, unlinkSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+// Remove CLAUDECODE to avoid nested session error
+delete process.env.CLAUDECODE;
+
+const PROJECT_DIR = "/Users/hienlh/Projects/ppm";
+const CLAUDE_PROJECTS_DIR = resolve(homedir(), ".claude/projects");
+const testName = process.argv[2] || "all";
+
+// Helpers
+function log(label, data) {
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(`[${label}]`);
+  console.log("=".repeat(60));
+  if (data !== undefined) console.log(typeof data === "string" ? data : JSON.stringify(data, null, 2));
+}
+
+function logOk(msg) { console.log(`  ✅ ${msg}`); }
+function logFail(msg) { console.log(`  ❌ ${msg}`); }
+function logInfo(msg) { console.log(`  ℹ️  ${msg}`); }
+
+// ─── Test 1: List Sessions ──────────────────────────────────────────────────
+async function testListSessions() {
+  log("TEST: listSessions");
+
+  // List all sessions for PPM project
+  const sessions = await listSessions({ dir: PROJECT_DIR, limit: 10 });
+  logInfo(`Found ${sessions.length} sessions for PPM project`);
+
+  for (const s of sessions.slice(0, 5)) {
+    console.log(`  - ${s.sessionId.slice(0, 8)}... | "${s.summary?.slice(0, 50)}" | modified=${new Date(s.lastModified).toISOString().slice(0, 16)} | tag=${s.tag ?? "none"}`);
+  }
+
+  if (sessions.length > 0) logOk("listSessions works");
+  else logFail("No sessions found");
+
+  return sessions;
+}
+
+// ─── Test 2: Get Session Messages ───────────────────────────────────────────
+async function testGetMessages(sessionId) {
+  log("TEST: getSessionMessages");
+
+  if (!sessionId) {
+    const sessions = await listSessions({ dir: PROJECT_DIR, limit: 5 });
+    sessionId = sessions[0]?.sessionId;
+    if (!sessionId) { logFail("No session to test"); return; }
+  }
+
+  logInfo(`Reading messages from session ${sessionId.slice(0, 8)}...`);
+
+  // Test with no limit
+  const allMsgs = await getSessionMessages(sessionId, { dir: PROJECT_DIR });
+  logInfo(`Total messages: ${allMsgs.length}`);
+
+  // Show first few messages with UUIDs (needed for fork-mid test)
+  for (const [i, msg] of allMsgs.slice(0, 6).entries()) {
+    const preview = typeof msg.message === "object"
+      ? JSON.stringify(msg.message).slice(0, 80)
+      : String(msg.message).slice(0, 80);
+    console.log(`  [${i}] type=${msg.type} uuid=${msg.uuid.slice(0, 8)}... | ${preview}`);
+  }
+
+  // Test with limit/offset
+  const page1 = await getSessionMessages(sessionId, { dir: PROJECT_DIR, limit: 2 });
+  const page2 = await getSessionMessages(sessionId, { dir: PROJECT_DIR, limit: 2, offset: 2 });
+  logInfo(`Pagination: page1=${page1.length} msgs, page2=${page2.length} msgs`);
+
+  if (allMsgs.length > 0) logOk(`getSessionMessages works (${allMsgs.length} messages)`);
+  else logFail("No messages found");
+
+  return allMsgs;
+}
+
+// ─── Test 3: Fork at Mid-Message ────────────────────────────────────────────
+async function testForkMid() {
+  log("TEST: forkSession with upToMessageId");
+
+  // Find a session with multiple messages
+  const sessions = await listSessions({ dir: PROJECT_DIR, limit: 20 });
+  let sourceSession = null;
+  let sourceMessages = [];
+
+  for (const s of sessions) {
+    const msgs = await getSessionMessages(s.sessionId, { dir: PROJECT_DIR });
+    if (msgs.length >= 4) {
+      sourceSession = s;
+      sourceMessages = msgs;
+      break;
+    }
+  }
+
+  if (!sourceSession) {
+    logFail("No session with 4+ messages found");
+    return;
+  }
+
+  logInfo(`Source: ${sourceSession.sessionId.slice(0, 8)}... (${sourceMessages.length} messages)`);
+
+  // Fork at the 2nd message (mid-conversation)
+  const forkAtMsg = sourceMessages[1]; // 2nd message
+  logInfo(`Forking at message[1]: uuid=${forkAtMsg.uuid.slice(0, 8)}... type=${forkAtMsg.type}`);
+
+  try {
+    const result = await forkSession(sourceSession.sessionId, {
+      dir: PROJECT_DIR,
+      upToMessageId: forkAtMsg.uuid,
+      title: `[TEST] Fork at msg[1] - ${new Date().toISOString().slice(11, 19)}`,
+    });
+
+    logOk(`Fork created! New sessionId: ${result.sessionId}`);
+
+    // Verify forked session has fewer messages
+    const forkedMsgs = await getSessionMessages(result.sessionId, { dir: PROJECT_DIR });
+    logInfo(`Forked session has ${forkedMsgs.length} messages (source had ${sourceMessages.length})`);
+
+    if (forkedMsgs.length <= sourceMessages.length) {
+      logOk(`Mid-fork works: ${forkedMsgs.length} ≤ ${sourceMessages.length} messages`);
+    } else {
+      logFail(`Fork has more messages than source?!`);
+    }
+
+    // Get info about forked session
+    const info = await getSessionInfo(result.sessionId, { dir: PROJECT_DIR });
+    logInfo(`Fork info: title="${info?.summary}" created=${info?.createdAt ? new Date(info.createdAt).toISOString().slice(0, 16) : "?"}`);
+
+    return result.sessionId;
+  } catch (e) {
+    logFail(`forkSession failed: ${e.message}`);
+    console.error(e);
+  }
+}
+
+// ─── Test 4: Delete Session (JSONL) ─────────────────────────────────────────
+async function testDelete(sessionIdToDelete) {
+  log("TEST: deleteSession (JSONL unlink)");
+
+  // If no specific session, create a disposable one first via forkSession
+  if (!sessionIdToDelete) {
+    logInfo("Creating disposable session via fork for delete test...");
+    const sessions = await listSessions({ dir: PROJECT_DIR, limit: 5 });
+    if (sessions.length === 0) { logFail("No sessions to fork from"); return; }
+
+    const result = await forkSession(sessions[0].sessionId, {
+      dir: PROJECT_DIR,
+      title: "[TEST] Disposable for delete test",
+    });
+    sessionIdToDelete = result.sessionId;
+    logInfo(`Created disposable: ${sessionIdToDelete}`);
+  }
+
+  // Find the JSONL file on disk
+  const projectDirs = readdirSync(CLAUDE_PROJECTS_DIR);
+  let jsonlPath = null;
+
+  for (const dir of projectDirs) {
+    const candidate = resolve(CLAUDE_PROJECTS_DIR, dir, `${sessionIdToDelete}.jsonl`);
+    if (existsSync(candidate)) {
+      jsonlPath = candidate;
+      break;
+    }
+  }
+
+  if (!jsonlPath) {
+    logFail(`JSONL file not found for session ${sessionIdToDelete}`);
+    return;
+  }
+
+  logInfo(`Found JSONL: ${jsonlPath}`);
+
+  // Delete the file
+  unlinkSync(jsonlPath);
+  logInfo("JSONL deleted");
+
+  // Verify it's gone from listSessions
+  const afterSessions = await listSessions({ dir: PROJECT_DIR, limit: 100 });
+  const stillExists = afterSessions.some(s => s.sessionId === sessionIdToDelete);
+
+  if (!stillExists) {
+    logOk("Session deleted successfully — no longer in listSessions");
+  } else {
+    logFail("Session still appears in listSessions after JSONL deletion!");
+  }
+}
+
+// ─── Test 5: resumeSessionAt ────────────────────────────────────────────────
+async function testResumeAt() {
+  log("TEST: resumeSessionAt (resume from specific message)");
+
+  // Find a session with enough messages
+  const sessions = await listSessions({ dir: PROJECT_DIR, limit: 20 });
+  let sourceSession = null;
+  let sourceMessages = [];
+
+  for (const s of sessions) {
+    const msgs = await getSessionMessages(s.sessionId, { dir: PROJECT_DIR });
+    if (msgs.length >= 4) {
+      sourceSession = s;
+      sourceMessages = msgs;
+      break;
+    }
+  }
+
+  if (!sourceSession) {
+    logFail("No session with 4+ messages for resumeAt test");
+    return;
+  }
+
+  // Pick middle message to resume from
+  const midIdx = Math.floor(sourceMessages.length / 2);
+  const resumeAtMsg = sourceMessages[midIdx];
+  logInfo(`Source: ${sourceSession.sessionId.slice(0, 8)}... (${sourceMessages.length} msgs)`);
+  logInfo(`Resuming at message[${midIdx}]: uuid=${resumeAtMsg.uuid.slice(0, 8)}... type=${resumeAtMsg.type}`);
+
+  try {
+    // Use query() with resume + resumeSessionAt + forkSession to test
+    const q = query({
+      prompt: "Just say 'RESUME_AT_TEST_OK' and nothing else.",
+      options: {
+        resume: sourceSession.sessionId,
+        resumeSessionAt: resumeAtMsg.uuid,
+        forkSession: true,
+        cwd: PROJECT_DIR,
+        maxTurns: 1,
+        allowedTools: [],
+        permissionMode: "bypassPermissions",
+        systemPrompt: { type: "custom", value: "You are a test assistant. Reply exactly as instructed." },
+      },
+    });
+
+    let resultSessionId = null;
+    let gotText = false;
+
+    for await (const msg of q) {
+      if (msg.type === "assistant") {
+        const textBlocks = (msg.message?.content || []).filter(b => b.type === "text");
+        if (textBlocks.length > 0) {
+          logInfo(`Assistant replied: "${textBlocks.map(b => b.text).join("").slice(0, 100)}"`);
+          gotText = true;
+        }
+      }
+      if (msg.type === "result") {
+        resultSessionId = msg.session_id;
+        logInfo(`Result: subtype=${msg.subtype} session=${resultSessionId?.slice(0, 8)}... cost=$${msg.total_cost_usd?.toFixed(4)}`);
+      }
+    }
+
+    if (gotText && resultSessionId) {
+      logOk(`resumeSessionAt works! Forked session: ${resultSessionId}`);
+
+      // Check the forked session has truncated history
+      const forkedMsgs = await getSessionMessages(resultSessionId, { dir: PROJECT_DIR });
+      logInfo(`Forked session messages: ${forkedMsgs.length} (original: ${sourceMessages.length})`);
+
+      // Cleanup: delete test session
+      return resultSessionId;
+    } else {
+      logFail("resumeSessionAt did not produce expected output");
+    }
+  } catch (e) {
+    logFail(`resumeSessionAt failed: ${e.message}`);
+    console.error(e);
+  }
+}
+
+// ─── Test 6: Compact/Summary for Merge ──────────────────────────────────────
+async function testCompactSummary() {
+  log("TEST: Generate summary for merge (using query + compact approach)");
+
+  // Find a session with enough content
+  const sessions = await listSessions({ dir: PROJECT_DIR, limit: 20 });
+  let sourceSession = null;
+  let sourceMessages = [];
+
+  for (const s of sessions) {
+    const msgs = await getSessionMessages(s.sessionId, { dir: PROJECT_DIR });
+    if (msgs.length >= 6) {
+      sourceSession = s;
+      sourceMessages = msgs;
+      break;
+    }
+  }
+
+  if (!sourceSession) {
+    logFail("No session with 6+ messages for compact test");
+    return;
+  }
+
+  logInfo(`Source: ${sourceSession.sessionId.slice(0, 8)}... (${sourceMessages.length} msgs)`);
+
+  // Extract conversation text for summary
+  const conversationText = sourceMessages.slice(0, 10).map((msg, i) => {
+    const content = msg.message?.content;
+    let text = "";
+    if (typeof content === "string") {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter(b => b.type === "text")
+        .map(b => b.text)
+        .join("\n")
+        .slice(0, 500);
+    }
+    return `[${msg.type}] ${text.slice(0, 300)}`;
+  }).join("\n---\n");
+
+  logInfo(`Conversation excerpt (${conversationText.length} chars):\n${conversationText.slice(0, 500)}...`);
+
+  // Use a cheap query to generate summary
+  logInfo("Generating summary via Claude (short query)...");
+  try {
+    const summaryPrompt = `Summarize this conversation in 3-5 bullet points. Focus on: what was discussed, what decisions were made, what files were modified.
+
+CONVERSATION:
+${conversationText.slice(0, 3000)}
+
+Reply with ONLY the bullet points, no preamble.`;
+
+    const q = query({
+      prompt: summaryPrompt,
+      options: {
+        cwd: PROJECT_DIR,
+        maxTurns: 1,
+        allowedTools: [],
+        permissionMode: "bypassPermissions",
+        model: "haiku",
+        systemPrompt: { type: "custom", value: "You are a concise conversation summarizer." },
+        persistSession: false, // Don't save this summary session
+      },
+    });
+
+    let summary = "";
+    for await (const msg of q) {
+      if (msg.type === "assistant") {
+        const textBlocks = (msg.message?.content || []).filter(b => b.type === "text");
+        summary += textBlocks.map(b => b.text).join("");
+      }
+      if (msg.type === "result") {
+        logInfo(`Summary cost: $${msg.total_cost_usd?.toFixed(4)}`);
+      }
+    }
+
+    if (summary) {
+      logOk("Summary generated successfully:");
+      console.log(`\n${summary}\n`);
+      logInfo("This summary could be injected into a merge session's system prompt");
+    } else {
+      logFail("No summary text produced");
+    }
+  } catch (e) {
+    logFail(`Summary generation failed: ${e.message}`);
+    console.error(e);
+  }
+}
+
+// ─── Test 7: Tag Session ────────────────────────────────────────────────────
+async function testTagSession() {
+  log("TEST: tagSession");
+
+  const sessions = await listSessions({ dir: PROJECT_DIR, limit: 5 });
+  if (sessions.length === 0) { logFail("No sessions"); return; }
+
+  const target = sessions[0];
+  logInfo(`Tagging session ${target.sessionId.slice(0, 8)}... (current tag: ${target.tag ?? "none"})`);
+
+  try {
+    await tagSession(target.sessionId, "test-tag", { dir: PROJECT_DIR });
+    const info = await getSessionInfo(target.sessionId, { dir: PROJECT_DIR });
+    logInfo(`After tag: tag="${info?.tag}"`);
+
+    if (info?.tag === "test-tag") {
+      logOk("tagSession works");
+    } else {
+      logFail(`Expected tag="test-tag", got "${info?.tag}"`);
+    }
+
+    // Clear tag
+    await tagSession(target.sessionId, null, { dir: PROJECT_DIR });
+    logInfo("Tag cleared");
+
+  } catch (e) {
+    logFail(`tagSession failed: ${e.message}`);
+  }
+}
+
+// ─── Runner ─────────────────────────────────────────────────────────────────
+async function main() {
+  console.log(`\n🧪 Session Operations Test Suite`);
+  console.log(`Project: ${PROJECT_DIR}`);
+  console.log(`Test: ${testName}\n`);
+
+  const tests = {
+    list: testListSessions,
+    messages: testGetMessages,
+    "fork-mid": testForkMid,
+    delete: testDelete,
+    "resume-at": testResumeAt,
+    "compact-summary": testCompactSummary,
+    tag: testTagSession,
+  };
+
+  if (testName === "all") {
+    // Run non-destructive tests first
+    await testListSessions();
+    await testGetMessages();
+    await testTagSession();
+    await testForkMid();
+    // resume-at and compact-summary cost API tokens — ask first
+    console.log("\n⚠️  Remaining tests (resume-at, compact-summary) cost API tokens.");
+    console.log("   Run individually: bun test-session-ops.mjs resume-at");
+    console.log("   Run individually: bun test-session-ops.mjs compact-summary");
+    console.log("   Delete test: bun test-session-ops.mjs delete");
+  } else if (tests[testName]) {
+    await tests[testName]();
+  } else {
+    console.log(`Unknown test: ${testName}`);
+    console.log(`Available: ${Object.keys(tests).join(", ")}, all`);
+  }
+
+  log("DONE", `Finished ${testName} test(s)`);
+}
+
+main().catch(e => {
+  console.error("Fatal:", e);
+  process.exit(1);
+});