@baique/pi-web-sky 0.1.35 → 0.1.37

package/lib/task-store.test.mjs

@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { DatabaseSync } from "node:sqlite";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+const { getDb, setDbForTesting } = await jiti.import("./sqlite-db.ts");
+const { createTask, deleteTask, listTasks, updateTask, taskForSession, assignSessionToTask, reorderTasks } = await jiti.import("./task-store.ts");
+const { getBoard, getBoardCanvas, getOrCreateTaskBoard, addNode, createBoard } = await jiti.import("./board-store.ts");
+const { createCard, addLink, createQuestion } = await jiti.import("./task-card-store.ts");
+
+function freshDb() {
+  setDbForTesting(new DatabaseSync(":memory:"));
+}
+
+// Seed a session_meta row directly — in real flow membership writes these
+// rows, but a NULL-task row is exactly a temp session's state.
+function seedSession(sessionId, taskId) {
+  getDb()
+    .prepare("INSERT INTO session_meta (session_id, task_id, updated) VALUES (?, ?, ?)")
+    .run(sessionId, taskId, Date.now());
+}
+
+test("createTask and listTasks per project", () => {
+  freshDb();
+  const a = createTask("proj-a", " 重构登录 ");
+  assert.equal(a.name, "重构登录");
+  assert.deepEqual(a.sessionIds, []);
+  createTask("proj-a", "另一任务");
+  createTask("proj-b", "别项目");
+  const names = listTasks("proj-a").map((t) => t.name).sort();
+  assert.deepEqual(names, ["另一任务", "重构登录"]);
+  assert.equal(listTasks("proj-b").length, 1);
+  assert.equal(listTasks("proj-none").length, 0);
+});
+
+test("updateTask tracks membership diff without touching other tasks", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  const b = createTask("p", "B");
+  seedSession("s1", null); // temp
+  seedSession("s2", null); // temp
+  seedSession("s3", b.id); // belongs to task B
+
+  let updated = updateTask(a.id, { sessionIds: ["s1", "s3"] });
+  // listTaskSessionIds 按 pinned DESC, updated DESC, rowid DESC 排序：
+  // 同批分配时后插入的行在前，这里做顺序无关的集合断言。
+  assert.deepEqual([...updated.sessionIds].sort(), ["s1", "s3"]);
+  // s1 newly assigned, s3 moved away from B, B untouched otherwise.
+  assert.equal(taskForSession("s1"), a.id);
+  assert.equal(taskForSession("s3"), a.id);
+  assert.equal(taskForSession("s2"), null);
+  assert.deepEqual(listTasks("p").find((t) => t.id === b.id).sessionIds, []);
+
+  // Replace: s1 falls back to temp, s3 kept.
+  updated = updateTask(a.id, { sessionIds: ["s3"] });
+  assert.deepEqual(updated.sessionIds, ["s3"]);
+  assert.equal(taskForSession("s1"), null);
+  assert.equal(taskForSession("s3"), a.id);
+
+  // Rename only — membership untouched.
+  updated = updateTask(a.id, { name: "改名任务" });
+  assert.equal(updated.name, "改名任务");
+  assert.deepEqual(updated.sessionIds, ["s3"]);
+
+  // Pin sorting: pinned sessions float before unpinned regardless of recency.
+  seedSession("sp", a.id);
+  getDb().prepare("UPDATE session_meta SET pinned = 1 WHERE session_id = ?").run("sp");
+  updated = updateTask(a.id, { sessionIds: ["sp", "s3", "s1"] });
+  assert.deepEqual(updated.pinnedSessionIds, ["sp"]);
+  assert.equal(updated.sessionIds[0], "sp");
+});
+
+test("deleteTask unassigns members and removes the task", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  seedSession("s1", null);
+  updateTask(a.id, { sessionIds: ["s1"] });
+  deleteTask(a.id);
+  assert.equal(taskForSession("s1"), null);
+  assert.equal(listTasks("p").length, 0);
+  assert.equal(updateTask(a.id, { name: "x" }), null);
+});
+
+test("deleteTask cascades task_cards / links / questions (no orphan cards)", () => {
+  freshDb();
+  const t = createTask("p", "A");
+  const board = getOrCreateTaskBoard(t.id, "p", "A");
+  const c1 = createCard({ boardId: board.id, projectKey: "p", name: "卡1" });
+  const c2 = createCard({ boardId: board.id, projectKey: "p", name: "卡2" });
+  addLink(c1.id, c2.id, "prerequisite");
+  createQuestion(c1.id, "sess", "问题");
+
+  deleteTask(t.id);
+  assert.equal(getDb().prepare("SELECT COUNT(*) AS n FROM task_cards WHERE board_id = ?").get(t.id).n, 0);
+  assert.equal(getDb().prepare("SELECT COUNT(*) AS n FROM task_card_links").get().n, 0);
+  assert.equal(getDb().prepare("SELECT COUNT(*) AS n FROM task_card_questions").get().n, 0);
+  // 任务看板也随之删（deleteBoardCascade）
+  assert.equal(getBoard(t.id), undefined);
+});
+
+test("createTask validates input", () => {
+  freshDb();
+  assert.throws(() => createTask("", "x"), /projectKey is required/);
+  assert.throws(() => createTask("p", "   "), /name must not be empty/);
+});
+
+test("updateTask returns null for unknown id and rejects empty rename", () => {
+  freshDb();
+  assert.equal(updateTask("nope", { name: "x" }), null);
+  const a = createTask("p", "A");
+  assert.throws(() => updateTask(a.id, { name: "  " }), /name must not be empty/);
+});
+
+test("assignSessionToTask attaches a session atomically and bumps the task's updated", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  seedSession("s1", null); // temp
+  seedSession("s2", a.id); // already a member
+
+  assert.equal(assignSessionToTask("s1", a.id), true);
+  assert.equal(taskForSession("s1"), a.id);
+  // 重复归属幂等：已是成员再归一次仍成功且不重复。
+  assert.equal(assignSessionToTask("s2", a.id), true);
+
+  const task = listTasks("p")[0];
+  assert.deepEqual([...task.sessionIds].sort(), ["s1", "s2"]);
+  assert.ok(task.updated >= task.created, "归属会刷新任务的 updated（排序用）");
+});
+
+test("assignSessionToTask returns false for a missing task without writing anything", () => {
+  freshDb();
+  seedSession("s1", null);
+  assert.equal(assignSessionToTask("s1", "no-such-task"), false);
+  assert.equal(taskForSession("s1"), null);
+  assert.equal(listTasks("p").length, 0);
+});
+
+test("listTasks honors sort_order within each pinned region", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  const b = createTask("p", "B");
+  const c = createTask("p", "C");
+  // 新任务置顶：sort_order 取最小值 - 1，按创建序倒排（最新在最上）。
+  assert.deepEqual(listTasks("p").map((t) => t.name), ["C", "B", "A"]);
+
+  // 手动重排：C 置顶，A/B 非置顶区交换。
+  updateTask(c.id, { pinned: true });
+  reorderTasks("p", [b.id, a.id]); // 非置顶区顺序
+  assert.deepEqual(listTasks("p").map((t) => t.name), ["C", "B", "A"]);
+});
+
+test("reorderTasks validates ownership and preserves region isolation", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  createTask("p", "B");
+  createTask("other", "X"); // 别项目
+  // 传入不属于该项目的 id → 抛错，事务回滚。
+  const other = listTasks("other")[0];
+  assert.throws(() => reorderTasks("p", [a.id, other.id]), /does not belong/);
+  // 回滚后顺序未变。
+  assert.deepEqual(listTasks("p").map((t) => t.name), ["B", "A"]);
+});
+
+test("updateTask supports sortOrder patch", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  const b = createTask("p", "B");
+  // 新任务置顶（sort_order 递减），默认顺序：B(-1) 在 A(0) 前。
+  assert.deepEqual(listTasks("p").map((t) => t.name), ["B", "A"]);
+  // sortOrder 越大越靠后：A 设 99 后仍在 B 后面（B 为负数，排前面）。
+  updateTask(a.id, { sortOrder: 99 });
+  assert.deepEqual(listTasks("p").map((t) => t.name), ["B", "A"]);
+  // sortOrder 字段随任务返回。
+  const task = listTasks("p").find((t) => t.id === a.id);
+  assert.equal(task.sortOrder, 99);
+  assert.equal(b.sortOrder < 0, true);
+});
+
+test("assignSessionToTask moves a session out of its previous task", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  const b = createTask("p", "B");
+  seedSession("s1", null);
+  assignSessionToTask("s1", a.id);
+  assignSessionToTask("s1", b.id); // 移动到 B
+  assert.equal(taskForSession("s1"), b.id);
+  const taskA = listTasks("p").find((t) => t.id === a.id);
+  assert.deepEqual(taskA.sessionIds, []);
+});
+
+test("deleteTask cascades to its task board (nodes/edges/view gone)", () => {
+  freshDb();
+  const a = createTask("p", "A");
+  const board = getOrCreateTaskBoard(a.id, "p", "A");
+  const n1 = addNode(board.id, { x: 0, y: 0, refId: "s1" });
+  assert.ok(n1);
+  deleteTask(a.id);
+  assert.equal(getBoard(board.id), undefined);
+  assert.equal(getBoardCanvas(board.id), null);
+  // 手动看板不受影响
+  const manual = createBoard("p", "manual");
+  assert.ok(getBoard(manual.id));
+});
+
+test("updateTask rename syncs task board name", () => {
+  freshDb();
+  const a = createTask("p", "旧名");
+  const board = getOrCreateTaskBoard(a.id, "p", "旧名");
+  assert.equal(board.name, "旧名");
+  updateTask(a.id, { name: "新名" });
+  assert.equal(getBoard(board.id)?.name, "新名");
+  // 看板未创建时改名无副作用
+  const b = createTask("p", "B");
+  updateTask(b.id, { name: "B2" });
+});

