@zzusp/ccsm 1.0.1 → 1.0.2

package/server/lib/parse-jsonl.ts

@@ -1,139 +1,160 @@
-import fs from 'node:fs';
-import readline from 'node:readline';
-import { INTERRUPTED_MARKER_RE } from './constants.ts';
-import { SYSTEM_TAG_RE, pickTitleText } from './system-tags.ts';
-
-export interface JsonlMeta {
-  title: string;
-  /** Latest `custom-title` record value, or null if never renamed. */
-  customTitle: string | null;
-  firstAt: string | null;
-  lastAt: string | null;
-  messageCount: number;
-  cwdFromMessages: string | null;
-  /**
-   * The last conversation turn is unfinished — Claude still owes output. True when
-   * the final `user`/`assistant` record is either a `user` message (and not an
-   * abort marker) or an `assistant` message that ends on a `tool_use` block. This
-   * is the structural half of "working"; liveness gating happens in the caller.
-   */
-  lastTurnIncomplete: boolean;
-}
-
-export async function parseJsonlMeta(filePath: string): Promise<JsonlMeta> {
-  let firstUserTitle = '';
-  let aiTitle: string | null = null;
-  let customTitle: string | null = null;
-  let firstAt: string | null = null;
-  let lastAt: string | null = null;
-  let messageCount = 0;
-  let cwdFromMessages: string | null = null;
-  // Re-evaluated on every conversation record so it reflects the *last* turn once
-  // the scan finishes.
-  let lastTurnIncomplete = false;
-
-  const rl = readline.createInterface({
-    input: fs.createReadStream(filePath, { encoding: 'utf8' }),
-    crlfDelay: Infinity,
-  });
-
-  for await (const raw of rl) {
-    const line = raw.trim();
-    if (!line) continue;
-    let obj: Record<string, unknown>;
-    try {
-      obj = JSON.parse(line) as Record<string, unknown>;
-    } catch {
-      continue;
-    }
-
-    const ts = typeof obj.timestamp === 'string' ? obj.timestamp : null;
-    if (ts) {
-      if (!firstAt) firstAt = ts;
-      lastAt = ts;
-    }
-
-    if (obj.cwd && typeof obj.cwd === 'string' && !cwdFromMessages) {
-      cwdFromMessages = obj.cwd;
-    }
-
-    if (obj.type === 'custom-title' && typeof obj.customTitle === 'string') {
-      customTitle = obj.customTitle;
-    }
-
-    // Claude Code rewrites this record every turn; the latest copy is canonical.
-    if (obj.type === 'ai-title' && typeof obj.aiTitle === 'string') {
-      aiTitle = obj.aiTitle;
-    }
-
-    if (obj.type === 'user' || obj.type === 'assistant') {
-      messageCount += 1;
-      const msg = obj.message as { content?: unknown } | undefined;
-
-      if (obj.type === 'assistant') {
-        lastTurnIncomplete = endsWithToolUse(msg?.content);
-      } else {
-        const candidate = extractUserText(msg?.content);
-        // A trailing user record means Claude owes a reply — unless it is the
-        // synthetic abort marker, which means the operator stopped the turn.
-        lastTurnIncomplete = !INTERRUPTED_MARKER_RE.test(candidate);
-
-        if (!firstUserTitle && candidate && !SYSTEM_TAG_RE.test(candidate)) {
-          const usable = pickTitleText(candidate);
-          if (usable) {
-            firstUserTitle = usable.slice(0, 80).replace(/\s+/g, ' ').trim();
-          }
-        }
-      }
-    }
-  }
-
-  // `claude code resume` keys off file mtime, which advances even when Claude Code
-  // rewrites untimestamped meta records (ai-title rotate, custom-title/agent-name on
-  // rename, last-prompt, permission-mode). Reconcile so the UI agrees with resume.
-  const mtimeIso = fs.statSync(filePath).mtime.toISOString();
-  const reconciledLastAt = !lastAt || mtimeIso > lastAt ? mtimeIso : lastAt;
-
-  return {
-    title: aiTitle || firstUserTitle || '(untitled)',
-    customTitle,
-    firstAt,
-    lastAt: reconciledLastAt,
-    messageCount,
-    cwdFromMessages,
-    lastTurnIncomplete,
-  };
-}
-
-// An assistant message that ends on a `tool_use` block (Anthropic `stop_reason:
-// "tool_use"`) is mid-work: a tool is pending and Claude will continue once it
-// returns. Verified 1:1 against `stop_reason` across real sessions.
-function endsWithToolUse(content: unknown): boolean {
-  if (!Array.isArray(content)) return false;
-  for (let i = content.length - 1; i >= 0; i--) {
-    const block = content[i];
-    if (block && typeof block === 'object' && typeof (block as { type?: unknown }).type === 'string') {
-      return (block as { type: string }).type === 'tool_use';
-    }
-  }
-  return false;
-}
-
-function extractUserText(content: unknown): string {
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) {
-    for (const block of content) {
-      if (
-        block &&
-        typeof block === 'object' &&
-        'type' in block &&
-        block.type === 'text' &&
-        'text' in block &&
-        typeof (block as { text: unknown }).text === 'string'
-      ) {
-        return (block as { text: string }).text;
-      }
-    }
-  }
-  return '';
-}
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { INTERRUPTED_MARKER_RE } from './constants.ts';
+import { SYSTEM_TAG_RE, pickTitleText } from './system-tags.ts';
+
+export interface JsonlMeta {
+  title: string;
+  /** Latest `custom-title` record value, or null if never renamed. */
+  customTitle: string | null;
+  firstAt: string | null;
+  lastAt: string | null;
+  messageCount: number;
+  /** Count of tool_result blocks flagged `is_error` across the session. */
+  errorCount: number;
+  cwdFromMessages: string | null;
+  /**
+   * The last conversation turn is unfinished — Claude still owes output. True when
+   * the final `user`/`assistant` record is either a `user` message (and not an
+   * abort marker) or an `assistant` message that ends on a `tool_use` block. This
+   * is the structural half of "working"; liveness gating happens in the caller.
+   */
+  lastTurnIncomplete: boolean;
+}
+
+export async function parseJsonlMeta(filePath: string): Promise<JsonlMeta> {
+  let firstUserTitle = '';
+  let aiTitle: string | null = null;
+  let customTitle: string | null = null;
+  let firstAt: string | null = null;
+  let lastAt: string | null = null;
+  let messageCount = 0;
+  let errorCount = 0;
+  let cwdFromMessages: string | null = null;
+  // Re-evaluated on every conversation record so it reflects the *last* turn once
+  // the scan finishes.
+  let lastTurnIncomplete = false;
+
+  const rl = readline.createInterface({
+    input: fs.createReadStream(filePath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const raw of rl) {
+    const line = raw.trim();
+    if (!line) continue;
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    const ts = typeof obj.timestamp === 'string' ? obj.timestamp : null;
+    if (ts) {
+      if (!firstAt) firstAt = ts;
+      lastAt = ts;
+    }
+
+    if (obj.cwd && typeof obj.cwd === 'string' && !cwdFromMessages) {
+      cwdFromMessages = obj.cwd;
+    }
+
+    if (obj.type === 'custom-title' && typeof obj.customTitle === 'string') {
+      customTitle = obj.customTitle;
+    }
+
+    // Claude Code rewrites this record every turn; the latest copy is canonical.
+    if (obj.type === 'ai-title' && typeof obj.aiTitle === 'string') {
+      aiTitle = obj.aiTitle;
+    }
+
+    if (obj.type === 'user' || obj.type === 'assistant') {
+      messageCount += 1;
+      const msg = obj.message as { content?: unknown } | undefined;
+      errorCount += countErrorResults(msg?.content);
+
+      if (obj.type === 'assistant') {
+        lastTurnIncomplete = endsWithToolUse(msg?.content);
+      } else {
+        const candidate = extractUserText(msg?.content);
+        // A trailing user record means Claude owes a reply — unless it is the
+        // synthetic abort marker, which means the operator stopped the turn.
+        lastTurnIncomplete = !INTERRUPTED_MARKER_RE.test(candidate);
+
+        if (!firstUserTitle && candidate && !SYSTEM_TAG_RE.test(candidate)) {
+          const usable = pickTitleText(candidate);
+          if (usable) {
+            firstUserTitle = usable.slice(0, 80).replace(/\s+/g, ' ').trim();
+          }
+        }
+      }
+    }
+  }
+
+  // `claude code resume` keys off file mtime, which advances even when Claude Code
+  // rewrites untimestamped meta records (ai-title rotate, custom-title/agent-name on
+  // rename, last-prompt, permission-mode). Reconcile so the UI agrees with resume.
+  const mtimeIso = fs.statSync(filePath).mtime.toISOString();
+  const reconciledLastAt = !lastAt || mtimeIso > lastAt ? mtimeIso : lastAt;
+
+  return {
+    title: aiTitle || firstUserTitle || '(untitled)',
+    customTitle,
+    firstAt,
+    lastAt: reconciledLastAt,
+    messageCount,
+    errorCount,
+    cwdFromMessages,
+    lastTurnIncomplete,
+  };
+}
+
+// An assistant message that ends on a `tool_use` block (Anthropic `stop_reason:
+// "tool_use"`) is mid-work: a tool is pending and Claude will continue once it
+// returns. Verified 1:1 against `stop_reason` across real sessions.
+function endsWithToolUse(content: unknown): boolean {
+  if (!Array.isArray(content)) return false;
+  for (let i = content.length - 1; i >= 0; i--) {
+    const block = content[i];
+    if (block && typeof block === 'object' && typeof (block as { type?: unknown }).type === 'string') {
+      return (block as { type: string }).type === 'tool_use';
+    }
+  }
+  return false;
+}
+
+function extractUserText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (
+        block &&
+        typeof block === 'object' &&
+        'type' in block &&
+        block.type === 'text' &&
+        'text' in block &&
+        typeof (block as { text: unknown }).text === 'string'
+      ) {
+        return (block as { text: string }).text;
+      }
+    }
+  }
+  return '';
+}
+
+function countErrorResults(content: unknown): number {
+  if (!Array.isArray(content)) return 0;
+  let n = 0;
+  for (const block of content) {
+    if (
+      block &&
+      typeof block === 'object' &&
+      (block as { type?: unknown }).type === 'tool_result' &&
+      (block as { is_error?: unknown }).is_error === true
+    ) {
+      n += 1;
+    }
+  }
+  return n;
+}

