feat(checkpoints): surface non-git workdir with a helpful hint

/api/sessions/{name}/checkpoints response is now
{git_workdir: bool, checkpoints: Checkpoint[]}. When the workdir has
no .git dir, the handler short-circuits before touching git and
returns git_workdir:false; the UI renders an explanatory panel on
the Checkpoints tab instead of a silent empty list, pointing the
user at 'git init'.

Mocks and checkpoint-diff e2e updated to match the new shape.

Author: aksOps

internal/serve/api/checkpoints.go

@@ -3,6 +3,8 @@ package api
 import (
 	"encoding/json"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strconv"
 	"sync"
 	"time"
@@ -141,10 +143,20 @@ func Checkpoints(resolveWorkdir func(name string) (string, bool), cache *Checkpo
 			}
 		}
 
+		gitDir := isGitWorkdir(workdir)
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Cache-Control", "no-store")
+
+		if !gitDir {
+			_ = json.NewEncoder(w).Encode(checkpointsResp{
+				GitWorkdir:  false,
+				Checkpoints: []git.Checkpoint{},
+			})
+			return
+		}
+
 		list, err := cache.Get(workdir, name, limit)
 		if err != nil {
-			w.Header().Set("Content-Type", "application/json")
-			w.Header().Set("Cache-Control", "no-store")
 			w.WriteHeader(http.StatusInternalServerError)
 			_ = json.NewEncoder(w).Encode(map[string]string{"error": "git_failed"})
 			return
@@ -153,8 +165,25 @@ func Checkpoints(resolveWorkdir func(name string) (string, bool), cache *Checkpo
 			list = []git.Checkpoint{}
 		}
 
-		w.Header().Set("Content-Type", "application/json")
-		w.Header().Set("Cache-Control", "no-store")
-		_ = json.NewEncoder(w).Encode(list)
+		_ = json.NewEncoder(w).Encode(checkpointsResp{
+			GitWorkdir:  true,
+			Checkpoints: list,
+		})
+	}
+}
+
+type checkpointsResp struct {
+	GitWorkdir  bool             `json:"git_workdir"`
+	Checkpoints []git.Checkpoint `json:"checkpoints"`
+}
+
+// isGitWorkdir reports whether workdir contains a `.git` entry (dir
+// or file — worktrees use a file). No stat = no git repo = no
+// checkpoints possible.
+func isGitWorkdir(workdir string) bool {
+	if workdir == "" {
+		return false
 	}
+	_, err := os.Stat(filepath.Join(workdir, ".git"))
+	return err == nil
 }

internal/serve/api/checkpoints_test.go

@@ -4,13 +4,27 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"sync/atomic"
 	"testing"
 	"time"
 
 	"github.com/RandomCodeSpace/ctm/internal/serve/git"
 )
 