package/lib/task-store.ts

@@ -0,0 +1,271 @@
+import { randomUUID } from "crypto";
+import { getDb } from "./sqlite-db";
+import { deleteBoardCascade, renameTaskBoard } from "./board-store";
+
+export interface Task {
+  id: string;
+  projectKey: string;
+  name: string;
+  created: number;
+  updated: number;
+  pinned: boolean;
+  sortOrder: number;
+  sessionIds: string[];
+  pinnedSessionIds: string[];
+}
+
+interface TaskRow {
+  id: string;
+  projectKey: string;
+  name: string;
+  created: number;
+  updated: number;
+  pinned: number;
+  sortOrder: number;
+}
+
+const now = () => Date.now();
+
+/** 任务下根会话 id（不含 fork 子树，子树由树结构隐含归属）。 */
+export function listTaskSessionIds(taskId: string): string[] {
+  // Order here is a fallback only: the sidebar re-sorts group contents by
+  // session modified-time (desc) + pinned segment, so this must stay in sync
+  // directionally (pinned first, then descending recency).
+  return getDb()
+    .prepare("SELECT session_id FROM session_meta WHERE task_id = ? ORDER BY pinned DESC, updated DESC, rowid DESC")
+    .all(taskId)
+    .map((r) => (r as { session_id: string }).session_id);
+}
+
+function getTaskRow(id: string): TaskRow | undefined {
+  return getDb()
+    .prepare(
+      "SELECT id, project_key AS projectKey, name, created, updated, pinned, sort_order AS sortOrder FROM tasks WHERE id = ?",
+    )
+    .get(id) as TaskRow | undefined;
+}
+
+function listPinnedTaskSessionIds(taskId: string): string[] {
+  return getDb()
+    .prepare("SELECT session_id FROM session_meta WHERE task_id = ? AND pinned = 1")
+    .all(taskId)
+    .map((r) => (r as { session_id: string }).session_id);
+}
+
+function rowToTask(row: TaskRow): Task {
+  return {
+    ...row,
+    pinned: row.pinned === 1,
+    sessionIds: listTaskSessionIds(row.id),
+    pinnedSessionIds: listPinnedTaskSessionIds(row.id),
+  };
+}
+
+/** A single task by id, or undefined. */
+export function getTask(id: string): Task | undefined {
+  const row = getTaskRow(id);
+  return row ? rowToTask(row) : undefined;
+}
+
+/** All tasks of one project: pinned segment first, then manual order
+ *  (sort_order), then creation time as a stable fallback. */
+export function listTasks(projectKey: string): Task[] {
+  const rows = getDb()
+    .prepare(
+      "SELECT id, project_key AS projectKey, name, created, updated, pinned, sort_order AS sortOrder FROM tasks WHERE project_key = ? ORDER BY pinned DESC, sort_order, created, rowid",
+    )
+    .all(projectKey) as unknown as TaskRow[];
+  return rows.map(rowToTask);
+}
+
+export function createTask(projectKey: string, name: string): Task {
+  const trimmed = name.trim();
+  if (!projectKey) throw new Error("projectKey is required");
+  if (!trimmed) throw new Error("name must not be empty");
+  const id = randomUUID();
+  const ts = now();
+  // 新任务置顶：sort_order 取当前项目最小值 - 1（与看板 createBoard 一致），
+  // 保证新建任务出现在任务区最上方。
+  const minRow = getDb()
+    .prepare("SELECT MIN(sort_order) AS minOrder FROM tasks WHERE project_key = ?")
+    .get(projectKey) as { minOrder: number | null };
+  const sortOrder = minRow.minOrder === null ? 0 : minRow.minOrder - 1;
+  getDb()
+    .prepare("INSERT INTO tasks (id, project_key, name, created, updated, sort_order) VALUES (?, ?, ?, ?, ?, ?)")
+    .run(id, projectKey, trimmed, ts, ts, sortOrder);
+  return { id, projectKey: projectKey, name: trimmed, created: ts, updated: ts, pinned: false, sortOrder, sessionIds: [], pinnedSessionIds: [] };
+}
+
+/**
+ * Rename and/or replace task membership. `sessionIds` is a full-replace list:
+ * the diff only touches this task's members — added ids get task_id set (or
+ * moved from another task), removed ids fall back to temp (NULL), members of
+ * other tasks are never modified. Returns null when the task does not exist.
+ */
+export function updateTask(
+  id: string,
+  patch: { name?: string; sessionIds?: string[]; pinned?: boolean; sortOrder?: number },
+): Task | null {
+  const db = getDb();
+  const existing = getTaskRow(id);
+  if (!existing) return null;
+
+  db.exec("BEGIN");
+  try {
+    if (patch.name !== undefined) {
+      const trimmed = patch.name.trim();
+      if (!trimmed) throw new Error("name must not be empty");
+      db.prepare("UPDATE tasks SET name = ?, updated = ? WHERE id = ?").run(trimmed, now(), id);
+      // 任务型看板名随任务同步（看板未创建则 0 行无害）
+      renameTaskBoard(id, trimmed);
+    }
+    if (patch.pinned !== undefined) {
+      db.prepare("UPDATE tasks SET pinned = ?, updated = ? WHERE id = ?").run(
+        patch.pinned ? 1 : 0,
+        now(),
+        id,
+      );
+    }
+    if (patch.sortOrder !== undefined) {
+      db.prepare("UPDATE tasks SET sort_order = ?, updated = ? WHERE id = ?").run(
+        patch.sortOrder,
+        now(),
+        id,
+      );
+    }
+    if (patch.sessionIds !== undefined) {
+      const current = new Set(listTaskSessionIds(id));
+      const next = new Set(patch.sessionIds);
+      const ts = now();
+      const assign = db.prepare(
+        "INSERT INTO session_meta (session_id, task_id, updated) VALUES (?, ?, ?) " +
+          "ON CONFLICT(session_id) DO UPDATE SET task_id = excluded.task_id, updated = excluded.updated",
+      );
+      const unassign = db.prepare(
+        "UPDATE session_meta SET task_id = NULL, updated = ? WHERE session_id = ?",
+      );
+      for (const sessionId of patch.sessionIds) {
+        if (!current.has(sessionId)) assign.run(sessionId, id, ts);
+      }
+      for (const sessionId of current) {
+        if (!next.has(sessionId)) unassign.run(ts, sessionId);
+      }
+      db.prepare("UPDATE tasks SET updated = ? WHERE id = ?").run(ts, id);
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return rowToTask(getTaskRow(id)!);
+}
+
+/**
+ * Bulk-reorder tasks within one project. `orderedIds` is the full ordered
+ * list of task ids for one pinned segment (caller splits pinned/unpinned);
+ * each id must belong to the project. sort_order values are written as the
+ * array position (0-based), preserving relative order.
+ */
+export function reorderTasks(projectKey: string, orderedIds: string[]): Task[] {
+  const db = getDb();
+  if (orderedIds.length === 0) return listTasks(projectKey);
+  db.exec("BEGIN");
+  try {
+    const stmt = db.prepare("UPDATE tasks SET sort_order = ?, updated = ? WHERE id = ? AND project_key = ?");
+    orderedIds.forEach((id, index) => {
+      const res = stmt.run(index, now(), id, projectKey);
+      if (res.changes === 0) {
+        throw new Error(`task ${id} does not belong to project ${projectKey}`);
+      }
+    });
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return listTasks(projectKey);
+}
+
+/** Delete the task; all its sessions fall back to temp (task_id = NULL).
+ *  任务型看板（boards.task_id = 任务 id）连带级联删除。 */
+export function deleteTask(id: string): void {
+  const db = getDb();
+  db.exec("BEGIN");
+  try {
+    db.prepare("UPDATE session_meta SET task_id = NULL, updated = ? WHERE task_id = ?").run(
+      now(),
+      id,
+    );
+    db.prepare("DELETE FROM tasks WHERE id = ?").run(id);
+    // 任务卡级联：该任务看板（board_id = 任务 id）下的任务卡 + 依赖线 + 待答问题清掉，
+    // 防孤儿任务卡（任务卡节点/边已由 deleteBoardCascade 删，这里清业务表）。
+    db.prepare(
+      "DELETE FROM task_card_links WHERE card_id IN (SELECT id FROM task_cards WHERE board_id = ?) OR target_card_id IN (SELECT id FROM task_cards WHERE board_id = ?)",
+    ).run(id, id);
+    db.prepare("DELETE FROM task_card_questions WHERE card_id IN (SELECT id FROM task_cards WHERE board_id = ?)").run(id);
+    db.prepare("DELETE FROM task_cards WHERE board_id = ?").run(id);
+    // 任务即看板：删任务连带删其看板（含 nodes/edges/view）
+    deleteBoardCascade(id);
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+/** Session's current task id, or null when it is a temp session. */
+export function taskForSession(sessionId: string): string | null {
+  const row = getDb()
+    .prepare("SELECT task_id FROM session_meta WHERE session_id = ?")
+    .get(sessionId) as { task_id: string | null } | undefined;
+  return row?.task_id ?? null;
+}
+
+/** Session's current task name, or null when it is a temp session. */
+export function taskNameForSession(sessionId: string): string | null {
+  const row = getDb()
+    .prepare(
+      "SELECT t.name FROM session_meta m JOIN tasks t ON t.id = m.task_id WHERE m.session_id = ?",
+    )
+    .get(sessionId) as { name: string } | undefined;
+  return row?.name ?? null;
+}
+
+/**
+ * 把一个会话原子归属到任务（任务不存在返回 false）。会刷新任务的 updated
+ * 使置顶/最近排序生效；会话原本在其他任务下则移动（ON CONFLICT 更新）。
+ * 会话创建完成时由服务端调用，避免前端两跳 PATCH 造成的“先临时区后任务”窗口。
+ */
+export function assignSessionToTask(sessionId: string, taskId: string): boolean {
+  const db = getDb();
+  const task = getTaskRow(taskId);
+  if (!task) return false;
+  const ts = now();
+  db.exec("BEGIN");
+  try {
+    db.prepare(
+      "INSERT INTO session_meta (session_id, task_id, updated) VALUES (?, ?, ?) " +
+        "ON CONFLICT(session_id) DO UPDATE SET task_id = excluded.task_id, updated = excluded.updated",
+    ).run(sessionId, taskId, ts);
+    db.prepare("UPDATE tasks SET updated = ? WHERE id = ?").run(ts, taskId);
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return true;
+}
+
+/** Pin / unpin a session (region-relative: inside its task group, or in chat). */
+export function setSessionPinned(sessionId: string, pinned: boolean): void {
+  const db = getDb();
+  db.prepare(
+    "INSERT INTO session_meta (session_id, task_id, updated, pinned) VALUES (?, NULL, ?, ?) " +
+      "ON CONFLICT(session_id) DO UPDATE SET pinned = excluded.pinned",
+  ).run(sessionId, now(), pinned ? 1 : 0);
+}
+
+/** Drop all task/meta bookkeeping for a session (used on session delete). */
+export function unassignSession(sessionId: string): void {
+  getDb().prepare("DELETE FROM session_meta WHERE session_id = ?").run(sessionId);
+}

package/lib/terminal-input.test.mjs

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+async function loadSubject() {
+  return import("./terminal-input.ts");
+}
+
+function key(keyValue, modifiers = {}) {
+  return {
+    key: keyValue,
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    ...modifiers,
+  };
+}
+
+test("maps navigation and editing keys to terminal sequences", async () => {
+  const { toTerminalKeyData } = await loadSubject();
+
+  assert.equal(toTerminalKeyData(key("ArrowDown")), "\x1b[B");
+  assert.equal(toTerminalKeyData(key("Home")), "\x1b[H");
+  assert.equal(toTerminalKeyData(key("Delete")), "\x1b[3~");
+  assert.equal(toTerminalKeyData(key("Tab", { shiftKey: true })), "\x1b[Z");
+  assert.equal(toTerminalKeyData(key("Enter", { shiftKey: true })), "\n");
+});
+
+test("maps legacy control and alt keys used by pi-tui", async () => {
+  const { toTerminalKeyData } = await loadSubject();
+
+  assert.equal(toTerminalKeyData(key("c", { ctrlKey: true })), "\x03");
+  assert.equal(toTerminalKeyData(key("]", { ctrlKey: true })), "\x1d");
+  assert.equal(toTerminalKeyData(key("ArrowLeft", { altKey: true })), "\x1bb");
+  assert.equal(toTerminalKeyData(key("x", { altKey: true })), "\x1bx");
+  assert.equal(toTerminalKeyData(key("v", { ctrlKey: true })), null);
+  assert.equal(toTerminalKeyData(key("x", { metaKey: true })), null);
+});
+
+test("leaves printable text to the text input and wraps pasted text", async () => {
+  const { asBracketedPaste, toTerminalKeyData } = await loadSubject();
+
+  assert.equal(toTerminalKeyData(key("a")), null);
+  assert.equal(toTerminalKeyData(key(" ")), null);
+  assert.equal(asBracketedPaste("first\nsecond"), "\x1b[200~first\nsecond\x1b[201~");
+});

package/lib/terminal-input.ts

@@ -0,0 +1,63 @@
+export interface TerminalKeyEventLike {
+  key: string;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+}
+
+const SPECIAL_KEY_SEQUENCES: Record<string, string> = {
+  ArrowUp: "\x1b[A",
+  ArrowDown: "\x1b[B",
+  ArrowRight: "\x1b[C",
+  ArrowLeft: "\x1b[D",
+  Home: "\x1b[H",
+  End: "\x1b[F",
+  Insert: "\x1b[2~",
+  Delete: "\x1b[3~",
+  PageUp: "\x1b[5~",
+  PageDown: "\x1b[6~",
+  Escape: "\x1b",
+  Backspace: "\x7f",
+};
+
+const ALT_ARROW_SEQUENCES: Record<string, string> = {
+  ArrowLeft: "\x1bb",
+  ArrowRight: "\x1bf",
+  ArrowUp: "\x1bp",
+  ArrowDown: "\x1bn",
+};
+
+function legacyCtrlSequence(key: string): string | null {
+  if (key.length !== 1) return null;
+  const code = key.toUpperCase().charCodeAt(0);
+  if (code >= 64 && code <= 95) return String.fromCharCode(code & 0x1f);
+  if (key === "?") return "\x7f";
+  return null;
+}
+
+export function toTerminalKeyData(event: TerminalKeyEventLike): string | null {
+  if (event.metaKey) return null;
+  if (event.ctrlKey && !event.altKey && event.key.toLowerCase() === "v") return null;
+
+  if (event.ctrlKey && !event.altKey) {
+    const control = legacyCtrlSequence(event.key);
+    if (control) return control;
+  }
+
+  if (event.altKey && !event.ctrlKey) {
+    if (event.key === "Backspace") return "\x1b\x7f";
+    const arrow = ALT_ARROW_SEQUENCES[event.key];
+    if (arrow) return arrow;
+    if (event.key.length === 1) return `\x1b${event.key}`;
+  }
+
+  if (event.key === "Enter") return event.shiftKey ? "\n" : "\r";
+  if (event.key === "Tab") return event.shiftKey ? "\x1b[Z" : "\t";
+
+  return SPECIAL_KEY_SEQUENCES[event.key] ?? null;
+}
+
+export function asBracketedPaste(text: string): string {
+  return `\x1b[200~${text}\x1b[201~`;
+}

package/lib/terminal-manager.test.mjs

@@ -0,0 +1,71 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  createTerminal, writeTerminal, outputSince, fullBuffer,
+  currentOffset, removeTerminal, listTerminals, trimRingBuffer,
+} from "./terminal-manager.ts";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+test("session echoes input; offsets let SSE clients resume", async () => {
+  const t = await createTerminal({ cwd: "/tmp", projectRoot: null, projectLabel: "t", cols: 80, rows: 24 });
+  try {
+    assert.ok(t.id);
+    assert.equal(t.running, true);
+    await wait(400); // let the shell print its prompt
+
+    const before = currentOffset(t.id);
+    writeTerminal(t.id, "echo hi-marker-$$\r");
+    await wait(900);
+
+    const replay = outputSince(t.id, before);
+    assert.ok(replay !== null && replay.includes("hi-marker-"), "resume slice contains new output");
+    assert.ok(fullBuffer(t.id)?.data.includes("hi-marker-"), "full buffer contains output");
+
+    // Offsets are cumulative: replaying from an older point still works while
+    // everything fits in the ring buffer.
+    assert.ok(outputSince(t.id, 0)?.includes("hi-marker-"));
+  } finally {
+    removeTerminal(t.id);
+  }
+  assert.equal(listTerminals().some((s) => s.id === t.id), false);
+});
+
+test("trimRingBuffer cuts at a line boundary", () => {
+  // Overflow lands inside a line → keep from the next line start.
+  const [kept, dropped] = trimRingBuffer("aaaa\nbbbb\ncccc\ndddd", 12);
+  assert.equal(dropped, 5, "drops up to (and including) the line break");
+  assert.equal(kept, "bbbb\ncccc\ndddd");
+
+  // Fits → untouched.
+  const [kept2, dropped2] = trimRingBuffer("short", 10);
+  assert.equal(kept2, "short");
+  assert.equal(dropped2, 0);
+
+  // Newline-free overflow → plain cut fallback (cannot align).
+  const [kept3, dropped3] = trimRingBuffer("xxxxx", 3);
+  assert.equal(kept3, "xxx");
+  assert.equal(dropped3, 2);
+});
+
+test("ring buffer rotation invalidates stale offsets", async () => {
+  const t = await createTerminal({
+    cwd: "/tmp", projectRoot: null, projectLabel: "t",
+    cols: 200, rows: 50,
+  });
+  try {
+    await wait(400);
+    // Push > 256KB through the shell so the buffer rotates.
+    writeTerminal(t.id, "head -c 400000 /dev/zero | tr '\\0' 'x'\r");
+    await wait(2500);
+    const fb = fullBuffer(t.id);
+    assert.ok(fb && fb.data.length <= 256 * 1024 + 4096, "buffer stays bounded");
+    assert.ok(fb.startOffset > 0 || fb.data.length < 400000, "rotation tracked");
+    // Offset 0 fell out of the window → null tells the client to full-replay.
+    if ((fb?.startOffset ?? 0) > 0) {
+      assert.equal(outputSince(t.id, 0), null);
+    }
+  } finally {
+    removeTerminal(t.id);
+  }
+});