claude-garage 0.2.0 → 0.3.0

package/daemon/src/poller.js

@@ -1,19 +1,38 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { EventEmitter } from "node:events";
-import { listSessions } from "./tmux.js";
-import { setStatus, getStatus, dropSession } from "./status.js";
+import os from "node:os";
+import { listSessions, normalizeTitle } from "./tmux.js";
+import { setStatus, getStatus, dropSession as dropStatus } from "./status.js";
+import { dropSession as dropStatuslineContext } from "./statusline.js";
 import { upsertSessionMeta } from "./registry.js";
 
+// p11: a dead session's statusline-fed context must be cleared alongside
+// its status entry (context-telemetry spec) — a future reuse of the same
+// garage session id must never inherit a stale percentage from a prior,
+// unrelated conversation.
+function dropSession(id) {
+  dropStatus(id);
+  dropStatuslineContext(id);
+}
+
 const run = promisify(execFile);
 const POLL_MS = 2000;
 
-// Emits "sessions-changed" whenever the poller notices the garage session
-// list itself changed (spawn/death), so events.js can tell the UI to refetch.
+// Emits "sessions-changed" whenever the poller notices something the wall's
+// session listing depends on changed: the garage session set itself
+// (spawn/death) OR — p10 — a live session's normalized pane title, so a
+// `tmux select-pane -T` (e.g. Claude Code's OSC title) gets pushed to the
+// UI instead of only being picked up on the next unrelated refetch.
 export const pollerEvents = new EventEmitter();
 pollerEvents.setMaxListeners(0);
 
 let lastSessionIds = new Set();
+// p10: normalized title per currently-live garage session, from the tick
+// this map was last rebuilt in. Rebuilt wholesale every tick from `sessions`
+// (never merged), so a session that dies has its entry dropped for free —
+// memory-trivial, sessions-only.
+let lastTitles = new Map();
 
 // `claude agents --json` — missing CLI or any failure is a silent no-op,
 // per D-status's graceful degradation to poller-absent behavior.
@@ -26,22 +45,26 @@ async function getAgents() {
   }
 }
 
