@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/project-routes.ts

@@ -0,0 +1,46 @@
+import type { Hono } from "hono";
+import { HttpError, projectPath } from "./sessions.ts";
+import { turnChanges, turnFileDiff } from "./turn-changes.ts";
+import { addExtraDir, extraDirs, removeExtraDir } from "./add-dirs.ts";
+import { createWorktree, createWorktreeSession, listWorktrees, removeWorktree } from "./worktrees.ts";
+
+/** M4 routes: files changed per turn, extra directories (/add-dir), git worktrees. */
+export function registerProjectRoutes(app: Hono) {
+  const pp = (c: { req: { param(k: string): string | undefined } }) => projectPath(c.req.param("pid") ?? "");
+
+  app.get("/api/projects/:pid/sessions/:sid/turn-changes", async (c) => c.json(await turnChanges(pp(c), c.req.param("sid"))));
+
+  app.get("/api/projects/:pid/sessions/:sid/turn-changes/diff", async (c) => {
+    const turn = c.req.query("turn");
+    const file = c.req.query("path");
+    if (!turn || !file) throw new HttpError(400, "缺少 turn 或 path");
+    return c.json(await turnFileDiff(pp(c), c.req.param("sid"), turn, file));
+  });
+
+  app.get("/api/projects/:pid/sessions/:sid/dirs", async (c) => c.json(await extraDirs(pp(c), c.req.param("sid"))));
+
+  app.post("/api/projects/:pid/sessions/:sid/dirs", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    return c.json(await addExtraDir(pp(c), c.req.param("sid"), String(body?.path ?? ""), !!body?.remember));
+  });
+
+  app.delete("/api/projects/:pid/sessions/:sid/dirs", async (c) => {
+    const dir = c.req.query("path");
+    if (!dir) throw new HttpError(400, "缺少 path");
+    return c.json(await removeExtraDir(pp(c), c.req.param("sid"), dir));
+  });
+
+  app.get("/api/projects/:pid/worktrees", async (c) => c.json(await listWorktrees(pp(c))));
+
+  app.post("/api/projects/:pid/worktrees", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const project = pp(c);
+    const wt = await createWorktree(project, String(body?.name ?? ""));
+    const sessionId = body?.session ? await createWorktreeSession(project, wt.name) : undefined;
+    return c.json({ worktree: wt, sessionId });
+  });
+
+  app.post("/api/projects/:pid/worktrees/:name/sessions", async (c) => c.json({ id: await createWorktreeSession(pp(c), c.req.param("name")) }));
+
+  app.delete("/api/projects/:pid/worktrees/:name", async (c) => c.json(await removeWorktree(pp(c), c.req.param("name"), c.req.query("force") === "1")));
+}

package/server/projects.test.ts

@@ -0,0 +1,28 @@
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { channelFixture } from "./http-channel-test-fixture.ts";
+
+const fixture = await channelFixture();
+after(() => fixture.close());
+const { addProject, removeProject, listProjects, overview } = await import("./sessions.ts");
+
+test("removing a project only unregisters it, preserves files and session state, and hides its overview links", async () => {
+  const project = fixture.project;
+  const file = path.join(fixture.tmp, "keep.txt");
+  fs.writeFileSync(file, "project content");
+  const sessionId = fixture.newSession();
+  const live = await fixture.sessions.getOrCreate(sessionId, fixture.tmp);
+  await live.sendExternalText(fixture.id(), "running", () => true);
+  assert.ok((await overview()).some((entry) => entry.sessionId === sessionId));
+  const sessionRow = fixture.db.prepare("SELECT * FROM session_view WHERE session_id=?").get(sessionId);
+  removeProject(project.id);
+  assert.ok(!(await listProjects()).some((entry) => entry.id === project.id));
+  assert.equal(fs.readFileSync(file, "utf8"), "project content");
+  assert.deepEqual(fixture.db.prepare("SELECT * FROM session_view WHERE session_id=?").get(sessionId), sessionRow);
+  assert.equal(fixture.sessions.get(sessionId), live);
+  assert.ok(!(await overview()).some((entry) => entry.sessionId === sessionId));
+  assert.equal((await addProject(fixture.tmp)).id, project.id);
+  assert.ok((await overview()).some((entry) => entry.sessionId === sessionId));
+});

package/server/push.ts

