claude-garage 0.2.0 → 0.3.0

package/daemon/src/statusline.js

@@ -0,0 +1,200 @@
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getHookToken } from "./registry.js";
+import { tokenMatches } from "./token-auth.js";
+import { resolveSessionIds } from "./session-resolve.js";
+import { readSettingsOrRefuse, writeSettingsAtomic } from "./settings-install.js";
+import { claudeHome } from "./claude-home.js";
+
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+const SETTINGS_PATH = join(claudeHome(), "settings.json");
+const WRAPPER_PATH = join(claudeHome(), "garage-statusline.sh");
+
+// ---------------------------------------------------------------------------
+// In-memory store — mirrors status.js's shape (a Map, no persistence, wiped
+// per the id it's keyed on). Two slots: per-session context percentage, and
+// ONE account-wide rate-limits record (statusline posts carry the whole
+// account's rate limits on every post, not a per-session figure).
+// ---------------------------------------------------------------------------
+
+const contextStore = new Map(); // garage session id -> { usedPercentage }
+let rateLimits = { fiveHour: null, sevenDay: null };
+
+// Exported so the pure clamp logic is directly unit-testable (mirrors
+// hooks.js's isIdleReminder being exported for the same reason).
+export function clampPercentage(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.min(100, Math.max(0, value));
+}
+
+export function setContext(id, usedPercentage) {
+  contextStore.set(id, { usedPercentage });
+}
+
+// Read shape matches what sessions.js puts on the listing entry directly:
+// {usedPercentage, source: "statusline"} | null.
+export function getStatuslineContext(id) {
+  const entry = contextStore.get(id);
+  return entry ? { usedPercentage: entry.usedPercentage, source: "statusline" } : null;
+}
+
+// Called (like status.js's dropSession) when a session disappears from tmux,
+// so a future reuse of the same garage session id starts clean — see
+// poller.js. Also usable directly by tests.
+export function dropSession(id) {
+  contextStore.delete(id);
+}
+
+function normalizeLimit(limit) {
+  if (!limit || typeof limit !== "object") return null;
+  const usedPercentage = clampPercentage(limit.used_percentage);
+  if (usedPercentage === null) return null;
+  return { usedPercentage, resetsAt: limit.resets_at ?? null };
+}
+
+// Partial-update semantics: a post carrying only one of the two buckets
+// updates that bucket and leaves the other exactly as it was — a statusline
+// post's rate_limits object isn't guaranteed to always carry both.
+export function setRateLimits(raw) {
+  if (!raw || typeof raw !== "object") return;
+  const fiveHour = normalizeLimit(raw.five_hour);
+  const sevenDay = normalizeLimit(raw.seven_day);
+  if (fiveHour) rateLimits = { ...rateLimits, fiveHour };
+  if (sevenDay) rateLimits = { ...rateLimits, sevenDay };
+}
+
+export function getRateLimits() {
+  return { fiveHour: rateLimits.fiveHour, sevenDay: rateLimits.sevenDay };
+}
+
+// ---------------------------------------------------------------------------
+// Chaining wrapper — see design.md D-wrapper. The wrapper is a tiny POSIX sh
+// script (not an inline settings.json command string) so chaining an
+// arbitrary pre-existing command never fights JSON/shell quoting inside
+// settings.json itself; settings.json only ever gets a fixed `sh <path>`
+// command pointing at it.
+// ---------------------------------------------------------------------------
+
+// Single-quote a string for safe embedding in a POSIX sh script: close the
+// quote, emit an escaped literal quote, reopen it.
+function shSingleQuote(str) {
+  return `'${String(str).replace(/'/g, `'\\''`)}'`;
+}
+
+// `originalCommand` is the pre-existing statusLine command to chain (its
+// stdout must ride through unchanged), or null when there was none.
+export function wrapperScript({ token, port = PORT, originalCommand = null }) {
+  const url = `http://127.0.0.1:${port}/api/statusline/claude?token=${token}`;
+  const chain = originalCommand
+    ? `printf '%s' "$INPUT" | sh -c ${shSingleQuote(originalCommand)}\n`
+    : ""; // no pre-existing statusline — post and print nothing, per spec
+  return (
+    `#!/bin/sh\n` +
+    `# claude-garage statusline wrapper — auto-generated, do not hand-edit.\n` +
+    `# Reinstall (POST /api/statusline/install) regenerates this file.\n` +
+    `INPUT="$(cat)"\n` +
+    `printf '%s' "$INPUT" | curl -fsS --max-time 1 -X POST ${shSingleQuote(url)} ` +
+    `-H "Content-Type: application/json" --data-binary @- >/dev/null 2>&1 &\n` +
+    chain
+  );
+}
+
+function wrapperCommand() {
+  return `sh ${shSingleQuote(WRAPPER_PATH)}`;
+}
+
+async function writeWrapperScript(content) {
+  await mkdir(dirname(WRAPPER_PATH), { recursive: true });
+  const tmp = `${WRAPPER_PATH}.garage-tmp-${process.pid}`;
+  await writeFile(tmp, content, "utf8");
+  await chmod(tmp, 0o755);
+  await rename(tmp, WRAPPER_PATH);
+}
+
+export async function statuslineSnippet() {
+  const token = await getHookToken();
+  return {
+    statusLine: { type: "command", command: wrapperCommand() },
+    script: wrapperScript({ token, originalCommand: null }),
+  };
+}
+
+// Same safety order as hooks.js's installHooks: parse-or-refuse -> compute
+// the merge -> backup + atomic write only if something actually changes.
+// Idempotency: if settings.statusLine.command already IS our wrapper
+// command, there's nothing new to capture or write (see design.md's note on
+// the GARAGE_PORT-change edge case — out of scope here, matches hooks.js's
+// own idempotency granularity).
+async function installStatusline() {
+  const { settings, raw } = await readSettingsOrRefuse(SETTINGS_PATH);
+  const token = await getHookToken();
+  const command = wrapperCommand();
+
+  const existing = settings.statusLine ?? null;
+  if (existing && existing.command === command) {
+    return { ok: true, installed: true, alreadyInstalled: true, chained: null, backup: null };
+  }
+
+  // Only a `type: "command"` statusLine has a shell command we can chain;
+  // anything else (absent, or an unrecognized future type) is treated as
+  // "nothing to chain" rather than erroring — the wrapper simply posts and
+  // prints nothing, same as a fresh install.
+  const originalCommand =
+    existing && existing.type === "command" && typeof existing.command === "string"
+      ? existing.command
+      : null;
+
+  await writeWrapperScript(wrapperScript({ token, originalCommand }));
+
+  const merged = { ...settings, statusLine: { type: "command", command } };
+  const backup = await writeSettingsAtomic(SETTINGS_PATH, raw, merged);
+
+  return {
+    ok: true,
+    installed: true,
+    alreadyInstalled: false,
+    chained: originalCommand !== null,
+    backup,
+  };
+}
+
+export default async function statuslineRoutes(app) {
+  // Auth: same per-install token as hooks.js's /api/hooks/claude — the
+  // wrapper script is URL-only config (no way to send a header), so the
+  // token rides as a query param.
+  app.post("/api/statusline/claude", async (req, reply) => {
+    const expected = await getHookToken();
+    if (!tokenMatches(req.query?.token, expected)) {
+      return reply.code(401).send({ error: "missing or invalid hook token" });
+    }
+
+    const payload = req.body ?? {};
+    const ids = await resolveSessionIds(payload);
+    if (ids.length === 0) {
+      // Unresolvable session — no error, nothing recorded (context or
+      // account-wide rate limits): a post that can't be attributed to a
+      // known garage session tells us nothing trustworthy.
+      return reply.code(200).send({ ok: true, ignored: true });
+    }
+
+    const pct = clampPercentage(payload?.context_window?.used_percentage);
+    if (pct !== null) {
+      for (const id of ids) setContext(id, pct);
+    }
+    setRateLimits(payload?.rate_limits);
+
+    return reply.code(200).send({ ok: true, applied: ids });
+  });
+
+  app.get("/api/statusline/snippet", async () => statuslineSnippet());
+
+  app.post("/api/statusline/install", async (req, reply) => {
+    try {
+      return await installStatusline();
+    } catch (err) {
+      return reply
+        .code(err.statusCode ?? 500)
+        .send({ error: err.message ?? "statusline install failed" });
+    }
+  });
+}

