tmux-ide 2.1.5 → 2.6.1

package/packages/daemon/src/lib/project-registry.ts

@@ -0,0 +1,296 @@
+/**
+ * Project registry — persists the list of projects the user has registered
+ * with tmux-ide via the dashboard. Stored at `~/.tmux-ide/projects.json`,
+ * written atomically via temp+rename (same approach as task-store).
+ *
+ * The pure decider (`applyAction`) is exported separately from the io-bound
+ * accessors so tests can reason about state transitions without hitting the
+ * filesystem. The module also exposes a `projectRegistryEmitter` that the
+ * `/ws/events` channel listens on to broadcast `projects.changed` frames.
+ */
+
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { z } from "zod";
+import { RegisteredProjectSchemaZ, type RegisteredProject } from "../schemas/registry.ts";
+import { probeProject, sanitizeName, type ProbeIo, type ProjectProbe } from "./project-probe.ts";
+
+const REGISTRY_DIR_ENV = "TMUX_IDE_REGISTRY_DIR";
+
+const RegistryFileSchemaZ = z.object({
+  version: z.literal(1),
+  projects: z.array(RegisteredProjectSchemaZ),
+});
+
+type RegistryFile = z.infer<typeof RegistryFileSchemaZ>;
+
+// ---------------------------------------------------------------------------
+// Typed errors — never use stringly-typed catches at the boundary
+// ---------------------------------------------------------------------------
+
+export class ProjectRegistryError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "ProjectRegistryError";
+    this.code = code;
+  }
+}
+
+export class ProjectAlreadyRegisteredError extends ProjectRegistryError {
+  readonly suggestion: string;
+  constructor(name: string, suggestion: string) {
+    super(`Project "${name}" is already registered`, "ALREADY_REGISTERED");
+    this.name = "ProjectAlreadyRegisteredError";
+    this.suggestion = suggestion;
+  }
+}
+
+export class ProjectNotFoundError extends ProjectRegistryError {
+  constructor(name: string) {
+    super(`Project "${name}" not found in registry`, "NOT_FOUND");
+    this.name = "ProjectNotFoundError";
+  }
+}
+
+export class ProjectDirNotFoundError extends ProjectRegistryError {
+  constructor(dir: string) {
+    super(`Directory "${dir}" does not exist`, "DIR_NOT_FOUND");
+    this.name = "ProjectDirNotFoundError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure decider: state in → state out. No io.
+// ---------------------------------------------------------------------------
+
+export type RegistryAction =
+  | { type: "register"; project: RegisteredProject }
+  | { type: "unregister"; name: string }
+  | { type: "replace"; project: RegisteredProject };
+
+export function applyAction(
+  state: readonly RegisteredProject[],
+  action: RegistryAction,
+): RegisteredProject[] {
+  switch (action.type) {
+    case "register":
+      return [...state, action.project];
+    case "unregister":
+      return state.filter((p) => p.name !== action.name);
+    case "replace":
+      return state.map((p) => (p.name === action.project.name ? action.project : p));
+  }
+}
+
+/**
+ * Resolve a unique name for a probed project, appending `-2`, `-3`, … until
+ * we don't collide with an existing entry.
+ */
+export function resolveUniqueName(state: readonly RegisteredProject[], desired: string): string {
+  const used = new Set(state.map((p) => p.name));
+  if (!used.has(desired)) return desired;
+  let counter = 2;
+  while (used.has(`${desired}-${counter}`)) counter++;
+  return `${desired}-${counter}`;
+}
+
+/**
+ * Build a `RegisteredProject` value from a probe + chosen name + timestamp.
+ * Pure — separated from `registerProject` so tests can verify the shape
+ * without io.
+ */
+export function buildRegisteredProject(
+  probe: ProjectProbe,
+  name: string,
+  registeredAt: string,
+): RegisteredProject {
+  return {
+    name,
+    dir: probe.dir,
+    hasIdeYml: probe.hasIdeYml,
+    gitOrigin: probe.gitOrigin,
+    gitBranch: probe.gitBranch,
+    registeredAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Module-level emitter — listened on by ws-events.handleWsEventsConnection
+// ---------------------------------------------------------------------------
+
+export const projectRegistryEmitter = new EventEmitter();
+// One listener per connected ws-events client; can grow with tabs.
+projectRegistryEmitter.setMaxListeners(0);
+
+// ---------------------------------------------------------------------------
+// Persistence — io-bound, single mutex (registry is small + writes are rare)
+// ---------------------------------------------------------------------------
+
+function registryDir(): string {
+  const override = process.env[REGISTRY_DIR_ENV];
+  if (override && override.length > 0) return override;
+  return join(homedir(), ".tmux-ide");
+}
+
+function registryPath(): string {
+  return join(registryDir(), "projects.json");
+}
+
+let cache: RegisteredProject[] | null = null;
+
+function readDisk(): RegisteredProject[] {
+  const path = registryPath();
+  if (!existsSync(path)) return [];
+  const raw = readFileSync(path, "utf-8");
+  if (raw.trim().length === 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn("[project-registry] %s contains invalid JSON; ignoring", path);
+    return [];
+  }
+  const result = RegistryFileSchemaZ.safeParse(parsed);
+  if (!result.success) {
+    console.warn(
+      "[project-registry] %s failed schema validation; ignoring (%s)",
+      path,
+      result.error.issues
+        .slice(0, 3)
+        .map((i) => `${i.path.join(".")}: ${i.message}`)
+        .join("; "),
+    );
+    return [];
+  }
+  return result.data.projects;
+}
+
+function writeDisk(projects: RegisteredProject[]): void {
+  const path = registryPath();
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  const file: RegistryFile = { version: 1, projects };
+  const tmpPath = `${path}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(file, null, 2) + "\n");
+  renameSync(tmpPath, path);
+}
+
+function ensureCache(): RegisteredProject[] {
+  if (cache !== null) return cache;
+  cache = readDisk();
+  return cache;
+}
+
+function commit(next: RegisteredProject[]): void {
+  cache = next;
+  writeDisk(next);
+  projectRegistryEmitter.emit("change");
+}
+
+// ---------------------------------------------------------------------------
+// Public api
+// ---------------------------------------------------------------------------
+
+export function listProjects(): RegisteredProject[] {
+  // Return a defensive copy so callers can't mutate the cache.
+  return [...ensureCache()];
+}
+
+export function getProject(name: string): RegisteredProject | null {
+  return ensureCache().find((p) => p.name === name) ?? null;
+}
+
+export interface RegisterInput {
+  dir: string;
+  name?: string;
+  /** Pluggable io for tests. */
+  io?: ProbeIo;
+  /** Override `Date.now()` for deterministic tests. */
+  now?: () => Date;
+  /** Override existsSync for the dir-validity check (tests). */
+  exists?: (path: string) => boolean;
+}
+
+export async function registerProject(input: RegisterInput): Promise<RegisteredProject> {
+  const exists = input.exists ?? existsSync;
+  const absoluteDir = isAbsolute(input.dir) ? input.dir : resolve(input.dir);
+  if (!exists(absoluteDir)) {
+    throw new ProjectDirNotFoundError(absoluteDir);
+  }
+
+  const probe = await probeProject(absoluteDir, input.io);
+  const state = ensureCache();
+
+  // If a name was explicitly requested, treat collisions as hard errors and
+  // suggest an alternative. If no name was given, auto-resolve via -2/-3/…
+  const desired = input.name ? sanitizeName(input.name) : probe.name;
+  const cleaned = desired.length > 0 ? desired : probe.name;
+  let resolvedName: string;
+  if (input.name) {
+    if (state.some((p) => p.name === cleaned)) {
+      throw new ProjectAlreadyRegisteredError(cleaned, resolveUniqueName(state, cleaned));
+    }
+    resolvedName = cleaned;
+  } else {
+    resolvedName = resolveUniqueName(state, cleaned);
+  }
+
+  // Reject re-registering the same dir (different name). Probe again under a
+  // different name is fine, but we want to avoid duplicate dirs in the list.
+  const dupDir = state.find((p) => p.dir === probe.dir);
+  if (dupDir) {
+    throw new ProjectAlreadyRegisteredError(dupDir.name, dupDir.name);
+  }
+
+  const now = (input.now ?? (() => new Date()))();
+  const project = buildRegisteredProject(probe, resolvedName, now.toISOString());
+  commit(applyAction(state, { type: "register", project }));
+  return project;
+}
+
+export function unregisterProject(name: string): void {
+  const state = ensureCache();
+  if (!state.some((p) => p.name === name)) {
+    throw new ProjectNotFoundError(name);
+  }
+  commit(applyAction(state, { type: "unregister", name }));
+}
+
+export interface ProbeOptions {
+  io?: ProbeIo;
+}
+
+/**
+ * Re-probe a registered project by name, persist the refreshed snapshot, and
+ * broadcast the change. Throws if the project isn't registered.
+ */
+export async function refreshProject(
+  name: string,
+  options: ProbeOptions = {},
+): Promise<RegisteredProject> {
+  const state = ensureCache();
+  const existing = state.find((p) => p.name === name);
+  if (!existing) throw new ProjectNotFoundError(name);
+
+  const probe = await probeProject(existing.dir, options.io);
+  const refreshed = buildRegisteredProject(probe, existing.name, existing.registeredAt);
+  commit(applyAction(state, { type: "replace", project: refreshed }));
+  return refreshed;
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers — never call from production code
+// ---------------------------------------------------------------------------
+
+/** Reset the in-memory cache. Tests use this between cases. */
+export function _resetCacheForTests(): void {
+  cache = null;
+}
+
+/** Force a re-read from disk on next access. */
+export function _invalidateCacheForTests(): void {
+  cache = null;
+}

package/packages/daemon/src/lib/session-monitor.ts

@@ -0,0 +1,122 @@
+import { execFileSync } from "node:child_process";
+
+const SPINNERS = /^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠂⠒⠢⠆⠐⠠⠄◐◓◑◒|/\\-] /;
+
+interface MonitorPane {
+  id: string;
+  pid: string;
+  cmd?: string;
+  title?: string;
+  role?: string;
+  type?: string;
+  name?: string;
+}
+
+// --- Port detection (pure helpers) ---
+
+function getListeningPids(): Set<string> {
+  // Returns Set of PIDs that have a listening TCP port in range 1024-20000
+  try {
+    const raw = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPn"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    const pids = new Set<string>();
+    let currentPid: string | null = null;
+    for (const line of raw.split("\n")) {
+      if (line.startsWith("p")) {
+        currentPid = line.slice(1);
+      } else if (line.startsWith("n") && currentPid) {
+        const match = line.match(/:(\d+)$/);
+        if (match) {
+          const port = parseInt(match[1]!, 10);
+          if (port >= 1024 && port <= 20000) pids.add(currentPid);
+        }
+      }
+    }
+    return pids;
+  } catch {
+    return new Set<string>();
+  }
+}
+
+function getProcessTree(): Map<string, string> {
+  // Returns Map<pid, ppid>
+  try {
+    const raw = execFileSync("ps", ["-axo", "pid=,ppid="], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    const tree = new Map<string, string>();
+    for (const line of raw.trim().split("\n")) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length === 2) tree.set(parts[0]!, parts[1]!);
+    }
+    return tree;
+  } catch {
+    return new Map<string, string>();
+  }
+}
+
+export function computePortPanes(
+  panes: MonitorPane[],
+  { listeners, tree }: { listeners?: Set<string>; tree?: Map<string, string> } = {},
+): Set<string> {
+  // Walk up from each listening PID to find which pane owns it
+  const resolvedListeners = listeners ?? getListeningPids();
+  const resolvedTree = tree ?? getProcessTree();
+  if (resolvedListeners.size === 0) return new Set<string>();
+
+  const panePids = new Map(panes.map((p) => [p.pid, p.id]));
+  const result = new Set<string>();
+
+  for (const listenerPid of resolvedListeners) {
+    let pid: string | undefined = listenerPid;
+    while (pid && pid !== "0") {
+      if (panePids.has(pid)) {
+        result.add(panePids.get(pid)!);
+        break;
+      }
+      pid = resolvedTree.get(pid);
+    }
+  }
+  return result;
+}
+
+// --- Agent detection ---
+
+export function computeAgentStates(panes: MonitorPane[]): Map<string, "busy" | "idle" | null> {
+  // Returns Map<paneId, "busy" | "idle" | null>
+  const states = new Map<string, "busy" | "idle" | null>();
+  for (const pane of panes) {
+    const role = pane.role ?? "";
+
+    // Primary: use @ide_role pane option if available
+    if (role === "lead" || role === "teammate") {
+      states.set(pane.id, SPINNERS.test(pane.title ?? "") ? "busy" : "idle");
+      continue;
+    }
+
+    // Fallback: command-based detection for pre-upgrade sessions
+    const cmd = (pane.cmd ?? "").toLowerCase();
+    if (!cmd.includes("claude") && !cmd.includes("codex")) {
+      states.set(pane.id, null);
+      continue;
+    }
+    states.set(pane.id, SPINNERS.test(pane.title ?? "") ? "busy" : "idle");
+  }
+  return states;
+}
+
+// The per-session tick loop / orchestrator bootstrap that used to live
+// here was orphaned by the canonical-tree fold — `daemon-embed.ts` owns
+// both responsibilities now (see `startEmbeddedDaemon` + its
+// orchestrator branch). Removing the legacy CLI block also fixes the
+// esbuild-bundle case where `import.meta.url`-vs-`process.argv[1]`
+// resolved to true at the bin/cli.js entry, causing the daemon's
+// session monitor to hijack every CLI invocation (see N1 of
+// docs/npm-distribution-audit.md). The pure exports above
+// (`computeAgentStates`, `computePortPanes`) remain — that's what
+// `daemon-embed.ts` actually imports.

package/packages/daemon/src/lib/skill-sync.ts

@@ -0,0 +1,155 @@
+/**
+ * Managed sync of the bundled Claude Code skill → `~/.claude/skills/tmux-ide`.
+ *
+ * `skill/SKILL.md` is the manual a coding agent loads to drive tmux-ide. It ships
+ * IN the package, but the copy that agents actually read lives in the user's
+ * `~/.claude/skills/` — so every install AND every update has to keep that copy
+ * fresh, or agents drive an old CLI. This module is that refresh: it copies the
+ * bundled SKILL.md into the tmux-ide skill dir with the version marker rewritten
+ * to the installed package version, and reports whether that was an install, an
+ * update, or a no-op.
+ *
+ * The dir is FULLY MANAGED: overwriting our own `~/.claude/skills/tmux-ide` is
+ * correct, and this NEVER touches anything outside it (user-authored skills in
+ * sibling dirs are safe). The version marker is line 2 of SKILL.md, an HTML
+ * comment ({@link VERSION_MARKER_RE}); {@link parseSkillVersion} reads it and
+ * {@link rewriteVersionMarker} substitutes it at copy time.
+ *
+ * The parse/render helpers are PURE and tested against fixtures; {@link syncSkill}
+ * is the thin io wrapper (tested with tmp dirs). Wired from three places — the
+ * npm `postinstall` (which re-implements the marker rewrite in plain JS since it
+ * can't import TS — see scripts/postinstall.js), `tmux-ide skill-sync` / the dev
+ * path of `tmux-ide update`, and `tmux-ide integration install claude`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getCurrentVersion } from "./update-check.ts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Claude Code's config dir: `TMUX_IDE_CLAUDE_DIR` when set (tests / per-run
+ * overrides), else `~/.claude`. Mirrors the {@link ../tui/integrations/claude.ts}
+ * settings override so both halves of the agent setup honor the same scratch dir.
+ */
+export function claudeDir(): string {
+  return process.env.TMUX_IDE_CLAUDE_DIR ?? join(homedir(), ".claude");
+}
+
+/** The fully-managed tmux-ide skill dir: `<claudeDir>/skills/tmux-ide`. */
+export function skillTargetDir(): string {
+  return join(claudeDir(), "skills", "tmux-ide");
+}
+
+/** The installed SKILL.md path (inside {@link skillTargetDir}). */
+export function skillTargetFile(): string {
+  return join(skillTargetDir(), "SKILL.md");
+}
+
+/**
+ * io — the bundled SKILL.md that ships in the package. Resolved relative to this
+ * module, handling BOTH the esbuild-bundled CLI (this file inlines into
+ * `bin/cli.js`, so `here` is `bin/` and the skill is one level up) AND the dev
+ * source tree (`packages/daemon/src/lib/`, four levels below the repo root) — the
+ * same dual-candidate trick as {@link getCurrentVersion}. Returns the first that
+ * exists, else the bundled-layout guess.
+ */
+export function defaultSkillSource(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "../skill/SKILL.md"), // bundled bin/cli.js → repo root
+    join(here, "../../../../skill/SKILL.md"), // dev src/lib → repo root
+  ];
+  return candidates.find((c) => existsSync(c)) ?? candidates[0]!;
+}
+
+// ---------------------------------------------------------------------------
+// Pure — version marker
+// ---------------------------------------------------------------------------
+
+/**
+ * The version marker line (an HTML comment on line 2 of SKILL.md). The sync
+ * machinery reads it to know which version an installed copy is, and rewrites it
+ * to the installed package version at copy time.
+ */
+export const VERSION_MARKER_RE = /<!--\s*tmux-ide-skill-version:\s*([^\s]+)\s*-->/;
+
+/** PURE — render the marker line for a given version. */
+export function versionMarker(version: string): string {
+  return `<!-- tmux-ide-skill-version: ${version} -->`;
+}
+
+/** PURE — the version in a SKILL.md body, or null when the marker is absent. */
+export function parseSkillVersion(content: string): string | null {
+  const match = content.match(VERSION_MARKER_RE);
+  return match ? match[1]! : null;
+}
+
+/**
+ * PURE — return `content` with its version marker rewritten to `version`. When no
+ * marker is present the content is returned unchanged (the bundled SKILL.md
+ * always carries one; this just never corrupts a hand-stripped file).
+ */
+export function rewriteVersionMarker(content: string, version: string): string {
+  if (!VERSION_MARKER_RE.test(content)) return content;
+  return content.replace(VERSION_MARKER_RE, versionMarker(version));
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/** The version marker read off an installed SKILL.md, or null if absent/unreadable. */
+export function installedSkillVersion(dir: string = skillTargetDir()): string | null {
+  const file = join(dir, "SKILL.md");
+  if (!existsSync(file)) return null;
+  try {
+    return parseSkillVersion(readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** What a {@link syncSkill} did. */
+export interface SyncResult {
+  /** `installed` = target was absent; `updated` = content changed; `unchanged` = no-op. */
+  action: "installed" | "updated" | "unchanged";
+  /** The written SKILL.md path. */
+  path: string;
+  /** The installed version before an `updated` (the marker we replaced), if any. */
+  from?: string | null;
+  /** The version written into the copy's marker. */
+  to: string;
+}
+
+/**
+ * io — copy the bundled SKILL.md into the managed skill dir with its version
+ * marker rewritten to `version`. Content-driven and idempotent: the RENDERED
+ * source (marker substituted) is compared byte-for-byte against the installed
+ * copy — identical → `unchanged` (no write), absent → `installed`, otherwise
+ * `updated`. Only ever writes inside {@link skillTargetDir}; nothing outside it
+ * is read or touched.
+ */
+export function syncSkill({
+  source = defaultSkillSource(),
+  version = getCurrentVersion(),
+}: { source?: string; version?: string } = {}): SyncResult {
+  const rendered = rewriteVersionMarker(readFileSync(source, "utf-8"), version);
+  const dir = skillTargetDir();
+  const target = join(dir, "SKILL.md");
+
+  const existing = existsSync(target) ? readFileSync(target, "utf-8") : null;
+  if (existing === rendered) {
+    return { action: "unchanged", path: target, to: version };
+  }
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, rendered, "utf-8");
+
+  if (existing === null) return { action: "installed", path: target, to: version };
+  return { action: "updated", path: target, from: parseSkillVersion(existing), to: version };
+}

package/packages/daemon/src/lib/terminals-store.ts

@@ -0,0 +1,125 @@
+/**
+ * Terminals registry (G20-P1).
+ *
+ * JSON-backed persistence for tab-strip metadata — names, scopes, and
+ * kind. The actual PTY process lives in `PtyBridgeRegistry`; this
+ * store only persists what the UI needs to restore tab labels across
+ * reloads. Atomic writes (temp + rename) so a crash mid-write leaves
+ * the previous list intact.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Terminal, TerminalKind } from "@tmux-ide/contracts";
+
+const TERMINALS_FILE = ".tmux-ide/terminals.json";
+const SAFE_ID = /^[A-Za-z0-9_-]+$/u;
+
+function path(dir: string): string {
+  return join(dir, TERMINALS_FILE);
+}
+
+function ensureDir(dir: string): void {
+  mkdirSync(dirname(path(dir)), { recursive: true });
+}
+
+/** Load the full list for a session. Missing file → empty list. */
+export function loadTerminals(dir: string): Terminal[] {
+  const file = path(dir);
+  if (!existsSync(file)) return [];
+  try {
+    const body = readFileSync(file, "utf-8");
+    const parsed = JSON.parse(body) as { terminals?: unknown };
+    if (!parsed.terminals || !Array.isArray(parsed.terminals)) return [];
+    return parsed.terminals.filter((t): t is Terminal => isTerminal(t)).map((t) => ({ ...t }));
+  } catch {
+    return [];
+  }
+}
+
+function isTerminal(value: unknown): value is Terminal {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" &&
+    SAFE_ID.test(v.id) &&
+    typeof v.projectId === "string" &&
+    typeof v.scopeId === "string" &&
+    typeof v.name === "string" &&
+    (v.kind === "shell" || v.kind === "setup" || v.kind === "run" || v.kind === "teardown") &&
+    typeof v.createdAt === "string" &&
+    typeof v.updatedAt === "string"
+  );
+}
+
+function writeAtomic(dir: string, terminals: Terminal[]): void {
+  ensureDir(dir);
+  const file = path(dir);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ terminals }, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+export interface CreateInput {
+  id: string;
+  projectId: string;
+  scopeId: string;
+  name: string;
+  kind: TerminalKind;
+  scripted?: boolean;
+}
+
+/** Insert OR replace a terminal record by id. Idempotent — calling
+ *  `createTerminal` twice with the same deterministic id is a no-op
+ *  on the canonical fields and updates `updatedAt`. */
+export function upsertTerminal(dir: string, input: CreateInput): Terminal {
+  if (!SAFE_ID.test(input.id)) {
+    throw new Error(`invalid terminal id "${input.id}"`);
+  }
+  const existing = loadTerminals(dir);
+  const idx = existing.findIndex((t) => t.id === input.id);
+  const now = new Date().toISOString();
+  const next: Terminal = {
+    id: input.id,
+    projectId: input.projectId,
+    scopeId: input.scopeId,
+    name: input.name,
+    kind: input.kind,
+    createdAt: existing[idx]?.createdAt ?? now,
+    updatedAt: now,
+    ...(input.scripted ? { scripted: true } : {}),
+  };
+  if (idx === -1) existing.push(next);
+  else existing[idx] = next;
+  writeAtomic(dir, existing);
+  return next;
+}
+
+export function renameTerminal(dir: string, id: string, name: string): Terminal | null {
+  const all = loadTerminals(dir);
+  const idx = all.findIndex((t) => t.id === id);
+  if (idx === -1) return null;
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error("name required");
+  const next: Terminal = {
+    ...all[idx]!,
+    name: trimmed,
+    updatedAt: new Date().toISOString(),
+  };
+  all[idx] = next;
+  writeAtomic(dir, all);
+  return next;
+}
+
+export function deleteTerminal(dir: string, id: string): boolean {
+  const all = loadTerminals(dir);
+  const next = all.filter((t) => t.id !== id);
+  if (next.length === all.length) return false;
+  writeAtomic(dir, next);
+  return true;
+}
+
+export function findTerminal(dir: string, id: string): Terminal | null {
+  const all = loadTerminals(dir);
+  return all.find((t) => t.id === id) ?? null;
+}