claude-garage 0.1.0

package/daemon/src/registry.js

@@ -0,0 +1,189 @@
+import { readFile, writeFile, rename, mkdir, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { GARAGE_PREFIX } from "./tmux.js";
+
+// D-registry: ~/.garage/state.json {workspaces:{name:{dir}}}.
+// Created lazily on first write — a user who registers nothing has no file
+// to migrate or corrupt. tmux ls remains the sole source of truth for
+// sessions; this file is a directory mapping only, never a session list.
+const GARAGE_DIR = path.join(homedir(), ".garage");
+const STATE_PATH = path.join(GARAGE_DIR, "state.json");
+
+async function readState() {
+  try {
+    const raw = await readFile(STATE_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    const workspaces =
+      parsed && typeof parsed.workspaces === "object" && parsed.workspaces !== null
+        ? parsed.workspaces
+        : {};
+    // D-resume-meta: sessions map defaulted the same way workspaces always
+    // has been — a pre-P3 state.json (no `sessions` key) loads exactly as it
+    // did before, and silently gains the key on the first write post-upgrade.
+    // Spreading `parsed` preserves hookToken and any other existing keys.
+    const sessions =
+      parsed && typeof parsed.sessions === "object" && parsed.sessions !== null
+        ? parsed.sessions
+        : {};
+    return { ...parsed, workspaces, sessions };
+  } catch {
+    // Missing file, unreadable, or malformed JSON — treat as empty registry.
+    return { workspaces: {}, sessions: {} };
+  }
+}
+
+// Atomic write: temp file in the same directory, then rename(). rename() is
+// atomic on the same filesystem, so a crash mid-write leaves the previous
+// complete file or the new complete file — never a truncated one.
+async function writeState(state) {
+  await mkdir(GARAGE_DIR, { recursive: true });
+  const tmpPath = path.join(GARAGE_DIR, `.state.json.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(tmpPath, JSON.stringify(state, null, 2));
+    await rename(tmpPath, STATE_PATH);
+  } catch (err) {
+    await unlink(tmpPath).catch(() => {});
+    throw err;
+  }
+}
+
+export async function listWorkspaces() {
+  const state = await readState();
+  return Object.entries(state.workspaces).map(([name, entry]) => ({
+    name,
+    dir: entry.dir,
+  }));
+}
+
+export async function getWorkspace(name) {
+  const state = await readState();
+  return state.workspaces[name] ?? null;
+}
+
+export async function upsertWorkspace(name, dir) {
+  const state = await readState();
+  state.workspaces[name] = { dir };
+  await writeState(state);
+  return { name, dir };
+}
+
+// D-rename: moves the workspace's registry key and rewrites every
+// resume-metadata key that embeds the old name (`garage/<old>/<label>` ->
+// `garage/<new>/<label>`, plus the meta's own `workspace` field) in one
+// atomic write — mirrors the live tmux renames the caller performs
+// separately. Callers are expected to have already validated oldName exists
+// and newName is free; this function trusts its inputs.
+export async function renameWorkspace(oldName, newName) {
+  const state = await readState();
+  const entry = state.workspaces[oldName];
+  if (!entry) return null;
+
+  delete state.workspaces[oldName];
+  state.workspaces[newName] = entry;
+
+  const oldPrefix = `${GARAGE_PREFIX}${oldName}/`;
+  const newPrefix = `${GARAGE_PREFIX}${newName}/`;
+  const nextSessions = {};
+  for (const [id, meta] of Object.entries(state.sessions)) {
+    if (id.startsWith(oldPrefix)) {
+      const newId = newPrefix + id.slice(oldPrefix.length);
+      nextSessions[newId] = { ...meta, workspace: newName };
+    } else {
+      nextSessions[id] = meta;
+    }
+  }
+  state.sessions = nextSessions;
+
+  await writeState(state);
+  return { name: newName, dir: entry.dir };
+}
+
+// D-resume-meta / D-wt-meta: sessions map, keyed by garage session id,
+// {claudeSessionId, workspace, label, worktree}. `claudeSessionId`/
+// `workspace`/`label` are written opportunistically by the poller whenever
+// it observes a session's Claude Code sessionId (see poller.js); `worktree`
+// (`{path, branch, repoDir}` or `null`) is written once, at spawn, by
+// sessions.js and never touched by the poller — see upsertSessionMeta's
+// field-level merge below. Deleted only on a deliberate DELETE
+// /api/sessions/:id (see sessions.js) — a session vanishing from tmux any
+// other way (reboot, `tmux kill-server`, an out-of-band `tmux kill-session`)
+// leaves its meta in place so it can be offered as restorable.
+export async function getSessionMeta(id) {
+  const state = await readState();
+  return state.sessions[id] ?? null;
+}
+
+export async function listSessionMetas() {
+  const state = await readState();
+  return Object.entries(state.sessions).map(([id, meta]) => ({ id, ...meta }));
+}
+
+// Write only if changed: a session's claudeSessionId is stable for the life
+// of one conversation, so after the first tick following spawn this is a
+// no-op comparison on every subsequent poll — the file is touched once per
+// session's lifetime in the common case, mirroring getHookToken()'s
+// generate-and-persist-once discipline and avoiding the write-amplification
+// D-registry (P0) was careful to avoid.
+//
+// D-wt-meta: field-level merge, not a blind overwrite. Two independent
+// writers share this record — sessions.js writes `worktree` once, at spawn,
+// and never touches `claudeSessionId`/`label`/`workspace` again; poller.js
+// writes `claudeSessionId`/`workspace`/`label` on every tick once it learns
+// the Claude Code sessionId, and never mentions `worktree`. A field absent
+// (`undefined`) from the incoming `meta` falls back to whatever's already on
+// disk, so neither writer can clobber the other's field — only a caller that
+// explicitly passes a field (including `null`) can change or clear it.
+export async function upsertSessionMeta(id, meta) {
+  const state = await readState();
+  const existing = state.sessions[id];
+  const next = {
+    claudeSessionId:
+      meta.claudeSessionId !== undefined ? meta.claudeSessionId : (existing?.claudeSessionId ?? null),
+    workspace: meta.workspace !== undefined ? meta.workspace : existing?.workspace,
+    label: meta.label !== undefined ? meta.label : existing?.label,
+    worktree: meta.worktree !== undefined ? meta.worktree : (existing?.worktree ?? null),
+  };
+  const unchanged = existing && JSON.stringify(existing) === JSON.stringify(next);
+  if (unchanged) return existing;
+
+  state.sessions[id] = next;
+  await writeState(state);
+  return next;
+}
+
+export async function removeSessionMeta(id) {
+  const state = await readState();
+  if (!(id in state.sessions)) return;
+  delete state.sessions[id];
+  await writeState(state);
+}
+
+// Deleting a workspace drops its registry entry AND its sessions' resume
+// metadata (they could never restore without a registered dir — a 409 loop),
+// but by design never touches tmux; see workspaces.js DELETE.
+export async function removeWorkspace(name) {
+  const state = await readState();
+  if (!(name in state.workspaces)) return;
+  delete state.workspaces[name];
+  const prefix = `garage/${name}/`;
+  for (const id of Object.keys(state.sessions)) {
+    if (id.startsWith(prefix)) delete state.sessions[id];
+  }
+  await writeState(state);
+}
+
+// Per-install shared secret for the hook endpoint (CSRF defense-in-depth):
+// generated once, embedded in the hook snippet URL, persisted so daemon
+// restarts don't invalidate hooks already installed in ~/.claude/settings.json.
+export async function getHookToken() {
+  const state = await readState();
+  if (typeof state.hookToken === "string" && state.hookToken.length >= 32) {
+    return state.hookToken;
+  }
+  const { randomBytes } = await import("node:crypto");
+  state.hookToken = randomBytes(32).toString("hex");
+  await writeState(state);
+  return state.hookToken;
+}

package/daemon/src/security.js

@@ -0,0 +1,39 @@
+// Browser pages are confused deputies: any website can fire requests at
+// 127.0.0.1, and WebSockets are exempt from CORS. Browsers always send an
+// Origin header, so we allowlist the UI's origin. Requests WITHOUT an Origin
+// (curl, scripts) are allowed — a local process needs no browser to reach
+// tmux and already runs with the user's privileges.
+//
+// D-packaging: in same-process serving mode (GARAGE_SERVE_UI=1) the UI is
+// served from the daemon's own origin instead of Vite's :5173, so that
+// origin (following GARAGE_PORT, same as index.js) must be allowlisted too —
+// otherwise the served UI's own fetch/EventSource calls would be rejected as
+// foreign.
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+const DEFAULT_ORIGINS = [
+  "http://127.0.0.1:5173",
+  "http://localhost:5173",
+  `http://127.0.0.1:${PORT}`,
+  `http://localhost:${PORT}`,
+];
+
+export const ALLOWED_ORIGINS = new Set(
+  process.env.GARAGE_UI_ORIGINS?.split(",").map((s) => s.trim()) ??
+    DEFAULT_ORIGINS
+);
+
+export function originAllowed(origin) {
+  return origin === undefined || ALLOWED_ORIGINS.has(origin);
+}
+
+const STATE_CHANGING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+// No exemptions: claude's hook posts carry no Origin header, so they pass
+// the allowlist naturally (header-less = ordinary local process). The hook
+// endpoint additionally requires a per-install token — see hooks.js.
+export async function rejectForeignOrigins(req, reply) {
+  if (!STATE_CHANGING.has(req.method)) return;
+  if (!originAllowed(req.headers.origin)) {
+    return reply.code(403).send({ error: "origin not allowed" });
+  }
+}

package/daemon/src/sessions.js

@@ -0,0 +1,255 @@
+import { stat } from "node:fs/promises";
+import {
+  GARAGE_PREFIX,
+  NAME_RE,
+  sessionId,
+  listSessions,
+  listPanePaths,
+  resolveBranch,
+  hasSession,
+  createSession,
+  killSession,
+} from "./tmux.js";
+import {
+  getWorkspace,
+  listSessionMetas,
+  getSessionMeta,
+  upsertSessionMeta,
+  removeSessionMeta,
+} from "./registry.js";
+import { getStatus } from "./status.js";
+import { createWorktree } from "./worktrees.js";
+
+const CLAUDE_CMD = process.env.GARAGE_CLAUDE_CMD ?? "claude";
+
+export default async function sessionRoutes(app) {
+  app.get("/api/sessions", async () => {
+    const sessions = await listSessions();
+    const panePaths = await listPanePaths();
+
+    // D-branch: this route is re-hit on every SSE-driven refetch, so the
+    // git calls it triggers must stay cheap — one execFile per unique
+    // directory per request, not per session. `getBranch` memoizes on
+    // that dir for the lifetime of this single request only (a fresh Map
+    // per call, no cross-request caching); resolveBranch itself already
+    // swallows errors and returns null, so a bad/non-git dir never surfaces
+    // here as a rejection.
+    const branchCache = new Map();
+    const getBranch = (dir) => {
+      if (!dir) return Promise.resolve(null);
+      if (!branchCache.has(dir)) branchCache.set(dir, resolveBranch(dir));
+      return branchCache.get(dir);
+    };
+
+    const live = await Promise.all(
+      sessions.map(async (s) => ({
+        ...s,
+        status: getStatus(s.id),
+        // Live pane cwd, not session_path (see listPanePaths) — falls back
+        // to session_path only if the pane vanished between the two tmux
+        // calls above (a session that died mid-request).
+        branch: await getBranch(panePaths.get(s.id) ?? s.dir),
+      }))
+    );
+    const liveIds = new Set(live.map((s) => s.id));
+
+    // D-restore-flow: append one entry per resume-metadata record whose id
+    // has no matching live tmux session. dir is re-resolved from the
+    // registry (not a cached copy in the meta record) so a workspace
+    // re-registered to a new path since the crash is reflected correctly.
+    const metas = await listSessionMetas();
+    const restorable = [];
+    for (const meta of metas) {
+      if (liveIds.has(meta.id)) continue;
+      const registered = await getWorkspace(meta.workspace);
+      const dir = registered?.dir ?? null;
+      restorable.push({
+        id: meta.id,
+        workspace: meta.workspace,
+        label: meta.label,
+        dir,
+        attached: false,
+        status: "restorable",
+        restorable: true,
+        // No live pane to read a cwd from — resolve against the
+        // registered workspace dir instead; null if that's gone too.
+        branch: await getBranch(dir),
+      });
+    }
+
+    return [...live, ...restorable];
+  });
+
+  app.post("/api/sessions", async (req, reply) => {
+    const { workspace, label, worktree: wantWorktree } = req.body ?? {};
+
+    if (!NAME_RE.test(workspace ?? "") || !NAME_RE.test(label ?? "")) {
+      return reply
+        .code(400)
+        .send({ error: "workspace and label must match [a-z0-9-]+" });
+    }
+
+    const registered = await getWorkspace(workspace);
+    if (!registered) {
+      return reply.code(404).send({ error: `unknown workspace: ${workspace}` });
+    }
+
+    const dirStat = await stat(registered.dir).catch(() => null);
+    if (!dirStat?.isDirectory()) {
+      return reply
+        .code(400)
+        .send({ error: `registered dir no longer exists: ${registered.dir}` });
+    }
+
+    const id = sessionId(workspace, label);
+    if (await hasSession(id)) {
+      return reply.code(409).send({ error: `session already exists: ${id}` });
+    }
+
+    // D-wt-meta: worktree creation happens before any tmux state exists —
+    // createWorktree throws (400, with git's stderr) on a non-git repoDir or
+    // a failed `git worktree add`, and nothing has been spawned yet to clean
+    // up in that case.
+    let worktree = null;
+    if (wantWorktree) {
+      try {
+        worktree = await createWorktree({ repoDir: registered.dir, workspace, label });
+      } catch (err) {
+        return reply.code(err.statusCode ?? 400).send({ error: err.message });
+      }
+    }
+
+    const spawnDir = worktree?.path ?? registered.dir;
+    await createSession(id, spawnDir, CLAUDE_CMD);
+
+    if (worktree) {
+      // Written immediately, at spawn — not by the poller. The poller's own
+      // upserts (claudeSessionId/workspace/label, once it observes the
+      // agent) merge alongside this without clobbering it; see registry.js.
+      await upsertSessionMeta(id, {
+        workspace,
+        label,
+        worktree: { ...worktree, repoDir: registered.dir },
+      });
+    }
+
+    return reply.code(201).send({ id, workspace, label, dir: spawnDir, worktree });
+  });
+
+  // D-restore-flow: {id} restores one restorable session; {all:true}
+  // restores every session whose metadata has no live tmux match. Each
+  // target is independent — one failure (stale workspace, missing dir, name
+  // collision) never blocks the rest, and the meta record is retained on
+  // failure so a later retry can still succeed.
+  app.post("/api/sessions/restore", async (req, reply) => {
+    const { id, all } = req.body ?? {};
+    if (!id && !all) {
+      return reply.code(400).send({ error: "must provide id or all:true" });
+    }
+
+    const metas = await listSessionMetas();
+    let targets;
+    if (all) {
+      const liveIds = new Set((await listSessions()).map((s) => s.id));
+      targets = metas.filter((m) => !liveIds.has(m.id));
+    } else {
+      const meta = metas.find((m) => m.id === id);
+      if (!meta) {
+        return reply.code(404).send({ error: `no resume metadata for: ${id}` });
+      }
+      targets = [meta];
+    }
+
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+    // Targets are independent — restore them concurrently so the
+    // died-on-resume confirmation waits below don't serialize restore-all.
+    const results = await Promise.all(
+      targets.map(async (meta) => {
+        const registered = await getWorkspace(meta.workspace);
+        if (!registered) {
+          return { failed: { id: meta.id, reason: "workspace no longer registered" } };
+        }
+
+        // D-wt-meta: a worktree session restores INTO its worktree, not the
+        // registered workspace dir. The stat-gate keeps the metadata
+        // (neither the session nor the worktree record is removed on
+        // failure) so a later retry — or a manual `finish` with the
+        // recorded path/branch — can still recover.
+        const spawnDir = meta.worktree?.path ?? registered.dir;
+        const dirStat = await stat(spawnDir).catch(() => null);
+        if (!dirStat?.isDirectory()) {
+          const reason = meta.worktree ? "worktree missing" : "registered dir no longer exists";
+          return { failed: { id: meta.id, reason } };
+        }
+
+        if (await hasSession(meta.id)) {
+          return { failed: { id: meta.id, reason: "session already running" } };
+        }
+
+        await createSession(meta.id, spawnDir, CLAUDE_CMD, [
+          "--resume",
+          meta.claudeSessionId,
+        ]);
+
+        // `claude --resume` exits (after printing "No conversation found")
+        // when the conversation was never persisted — a session with no
+        // submitted exchange — killing the new tmux session and leaving a
+        // restore loop. The exit isn't instant, so confirm twice before
+        // trusting the resume; if it died, fall back to a fresh claude.
+        let resumed = true;
+        await sleep(1500);
+        if (await hasSession(meta.id)) {
+          await sleep(2000);
+        }
+        if (!(await hasSession(meta.id))) {
+          resumed = false;
+          await createSession(meta.id, spawnDir, CLAUDE_CMD);
+        }
+
+        return {
+          restored: {
+            id: meta.id,
+            workspace: meta.workspace,
+            label: meta.label,
+            dir: spawnDir,
+            worktree: meta.worktree ?? null,
+            resumed,
+          },
+        };
+      })
+    );
+
+    const restored = results.filter((r) => r.restored).map((r) => r.restored);
+    const failed = results.filter((r) => r.failed).map((r) => r.failed);
+
+    const status = restored.length > 0 ? (all ? 200 : 201) : 409;
+    return reply.code(status).send({ restored, failed });
+  });
+
+  // id contains slashes — capture the whole tail as a wildcard.
+  app.delete("/api/sessions/*", async (req, reply) => {
+    const id = decodeURIComponent(req.params["*"]);
+
+    if (!id.startsWith(GARAGE_PREFIX)) {
+      return reply
+        .code(403)
+        .send({ error: "refusing to touch non-garage sessions" });
+    }
+    if (!(await hasSession(id))) {
+      return reply.code(404).send({ error: `no such session: ${id}` });
+    }
+
+    // D-wt-meta: capture the meta BEFORE removing it — the worktree record
+    // (if any) rides the response body so the caller can drive
+    // POST /api/worktrees/finish afterward, since by then the session (and
+    // its metadata) are already gone.
+    const meta = await getSessionMeta(id).catch(() => null);
+
+    await killSession(id);
+    // Deliberate kill: the user is done with this conversation, so there's
+    // nothing to offer restoring later.
+    await removeSessionMeta(id).catch(() => {});
+    return reply.code(200).send({ deleted: true, worktree: meta?.worktree ?? null });
+  });
+}

package/daemon/src/status.js

@@ -0,0 +1,59 @@
+import { EventEmitter } from "node:events";
+
+// D-status: StatusStore. Four states: needs-input | working | done | idle.
+// setStatus is the single write path — API, SSE, and notifications only
+// ever read (getStatus) or subscribe (statusEvents). `done` decays to `idle`
+// after DECAY_MS with no further transition; `needs-input` never
+// auto-decays — it only clears via a new setStatus call (poller 'busy' or a
+// hook Stop/new activity).
+const DECAY_MS = 2 * 60 * 1000;
+
+const store = new Map(); // id -> { state, since }
+const decayTimers = new Map(); // id -> Timeout
+
+export const statusEvents = new EventEmitter();
+statusEvents.setMaxListeners(0);
+
+function clearDecay(id) {
+  const timer = decayTimers.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    decayTimers.delete(id);
+  }
+}
+
+// Unknown/never-signaled sessions read as idle.
+export function getStatus(id) {
+  return store.get(id)?.state ?? "idle";
+}
+
+export function getAllStatuses() {
+  return new Map(store);
+}
+
+export function setStatus(id, state) {
+  const existing = store.get(id);
+  const prev = existing?.state ?? "idle";
+  const changed = prev !== state;
+  const since = changed ? Date.now() : existing?.since ?? Date.now();
+
+  clearDecay(id);
+  store.set(id, { state, since });
+
+  if (state === "done") {
+    const timer = setTimeout(() => setStatus(id, "idle"), DECAY_MS);
+    timer.unref?.();
+    decayTimers.set(id, timer);
+  }
+
+  if (changed) {
+    statusEvents.emit("transition", { id, from: prev, to: state });
+  }
+}
+
+// Called when a session disappears from tmux (poller-detected death) so
+// timers don't leak and a future reuse of the same id starts clean.
+export function dropSession(id) {
+  clearDecay(id);
+  store.delete(id);
+}

package/daemon/src/term.js

@@ -0,0 +1,94 @@
+import { WebSocketServer } from "ws";
+import pty from "node-pty";
+import { GARAGE_PREFIX } from "./tmux.js";
+import { originAllowed } from "./security.js";
+
+const SWEEP_MS = 30_000;
+
+// ws → pty. The socket owns the pty: socket dies → pty dies (detach).
+// The tmux session itself is never touched from here.
+const bridges = new Map();
+
+export function attachTermServer(app) {
+  const wss = new WebSocketServer({ noServer: true });
+
+  app.server.on("upgrade", (req, socket, head) => {
+    // WebSockets bypass CORS — block browser pages from foreign origins.
+    if (!originAllowed(req.headers.origin)) {
+      socket.destroy();
+      return;
+    }
+    const url = new URL(req.url, "http://127.0.0.1");
+    if (!url.pathname.startsWith("/term/")) {
+      socket.destroy();
+      return;
+    }
+    const id = decodeURIComponent(url.pathname.slice("/term/".length));
+    if (!id.startsWith(GARAGE_PREFIX)) {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => bridge(app, ws, id));
+  });
+
+  const sweep = setInterval(() => {
+    for (const [ws, term] of bridges) {
+      if (ws.readyState === ws.CLOSED || ws.readyState === ws.CLOSING) {
+        term.kill();
+        bridges.delete(ws);
+      }
+    }
+  }, SWEEP_MS);
+  app.addHook("onClose", async () => {
+    clearInterval(sweep);
+    for (const term of bridges.values()) term.kill();
+    bridges.clear();
+  });
+}
+
+function bridge(app, ws, id) {
+  let term;
+  try {
+    term = pty.spawn("tmux", ["attach", "-t", `=${id}`], {
+      name: "xterm-256color",
+      cols: 80,
+      rows: 24,
+      cwd: process.env.HOME,
+      env: process.env,
+    });
+  } catch (err) {
+    app.log.error({ err, id }, "pty spawn failed");
+    ws.close(1011, "pty spawn failed");
+    return;
+  }
+  bridges.set(ws, term);
+  app.log.info({ id, pid: term.pid }, "term attached");
+
+  term.onData((data) => {
+    if (ws.readyState === ws.OPEN) ws.send(Buffer.from(data));
+  });
+  term.onExit(({ exitCode }) => {
+    bridges.delete(ws);
+    app.log.info({ id, exitCode }, "term detached");
+    if (ws.readyState === ws.OPEN) ws.close(1000, "detached");
+  });
+
+  ws.on("message", (data, isBinary) => {
+    if (isBinary) {
+      term.write(data.toString("utf8"));
+      return;
+    }
+    try {
+      const msg = JSON.parse(data.toString("utf8"));
+      if (msg.type === "resize" && msg.cols > 0 && msg.rows > 0) {
+        term.resize(msg.cols, msg.rows);
+      }
+    } catch {
+      app.log.warn({ id }, "ignoring malformed control frame");
+    }
+  });
+  ws.on("close", () => {
+    bridges.delete(ws);
+    term.kill();
+  });
+}