package/daemon/src/tmux.js

@@ -19,7 +19,10 @@ export async function listSessions() {
     ({ stdout } = await run("tmux", [
       "ls",
       "-F",
-      "#{session_name}\t#{session_path}\t#{session_attached}",
+      // `session_created` (epoch SECONDS) backs the UI's elapsed timer for a
+      // session that has never had a status transition — without it a live
+      // session with no recorded `since` renders "—" instead of its age.
+      "#{session_name}\t#{session_path}\t#{session_attached}\t#{session_created}",
     ]));
   } catch {
     // tmux exits non-zero when no server is running — that means "no sessions".
@@ -29,20 +32,41 @@ export async function listSessions() {
     .split("\n")
     .filter((line) => line.startsWith(GARAGE_PREFIX))
     .map((line) => {
-      const [name, dir, attached] = line.split("\t");
+      const [name, dir, attached, created] = line.split("\t");
       const [, workspace, label] = name.split("/");
-      return { id: name, workspace, label, dir, attached: attached !== "0" };
+      const createdMs = Number(created) * 1000;
+      return {
+        id: name,
+        workspace,
+        label,
+        dir,
+        attached: attached !== "0",
+        createdAt: Number.isFinite(createdMs) && createdMs > 0 ? createdMs : null,
+      };
     });
 }
 
-// D-branch: live pane cwd per garage session, keyed by session name — NOT
-// `session_path` (that's the session's *starting* dir, frozen at creation;
-// a user who `cd`s into a worktree inside the pane changes pane_current_path
-// but not session_path). `-a` lists every pane on the server across every
-// session, so results are filtered to the garage prefix same as
-// listSessions(). A session can have multiple panes/windows if the user
-// split it manually — only the first pane encountered per session is kept,
-// there's no principled way to pick "the" cwd of a multi-pane session.
+// p10: pane titles are free text — tmux doesn't forbid a literal tab in one
+// (unlikely, but "typically" isn't "never"). `#{pane_title}` sits LAST in
+// the format string and everything from the second tab onward is rejoined
+// into the title field, so an embedded separator there can never shift
+// session_name/pane_current_path out from under the earlier destructuring.
+// Exported (pure, no tmux call) so the split logic is unit-testable without
+// a live server.
+export function parsePaneLine(line) {
+  const [name, panePath, ...rest] = line.split("\t");
+  return { name, panePath, title: rest.join("\t") };
+}
+
+// D-branch: live pane cwd + title per garage session, keyed by session name
+// — NOT `session_path` (that's the session's *starting* dir, frozen at
+// creation; a user who `cd`s into a worktree inside the pane changes
+// pane_current_path but not session_path). `-a` lists every pane on the
+// server across every session, so results are filtered to the garage prefix
+// same as listSessions(). A session can have multiple panes/windows if the
+// user split it manually — only the first pane encountered per session is
+// kept, there's no principled way to pick "the" cwd/title of a multi-pane
+// session.
 export async function listPanePaths() {
   let stdout;
   try {
@@ -50,19 +74,55 @@ export async function listPanePaths() {
       "list-panes",
       "-a",
       "-F",
-      "#{session_name}\t#{pane_current_path}",
+      "#{session_name}\t#{pane_current_path}\t#{pane_title}",
     ]));
   } catch {
     // No tmux server running — no panes.
     return new Map();
   }