package/server/lib/port.ts

@@ -1,23 +1,23 @@
-import { createServer } from 'node:net';
-
-export async function findAvailablePort(
-  start: number,
-  end: number,
-  host = '127.0.0.1',
-): Promise<number> {
-  for (let port = start; port <= end; port++) {
-    if (await isPortFree(port, host)) return port;
-  }
-  throw new Error(`No free port in range ${start}..${end} on ${host}`);
-}
-
-function isPortFree(port: number, host: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    const server = createServer();
-    server.once('error', () => resolve(false));
-    server.once('listening', () => {
-      server.close(() => resolve(true));
-    });
-    server.listen(port, host);
-  });
-}
+import { createServer } from 'node:net';
+
+export async function findAvailablePort(
+  start: number,
+  end: number,
+  host = '127.0.0.1',
+): Promise<number> {
+  for (let port = start; port <= end; port++) {
+    if (await isPortFree(port, host)) return port;
+  }
+  throw new Error(`No free port in range ${start}..${end} on ${host}`);
+}
+
+function isPortFree(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}

package/server/lib/safe-id.test.ts

@@ -1,41 +1,41 @@
-import { describe, expect, it } from 'vitest';
-import { isSafeId } from './safe-id.ts';
-
-// 守门：URL 参数里的 sessionId / projectId 走到任何 fs.* 之前必须先过这一关，
-// 漏一类就会让攻击者用 ../ 跳出 ~/.claude，所以四个拒绝点逐条钉死。
-describe('isSafeId', () => {
-  it('接受常规 uuid / 编码后的 cwd', () => {
-    expect(isSafeId('019410ce-49fb-7d5c-b0a4-2d7d2b6a4b7d')).toBe(true);
-    expect(isSafeId('-Users-sunpeng-workspace-claude-code-session')).toBe(true);
-    expect(isSafeId('C--Users-sunpeng')).toBe(true);
-  });
-
-  it('拒绝空字符串', () => {
-    expect(isSafeId('')).toBe(false);
-  });
-
-  it('拒绝包含正斜杠的 id（path-traversal 入口）', () => {
-    expect(isSafeId('a/b')).toBe(false);
-    expect(isSafeId('../etc/passwd')).toBe(false);
-  });
-
-  it('拒绝包含反斜杠的 id（Windows path-traversal）', () => {
-    expect(isSafeId('a\\b')).toBe(false);
-    expect(isSafeId('..\\windows')).toBe(false);
-  });
-
-  it('拒绝包含 .. 的 id（即便不带分隔符）', () => {
-    expect(isSafeId('foo..bar')).toBe(false);
-    expect(isSafeId('..')).toBe(false);
-  });
-
-  it('拒绝以 . 开头的 id（屏蔽 dotfile）', () => {
-    expect(isSafeId('.hidden')).toBe(false);
-    expect(isSafeId('.bak-1700000000')).toBe(false);
-  });
-
-  it('单点开头的拒绝不影响中间含 . 的合法 id', () => {
-    expect(isSafeId('memory.md')).toBe(true);
-    expect(isSafeId('file.imported-abcd1234.md')).toBe(true);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { isSafeId } from './safe-id.ts';
+
+// 守门：URL 参数里的 sessionId / projectId 走到任何 fs.* 之前必须先过这一关，
+// 漏一类就会让攻击者用 ../ 跳出 ~/.claude，所以四个拒绝点逐条钉死。
+describe('isSafeId', () => {
+  it('接受常规 uuid / 编码后的 cwd', () => {
+    expect(isSafeId('019410ce-49fb-7d5c-b0a4-2d7d2b6a4b7d')).toBe(true);
+    expect(isSafeId('-Users-sunpeng-workspace-claude-code-session')).toBe(true);
+    expect(isSafeId('C--Users-sunpeng')).toBe(true);
+  });
+
+  it('拒绝空字符串', () => {
+    expect(isSafeId('')).toBe(false);
+  });
+
+  it('拒绝包含正斜杠的 id（path-traversal 入口）', () => {
+    expect(isSafeId('a/b')).toBe(false);
+    expect(isSafeId('../etc/passwd')).toBe(false);
+  });
+
+  it('拒绝包含反斜杠的 id（Windows path-traversal）', () => {
+    expect(isSafeId('a\\b')).toBe(false);
+    expect(isSafeId('..\\windows')).toBe(false);
+  });
+
+  it('拒绝包含 .. 的 id（即便不带分隔符）', () => {
+    expect(isSafeId('foo..bar')).toBe(false);
+    expect(isSafeId('..')).toBe(false);
+  });
+
+  it('拒绝以 . 开头的 id（屏蔽 dotfile）', () => {
+    expect(isSafeId('.hidden')).toBe(false);
+    expect(isSafeId('.bak-1700000000')).toBe(false);
+  });
+
+  it('单点开头的拒绝不影响中间含 . 的合法 id', () => {
+    expect(isSafeId('memory.md')).toBe(true);
+    expect(isSafeId('file.imported-abcd1234.md')).toBe(true);
+  });
+});

package/server/lib/safe-id.ts

@@ -1,6 +1,6 @@
-export function isSafeId(id: string): boolean {
-  if (!id) return false;
-  if (id.includes('/') || id.includes('\\') || id.includes('..')) return false;
-  if (id.startsWith('.')) return false;
-  return true;
-}
+export function isSafeId(id: string): boolean {
+  if (!id) return false;
+  if (id.includes('/') || id.includes('\\') || id.includes('..')) return false;
+  if (id.startsWith('.')) return false;
+  return true;
+}

package/server/lib/safe-remove.test.ts

@@ -1,73 +1,73 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-// safeRemove 是 deleteSessions 与 deleteOrphan 共用的"路径校验 + 实际 rm"唯一入口。
-// 这里把 claude-paths.ts mock 到一个独立 tmp root（通过 process.env.CCSM_TEST_ROOT 桥接，
-// 与 delete.test.ts 同套路），校验它只删 root 子树内的东西、逃出去的一律抛错。
-
-let fakeRoot: string;
-
-vi.mock('./claude-paths.ts', () => {
-  return {
-    isUnderClaudeRoot(target: string): boolean {
-      const root = process.env.CCSM_TEST_ROOT!;
-      const resolved = path.resolve(target);
-      return resolved === root || resolved.startsWith(root + path.sep);
-    },
-  };
-});
-
-beforeEach(() => {
-  fakeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ccsm-safe-remove-test-'));
-  process.env.CCSM_TEST_ROOT = fakeRoot;
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-  delete process.env.CCSM_TEST_ROOT;
-  fs.rmSync(fakeRoot, { recursive: true, force: true });
-});
-
-describe('safeRemove', () => {
-  it('删 root 子树内的文件，返回 true', async () => {
-    const { safeRemove } = await import('./safe-remove.ts');
-    const f = path.join(fakeRoot, 'a.jsonl');
-    fs.writeFileSync(f, 'x');
-
-    expect(safeRemove(f)).toBe(true);
-    expect(fs.existsSync(f)).toBe(false);
-  });
-
-  it('删 root 子树内的目录（recursive），返回 true', async () => {
-    const { safeRemove } = await import('./safe-remove.ts');
-    const dir = path.join(fakeRoot, 'file-history', 'sid-1');
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'nested.txt'), 'y');
-
-    expect(safeRemove(dir)).toBe(true);
-    expect(fs.existsSync(dir)).toBe(false);
-  });
-
-  it('目标不存在返回 false（幂等，不抛）', async () => {
-    const { safeRemove } = await import('./safe-remove.ts');
-    expect(safeRemove(path.join(fakeRoot, 'missing'))).toBe(false);
-  });
-
-  it('逃出 ~/.claude 子树的目标一律抛错，且不删任何东西', async () => {
-    const { safeRemove } = await import('./safe-remove.ts');
-    // 在 fakeRoot 之外铺一个文件，确认它不会被删
-    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'ccsm-safe-remove-outside-'));
-    const victim = path.join(outside, 'do-not-delete.txt');
-    fs.writeFileSync(victim, 'keep me');
-    try {
-      expect(() => safeRemove(victim)).toThrow(/outside ~\/\.claude/);
-      expect(fs.existsSync(victim)).toBe(true);
-      // 兄弟目录（同前缀但非子树）也必须拒绝
-      expect(() => safeRemove(fakeRoot + '_evil')).toThrow(/outside ~\/\.claude/);
-    } finally {
-      fs.rmSync(outside, { recursive: true, force: true });
-    }
-  });
-});
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// safeRemove 是 deleteSessions 与 deleteOrphan 共用的"路径校验 + 实际 rm"唯一入口。
+// 这里把 claude-paths.ts mock 到一个独立 tmp root（通过 process.env.CCSM_TEST_ROOT 桥接，
+// 与 delete.test.ts 同套路），校验它只删 root 子树内的东西、逃出去的一律抛错。
+
+let fakeRoot: string;
+
+vi.mock('./claude-paths.ts', () => {
+  return {
+    isUnderClaudeRoot(target: string): boolean {
+      const root = process.env.CCSM_TEST_ROOT!;
+      const resolved = path.resolve(target);
+      return resolved === root || resolved.startsWith(root + path.sep);
+    },
+  };
+});
+
+beforeEach(() => {
+  fakeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ccsm-safe-remove-test-'));
+  process.env.CCSM_TEST_ROOT = fakeRoot;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete process.env.CCSM_TEST_ROOT;
+  fs.rmSync(fakeRoot, { recursive: true, force: true });
+});
+
+describe('safeRemove', () => {
+  it('删 root 子树内的文件，返回 true', async () => {
+    const { safeRemove } = await import('./safe-remove.ts');
+    const f = path.join(fakeRoot, 'a.jsonl');
+    fs.writeFileSync(f, 'x');
+
+    expect(safeRemove(f)).toBe(true);
+    expect(fs.existsSync(f)).toBe(false);
+  });
+
+  it('删 root 子树内的目录（recursive），返回 true', async () => {
+    const { safeRemove } = await import('./safe-remove.ts');
+    const dir = path.join(fakeRoot, 'file-history', 'sid-1');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'nested.txt'), 'y');
+
+    expect(safeRemove(dir)).toBe(true);
+    expect(fs.existsSync(dir)).toBe(false);
+  });
+
+  it('目标不存在返回 false（幂等，不抛）', async () => {
+    const { safeRemove } = await import('./safe-remove.ts');
+    expect(safeRemove(path.join(fakeRoot, 'missing'))).toBe(false);
+  });
+
+  it('逃出 ~/.claude 子树的目标一律抛错，且不删任何东西', async () => {
+    const { safeRemove } = await import('./safe-remove.ts');
+    // 在 fakeRoot 之外铺一个文件，确认它不会被删
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'ccsm-safe-remove-outside-'));
+    const victim = path.join(outside, 'do-not-delete.txt');
+    fs.writeFileSync(victim, 'keep me');
+    try {
+      expect(() => safeRemove(victim)).toThrow(/outside ~\/\.claude/);
+      expect(fs.existsSync(victim)).toBe(true);
+      // 兄弟目录（同前缀但非子树）也必须拒绝
+      expect(() => safeRemove(fakeRoot + '_evil')).toThrow(/outside ~\/\.claude/);
+    } finally {
+      fs.rmSync(outside, { recursive: true, force: true });
+    }
+  });
+});