-// tmux pane pid per session name — pane_pid joins exactly to the `pid`
-// reported by `claude agents --json` since garage spawns claude as the
-// pane's root process (design D-status).
+// tmux pane pid + title per session name — pane_pid joins exactly to the
+// `pid` reported by `claude agents --json` since garage spawns claude as the
+// pane's root process (design D-status). p10: pane_title rides the same
+// list-panes call (kept to ONE per tick daemon-wide) so the title-change
+// diff below needs no tmux invocation of its own; title is free text, so it
+// sits last in the format string and everything past the second tab is
+// rejoined into it (same rationale as tmux.js's parsePaneLine).
 async function getPanePids() {
   try {
     const { stdout } = await run("tmux", [
       "list-panes",
       "-a",
       "-F",
-      "#{session_name}\t#{pane_pid}",
+      "#{session_name}\t#{pane_pid}\t#{pane_title}",
     ]);
     const map = new Map();
     for (const line of stdout.split("\n")) {
       if (!line.trim()) continue;
-      const [name, pid] = line.split("\t");
-      map.set(name, Number(pid));
+      const [name, pid, ...rest] = line.split("\t");
+      map.set(name, { pid: Number(pid), title: rest.join("\t") });
     }
     return map;
   } catch {
@@ -65,38 +88,82 @@ export function applyAgentStatus(id, agentStatus) {
   setStatus(id, mapped);
 }
 
-async function tick() {
-  const sessions = await listSessions().catch(() => []);
-
+// p10 wave-2 fix: pure id+title diff, no tmux/IO — exported so it's
+// exhaustively unit-testable without a live tmux server. `sessions` is this
+// tick's listSessions() result; `panePids` maps session id -> {pid, title}
+// (from this tick's single list-panes call — a session can be missing an
+// entry, e.g. mid-spawn); `prevIds`/`prevTitles` are the previous tick's
+// state. Session-id-set changes (spawn/death) AND a normalized-title change
+// on any still-live session both count as "changed" — a pane-title-only
+// change (`tmux select-pane -T`) never touches the id set, so without the
+// title half this would sit unpushed until some unrelated refetch noticed.
+export function diffSessionState(sessions, panePids, hostname, prevIds, prevTitles) {
   const currentIds = new Set(sessions.map((s) => s.id));
-  let changed = currentIds.size !== lastSessionIds.size;
-  for (const id of lastSessionIds) {
-    if (!currentIds.has(id)) {
-      dropSession(id);
-      changed = true;
+  let changed = currentIds.size !== prevIds.size;
+  if (!changed) {
+    for (const id of prevIds) {
+      if (!currentIds.has(id)) {
+        changed = true;
+        break;
+      }
     }
   }
   if (!changed) {
     for (const id of currentIds) {
-      if (!lastSessionIds.has(id)) {
+      if (!prevIds.has(id)) {
         changed = true;
         break;
       }
     }
   }
-  lastSessionIds = currentIds;
-  if (changed) pollerEvents.emit("sessions-changed");
 
-  if (sessions.length === 0) return;
+  const titles = new Map();
+  for (const session of sessions) {
+    const title = normalizeTitle(panePids.get(session.id)?.title, hostname);
+    titles.set(session.id, title);
+    if (prevTitles.get(session.id) !== title) changed = true;
+  }
+
+  return { changed, ids: currentIds, titles };
+}
+
+async function tick() {
+  const sessions = await listSessions().catch(() => []);
+
+  if (sessions.length === 0) {
+    for (const id of lastSessionIds) dropSession(id);
+    const changed = lastSessionIds.size !== 0;
+    lastSessionIds = new Set();
+    lastTitles = new Map();
+    if (changed) pollerEvents.emit("sessions-changed");
+    return;
+  }
 
+  // p10: title rides the same list-panes call already made for the pid
+  // join — kept to ONE list-panes invocation per tick daemon-wide.
   const [agents, panePids] = await Promise.all([getAgents(), getPanePids()]);
+  const hostname = os.hostname();
+  const { changed, ids, titles } = diffSessionState(
+    sessions,
+    panePids,
+    hostname,
+    lastSessionIds,
+    lastTitles
+  );
+  for (const id of lastSessionIds) {
+    if (!ids.has(id)) dropSession(id);
+  }
+  lastSessionIds = ids;
+  lastTitles = titles;
+  if (changed) pollerEvents.emit("sessions-changed");
+
   if (agents.length === 0) return; // claude CLI missing/no live agents
 
   const agentByPid = new Map(agents.map((a) => [a.pid, a]));
   const unmatched = [];
 
   for (const session of sessions) {
-    const panePid = panePids.get(session.id);
+    const panePid = panePids.get(session.id)?.pid;
     const agent = panePid !== undefined ? agentByPid.get(panePid) : undefined;
     if (agent) {
       applyAgentStatus(session.id, agent.status);

package/daemon/src/registry.js

@@ -8,7 +8,9 @@ import { GARAGE_PREFIX } from "./tmux.js";
 // 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");
+// GARAGE_DIR env override exists for testability (scratch daemons must not
+// share the real ~/.garage/state.json) — same spirit as GARAGE_PORT.
+const GARAGE_DIR = process.env.GARAGE_DIR ?? path.join(homedir(), ".garage");
 const STATE_PATH = path.join(GARAGE_DIR, "state.json");
 
 async function readState() {

package/daemon/src/session-resolve.js

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { listSessions } from "./tmux.js";
+
+const run = promisify(execFile);
+
+async function getAgents() {
+  try {
+    const { stdout } = await run("claude", ["agents", "--json"]);
+    return JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+}
+
+async function getPanePids() {
+  try {
+    const { stdout } = await run("tmux", [
+      "list-panes",
+      "-a",
+      "-F",
+      "#{session_name}\t#{pane_pid}",
+    ]);
+    const map = new Map(); // pid -> session name
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+      const [name, pid] = line.split("\t");
+      map.set(Number(pid), name);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+// Shared by hooks.js and statusline.js — both receive a Claude Code payload
+// carrying `session_id`/`cwd` and need the same garage session id(s) it
+// applies to. Precise path: payload session_id -> agents-json sessionId ->
+// its pid -> pane_pid join. Fallback: cwd fail-open, applied to every garage
+// session sharing that dir (over-notify/over-record rather than silently
+// drop).
+export async function resolveSessionIds({ session_id, cwd }) {
+  const [agents, pidToSession] = await Promise.all([getAgents(), getPanePids()]);
+
+  if (session_id) {
+    const agent = agents.find((a) => a.sessionId === session_id);
+    const sessionName = agent && pidToSession.get(agent.pid);
+    if (sessionName) return [sessionName];
+  }
+
+  if (cwd) {
+    const sessions = await listSessions();
+    const matches = sessions.filter((s) => s.dir === cwd).map((s) => s.id);
+    if (matches.length > 0) return matches;
+  }
+
+  return [];
+}

package/daemon/src/sessions.js

@@ -1,4 +1,5 @@
 import { stat } from "node:fs/promises";
+import os from "node:os";
 import {
   GARAGE_PREFIX,
   NAME_RE,
@@ -6,6 +7,7 @@ import {
   listSessions,
   listPanePaths,
   resolveBranch,
+  normalizeTitle,
   hasSession,
   createSession,
   killSession,
@@ -17,8 +19,10 @@ import {
   upsertSessionMeta,
   removeSessionMeta,
 } from "./registry.js";
-import { getStatus } from "./status.js";
+import { getStatusEntry } from "./status.js";
 import { createWorktree } from "./worktrees.js";
+import { getStatuslineContext, getRateLimits } from "./statusline.js";
+import { getCachedContext, refreshContext } from "./transcript.js";
 
 const CLAUDE_CMD = process.env.GARAGE_CLAUDE_CMD ?? "claude";
 
@@ -26,6 +30,8 @@ export default async function sessionRoutes(app) {
   app.get("/api/sessions", async () => {
     const sessions = await listSessions();
     const panePaths = await listPanePaths();
+    // p10: same tmux hostname for every session in this request — read once.
+    const hostname = os.hostname();
 
     // 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
@@ -41,15 +47,57 @@ export default async function sessionRoutes(app) {
       return branchCache.get(dir);
     };
 
+    // p11: fetched once up front (not per-session) — same cost discipline as
+    // branchCache above — so both the live loop's claudeSessionId lookup and
+    // the restorable loop below share one registry read.
+    const metas = await listSessionMetas();
+    const metaById = new Map(metas.map((m) => [m.id, m]));
+
     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),
-      }))
+      sessions.map(async (s) => {
+        // since: epoch ms the current status began, so the UI can render
+        // elapsed time without a second lookup (see status.js getStatusEntry).
+        const { state: status, since, message } = getStatusEntry(s.id);
+        const pane = panePaths.get(s.id);
+        const dir = pane?.path ?? s.dir;
+
+        // p11: context — statusline data (pushed by the wrapper) beats the
+        // transcript fallback beats null. The transcript path is a cache
+        // read only: getCachedContext never blocks, refreshContext kicks a
+        // background read (a no-op if the cache is still fresh or a read is
+        // already in flight) — this route must never block on file IO.
+        let context = getStatuslineContext(s.id);
+        if (!context) {
+          context = getCachedContext(s.id);
+          const claudeSessionId = metaById.get(s.id)?.claudeSessionId;
+          if (claudeSessionId && dir) {
+            refreshContext(s.id, { dir, claudeSessionId });
+          }
+        }
+
+        return {
+          ...s,
+          status,
+          // p8: the Notification hook's text for a needs-input session; the
+          // store guarantees null for every other state (see status.js).
+          message: message ?? null,
+          // A session that has never transitioned has no recorded `since`
+          // (the store only stamps one on a real state change), which would
+          // render as "—" in the UI even though the session is live and has
+          // an obvious age. Fall back to when tmux created it.
+          since: since ?? s.createdAt ?? null,
+          // 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(dir),
+          // p10: the pane's OSC title (e.g. Claude Code's "✳ <summary>"),
+          // filtered down to null when it's just tmux's own default (empty,
+          // hostname, bare shell name) — see normalizeTitle.
+          title: normalizeTitle(pane?.title, hostname),
+          // p11: {usedPercentage, source: "statusline"|"transcript"} | null.
+          context,
+        };
+      })
     );
     const liveIds = new Set(live.map((s) => s.id));
 
@@ -57,7 +105,6 @@ export default async function sessionRoutes(app) {
     // 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;
@@ -70,16 +117,29 @@ export default async function sessionRoutes(app) {
         dir,
         attached: false,
         status: "restorable",
+        since: null,
+        message: null,
+        // p10: no live pane to read a title from — restorable entries never
+        // have one (see session-status spec).
+        title: null,
         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),
+        // p11: restorable entries never carry context — there's no live
+        // session to have posted a statusline or grown a fresh transcript
+        // usage figure since it died (see context-telemetry spec).
+        context: null,
       });
     }
 
     return [...live, ...restorable];
   });
 
+  // p11: account-wide rate limits from the most recent statusline post —
+  // null until one arrives. See statusline.js for the store.
+  app.get("/api/usage", async () => getRateLimits());
+
   app.post("/api/sessions", async (req, reply) => {
     const { workspace, label, worktree: wantWorktree } = req.body ?? {};
 
@@ -236,6 +296,29 @@ export default async function sessionRoutes(app) {
         .code(403)
         .send({ error: "refusing to touch non-garage sessions" });
     }
+
+    // p8.1: `?meta=1` deletes ONLY the stored resume metadata of a NON-live
+    // (restorable) session — the plain DELETE below 404s for those since
+    // there is no tmux session to kill. Behavior without the param is
+    // unchanged (the web UI never sends it). The worktree record rides the
+    // response the same way, so the caller can still surface "worktree
+    // kept" for a discarded restorable worktree session.
+    if (req.query?.meta === "1") {
+      if (await hasSession(id)) {
+        return reply
+          .code(409)
+          .send({ error: `session is live — delete it without meta=1: ${id}` });
+      }
+      const meta = await getSessionMeta(id).catch(() => null);
+      if (!meta) {
+        return reply.code(404).send({ error: `no resume metadata for: ${id}` });
+      }
+      await removeSessionMeta(id).catch(() => {});
+      return reply
+        .code(200)
+        .send({ deleted: true, meta: true, worktree: meta?.worktree ?? null });
+    }
+
     if (!(await hasSession(id))) {
       return reply.code(404).send({ error: `no such session: ${id}` });
     }

package/daemon/src/settings-install.js

@@ -0,0 +1,62 @@
+import { copyFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// Shared by hooks.js and statusline.js — both merge a garage-owned fragment
+// into ~/.claude/settings.json with the same safety order: parse-or-refuse
+// (a corrupt file is reported as a 422, byte-for-byte untouched) -> caller
+// merges its own fragment -> timestamped backup of the pre-write file ->
+// atomic write (tmp + rename, same directory, so a crash mid-write can never
+// leave a half-written settings.json).
+
+// Read + parse settings.json. Returns `{settings, raw}`: `settings` is `{}`
+// for a missing/empty file (nothing to refuse), the parsed object otherwise;
+// `raw` is the exact original file text, or null if the file didn't exist
+// (used by writeSettingsAtomic to decide whether a backup is needed).
+// Throws a statusCode:422 error — file left completely untouched — for
+// invalid JSON or a non-object top level.
+export async function readSettingsOrRefuse(path) {
+  let raw = null;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  let settings = {};
+  if (raw !== null && raw.trim() !== "") {
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      const error = new Error(
+        `${path} is not valid JSON — fix it (or remove it) and retry; the file was left untouched`
+      );
+      error.statusCode = 422;
+      throw error;
+    }
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+      const error = new Error(`${path} is not a JSON object — the file was left untouched`);
+      error.statusCode = 422;
+      throw error;
+    }
+  }
+  return { settings, raw };
+}
+
+// Backs up (if `raw` is non-null, i.e. the file previously existed) then
+// atomically writes `merged`. Returns the backup path, or null when there
+// was nothing to back up.
+export async function writeSettingsAtomic(path, raw, merged) {
+  await mkdir(dirname(path), { recursive: true });
+
+  let backup = null;
+  if (raw !== null) {
+    backup = `${path}.garage-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    await copyFile(path, backup);
+  }
+
+  const tmp = `${path}.garage-tmp-${process.pid}`;
+  await writeFile(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  await rename(tmp, path);
+
+  return backup;
+}

package/daemon/src/status.js

@@ -2,58 +2,68 @@ 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;
+// ever read (getStatus/getStatusEntry) or subscribe (statusEvents). There
+// is NO auto-decay: `done` now holds until something else transitions it
+// (poller sees 'busy', a hook fires, or dropSession removes the entry when
+// the session dies). `needs-input` never auto-decayed either — same rule,
+// it only clears via a new setStatus call. `since` records the epoch ms of
+// the last actual state change (not touched by repeat setStatus calls with
+// the same state), so the UI can render "how long in this state".
+//
+// p8 message capture: needs-input may carry the Notification hook's message
+// text. Only hook-sourced writes pass one; the poller's coarse `waiting`
+// observation passes none, and a messageless same-state write must not wipe
+// a hook-set message (the 2s poller would otherwise erase it on the next
+// tick). Any transition away from needs-input clears it.
 
-const store = new Map(); // id -> { state, since }
-const decayTimers = new Map(); // id -> Timeout
+const store = new Map(); // id -> { state, since, message }
 
 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";
 }
 
+// Same lookup as getStatus but also exposes `since` (epoch ms the current
+// state began, or null for a never-signaled id) so callers can compute
+// elapsed time without a second store.
+export function getStatusEntry(id) {
+  return store.get(id) ?? { state: "idle", since: null, message: null };
+}
+
 export function getAllStatuses() {
   return new Map(store);
 }
 
-export function setStatus(id, state) {
+export function setStatus(id, state, message = undefined) {
   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 });
+  // Only needs-input carries a message. A messageless needs-input write
+  // (the poller) preserves what a hook already captured on a same-state
+  // tick, but never invents one on a fresh transition.
+  const nextMessage =
+    state !== "needs-input"
+      ? null
+      : message !== undefined
+        ? message
+        : prev === "needs-input"
+          ? existing?.message ?? null
+          : null;
 
-  if (state === "done") {
-    const timer = setTimeout(() => setStatus(id, "idle"), DECAY_MS);
-    timer.unref?.();
-    decayTimers.set(id, timer);
-  }
+  store.set(id, { state, since, message: nextMessage });
 
   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.
+// Called when a session disappears from tmux (poller-detected death) so a
+// future reuse of the same id starts clean.
 export function dropSession(id) {
-  clearDecay(id);
   store.delete(id);
 }