-  const paths = new Map();
+  const panes = new Map();
   for (const line of stdout.split("\n")) {
     if (!line.startsWith(GARAGE_PREFIX)) continue;
-    const [name, panePath] = line.split("\t");
-    if (!paths.has(name)) paths.set(name, panePath);
+    const { name, panePath, title } = parsePaneLine(line);
+    if (!panes.has(name)) panes.set(name, { path: panePath, title });
   }
-  return paths;
+  return panes;
+}
+
+// p10: tmux's own default pane titles carry no signal — empty, the machine
+// hostname (tmux's out-of-the-box default), or the bare shell/login-shell
+// name it sets before anything else runs. Filtering those down to null
+// means the UI only ever sees a title something *set* (e.g. Claude Code's
+// OSC title updates). Pure — hostname is passed in rather than read via
+// os.hostname() internally so this stays trivially unit-testable; the one
+// production caller (sessions.js) passes os.hostname().
+const BARE_PROCESS_NAMES = new Set([
+  "sh",
+  "bash",
+  "zsh",
+  "fish",
+  "-sh",
+  "-bash",
+  "-zsh",
+  "-fish",
+  "tmux",
+]);
+
+export function normalizeTitle(title, hostname) {
+  if (title == null) return null;
+  const trimmed = title.trim();
+  if (!trimmed) return null;
+
+  const lower = trimmed.toLowerCase();
+  if (BARE_PROCESS_NAMES.has(lower)) return null;
+
+  if (hostname) {
+    const hostLower = hostname.toLowerCase();
+    const shortHost = hostLower.split(".")[0];
+    if (lower === hostLower || lower === shortHost) return null;
+  }
+
+  return trimmed;
 }
 
 // D-branch: shared by sessions.js (per-session, keyed off live pane cwd)