package/server/lib/safe-remove.ts

@@ -1,25 +1,25 @@
-import fs from 'node:fs';
-import { isUnderClaudeRoot } from './claude-paths.ts';
-
-/**
- * ~/.claude/ 下所有删除的唯一入口：先过 isUnderClaudeRoot 路径校验，再真正 rm。
- *
- * deleteSessions（5 处级联）和 deleteOrphan（孤儿目录）共用这一份"路径校验 + 实际 rm"，
- * 把"目标必须落在 ~/.claude 子树内"这条安全网集中到一处——以后改删除约束
- * （加路径校验、改 rm 行为、加新防护）只改这里，不会两边各写一份、改一边漏一边。
- *
- * 文件和目录都走 recursive: true（对文件无副作用），所以单一入口能覆盖两种形态。
- *
- * @returns 是否真的删了东西（目标不存在 → false）
- * @throws 目标逃出 ~/.claude 子树 —— 最后一道兜底，绝不 silently 删 root 外的东西。
- *         调用方应在更早处用 isUnderClaudeRoot 做 graceful 预检并给出跳过原因，
- *         走到这里抛错说明前置校验漏了，是 bug 不是正常流程。
- */
-export function safeRemove(target: string): boolean {
-  if (!isUnderClaudeRoot(target)) {
-    throw new Error(`refuse to remove path outside ~/.claude: ${target}`);
-  }
-  if (!fs.existsSync(target)) return false;
-  fs.rmSync(target, { recursive: true, force: true });
-  return true;
-}
+import fs from 'node:fs';
+import { isUnderClaudeRoot } from './claude-paths.ts';
+
+/**
+ * ~/.claude/ 下所有删除的唯一入口：先过 isUnderClaudeRoot 路径校验，再真正 rm。
+ *
+ * deleteSessions（5 处级联）和 deleteOrphan（孤儿目录）共用这一份"路径校验 + 实际 rm"，
+ * 把"目标必须落在 ~/.claude 子树内"这条安全网集中到一处——以后改删除约束
+ * （加路径校验、改 rm 行为、加新防护）只改这里，不会两边各写一份、改一边漏一边。
+ *
+ * 文件和目录都走 recursive: true（对文件无副作用），所以单一入口能覆盖两种形态。
+ *
+ * @returns 是否真的删了东西（目标不存在 → false）
+ * @throws 目标逃出 ~/.claude 子树 —— 最后一道兜底，绝不 silently 删 root 外的东西。
+ *         调用方应在更早处用 isUnderClaudeRoot 做 graceful 预检并给出跳过原因，
+ *         走到这里抛错说明前置校验漏了，是 bug 不是正常流程。
+ */
+export function safeRemove(target: string): boolean {
+  if (!isUnderClaudeRoot(target)) {
+    throw new Error(`refuse to remove path outside ~/.claude: ${target}`);
+  }
+  if (!fs.existsSync(target)) return false;
+  fs.rmSync(target, { recursive: true, force: true });
+  return true;
+}