+// gitWorkdir returns a tempdir with a .git directory so the handler's
+// isGitWorkdir check passes — otherwise the handler short-circuits
+// before calling the lister.
+func gitWorkdir(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, ".git"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
 func TestCheckpoints_404OnUnknownSession(t *testing.T) {
 	h := Checkpoints(func(name string) (string, bool) { return "", false }, nil)
 	rec := httptest.NewRecorder()
@@ -42,7 +56,8 @@ func TestCheckpoints_CacheHitWithin5s(t *testing.T) {
 		return want, nil
 	}
 
-	h := Checkpoints(func(name string) (string, bool) { return "/fake/wd", true }, nil)
+	wd := gitWorkdir(t)
+	h := Checkpoints(func(name string) (string, bool) { return wd, true }, nil)
 
 	for i := 0; i < 5; i++ {
 		rec := httptest.NewRecorder()
@@ -52,11 +67,14 @@ func TestCheckpoints_CacheHitWithin5s(t *testing.T) {
 		if rec.Code != http.StatusOK {
 			t.Fatalf("call %d: status = %d", i, rec.Code)
 		}
-		var got []git.Checkpoint
+		var got checkpointsResp
 		if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
 			t.Fatalf("decode: %v", err)
 		}
-		if len(got) != 1 || got[0].SHA != "abc" {
+		if !got.GitWorkdir {
+			t.Fatalf("call %d: git_workdir = false, want true", i)
+		}
+		if len(got.Checkpoints) != 1 || got.Checkpoints[0].SHA != "abc" {
 			t.Errorf("call %d: payload = %+v", i, got)
 		}
 	}
@@ -74,7 +92,8 @@ func TestCheckpoints_CacheKeyedOnLimit(t *testing.T) {
 		atomic.AddInt32(&calls, 1)
 		return nil, nil
 	}
-	h := Checkpoints(func(name string) (string, bool) { return "/wd", true }, nil)
+	wd := gitWorkdir(t)
+	h := Checkpoints(func(name string) (string, bool) { return wd, true }, nil)
 
 	for _, q := range []string{"", "?limit=10", "?limit=10", "?limit=20"} {
 		rec := httptest.NewRecorder()
@@ -94,14 +113,56 @@ func TestCheckpoints_NilListEncodedAsEmptyArray(t *testing.T) {
 	checkpointsLister = func(workdir string, limit int) ([]git.Checkpoint, error) {
 		return nil, nil
 	}
-	h := Checkpoints(func(name string) (string, bool) { return "/wd", true }, nil)
+	wd := gitWorkdir(t)
+	h := Checkpoints(func(name string) (string, bool) { return wd, true }, nil)
 	rec := httptest.NewRecorder()
 	req := httptest.NewRequest(http.MethodGet, "/api/sessions/s/checkpoints", nil)
 	req.SetPathValue("name", "s")
 	h(rec, req)
-	body := rec.Body.String()
-	if body != "[]\n" {
-		t.Errorf("body = %q, want \"[]\\n\"", body)
+	var got checkpointsResp
+	if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if !got.GitWorkdir {
+		t.Fatalf("git_workdir = false, want true")
+	}
+	if got.Checkpoints == nil || len(got.Checkpoints) != 0 {
+		t.Errorf("checkpoints = %+v, want empty non-nil slice", got.Checkpoints)
+	}
+}
+
+func TestCheckpoints_NotGitWorkdir(t *testing.T) {
+	// No .git dir — handler must short-circuit and return
+	// git_workdir:false without calling the lister.
+	prev := checkpointsLister
+	t.Cleanup(func() { checkpointsLister = prev })
+	var calls int32
+	checkpointsLister = func(workdir string, limit int) ([]git.Checkpoint, error) {
+		atomic.AddInt32(&calls, 1)
+		return nil, nil
+	}
+
+	wd := t.TempDir() // no .git subdir
+	h := Checkpoints(func(name string) (string, bool) { return wd, true }, nil)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions/s/checkpoints", nil)
+	req.SetPathValue("name", "s")
+	h(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+	var got checkpointsResp
+	if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if got.GitWorkdir {
+		t.Errorf("git_workdir = true, want false for non-git workdir")
+	}
+	if len(got.Checkpoints) != 0 {
+		t.Errorf("checkpoints = %+v, want empty", got.Checkpoints)
+	}
+	if c := atomic.LoadInt32(&calls); c != 0 {
+		t.Errorf("lister called %d times for non-git workdir, want 0", c)
 	}
 }
 
@@ -118,8 +179,6 @@ func TestCheckpointsCache_IsCheckpointFullSHAOnly(t *testing.T) {
 	if !cache.IsCheckpoint("/wd", "name", fullSHA) {
 		t.Error("full SHA must be allowed")
 	}
-	// Abbreviated SHAs (UI might naively round-trip a 7-char display
-	// SHA) must be rejected to keep allowlist surface area minimal.
 	if cache.IsCheckpoint("/wd", "name", fullSHA[:7]) {
 		t.Error("7-char abbreviated SHA must be rejected")
 	}
@@ -140,13 +199,9 @@ func TestCheckpoints_CacheExpiresAfterTTL(t *testing.T) {
 		atomic.AddInt32(&calls, 1)
 		return nil, nil
 	}
-	h := Checkpoints(func(name string) (string, bool) { return "/wd", true }, nil)
+	wd := gitWorkdir(t)
+	h := Checkpoints(func(name string) (string, bool) { return wd, true }, nil)
 
-	// First call populates cache; manually expire the entry by reaching
-	// into the closure-captured cache via a real handler call before
-	// stale time, then asserting we miss after TTL by directly poking
-	// time isn't possible without a clock seam — instead we verify the
-	// hit-then-miss path by relying on TTL only when CTM_LONG_TESTS=1.
 	rec1 := httptest.NewRecorder()
 	r1 := httptest.NewRequest(http.MethodGet, "/api/sessions/s/checkpoints", nil)
 	r1.SetPathValue("name", "s")
@@ -158,5 +213,5 @@ func TestCheckpoints_CacheExpiresAfterTTL(t *testing.T) {
 	if c := atomic.LoadInt32(&calls); c != 1 {
 		t.Fatalf("cache miss within TTL: calls = %d", c)
 	}
-	_ = time.Now() // keep import even if long-test branch removed
+	_ = time.Now()
 }

ui/e2e/checkpoint-diff.spec.ts

@@ -23,20 +23,27 @@ test.describe("Checkpoint diff viewer", () => {
 
     // Checkpoint list: one commit; the "View diff" button's rendered
     // SHA will be derived from this row's `short_sha`.
-    await page.route("**/api/sessions/alpha/checkpoints**", (route: Route) =>
-      route.fulfill({
+    await page.route("**/api/sessions/alpha/checkpoints**", (route: Route) => {
+      // Diff endpoint also matches this glob (path includes /checkpoints/<sha>/diff).
+      // Fall through to the specific diff route when the path is deeper.
+      const url = new URL(route.request().url());
+      if (!url.pathname.endsWith("/checkpoints")) return route.fallback();
+      return route.fulfill({
         contentType: "application/json",
-        body: JSON.stringify([
-          {
-            sha: FULL_SHA,
-            short_sha: FULL_SHA.slice(0, 7),
-            subject: "checkpoint: pre-yolo 2026-04-21T12:00:00",
-            author: "ctm",
-            ts: new Date(Date.now() - 60_000).toISOString(),
-          },
-        ]),
-      }),
-    );
+        body: JSON.stringify({
+          git_workdir: true,
+          checkpoints: [
+            {
+              sha: FULL_SHA,
+              short_sha: FULL_SHA.slice(0, 7),
+              subject: "checkpoint: pre-yolo 2026-04-21T12:00:00",
+              author: "ctm",
+              ts: new Date(Date.now() - 60_000).toISOString(),
+            },
+          ],
+        }),
+      });
+    });
 
     // Diff endpoint. Note the path order differs from /checkpoints so
     // this route won't collide with the list mock above.

ui/e2e/fixtures/mocks.ts

@@ -73,7 +73,7 @@ export async function installMocks(
     } else if (path.endsWith("/teams")) {
       body = JSON.stringify({ teams: [] });
     } else if (path.endsWith("/checkpoints")) {
-      body = "[]";
+      body = JSON.stringify({ git_workdir: true, checkpoints: [] });
     } else if (path.endsWith("/feed/history")) {
       body = JSON.stringify({ events: [], has_more: false });
     } else if (path === "/api/logs/usage") {

ui/src/hooks/useCheckpoints.ts

@@ -9,11 +9,16 @@ export interface Checkpoint {
   short_sha: string;
 }
 
+export interface CheckpointsResponse {
+  git_workdir: boolean;
+  checkpoints: Checkpoint[];
+}
+
 export function useCheckpoints(sessionName: string | undefined, limit = 50) {
-  return useQuery<Checkpoint[]>({
+  return useQuery<CheckpointsResponse>({
     queryKey: ["checkpoints", sessionName, limit],
     queryFn: () =>
-      api<Checkpoint[]>(
+      api<CheckpointsResponse>(
         `/api/sessions/${encodeURIComponent(sessionName!)}/checkpoints?limit=${limit}`,
       ),
     enabled: Boolean(sessionName),

ui/src/routes/SessionDetail.tsx

@@ -356,6 +356,9 @@ function CheckpointsTab({ sessionName }: { sessionName: string }) {
   // flow are fully independent — closing one must not affect the other.
   const [diffTarget, setDiffTarget] = useState<Checkpoint | null>(null);
 
+  const checkpoints = data?.checkpoints ?? [];
+  const isGitWorkdir = data?.git_workdir ?? true;
+
   return (
     <>
       <div className="min-h-0 flex-1 overflow-y-auto">
@@ -374,13 +377,24 @@ function CheckpointsTab({ sessionName }: { sessionName: string }) {
             {error instanceof Error ? `: ${error.message}` : ""}
           </p>
         )}
-        {!isLoading && !isError && (data ?? []).length === 0 && (
+        {!isLoading && !isError && !isGitWorkdir && (
+          <div className="m-4 border-l-[3px] border-accent-gold bg-surface px-3 py-3 text-sm text-fg">
+            <div className="font-semibold">Checkpoints need a git repo</div>
+            <p className="mt-1 text-[12px] text-fg-dim">
+              This session&apos;s workdir isn&apos;t a git repository, so ctm has nothing to snapshot.
+              Run{" "}
+              <code className="rounded bg-surface-2 px-1 py-0.5 font-mono">git init</code>{" "}
+              in the workdir to enable pre-yolo checkpoints on the next tool call.
+            </p>
+          </div>
+        )}
+        {!isLoading && !isError && isGitWorkdir && checkpoints.length === 0 && (
           <p className="px-4 py-8 text-center text-sm text-fg-dim">
             No checkpoints. Run ctm yolo to create the first.
           </p>
         )}
         <ul role="list">
-          {(data ?? []).map((cp) => (
+          {checkpoints.map((cp) => (
             <li key={cp.sha}>
               <CheckpointRow
                 checkpoint={cp}