package/daemon/src/token-auth.js

@@ -0,0 +1,13 @@
+import { timingSafeEqual } from "node:crypto";
+
+// Shared by hooks.js and statusline.js — both authenticate a URL query-param
+// token (Claude Code's HTTP hooks and the statusline wrapper are both
+// URL-only config) against the same per-install hook token from
+// registry.js. Constant-time compare so response timing can't leak the
+// expected token a byte at a time.
+export function tokenMatches(given, expected) {
+  if (typeof given !== "string") return false;
+  const a = Buffer.from(given);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/daemon/src/transcript.js

@@ -0,0 +1,142 @@
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { claudeHome } from "./claude-home.js";
+
+const TAIL_BYTES = 256 * 1024;
+const TTL_MS = 15_000;
+const DEFAULT_WINDOW = 200_000;
+
+// Claude Code's own project-directory naming: the cwd with every `/`
+// replaced by `-` (leading slash included). Exported — pure — for direct
+// testing.
+export function slugifyCwd(cwd) {
+  return cwd.replaceAll("/", "-");
+}
+
+export function transcriptPath(dir, claudeSessionId) {
+  return join(claudeHome(), "projects", slugifyCwd(dir), `${claudeSessionId}.jsonl`);
+}
+
+// Small map of known exceptions to the 200k default — "[1m]" marks the
+// 1M-context beta variants of a model id (e.g.
+// "claude-sonnet-4-5-20250929[1m]"). Anything else, including an unknown or
+// missing model id, gets the default: a hint, not billing, per design.md.
+export function windowForModel(model) {
+  if (typeof model !== "string") return DEFAULT_WINDOW;
+  if (model.includes("[1m]")) return 1_000_000;
+  return DEFAULT_WINDOW;
+}
+
+// Scans `text` (the tail-bounded transcript content) backward for the last
+// assistant message carrying a `usage` block, skipping malformed JSON lines
+// and any line that isn't an assistant/usage entry. Returns
+// {tokens, model} | null. Pure — exported for direct unit tests.
+export function parseLastAssistantUsage(text) {
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // malformed line (or a partial line from the tail cut) — skip
+    }
+
+    if (entry?.type !== "assistant") continue;
+    const usage = entry?.message?.usage;
+    if (!usage || typeof usage !== "object") continue;
+
+    const input = Number(usage.input_tokens) || 0;
+    const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+    const cacheCreation = Number(usage.cache_creation_input_tokens) || 0;
+    return { tokens: input + cacheRead + cacheCreation, model: entry.message.model ?? null };
+  }
+  return null;
+}
+
+// Reads only the last <=256KB of the file (a multi-MB transcript must never
+// cost a full read). Returns the tail text, or null if the file doesn't
+// exist / can't be read. The first line of the tail may be a partial line
+// cut mid-record — parseLastAssistantUsage tolerates that by skipping
+// unparseable lines, which is exactly what a truncated leading line is.
+async function readTail(path) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+    const { size } = await handle.stat();
+    const start = Math.max(0, size - TAIL_BYTES);
+    const length = size - start;
+    const buffer = Buffer.alloc(length);
+    if (length > 0) {
+      await handle.read(buffer, 0, length, start);
+    }
+    return buffer.toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+// The percentage the fallback exposes: (input + cache_read + cache_creation)
+// over the model's context window. Async, does real file IO — callers on
+// the hot path must use the cache below (getCachedContext/refreshContext),
+// never call this directly from a request handler.
+export async function computeContext({ dir, claudeSessionId }) {
+  if (!dir || !claudeSessionId) return null;
+  const tail = await readTail(transcriptPath(dir, claudeSessionId));
+  if (tail === null) return null;
+
+  const usage = parseLastAssistantUsage(tail);
+  if (!usage) return null; // no assistant usage within the tail-bounded read
+
+  const window = windowForModel(usage.model);
+  const usedPercentage = Math.min(100, Math.max(0, Math.round((usage.tokens / window) * 100)));
+  return { usedPercentage, source: "transcript" };
+}
+
+// ---------------------------------------------------------------------------
+// Per-session cache: {value, at, pending}. `value` is null until the first
+// successful (or empty) read completes. The sessions route (sessions.js)
+// must NEVER block on a transcript read — it calls getCachedContext for the
+// synchronous, always-available answer, and refreshContext to kick a
+// background read when the cache is stale. refreshContext returns
+// immediately in every case; its promise is intentionally not returned so a
+// caller can't accidentally await it into the request path.
+// ---------------------------------------------------------------------------
+
+const cache = new Map(); // garage session id -> {value, at, pending}
+
+export function getCachedContext(id) {
+  return cache.get(id)?.value ?? null;
+}
+
+// Exposes the full cache entry (including `at`) — mainly for tests to
+// observe TTL behavior without waiting on wall-clock time.
+export function getCacheEntry(id) {
+  return cache.get(id) ?? { value: null, at: null };
+}
+
+export function clearCache(id) {
+  cache.delete(id);
+}
+
+export function refreshContext(id, { dir, claudeSessionId }) {
+  const entry = cache.get(id);
+  const fresh = entry && Date.now() - entry.at < TTL_MS;
+  if (fresh || entry?.pending) return;
+
+  cache.set(id, { value: entry?.value ?? null, at: entry?.at ?? 0, pending: true });
+  computeContext({ dir, claudeSessionId })
+    .then((value) => {
+      cache.set(id, { value, at: Date.now(), pending: false });
+    })
+    .catch(() => {
+      // A read failure keeps whatever was already cached (stale-but-known
+      // beats null) but still stamps `at` so a persistently failing read
+      // doesn't retry every single request.
+      cache.set(id, { value: entry?.value ?? null, at: Date.now(), pending: false });
+    });
+}

