feat(KB-104): move file browser from task modal to toolbar

- Add backend API routes and file service for project-scoped file operations - Create useProjectFileBrowser and useProjectFileEditor hooks with comprehensive tests - Update FileBrowserModal to support both task and project modes via dualMode prop - Add Files button to dashboard header toolbar - Remove Files tab from TaskDetailModal - Integrate project file browser into main App layout - Include changeset for @dustinbyrne/kb package
2026-03-30 17:06:50 -07:00
parent 0ab4f251cf
commit cf5a98fdf0
12 changed files with 1130 additions and 30 deletions
--- a/packages/dashboard/app/App.tsx
+++ b/packages/dashboard/app/App.tsx
@@ -6,6 +6,7 @@ import { Board } from "./components/Board";
 import { ListView } from "./components/ListView";
 import { TaskDetailModal } from "./components/TaskDetailModal";
 import { TerminalModal } from "./components/TerminalModal";
+import { FileBrowserModal } from "./components/FileBrowserModal";
 import { SettingsModal } from "./components/SettingsModal";
 import { PlanningModeModal } from "./components/PlanningModeModal";
 import type { SectionId } from "./components/SettingsModal";
@@ -29,8 +30,10 @@ function AppInner() {
  const [githubImportOpen, setGitHubImportOpen] = useState(false);
  const [usageOpen, setUsageOpen] = useState(false);
  const [terminalOpen, setTerminalOpen] = useState(false);
+  const [filesOpen, setFilesOpen] = useState(false);
  const [settingsInitialSection, setSettingsInitialSection] = useState<SectionId | undefined>(undefined);
  const [maxConcurrent, setMaxConcurrent] = useState(2);
+  const [rootDir, setRootDir] = useState<string>(".");
  const [autoMerge, setAutoMerge] = useState(true);
  const [globalPaused, setGlobalPaused] = useState(false);
  const [enginePaused, setEnginePaused] = useState(false);
@@ -61,7 +64,10 @@ function AppInner() {

  useEffect(() => {
    fetchConfig()
-      .then((cfg) => setMaxConcurrent(cfg.maxConcurrent))
+      .then((cfg) => {
+        setMaxConcurrent(cfg.maxConcurrent);
+        setRootDir(cfg.rootDir);
+      })
      .catch(() => {/* keep default */});
    fetchSettings()
      .then((s) => {
@@ -183,6 +189,10 @@ function AppInner() {
    setTerminalOpen(false);
  }, []);

+  const handleToggleFiles = useCallback(() => {
+    setFilesOpen((prev) => !prev);
+  }, []);
+
  return (
    <>
      <Header
@@ -192,6 +202,8 @@ function AppInner() {
        onOpenUsage={handleOpenUsage}
        onOpenSchedules={handleOpenSchedules}
        onToggleTerminal={handleToggleTerminal}
+        onToggleFiles={handleToggleFiles}
+        filesOpen={filesOpen}
        globalPaused={globalPaused}
        enginePaused={enginePaused}
        onToggleGlobalPause={handleToggleGlobalPause}
@@ -277,6 +289,13 @@ function AppInner() {
        isOpen={terminalOpen}
        onClose={handleTerminalClose}
      />
+      {filesOpen && (
+        <FileBrowserModal
+          projectRoot={rootDir}
+          isOpen={true}
+          onClose={() => setFilesOpen(false)}
+        />
+      )}
      <UsageIndicator
        isOpen={usageOpen}
        onClose={handleCloseUsage}
--- a/packages/dashboard/app/api.ts
+++ b/packages/dashboard/app/api.ts
@@ -137,8 +137,8 @@ export function rejectPlan(id: string): Promise<Task> {
  return api<Task>(`/tasks/${id}/reject-plan`, { method: "POST" });
 }

-export function fetchConfig(): Promise<{ maxConcurrent: number }> {
-  return api<{ maxConcurrent: number }>("/config");
+export function fetchConfig(): Promise<{ maxConcurrent: number; rootDir: string }> {
+  return api<{ maxConcurrent: number; rootDir: string }>("/config");
 }

 export function fetchSettings(): Promise<Settings> {
@@ -710,6 +710,27 @@ export function saveFileContent(taskId: string, filePath: string, content: strin
  });
 }

+// --- Project File Browser API ---
+
+/** List files in project root directory */
+export function fetchProjectFileList(path?: string): Promise<FileListResponse> {
+  const query = path ? `?path=${encodeURIComponent(path)}` : "";
+  return api<FileListResponse>(`/files${query}`);
+}
+
+/** Fetch file content from project directory */
+export function fetchProjectFileContent(filePath: string): Promise<FileContentResponse> {
+  return api<FileContentResponse>(`/files/${encodeURIComponent(filePath)}`);
+}
+
+/** Save file content to project directory */
+export function saveProjectFileContent(filePath: string, content: string): Promise<SaveFileResponse> {
+  return api<SaveFileResponse>(`/files/${encodeURIComponent(filePath)}`, {
+    method: "POST",
+    body: JSON.stringify({ content }),
+  });
+}
+
 // --- Planning Mode API ---

 /** Planning session state returned from API */
--- a/packages/dashboard/app/components/FileBrowserModal.tsx
+++ b/packages/dashboard/app/components/FileBrowserModal.tsx
@@ -2,19 +2,44 @@ import { useState, useCallback, useEffect } from "react";
 import { X, Save, RotateCcw, Folder } from "lucide-react";
 import { useFileBrowser } from "../hooks/useFileBrowser";
 import { useFileEditor } from "../hooks/useFileEditor";
+import { useProjectFileBrowser } from "../hooks/useProjectFileBrowser";
+import { useProjectFileEditor } from "../hooks/useProjectFileEditor";
 import { FileBrowser } from "./FileBrowser";
 import { FileEditor } from "./FileEditor";

-interface FileBrowserModalProps {
+type TaskModeProps = {
  taskId: string;
  worktreePath?: string;
+  projectRoot?: never;
+};
+
+type ProjectModeProps = {
+  projectRoot: string;
+  taskId?: never;
+  worktreePath?: never;
+};
+
+type FileBrowserModalProps = {
  isOpen?: boolean;
  onClose: () => void;
-}
+} & (TaskModeProps | ProjectModeProps);

-export function FileBrowserModal({ taskId, worktreePath, onClose }: FileBrowserModalProps) {
+export function FileBrowserModal(props: FileBrowserModalProps) {
+  const { taskId, projectRoot, onClose } = props;
  const [selectedFile, setSelectedFile] = useState<string | null>(null);

+  // Determine mode based on which prop is provided
+  const isTaskMode = taskId !== undefined;
+  const isProjectMode = projectRoot !== undefined;
+
+  // Use appropriate hooks based on mode
+  const taskBrowser = useFileBrowser(taskId ?? "", isTaskMode);
+  const projectBrowser = useProjectFileBrowser(projectRoot ?? "", isProjectMode);
+
+  const taskEditor = useFileEditor(taskId ?? "", selectedFile, isTaskMode);
+  const projectEditor = useProjectFileEditor(projectRoot ?? "", selectedFile, isProjectMode);
+
+  // Select the active hooks based on mode
  const {
    entries,
    currentPath,
@@ -22,7 +47,7 @@ export function FileBrowserModal({ taskId, worktreePath, onClose }: FileBrowserM
    loading: browserLoading,
    error: browserError,
    refresh,
-  } = useFileBrowser(taskId, true);
+  } = isTaskMode ? taskBrowser : projectBrowser;

  const {
    content,
@@ -34,7 +59,7 @@ export function FileBrowserModal({ taskId, worktreePath, onClose }: FileBrowserM
    save,
    hasChanges,
    mtime,
-  } = useFileEditor(taskId, selectedFile, true);
+  } = isTaskMode ? taskEditor : projectEditor;

  // Keyboard shortcuts
  useEffect(() => {
@@ -68,13 +93,16 @@ export function FileBrowserModal({ taskId, worktreePath, onClose }: FileBrowserM
    return `${(bytes / 1024).toFixed(1)} KB`;
  };

+  // Determine modal title based on mode
+  const modalTitle = isTaskMode ? `Files — ${taskId}` : "Files — Project";
+
  return (
    <div className="modal-overlay open" onClick={onClose}>
      <div className="modal file-browser-modal" onClick={(e) => e.stopPropagation()}>
        <div className="modal-header">
          <div className="file-browser-header-title">
            <Folder size={18} />
-            <span>Files</span>
+            <span>{modalTitle}</span>
            {selectedFile && (
              <span className="file-browser-header-path">
                {currentPath === "." ? "" : currentPath + "/"}
--- a/packages/dashboard/app/components/Header.tsx
+++ b/packages/dashboard/app/components/Header.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect, useRef, useCallback } from "react";
-import { Settings, Pause, Play, Square, Download, LayoutGrid, List, Terminal, Lightbulb, Search, X, Activity, MoreHorizontal, Clock } from "lucide-react";
+import { Settings, Pause, Play, Square, Download, LayoutGrid, List, Terminal, Lightbulb, Search, X, Activity, MoreHorizontal, Clock, Folder } from "lucide-react";

 interface HeaderProps {
  onOpenSettings?: () => void;
@@ -8,6 +8,8 @@ interface HeaderProps {
  onOpenUsage?: () => void;
  onOpenSchedules?: () => void;
  onToggleTerminal?: () => void;
+  onToggleFiles?: () => void;
+  filesOpen?: boolean;
  globalPaused?: boolean;
  enginePaused?: boolean;
  onToggleGlobalPause?: () => void;
@@ -42,6 +44,8 @@ export function Header({
  onOpenUsage,
  onOpenSchedules,
  onToggleTerminal,
+  onToggleFiles,
+  filesOpen,
  globalPaused,
  enginePaused,
  onToggleGlobalPause,
@@ -262,6 +266,18 @@ export function Header({
          </button>
        )}

+        {/* Files button - desktop only */}
+        {!isMobile && onToggleFiles && (
+          <button
+            className={`btn-icon${filesOpen ? " btn-icon--active" : ""}`}
+            onClick={onToggleFiles}
+            title="Browse Files"
+            data-testid="files-toggle-btn"
+          >
+            <Folder size={16} />
+          </button>
+        )}
+
        {/* Pause button (soft pause) - always inline */}
        <button
          className={`btn-icon${enginePaused ? " btn-icon--paused" : ""}`}
@@ -321,6 +337,18 @@ export function Header({
              <Terminal size={16} />
              <span>Open Terminal</span>
            </button>
+            {/* Files - in overflow on mobile */}
+            {onToggleFiles && (
+              <button
+                className="mobile-overflow-item"
+                onClick={() => handleOverflowAction(onToggleFiles)}
+                role="menuitem"
+                data-testid="overflow-files-btn"
+              >
+                <Folder size={16} />
+                <span>Browse Files</span>
+              </button>
+            )}
            <button
              className="mobile-overflow-item"
              onClick={() => handleOverflowAction(onOpenGitHubImport)}
--- a/packages/dashboard/app/components/TaskDetailModal.tsx
+++ b/packages/dashboard/app/components/TaskDetailModal.tsx
@@ -12,7 +12,6 @@ import { SteeringTab } from "./SteeringTab";
 import { ModelSelectorTab } from "./ModelSelectorTab";
 import { PrSection } from "./PrSection";
 import { SpecEditor } from "./SpecEditor";
-import { FileBrowserModal } from "./FileBrowserModal";

 interface ModelSelection {
  provider?: string;
@@ -105,7 +104,7 @@ export function TaskDetailModal({
  addToast,
  githubTokenConfigured,
 }: TaskDetailModalProps) {
-  const [activeTab, setActiveTab] = useState<"definition" | "activity" | "agent-log" | "steering" | "model" | "spec" | "files">("definition");
+  const [activeTab, setActiveTab] = useState<"definition" | "activity" | "agent-log" | "steering" | "model" | "spec">("definition");
  const [attachments, setAttachments] = useState<TaskAttachment[]>(task.attachments || []);
  const [uploading, setUploading] = useState(false);
  const [dependencies, setDependencies] = useState<string[]>(task.dependencies || []);
@@ -640,23 +639,8 @@ export function TaskDetailModal({
            >
              Spec
            </button>
-            {task.worktree && (
-              <button
-                className={`detail-tab${activeTab === "files" ? " detail-tab-active" : ""}`}
-                onClick={() => setActiveTab("files")}
-              >
-                Files
-              </button>
-            )}
          </div>
-          {activeTab === "files" ? (
-            <FileBrowserModal
-              taskId={task.id}
-              worktreePath={task.worktree}
-              isOpen={true}
-              onClose={() => setActiveTab("definition")}
-            />
-          ) : activeTab === "spec" ? (
+          {activeTab === "spec" ? (
            <div className="detail-section detail-section--spec">
              <SpecEditor
                content={task.prompt || ""}
--- a/packages/dashboard/app/hooks/tests/useProjectFileBrowser.test.ts
+++ b/packages/dashboard/app/hooks/tests/useProjectFileBrowser.test.ts
@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useProjectFileBrowser } from "../useProjectFileBrowser";
+import * as api from "../../api";
+import type { FileListResponse } from "../../api";
+
+// Mock the api module
+vi.mock("../../api", () => ({
+  fetchProjectFileList: vi.fn(),
+}));
+
+const mockFetchProjectFileList = vi.mocked(api.fetchProjectFileList);
+
+describe("useProjectFileBrowser", () => {
+  beforeEach(() => {
+    mockFetchProjectFileList.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("initializes with empty entries and loading false when disabled", () => {
+    const { result } = renderHook(() => useProjectFileBrowser("/project", false));
+
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.currentPath).toBe(".");
+  });
+
+  it("fetches file list when enabled", async () => {
+    const mockResponse: FileListResponse = {
+      path: ".",
+      entries: [
+        { name: "src", type: "directory", mtime: "2024-01-01T00:00:00Z" },
+        { name: "package.json", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" },
+      ],
+    };
+    mockFetchProjectFileList.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    // Should start loading
+    expect(result.current.loading).toBe(true);
+
+    // Wait for fetch to complete
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.entries).toHaveLength(2);
+    expect(result.current.entries[0].name).toBe("src");
+    expect(result.current.entries[1].name).toBe("package.json");
+    expect(mockFetchProjectFileList).toHaveBeenCalledWith(undefined);
+  });
+
+  it("fetches subdirectory when path changes", async () => {
+    const rootResponse: FileListResponse = {
+      path: ".",
+      entries: [{ name: "src", type: "directory", mtime: "2024-01-01T00:00:00Z" }],
+    };
+    const subdirResponse: FileListResponse = {
+      path: "src",
+      entries: [{ name: "index.ts", type: "file", size: 200, mtime: "2024-01-01T00:00:00Z" }],
+    };
+
+    mockFetchProjectFileList
+      .mockResolvedValueOnce(rootResponse)
+      .mockResolvedValueOnce(subdirResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.entries).toHaveLength(1);
+
+    // Navigate to subdirectory
+    act(() => {
+      result.current.setPath("src");
+    });
+
+    await waitFor(() => expect(result.current.currentPath).toBe("src"));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(mockFetchProjectFileList).toHaveBeenLastCalledWith("src");
+  });
+
+  it("handles fetch errors", async () => {
+    mockFetchProjectFileList.mockRejectedValueOnce(new Error("Failed to load files"));
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe("Failed to load files");
+    expect(result.current.entries).toEqual([]);
+  });
+
+  it("refreshes file list when refresh is called", async () => {
+    const initialResponse: FileListResponse = {
+      path: ".",
+      entries: [{ name: "file1.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+    };
+    const refreshedResponse: FileListResponse = {
+      path: ".",
+      entries: [
+        { name: "file1.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" },
+        { name: "file2.txt", type: "file", size: 200, mtime: "2024-01-02T00:00:00Z" },
+      ],
+    };
+
+    mockFetchProjectFileList
+      .mockResolvedValueOnce(initialResponse)
+      .mockResolvedValueOnce(refreshedResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.entries).toHaveLength(1);
+
+    // Refresh
+    act(() => {
+      result.current.refresh();
+    });
+
+    await waitFor(() => expect(result.current.entries).toHaveLength(2));
+    expect(mockFetchProjectFileList).toHaveBeenCalledTimes(2);
+  });
+
+  it("clears error when path changes", async () => {
+    mockFetchProjectFileList
+      .mockRejectedValueOnce(new Error("Failed to load files"))
+      .mockResolvedValueOnce({
+        path: ".",
+        entries: [{ name: "file.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+      });
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.error).toBe("Failed to load files"));
+
+    // Change path should clear error
+    act(() => {
+      result.current.setPath("subdir");
+    });
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it("does not fetch when disabled", async () => {
+    renderHook(() => useProjectFileBrowser("/project", false));
+
+    // Wait a bit to ensure no fetch happens
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(mockFetchProjectFileList).not.toHaveBeenCalled();
+  });
+
+  it("cancels in-flight requests on unmount", async () => {
+    let resolveFetch: (value: FileListResponse) => void;
+    const fetchPromise = new Promise<FileListResponse>((resolve) => {
+      resolveFetch = resolve;
+    });
+    mockFetchProjectFileList.mockReturnValueOnce(fetchPromise);
+
+    const { unmount } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    // Unmount before fetch completes
+    unmount();
+
+    // Complete the fetch after unmount
+    resolveFetch!({
+      path: ".",
+      entries: [{ name: "file.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+    });
+
+    // Wait a bit to ensure state update doesn't happen
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Should not throw or have any issues
+    expect(mockFetchProjectFileList).toHaveBeenCalledTimes(1);
+  });
+});
--- a/packages/dashboard/app/hooks/tests/useProjectFileEditor.test.ts
+++ b/packages/dashboard/app/hooks/tests/useProjectFileEditor.test.ts
@@ -0,0 +1,324 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useProjectFileEditor } from "../useProjectFileEditor";
+import * as api from "../../api";
+import type { FileContentResponse, SaveFileResponse } from "../../api";
+
+// Mock the api module
+vi.mock("../../api", () => ({
+  fetchProjectFileContent: vi.fn(),
+  saveProjectFileContent: vi.fn(),
+}));
+
+const mockFetchProjectFileContent = vi.mocked(api.fetchProjectFileContent);
+const mockSaveProjectFileContent = vi.mocked(api.saveProjectFileContent);
+
+describe("useProjectFileEditor", () => {
+  beforeEach(() => {
+    mockFetchProjectFileContent.mockReset();
+    mockSaveProjectFileContent.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("initializes with empty content when no file selected", () => {
+    const { result } = renderHook(() => useProjectFileEditor("/project", null, true));
+
+    expect(result.current.content).toBe("");
+    expect(result.current.originalContent).toBe("");
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.hasChanges).toBe(false);
+    expect(result.current.mtime).toBeNull();
+  });
+
+  it("initializes with empty content when disabled", () => {
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", false));
+
+    expect(result.current.content).toBe("");
+    expect(result.current.loading).toBe(false);
+    expect(mockFetchProjectFileContent).not.toHaveBeenCalled();
+  });
+
+  it("fetches file content when filePath is provided and enabled", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.content).toBe("console.log('hello');");
+    expect(result.current.originalContent).toBe("console.log('hello');");
+    expect(result.current.mtime).toBe("2024-01-01T00:00:00Z");
+    expect(result.current.hasChanges).toBe(false);
+    expect(mockFetchProjectFileContent).toHaveBeenCalledWith("src/index.ts");
+  });
+
+  it("tracks content changes", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.hasChanges).toBe(false);
+
+    // Edit content
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    expect(result.current.content).toBe("console.log('world');");
+    expect(result.current.hasChanges).toBe(true);
+  });
+
+  it("saves file content", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    const saveResponse: SaveFileResponse = {
+      success: true,
+      mtime: "2024-01-02T00:00:00Z",
+      size: 22,
+    };
+
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockResolvedValueOnce(saveResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    await act(async () => {
+      await result.current.save();
+    });
+
+    expect(mockSaveProjectFileContent).toHaveBeenCalledWith("src/index.ts", "console.log('world');");
+    expect(result.current.originalContent).toBe("console.log('world');");
+    expect(result.current.hasChanges).toBe(false);
+    expect(result.current.mtime).toBe("2024-01-02T00:00:00Z");
+  });
+
+  it("does not save when there are no changes", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Try to save without changes
+    await act(async () => {
+      await result.current.save();
+    });
+
+    expect(mockSaveProjectFileContent).not.toHaveBeenCalled();
+  });
+
+  it("handles fetch errors", async () => {
+    mockFetchProjectFileContent.mockRejectedValueOnce(new Error("File not found"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/missing.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe("File not found");
+    expect(result.current.content).toBe("");
+  });
+
+  it("handles save errors", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockRejectedValueOnce(new Error("Permission denied"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and try to save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    let saveError: Error | undefined;
+    await act(async () => {
+      try {
+        await result.current.save();
+      } catch (err) {
+        saveError = err as Error;
+      }
+    });
+
+    expect(saveError?.message).toBe("Permission denied");
+    expect(result.current.error).toBe("Permission denied");
+    // Original content should not be updated on error
+    expect(result.current.originalContent).toBe("console.log('hello');");
+    expect(result.current.hasChanges).toBe(true);
+  });
+
+  it("clears content when filePath changes", async () => {
+    const firstResponse: FileContentResponse = {
+      content: "// file 1",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 10,
+    };
+    const secondResponse: FileContentResponse = {
+      content: "// file 2",
+      mtime: "2024-01-02T00:00:00Z",
+      size: 10,
+    };
+
+    mockFetchProjectFileContent
+      .mockResolvedValueOnce(firstResponse)
+      .mockResolvedValueOnce(secondResponse);
+
+    const { result, rerender } = renderHook(
+      ({ filePath }) => useProjectFileEditor("/project", filePath, true),
+      { initialProps: { filePath: "file1.ts" } }
+    );
+
+    await waitFor(() => expect(result.current.content).toBe("// file 1"));
+
+    // Change file
+    rerender({ filePath: "file2.ts" });
+
+    await waitFor(() => expect(result.current.content).toBe("// file 2"));
+  });
+
+  it("clears content when disabled", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result, rerender } = renderHook(
+      ({ enabled }) => useProjectFileEditor("/project", "src/index.ts", enabled),
+      { initialProps: { enabled: true } }
+    );
+
+    await waitFor(() => expect(result.current.content).toBe("console.log('hello');"));
+
+    // Disable
+    rerender({ enabled: false });
+
+    expect(result.current.content).toBe("");
+    expect(result.current.originalContent).toBe("");
+    expect(result.current.mtime).toBeNull();
+  });
+
+  it("clears error when content is edited", async () => {
+    mockFetchProjectFileContent.mockRejectedValueOnce(new Error("File not found"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/missing.ts", true));
+
+    await waitFor(() => expect(result.current.error).toBe("File not found"));
+
+    // Edit content should clear error
+    act(() => {
+      result.current.setContent("new content");
+    });
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it("shows saving state during save operation", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    const saveResponse: SaveFileResponse = {
+      success: true,
+      mtime: "2024-01-02T00:00:00Z",
+      size: 22,
+    };
+
+    let resolveSave: (value: SaveFileResponse) => void;
+    const savePromise = new Promise<SaveFileResponse>((resolve) => {
+      resolveSave = resolve;
+    });
+
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockReturnValueOnce(savePromise);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    // Start save
+    let savePromiseResolved = false;
+    act(() => {
+      result.current.save().then(() => {
+        savePromiseResolved = true;
+      });
+    });
+
+    expect(result.current.saving).toBe(true);
+
+    // Complete save
+    resolveSave!(saveResponse);
+    await waitFor(() => expect(savePromiseResolved).toBe(true));
+
+    expect(result.current.saving).toBe(false);
+  });
+
+  it("cancels in-flight fetch on unmount", async () => {
+    let resolveFetch: (value: FileContentResponse) => void;
+    const fetchPromise = new Promise<FileContentResponse>((resolve) => {
+      resolveFetch = resolve;
+    });
+    mockFetchProjectFileContent.mockReturnValueOnce(fetchPromise);
+
+    const { unmount } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    // Unmount before fetch completes
+    unmount();
+
+    // Complete the fetch after unmount
+    resolveFetch!({
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    });
+
+    // Wait a bit to ensure state update doesn't happen
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(mockFetchProjectFileContent).toHaveBeenCalledTimes(1);
+  });
+});
--- a/packages/dashboard/app/hooks/useProjectFileBrowser.ts
+++ b/packages/dashboard/app/hooks/useProjectFileBrowser.ts
@@ -0,0 +1,83 @@
+import { useState, useEffect, useCallback } from "react";
+import type { FileNode, FileListResponse } from "../api";
+import { fetchProjectFileList } from "../api";
+
+interface UseProjectFileBrowserReturn {
+  entries: FileNode[];
+  currentPath: string;
+  setPath: (path: string) => void;
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+}
+
+/**
+ * Hook for browsing files in the project root directory.
+ *
+ * @param rootPath - The project root directory path (from config/store)
+ * @param enabled - Whether to enable fetching (e.g., when modal is open)
+ * @returns File browser state and controls
+ */
+export function useProjectFileBrowser(rootPath: string, enabled: boolean): UseProjectFileBrowserReturn {
+  const [entries, setEntries] = useState<FileNode[]>([]);
+  const [currentPath, setCurrentPath] = useState<string>(".");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const refresh = useCallback(() => {
+    setRefreshKey((k) => k + 1);
+  }, []);
+
+  const setPath = useCallback((path: string) => {
+    setCurrentPath(path);
+    setError(null);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    let cancelled = false;
+
+    async function loadFiles() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response: FileListResponse = await fetchProjectFileList(
+          currentPath === "." ? undefined : currentPath
+        );
+
+        if (!cancelled) {
+          setEntries(response.entries);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setError(err.message || "Failed to load files");
+          setEntries([]);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    loadFiles();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [currentPath, enabled, refreshKey]);
+
+  return {
+    entries,
+    currentPath,
+    setPath,
+    loading,
+    error,
+    refresh,
+  };
+}
--- a/packages/dashboard/app/hooks/useProjectFileEditor.ts
+++ b/packages/dashboard/app/hooks/useProjectFileEditor.ts
@@ -0,0 +1,120 @@
+import { useState, useEffect, useCallback } from "react";
+import type { FileContentResponse, SaveFileResponse } from "../api";
+import { fetchProjectFileContent, saveProjectFileContent } from "../api";
+
+interface UseProjectFileEditorReturn {
+  content: string;
+  setContent: (content: string) => void;
+  originalContent: string;
+  loading: boolean;
+  saving: boolean;
+  error: string | null;
+  save: () => Promise<void>;
+  hasChanges: boolean;
+  mtime: string | null;
+}
+
+/**
+ * Hook for editing a file in the project directory.
+ *
+ * @param rootPath - The project root directory path (from config/store)
+ * @param filePath - The file path to edit (null if no file selected)
+ * @param enabled - Whether to enable loading (e.g., when editor is visible)
+ * @returns File editor state and controls
+ */
+export function useProjectFileEditor(
+  rootPath: string,
+  filePath: string | null,
+  enabled: boolean
+): UseProjectFileEditorReturn {
+  const [content, setContentState] = useState<string>("");
+  const [originalContent, setOriginalContent] = useState<string>("");
+  const [mtime, setMtime] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const setContent = useCallback((newContent: string) => {
+    setContentState(newContent);
+    setError(null);
+  }, []);
+
+  // Load file content when filePath changes
+  useEffect(() => {
+    if (!enabled || !filePath) {
+      setContentState("");
+      setOriginalContent("");
+      setMtime(null);
+      setError(null);
+      return;
+    }
+
+    let cancelled = false;
+
+    async function loadFile() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response: FileContentResponse = await fetchProjectFileContent(filePath!);
+
+        if (!cancelled) {
+          setContentState(response.content);
+          setOriginalContent(response.content);
+          setMtime(response.mtime);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setError(err.message || "Failed to load file");
+          setContentState("");
+          setOriginalContent("");
+          setMtime(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    loadFile();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [filePath, enabled]);
+
+  const hasChanges = content !== originalContent;
+
+  const save = useCallback(async () => {
+    if (!filePath || !hasChanges) {
+      return;
+    }
+
+    setSaving(true);
+    setError(null);
+
+    try {
+      const response: SaveFileResponse = await saveProjectFileContent(filePath, content);
+      setOriginalContent(content);
+      setMtime(response.mtime);
+    } catch (err: any) {
+      setError(err.message || "Failed to save file");
+      throw err;
+    } finally {
+      setSaving(false);
+    }
+  }, [filePath, content, hasChanges]);
+
+  return {
+    content,
+    setContent,
+    originalContent,
+    loading,
+    saving,
+    error,
+    save,
+    hasChanges,
+    mtime,
+  };
+}
--- a/packages/dashboard/src/file-service.ts
+++ b/packages/dashboard/src/file-service.ts
@@ -127,6 +127,14 @@ async function getTaskBasePath(store: TaskStore, taskId: string): Promise<string
  }
 }

+/**
+ * Get the project root path for browsing files.
+ * Returns the root directory from the store.
+ */
+function getProjectBasePath(store: TaskStore): string {
+  return resolve(store.getRootDir());
+}
+
 /**
 * Validate and resolve a file path to ensure it stays within the allowed directory.
 * Prevents directory traversal attacks.
@@ -382,3 +390,217 @@ export async function writeFile(
    throw err;
  }
 }
+
+// ── Project File Functions ────────────────────────────────────────
+
+/**
+ * List files in the project root directory or subdirectory.
+ *
+ * @param store - The TaskStore instance
+ * @param subPath - Optional relative path within the project directory
+ * @returns File listing response with entries sorted (dirs first, then files alphabetically)
+ * @throws FileServiceError on validation or filesystem errors
+ */
+export async function listProjectFiles(
+  store: TaskStore,
+  subPath?: string,
+): Promise<FileListResponse> {
+  const projectBase = getProjectBasePath(store);
+  const targetPath = subPath ? validatePath(projectBase, subPath) : projectBase;
+
+  let stats;
+  try {
+    stats = await stat(targetPath);
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`Directory not found: ${subPath || "."}`, "ENOENT");
+    }
+    throw err;
+  }
+
+  if (!stats.isDirectory()) {
+    throw new FileServiceError(`Not a directory: ${subPath || "."}`, "ENOTDIR");
+  }
+
+  try {
+    const entries = await readdir(targetPath, { withFileTypes: true });
+    const fileNodes: FileNode[] = [];
+
+    for (const entry of entries) {
+      // Skip hidden files and directories
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+
+      const entryPath = join(targetPath, entry.name);
+      const entryStats = await stat(entryPath);
+
+      fileNodes.push({
+        name: entry.name,
+        type: entry.isDirectory() ? "directory" : "file",
+        size: entry.isFile() ? entryStats.size : undefined,
+        mtime: entryStats.mtime.toISOString(),
+      });
+    }
+
+    // Sort: directories first, then files, both alphabetically
+    fileNodes.sort((a, b) => {
+      if (a.type !== b.type) {
+        return a.type === "directory" ? -1 : 1;
+      }
+      return a.name.localeCompare(b.name);
+    });
+
+    // Calculate relative path from project base
+    const relativeBase = relative(projectBase, targetPath);
+
+    return {
+      path: relativeBase || ".",
+      entries: fileNodes,
+    };
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`Directory not found: ${subPath || "."}`, "ENOENT");
+    }
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new FileServiceError(`Permission denied: ${subPath || "."}`, "EACCES");
+    }
+    throw err;
+  }
+}
+
+/**
+ * Read file contents from the project directory.
+ *
+ * @param store - The TaskStore instance
+ * @param filePath - The relative file path
+ * @returns File content response with content, mtime, and size
+ * @throws FileServiceError on validation or filesystem errors
+ */
+export async function readProjectFile(
+  store: TaskStore,
+  filePath: string,
+): Promise<FileContentResponse> {
+  if (!filePath) {
+    throw new FileServiceError("File path is required", "EINVAL");
+  }
+
+  const projectBase = getProjectBasePath(store);
+  const resolvedPath = validatePath(projectBase, filePath);
+
+  let stats;
+  try {
+    stats = await stat(resolvedPath);
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`File not found: ${filePath}`, "ENOENT");
+    }
+    throw err;
+  }
+
+  if (!stats.isFile()) {
+    throw new FileServiceError(`Not a file: ${filePath}`, "EISDIR");
+  }
+
+  if (stats.size > MAX_FILE_SIZE) {
+    throw new FileServiceError(`File too large: ${stats.size} bytes (max ${MAX_FILE_SIZE})`, "ETOOLARGE");
+  }
+
+  // Check if it's a binary file
+  const basename = filePath.split("/").pop() || filePath;
+  if (isBinaryFile(basename)) {
+    throw new FileServiceError(`Binary file, cannot edit: ${filePath}`, "EINVAL");
+  }
+
+  try {
+    const content = await fsReadFile(resolvedPath, "utf-8");
+
+    return {
+      content,
+      mtime: stats.mtime.toISOString(),
+      size: stats.size,
+    };
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`File not found: ${filePath}`, "ENOENT");
+    }
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new FileServiceError(`Permission denied: ${filePath}`, "EACCES");
+    }
+    throw err;
+  }
+}
+
+/**
+ * Write file contents to the project directory.
+ *
+ * @param store - The TaskStore instance
+ * @param filePath - The relative file path
+ * @param content - The content to write
+ * @returns Save file response with success, mtime, and size
+ * @throws FileServiceError on validation or filesystem errors
+ */
+export async function writeProjectFile(
+  store: TaskStore,
+  filePath: string,
+  content: string,
+): Promise<SaveFileResponse> {
+  if (!filePath) {
+    throw new FileServiceError("File path is required", "EINVAL");
+  }
+
+  // Check content size
+  const contentBytes = Buffer.byteLength(content, "utf-8");
+  if (contentBytes > MAX_FILE_SIZE) {
+    throw new FileServiceError(`Content too large: ${contentBytes} bytes (max ${MAX_FILE_SIZE})`, "ETOOLARGE");
+  }
+
+  const projectBase = getProjectBasePath(store);
+  const resolvedPath = validatePath(projectBase, filePath);
+
+  // Check if target is a directory
+  try {
+    const stats = await stat(resolvedPath);
+    if (stats.isDirectory()) {
+      throw new FileServiceError(`Cannot write to directory: ${filePath}`, "EISDIR");
+    }
+  } catch (err: any) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+    // File doesn't exist, that's fine for writing
+  }
+
+  // Check if parent directory exists
+  const parentDir = dirname(resolvedPath);
+  try {
+    const parentStats = await stat(parentDir);
+    if (!parentStats.isDirectory()) {
+      throw new FileServiceError(`Parent is not a directory: ${filePath}`, "ENOENT");
+    }
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`Parent directory does not exist: ${filePath}`, "ENOENT");
+    }
+    throw err;
+  }
+
+  try {
+    await fsWriteFile(resolvedPath, content, "utf-8");
+
+    const stats = await stat(resolvedPath);
+    return {
+      success: true,
+      mtime: stats.mtime.toISOString(),
+      size: stats.size,
+    };
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new FileServiceError(`Parent directory does not exist: ${filePath}`, "ENOENT");
+    }
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new FileServiceError(`Permission denied: ${filePath}`, "EACCES");
+    }
+    throw err;
+  }
+}
--- a/packages/dashboard/src/routes.ts
+++ b/packages/dashboard/src/routes.ts
@@ -9,7 +9,7 @@ import { GitHubClient, getCurrentGitHubRepo, parseBadgeUrl } from "./github.js";
 import { githubRateLimiter } from "./github-poll.js";
 import { terminalSessionManager } from "./terminal.js";
 import { getTerminalService } from "./terminal-service.js";
-import { listFiles, readFile, writeFile, FileServiceError, type FileListResponse, type FileContentResponse, type SaveFileResponse } from "./file-service.js";
+import { listFiles, readFile, writeFile, listProjectFiles, readProjectFile, writeProjectFile, FileServiceError, type FileListResponse, type FileContentResponse, type SaveFileResponse } from "./file-service.js";
 import { fetchAllProviderUsage } from "./usage.js";
 import {
  getGitHubAppConfig,
@@ -576,9 +576,10 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
      res.json({
        maxConcurrent: settings.maxConcurrent ?? options?.maxConcurrent ?? 2,
        maxWorktrees: settings.maxWorktrees ?? 4,
+        rootDir: store.getRootDir(),
      });
    } catch {
-      res.json({ maxConcurrent: options?.maxConcurrent ?? 2, maxWorktrees: 4 });
+      res.json({ maxConcurrent: options?.maxConcurrent ?? 2, maxWorktrees: 4, rootDir: store.getRootDir() });
    }
  });

@@ -2746,6 +2747,86 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
    }
  });

+  // ── Project File API Routes ───────────────────────────────────────
+
+  /**
+   * GET /api/files
+   * List files in project root directory.
+   * Query param: ?path=relative/path for subdirectory navigation.
+   * Returns: { path: string; entries: FileNode[] }
+   */
+  router.get("/files", async (req, res) => {
+    try {
+      const { path: subPath } = req.query;
+      const result = await listProjectFiles(store, typeof subPath === "string" ? subPath : undefined);
+      res.json(result);
+    } catch (err: any) {
+      if (err instanceof FileServiceError) {
+        const status = err.code === "ENOENT" ? 404
+          : err.code === "EACCES" ? 403
+          : 400;
+        res.status(status).json({ error: err.message, code: err.code });
+      } else {
+        res.status(500).json({ error: err.message || "Internal server error" });
+      }
+    }
+  });
+
+  /**
+   * GET /api/files/{*filepath}
+   * Read file contents from project directory.
+   * Returns: { content: string; mtime: string; size: number }
+   */
+  router.get("/files/{*filepath}", async (req, res) => {
+    try {
+      const filePath = Array.isArray(req.params.filepath) ? req.params.filepath[0] : req.params.filepath ?? "";
+      const result = await readProjectFile(store, filePath);
+      res.json(result);
+    } catch (err: any) {
+      if (err instanceof FileServiceError) {
+        const status = err.code === "ENOENT" ? 404
+          : err.code === "EACCES" ? 403
+          : err.code === "ETOOLARGE" ? 413
+          : err.code === "EINVAL" && err.message.includes("Binary file") ? 415
+          : 400;
+        res.status(status).json({ error: err.message, code: err.code });
+      } else {
+        res.status(500).json({ error: err.message || "Internal server error" });
+      }
+    }
+  });
+
+  /**
+   * POST /api/files/{*filepath}
+   * Write file contents to project directory.
+   * Body: { content: string }
+   * Returns: { success: true; mtime: string; size: number }
+   */
+  router.post("/files/{*filepath}", async (req, res) => {
+    try {
+      const filePath = Array.isArray(req.params.filepath) ? req.params.filepath[0] : req.params.filepath ?? "";
+      const { content } = req.body;
+      
+      if (typeof content !== "string") {
+        res.status(400).json({ error: "content is required and must be a string" });
+        return;
+      }
+
+      const result = await writeProjectFile(store, filePath, content);
+      res.json(result);
+    } catch (err: any) {
+      if (err instanceof FileServiceError) {
+        const status = err.code === "ENOENT" ? 404
+          : err.code === "EACCES" ? 403
+          : err.code === "ETOOLARGE" ? 413
+          : 400;
+        res.status(status).json({ error: err.message, code: err.code });
+      } else {
+        res.status(500).json({ error: err.message || "Internal server error" });
+      }
+    }
+  });
+
  // ── Planning Mode Routes ──────────────────────────────────────────────────

  /**