@@ -0,0 +1,315 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import type { Hono } from "hono";
+import webpush from "web-push";
+import { config } from "./config.ts";
+import { db } from "./db.ts";
+
+/**
+ * Web Push: VAPID keys live in <dataDir>/vapid.json (generated on first run), subscriptions in
+ * sqlite (push_subscriptions). `notify()` is what the rest of the server calls.
+ */
+
+export type NotifyKind = "done" | "attention" | "error";
+export const NOTIFY_KINDS: NotifyKind[] = ["done", "attention", "error"];
+export type NotifyKinds = Record<NotifyKind, boolean>;
+
+export type NotifyInput = {
+  kind: NotifyKind;
+  title: string;
+  body?: string;
+  /** Same-origin path to open when the notification is clicked, e.g. /p/<pid>/s/<sid>. */
+  url?: string;
+  /** Notifications with the same tag replace each other on the device and are deduplicated here. */
+  tag?: string;
+  /**
+   * Session id: skip the push when some device is currently looking at this session.
+   * Only effective once a checker is installed with setViewingCheck().
+   */
+  skipIfViewing?: string;
+};
+
+export type NotifyResult = { sent: number; removed: number; failed: number; skipped?: "dedup" | "viewing" | "none" };
+
+/** The payload the service worker (web/sw.js) receives. */
+export type PushPayload = { kind: NotifyKind | "test"; title: string; body: string; url: string; tag?: string };
+
+// ---------- VAPID ----------
+
+type Vapid = { publicKey: string; privateKey: string };
+
+function loadVapid(): Vapid {
+  const file = path.join(config.dataDir, "vapid.json");
+  try {
+    const v = JSON.parse(fs.readFileSync(file, "utf8")) as Vapid;
+    if (v.publicKey && v.privateKey) return v;
+  } catch {
+    // generate below
+  }
+  const keys = webpush.generateVAPIDKeys();
+  fs.writeFileSync(file, JSON.stringify(keys, null, 2) + "\n", { mode: 0o600 });
+  return keys;
+}
+
+const vapid = loadVapid();
+/** Must be a mailto: or https: URL; Apple's push service rejects obviously fake ones (e.g. localhost). */
+const vapidSubject = process.env.CLAUDE_IDE_VAPID_SUBJECT ?? "mailto:claude-ide@example.com";
+
+export function vapidPublicKey(): string {
+  return vapid.publicKey;
+}
+
+// ---------- storage ----------
+
+type Row = {
+  id: string;
+  endpoint: string;
+  p256dh: string;
+  auth: string;
+  device: string | null;
+  user_agent: string | null;
+  created_at: number;
+  last_success_at: number | null;
+  notify_done: number;
+  notify_attention: number;
+  notify_error: number;
+};
+
+export type SubscriptionInfo = {
+  id: string;
+  device: string;
+  userAgent: string;
+  createdAt: number;
+  lastSuccessAt: number | null;
+  kinds: NotifyKinds;
+};
+
+const idOf = (endpoint: string) => crypto.createHash("sha256").update(endpoint).digest("base64url").slice(0, 16);
+
+function kindsOf(r: Row): NotifyKinds {
+  return { done: !!r.notify_done, attention: !!r.notify_attention, error: !!r.notify_error };
+}
+
+function info(r: Row): SubscriptionInfo {
+  return {
+    id: r.id,
+    device: r.device || guessDevice(r.user_agent ?? ""),
+    userAgent: r.user_agent ?? "",
+    createdAt: r.created_at,
+    lastSuccessAt: r.last_success_at,
+    kinds: kindsOf(r),
+  };
+}
+
+function guessDevice(ua: string): string {
+  const os = /iPhone/.test(ua) ? "iPhone" : /iPad/.test(ua) ? "iPad" : /Android/.test(ua) ? "Android" : /Mac OS X/.test(ua) ? "Mac" : /Windows/.test(ua) ? "Windows" : /Linux/.test(ua) ? "Linux" : "设备";
+  const browser = /Edg\//.test(ua) ? "Edge" : /Firefox\//.test(ua) ? "Firefox" : /Chrome\//.test(ua) ? "Chrome" : /Safari\//.test(ua) ? "Safari" : "";
+  return browser ? `${os} · ${browser}` : os;
+}
+
+const rowByEndpoint = (endpoint: string) => db.prepare("SELECT * FROM push_subscriptions WHERE endpoint = ?").get(endpoint) as Row | undefined;
+const deleteRow = (id: string) => db.prepare("DELETE FROM push_subscriptions WHERE id = ?").run(id);
+
+export function listSubscriptions(): SubscriptionInfo[] {
+  return (db.prepare("SELECT * FROM push_subscriptions ORDER BY created_at").all() as Row[]).map(info);
+}
+
+/**
+ * Push services are https. Plain http is accepted only for loopback endpoints, which lets the e2e
+ * tests stand in for a push service without touching the network.
+ */
+function validEndpoint(endpoint: unknown): endpoint is string {
+  if (typeof endpoint !== "string" || endpoint.length > 2048) return false;
+  try {
+    const u = new URL(endpoint);
+    if (u.protocol === "https:") return true;
+    return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function parseKinds(v: unknown): Partial<NotifyKinds> {
+  const out: Partial<NotifyKinds> = {};
+  if (v && typeof v === "object") {
+    for (const k of NOTIFY_KINDS) {
+      const b = (v as Record<string, unknown>)[k];
+      if (typeof b === "boolean") out[k] = b;
+    }
+  }
+  return out;
+}
+
+/** Upserts a subscription; undefined when the body is not a valid PushSubscription. */
+export function saveSubscription(body: unknown, userAgent: string): SubscriptionInfo | undefined {
+  const b = (body ?? {}) as { subscription?: { endpoint?: unknown; keys?: { p256dh?: unknown; auth?: unknown } }; device?: unknown; kinds?: unknown };
+  const sub = b.subscription;
+  const endpoint = sub?.endpoint;
+  const p256dh = sub?.keys?.p256dh;
+  const auth = sub?.keys?.auth;
+  if (!validEndpoint(endpoint) || typeof p256dh !== "string" || typeof auth !== "string" || !p256dh || !auth) {
+    return undefined;
+  }
+  try {
+    // Encrypting a dummy payload validates the keys (p256dh must be a P-256 point, auth 16 bytes).
+    webpush.encrypt(p256dh, auth, "x", "aes128gcm");
+  } catch {
+    return undefined;
+  }
+  const device = typeof b.device === "string" ? b.device.slice(0, 80) : null;
+  const kinds = { done: true, attention: true, error: true, ...parseKinds(b.kinds) };
+  const existing = rowByEndpoint(endpoint);
+  if (existing) {
+    const k = { ...kindsOf(existing), ...parseKinds(b.kinds) };
+    db.prepare(
+      "UPDATE push_subscriptions SET p256dh = ?, auth = ?, device = COALESCE(?, device), user_agent = ?, notify_done = ?, notify_attention = ?, notify_error = ? WHERE id = ?",
+    ).run(p256dh, auth, device, userAgent, +k.done, +k.attention, +k.error, existing.id);
+  } else {
+    db.prepare(
+      `INSERT INTO push_subscriptions (id, endpoint, p256dh, auth, device, user_agent, created_at, notify_done, notify_attention, notify_error)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(idOf(endpoint), endpoint, p256dh, auth, device, userAgent, Date.now(), +kinds.done, +kinds.attention, +kinds.error);
+  }
+  return info(rowByEndpoint(endpoint)!);
+}
+
+function findSub(body: { endpoint?: unknown; id?: unknown }): Row | undefined {
+  if (typeof body.endpoint === "string") return rowByEndpoint(body.endpoint);
+  if (typeof body.id === "string") return db.prepare("SELECT * FROM push_subscriptions WHERE id = ?").get(body.id) as Row | undefined;
+  return undefined;
+}
+
+function updateKinds(row: Row, kinds: Partial<NotifyKinds>): SubscriptionInfo {
+  const k = { ...kindsOf(row), ...kinds };
+  db.prepare("UPDATE push_subscriptions SET notify_done = ?, notify_attention = ?, notify_error = ? WHERE id = ?").run(+k.done, +k.attention, +k.error, row.id);
+  return info({ ...row, notify_done: +k.done, notify_attention: +k.attention, notify_error: +k.error });
+}
+
+// ---------- sending ----------
+
+type SendOutcome = { ok: true } | { ok: false; gone: boolean; status?: number; message: string };
+
+async function sendTo(row: Row, payload: PushPayload, urgency: "normal" | "high"): Promise<SendOutcome> {
+  let req;
+  try {
+    req = webpush.generateRequestDetails({ endpoint: row.endpoint, keys: { p256dh: row.p256dh, auth: row.auth } }, JSON.stringify(payload), {
+      vapidDetails: { subject: vapidSubject, publicKey: vapid.publicKey, privateKey: vapid.privateKey },
+      TTL: 60 * 60,
+      urgency,
+      // Topic collapses still-undelivered messages with the same tag on the push service.
+      ...(payload.tag ? { topic: crypto.createHash("sha256").update(payload.tag).digest("base64url").slice(0, 32) } : {}),
+    });
+  } catch (err) {
+    // Malformed keys can never work: treat like an expired subscription.
+    return { ok: false, gone: true, message: (err as Error).message };
+  }
+  try {
+    // web-push's own sender only speaks https; fetch lets loopback test endpoints work too.
+    const res = await fetch(req.endpoint, { method: req.method, headers: req.headers, body: new Uint8Array(req.body), signal: AbortSignal.timeout(15_000) });
+    if (res.ok) {
+      db.prepare("UPDATE push_subscriptions SET last_success_at = ? WHERE id = ?").run(Date.now(), row.id);
+      return { ok: true };
+    }
+    const text = (await res.text().catch(() => "")).slice(0, 200);
+    const gone = res.status === 404 || res.status === 410;
+    return { ok: false, gone, status: res.status, message: `推送服务返回 ${res.status}${text ? `：${text}` : ""}` };
+  } catch (err) {
+    return { ok: false, gone: false, message: `无法连接推送服务：${(err as Error).message}` };
+  }
+}
+
+let viewingCheck: ((sessionId: string) => boolean) | undefined;
+
+/** Install the "is any device looking at this session right now?" check used by skipIfViewing. */
+export function setViewingCheck(fn: ((sessionId: string) => boolean) | undefined): void {
+  viewingCheck = fn;
+}
+
+const DEDUP_MS = 10_000;
+const recentTags = new Map<string, number>();
+
+/**
+ * Push a notification to every subscribed device that wants this kind.
+ * Delivery failures never throw; expired subscriptions (404/410) are removed.
+ */
+export async function notify(input: NotifyInput): Promise<NotifyResult> {
+  const now = Date.now();
+  if (input.tag) {
+    for (const [t, at] of recentTags) if (now - at > DEDUP_MS) recentTags.delete(t);
+    if (recentTags.has(input.tag)) return { sent: 0, removed: 0, failed: 0, skipped: "dedup" };
+  }
+  if (input.skipIfViewing && viewingCheck?.(input.skipIfViewing)) return { sent: 0, removed: 0, failed: 0, skipped: "viewing" };
+  if (input.tag) recentTags.set(input.tag, now);
+
+  if (!NOTIFY_KINDS.includes(input.kind)) throw new Error(`unknown notification kind: ${String(input.kind)}`);
+  const column = `notify_${input.kind}`;
+  const rows = db.prepare(`SELECT * FROM push_subscriptions WHERE ${column} = 1`).all() as Row[];
+  if (rows.length === 0) return { sent: 0, removed: 0, failed: 0, skipped: "none" };
+  const payload: PushPayload = { kind: input.kind, title: input.title, body: input.body ?? "", url: input.url ?? "/", tag: input.tag };
+  const urgency = input.kind === "done" ? "normal" : "high";
+  const outcomes = await Promise.all(rows.map((r) => sendTo(r, payload, urgency)));
+  const result: NotifyResult = { sent: 0, removed: 0, failed: 0 };
+  outcomes.forEach((o, i) => {
+    if (o.ok) result.sent++;
+    else if (o.gone) {
+      deleteRow(rows[i]!.id);
+      result.removed++;
+    } else {
+      result.failed++;
+      console.warn(`push to ${rows[i]!.id} failed: ${o.message}`);
+    }
+  });
+  return result;
+}
+
+// ---------- routes ----------
+
+const NOT_SUBSCRIBED = "此设备尚未订阅推送";
+
+/** Routes under /api/push (behind requireAuth, which index.ts applies to /api/*). */
+export function registerPushRoutes(app: Hono) {
+  app.get("/api/push/key", (c) => c.json({ publicKey: vapid.publicKey }));
+
+  app.get("/api/push/subscriptions", (c) => c.json(listSubscriptions()));
+
+  /** Settings of one device (by endpoint) — `subscribed: false` when the server doesn't know it. */
+  app.get("/api/push/settings", (c) => {
+    const row = findSub({ endpoint: c.req.query("endpoint") });
+    return c.json(row ? { subscribed: true, ...info(row) } : { subscribed: false });
+  });
+
+  app.patch("/api/push/settings", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const row = findSub(body);
+    if (!row) return c.json({ error: NOT_SUBSCRIBED }, 404);
+    return c.json(updateKinds(row, parseKinds(body.kinds)));
+  });
+
+  app.post("/api/push/subscribe", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const saved = saveSubscription(body, c.req.header("user-agent") ?? "");
+    return saved ? c.json(saved) : c.json({ error: "无效的推送订阅" }, 400);
+  });
+
+  app.delete("/api/push/subscribe", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const row = findSub(body);
+    if (row) deleteRow(row.id);
+    return c.json({ ok: true, removed: !!row });
+  });
+
+  app.post("/api/push/test", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    if (typeof body.endpoint !== "string" && typeof body.id !== "string") return c.json({ error: "缺少 endpoint" }, 400);
+    const row = findSub(body);
+    if (!row) return c.json({ error: NOT_SUBSCRIBED }, 404);
+    const out = await sendTo(row, { kind: "test", title: "Claude IDE", body: "测试通知：推送已开启。", url: "/", tag: "test" }, "high");
+    if (out.ok) return c.json({ ok: true });
+    if (out.gone) {
+      deleteRow(row.id);
+      return c.json({ error: "订阅已失效，已删除；请重新开启推送" }, 410);
+    }
+    return c.json({ error: out.message }, 502);
+  });
+}

package/server/report-cache.ts

@@ -0,0 +1,28 @@
+/**
+ * The agent SDK detects musl vs glibc with `process.report.getReport()`. That
+ * walks every socket and calls getnameinfo() for each endpoint, which on WSL
+ * blocks in a synchronous reverse-DNS lookup (5s timeouts) and freezes the
+ * event loop. The report is also only inspected for `header.glibcVersionRuntime`,
+ * so compute it once at startup (no client sockets yet) and reuse it.
+ *
+ * CLAUDE_IDE_CACHE_REPORT=0 disables the workaround.
+ */
+import fs from "node:fs";
+
+const report = process.report as typeof process.report | undefined;
+
+if (process.env.CLAUDE_IDE_CACHE_REPORT !== "0" && process.platform === "linux" && typeof report?.getReport === "function") {
+  const original = report.getReport.bind(report);
+  let cached: ReturnType<typeof original> | undefined;
+  try {
+    cached = original();
+    fs.appendFileSync("/tmp/report-cache.log", `${new Date().toISOString()} cached report at startup pid=${process.pid}\n`);
+  } catch {
+    // fall through to the original call
+  }
+  if (cached) {
+    // Only the no-argument call (what the SDK makes) is served from the cache;
+    // options-bearing calls keep their original semantics.
+    report.getReport = ((...args: Parameters<typeof original>) => (args.length ? original(...args) : cached)) as typeof report.getReport;
+  }
+}

package/server/session-aliases.test.ts

@@ -0,0 +1,57 @@
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "cide-aliases-"));
+process.env.CLAUDE_IDE_DATA_DIR = dir;
+process.env.CLAUDE_IDE_PASSWORD = "synthetic-alias-test";
+const { db } = await import("./db.ts");
+const { aliasesFor, aliasTarget, aliasForTarget, setAlias, removeAlias, removeSessionAliases, validateAlias } = await import("./session-aliases.ts");
+after(async () => { db.close(); await fs.rm(dir, { recursive: true, force: true }); });
+
+test("aliases are owner-local, and reverse source lookup uses the receiver's address book", () => {
+  setAlias("a", "b", "reviewer");
+  setAlias("b", "a", "planner");
+  setAlias("c", "d", "reviewer");
+  assert.equal(aliasTarget("a", "reviewer"), "b");
+  assert.equal(aliasTarget("c", "reviewer"), "d");
+  assert.equal(aliasForTarget("b", "a"), "planner");
+  assert.equal(aliasForTarget("d", "a"), undefined);
+  assert.deepEqual(aliasesFor("a"), [{ alias: "reviewer", sessionId: "b" }]);
+});
+
+test("renaming keeps one nickname per target and refuses another contact's name", () => {
+  setAlias("rename-owner", "first", "old");
+  setAlias("rename-owner", "second", "taken");
+  assert.throws(() => setAlias("rename-owner", "first", "taken"), /already refers/);
+  assert.equal(aliasTarget("rename-owner", "old"), "first");
+  assert.equal(aliasTarget("rename-owner", "taken"), "second");
+  setAlias("rename-owner", "first", " new ");
+  assert.equal(aliasTarget("rename-owner", "old"), undefined);
+  assert.equal(aliasTarget("rename-owner", "new"), "first");
+  setAlias("rename-owner", "first", "new");
+  assert.equal(aliasesFor("rename-owner").length, 2);
+});
+
+test("removal is scoped to owner; actual deletion clears incoming and outgoing aliases only", () => {
+  setAlias("delete-a", "delete-b", "peer");
+  setAlias("delete-c", "delete-b", "peer");
+  setAlias("delete-b", "delete-c", "other");
+  setAlias("delete-c", "delete-d", "keep");
+  assert.equal(removeAlias("delete-a", "peer"), true);
+  assert.equal(removeAlias("delete-a", "peer"), false);
+  assert.equal(aliasTarget("delete-c", "peer"), "delete-b");
+  removeSessionAliases("delete-b");
+  assert.deepEqual(aliasesFor("delete-b"), []);
+  assert.deepEqual(aliasesFor("delete-c"), [{ alias: "keep", sessionId: "delete-d" }]);
+});
+
+test("invalid names cannot inject headers or shadow direct Session IDs", () => {
+  for (const alias of ["", "  ", "x".repeat(101), "x\ny", "x\r", "x\u0000", "x\u0085", "12345678-1234-1234-1234-123456789abc"]) {
+    assert.throws(() => validateAlias(alias));
+  }
+  assert.equal(validateAlias(" 审阅者 "), "审阅者");
+  assert.throws(() => setAlias("same", "same", "self"), /itself/);
+});

package/server/session-aliases.ts

@@ -0,0 +1,50 @@
+import { db } from "./db.ts";
+
+export type SessionAlias = { alias: string; sessionId: string };
+
+/** UUID-shaped names are reserved for direct session addressing. */
+export const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function validateAlias(value: string): string {
+  // Check before trimming so trailing line breaks cannot enter a message header.
+  if (/[\u0000-\u001f\u007f-\u009f]/u.test(value)) throw new Error("Alias must not contain control characters");
+  const alias = value.trim();
+  if (!alias || alias.length > 100) throw new Error("Alias must contain between 1 and 100 characters");
+  if (SESSION_ID_PATTERN.test(alias)) throw new Error("Alias must not look like a Session ID");
+  return alias;
+}
+
+export function aliasesFor(owner: string): SessionAlias[] {
+  const rows = db.prepare("SELECT alias, target_session_id AS sessionId FROM session_aliases WHERE owner_session_id = ? ORDER BY alias").all(owner) as SessionAlias[];
+  return rows.map(({ alias, sessionId }) => ({ alias, sessionId }));
+}
+
+export function aliasTarget(owner: string, alias: string): string | undefined {
+  return (db.prepare("SELECT target_session_id FROM session_aliases WHERE owner_session_id = ? AND alias = ?").get(owner, alias) as { target_session_id: string } | undefined)?.target_session_id;
+}
+
+export function aliasForTarget(owner: string, target: string): string | undefined {
+  return (db.prepare("SELECT alias FROM session_aliases WHERE owner_session_id = ? AND target_session_id = ?").get(owner, target) as { alias: string } | undefined)?.alias;
+}
+
+/** One nickname per contact. A rename cannot take another contact's nickname. */
+export function setAlias(owner: string, target: string, value: string): void {
+  const alias = validateAlias(value);
+  if (owner === target) throw new Error("Cannot assign an Alias to this session itself");
+  const current = aliasTarget(owner, alias);
+  if (current && current !== target) throw new Error("Alias already refers to another session; remove it first");
+  // Synchronous SQLite statements have no intervening await; the UNIQUE constraint
+  // also protects against another process writing the same database.
+  db.prepare(`INSERT INTO session_aliases (owner_session_id, target_session_id, alias) VALUES (?, ?, ?)
+    ON CONFLICT(owner_session_id, target_session_id) DO UPDATE SET alias = excluded.alias`).run(owner, target, alias);
+}
+
+export function removeAlias(owner: string, value: string): boolean {
+  const alias = validateAlias(value);
+  return db.prepare("DELETE FROM session_aliases WHERE owner_session_id = ? AND alias = ?").run(owner, alias).changes > 0;
+}
+
+/** Called only after actual session deletion, never process stop or idle reap. */
+export function removeSessionAliases(sessionId: string): void {
+  db.prepare("DELETE FROM session_aliases WHERE owner_session_id = ? OR target_session_id = ?").run(sessionId, sessionId);
+}

package/server/session-branch.ts

@@ -0,0 +1,71 @@
+/** Native JSONL graph selection shared by presentation and control-state readers.
+ * Presentation can stop at the last message; state replay includes metadata at
+ * the same branch tail. No message-body normalization belongs in this layer. */
+export type BranchEntry = {
+  uuid: string; order: number; type: string; subtype?: string;
+  parentUuid?: string | null; logicalParentUuid?: string;
+  isSidechain?: boolean; teamName?: string; attachmentType?: string;
+  compactMetadata?: { preservedMessages?: { uuids: string[]; anchorUuid: string }; preservedSegment?: { headUuid: string; tailUuid: string; anchorUuid: string } };
+};
+
+export class HistoryError extends Error {
+  constructor(public status: 400 | 404 | 409, message: string) { super(message); }
+}
+
+export const eligibleBranchEntry = (e: BranchEntry, sidechain = false) => (sidechain || !e.isSidechain && !e.teamName)
+  && e.type !== "progress" && !(e.type === "attachment" && e.attachmentType === "fork_briefing");
+
+export function selectSessionBranch<T extends BranchEntry>(entries: ReadonlyMap<string, T>, anchor?: string | null, sidechain = false, includeTail = false): { chain: T[]; tail?: T; cutoff: number } {
+  const cutoff = anchor ? entries.get(anchor)?.order ?? Infinity : Infinity;
+  const parents = new Map([...entries].map(([id, e]) => [id, e.parentUuid]));
+  for (const e of entries.values()) {
+    if (e.type !== "system" || e.subtype !== "compact_boundary" || e.order > cutoff) continue;
+    const p = e.compactMetadata?.preservedMessages;
+    const s = e.compactMetadata?.preservedSegment;
+    if (p?.uuids.length && p.uuids.every((id) => entries.has(id))) {
+      let previous = p.anchorUuid;
+      for (const id of p.uuids) { parents.set(id, previous); previous = id; }
+      for (const [id, parent] of parents) if (parent === p.anchorUuid && id !== p.uuids[0]) parents.set(id, previous);
+    } else if (s && entries.has(s.headUuid)) {
+      parents.set(s.headUuid, s.anchorUuid);
+      for (const [id, parent] of parents) if (parent === s.anchorUuid && id !== s.headUuid) parents.set(id, s.tailUuid);
+    }
+  }
+  const eligible = (e: T) => eligibleBranchEntry(e, sidechain);
+  const parentIds = new Set([...entries.values()].filter(eligible).map((e) => parents.get(e.uuid)).filter(Boolean));
+  const leaves = [...entries.values()].filter((e) => eligible(e) && !parentIds.has(e.uuid)).sort((a, b) => b.order - a.order);
+  let tail: T | undefined;
+  for (const leaf of leaves) {
+    let e: T | undefined = leaf;
+    const visited = new Set<string>();
+    while (e && !visited.has(e.uuid)) {
+      visited.add(e.uuid);
+      if (e.type === "user" || e.type === "assistant") { tail = includeTail ? leaf : e; break; }
+      e = entries.get(parents.get(e.uuid) ?? "");
+    }
+    if (tail) break;
+  }
+  if (anchor) {
+    const found = entries.get(anchor);
+    if (!found) throw new HistoryError(409, "回退位置已变化，请重新加载会话");
+    tail = found;
+  }
+  const seen = new Set<string>();
+  const chain: T[] = [];
+  let e = tail;
+  let beforeCompaction = false;
+  const walked = new Set<string>();
+  while (e) {
+    const visit = `${beforeCompaction}:${e.uuid}`;
+    if (walked.has(visit)) break;
+    walked.add(visit);
+    if (!seen.has(e.uuid)) { seen.add(e.uuid); chain.push(e); }
+    // Once crossing a boundary, follow original links through preserved duplicates.
+    // The current-context rewrites would otherwise lead back into the same summary.
+    let parent = beforeCompaction ? e.parentUuid : parents.get(e.uuid);
+    if (!parent && e.subtype === "compact_boundary" && e.logicalParentUuid) { parent = e.logicalParentUuid; beforeCompaction = true; }
+    e = entries.get(parent ?? "");
+  }
+  chain.reverse();
+  return { chain, tail, cutoff };
+}