package/daemon/src/worktrees.js

@@ -10,7 +10,11 @@ const run = promisify(execFile);
 // D-wt-location: outside any repo, so a worktree never pollutes `git status`
 // for the repo itself. Keyed by workspace so `~/.garage/worktrees/<ws>/` is
 // one place to `ls` per workspace.
-const WORKTREES_ROOT = path.join(homedir(), ".garage", "worktrees");
+// Follows the registry's GARAGE_DIR override (testability — see registry.js).
+const WORKTREES_ROOT = path.join(
+  process.env.GARAGE_DIR ?? path.join(homedir(), ".garage"),
+  "worktrees"
+);
 
 // D-wt-branch: namespaced so a repo's real branches never collide with ours,
 // and so the discard/merge cleanup guard below can refuse to touch anything

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-garage",
-  "version": "0.2.0",
-  "description": "Multiple Claude agents driving you crazy? Park them all in one garage: every session on one live terminal wall, no window juggling. Needs-input triage, worktree isolation, diff review. tmux owns the sessions; close the app and nothing dies.",
+  "version": "0.3.0",
+  "description": "Multiple Claude agents driving you crazy? Park them all in one garage: a needs-input queue that follows you across projects, a full-screen terminal TUI, and a browser wall with diff review. tmux owns the sessions; close the app and nothing dies.",
   "license": "MIT",
   "author": "Saiful Islam <saifulislamadar@gmail.com>",
   "repository": {
@@ -14,6 +14,7 @@
     "claude",
     "claude-code",
     "tmux",
+    "tui",
     "terminal",
     "agents",
     "session-manager",
@@ -33,7 +34,8 @@
     "bin",
     "daemon/src",
     "daemon/package.json",
-    "ui/dist"
+    "ui/dist",
+    "wall/dist"
   ],
   "workspaces": [
     "daemon",
@@ -42,6 +44,7 @@
   "scripts": {
     "dev": "concurrently -n daemon,ui -c blue,magenta \"npm:dev --workspace daemon\" \"npm:dev --workspace ui\"",
     "test": "node --test \"daemon/test/*.test.js\" \"ui/test/*.test.js\"",
+    "build:tui": "cd wall && cargo build --release && mkdir -p dist && cp target/release/garage-wall dist/garage-wall-$(node -p \"process.platform+'-'+process.arch\")",
     "postinstall": "chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper 2>/dev/null || true",
     "prepack": "npm run build --workspace ui"
   },