@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/tools/code-show.ts

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { readRange } from "../../operations/read-range.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { listProjectFiles } from "./git-files.js";
+import {
+  evaluatePrecisionPolicy,
+  getIndexedCommitCeilings,
+  listTrackedFilesAtRef,
+  loadFileContent,
+  normalizeRepoPath,
+  PrecisionSearchRequest,
+  type PrecisionSymbolMatch,
+  readRangeFromContent,
+  requireRepoPath,
+  resolveGitRef,
+  searchLiveSymbols,
+  searchWarpSymbols,
+} from "./precision.js";
+
+interface CodeShowOptions {
+  readonly allowWarp: boolean;
+}
+
+export async function runCodeShow(
+  ctx: ToolContext,
+  args: Record<string, unknown>,
+  options: CodeShowOptions,
+) {
+  const symbolName = args["symbol"] as string;
+  const rawPath = args["path"] as string | undefined;
+  const ref = args["ref"] as string | undefined;
+  const targetPath = rawPath !== undefined ? normalizeRepoPath(ctx.projectRoot, rawPath) : undefined;
+  const repoState = ctx.getRepoState();
+  const layer = ref !== undefined
+    ? "commit_worldline"
+    : repoState.dirty
+      ? "workspace_overlay"
+      : "ref_view";
+
+  let resolvedRef: string | undefined;
+  if (ref !== undefined) {
+    try {
+      resolvedRef = await resolveGitRef(ref, ctx.git, ctx.projectRoot);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      return ctx.respond("code_show", {
+        symbol: symbolName,
+        error: message,
+        source: "live",
+        layer,
+      });
+    }
+  }
+
+  let locations: PrecisionSymbolMatch[];
+  let source: "warp" | "live" = "live";
+
+  if (resolvedRef !== undefined) {
+    if (targetPath !== undefined) {
+      try {
+        requireRepoPath(ctx.projectRoot, targetPath);
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return ctx.respond("code_show", {
+          symbol: symbolName,
+          error: message,
+          source: "live",
+          layer,
+        });
+      }
+    }
+
+    try {
+      const repoPath = targetPath !== undefined ? requireRepoPath(ctx.projectRoot, targetPath) : undefined;
+      if (options.allowWarp) {
+        const warp = await ctx.getWarp();
+        const ceilings = await getIndexedCommitCeilings(warp);
+        const ceiling = ceilings.get(resolvedRef);
+        if (ceiling !== undefined) {
+          locations = await searchWarpSymbols(warp, new PrecisionSearchRequest({
+            exactName: symbolName,
+            ...(repoPath !== undefined ? { filePath: repoPath } : {}),
+            ceiling,
+          }));
+          source = "warp";
+        } else {
+          const filePaths = repoPath !== undefined
+            ? [repoPath]
+            : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
+          locations = await searchLiveSymbols(
+            ctx,
+            filePaths,
+            new PrecisionSearchRequest({ exactName: symbolName }),
+            resolvedRef,
+          );
+        }
+      } else {
+        const filePaths = repoPath !== undefined
+          ? [repoPath]
+          : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
+        locations = await searchLiveSymbols(
+          ctx,
+          filePaths,
+          new PrecisionSearchRequest({ exactName: symbolName }),
+          resolvedRef,
+        );
+      }
+    } catch {
+      const repoPath = targetPath !== undefined ? requireRepoPath(ctx.projectRoot, targetPath) : undefined;
+      const filePaths = repoPath !== undefined
+        ? [repoPath]
+        : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
+      locations = await searchLiveSymbols(
+        ctx,
+        filePaths,
+        new PrecisionSearchRequest({ exactName: symbolName }),
+        resolvedRef,
+      );
+      source = "live";
+    }
+  } else {
+    const filePaths = targetPath !== undefined
+      ? [targetPath]
+      : await listProjectFiles("", ctx.projectRoot, ctx.git);
+    locations = await searchLiveSymbols(
+      ctx,
+      filePaths,
+      new PrecisionSearchRequest({ exactName: symbolName }),
+    );
+  }
+
+  const visibleLocations: PrecisionSymbolMatch[] = [];
+  const fileCache = new Map<string, string>();
+  let firstRefusal:
+    | {
+      path: string;
+      reason: string;
+      reasonDetail: string;
+      next: readonly string[];
+      actual: { lines: number; bytes: number };
+    }
+    | undefined;
+
+  for (const location of locations) {
+    let content = fileCache.get(location.path);
+    if (content === undefined) {
+      const loaded = await loadFileContent(ctx, location.path, resolvedRef);
+      if (loaded === null) continue;
+      fileCache.set(location.path, loaded);
+      content = loaded;
+    }
+
+    const refusal = evaluatePrecisionPolicy(ctx, location.path, content);
+    if (refusal !== null) {
+      firstRefusal ??= refusal;
+      continue;
+    }
+
+    visibleLocations.push(location);
+  }
+
+  if (visibleLocations.length === 0) {
+    if (firstRefusal !== undefined) {
+      return ctx.respond("code_show", {
+        path: firstRefusal.path,
+        projection: "refused",
+        reason: firstRefusal.reason,
+        reasonDetail: firstRefusal.reasonDetail,
+        next: [...firstRefusal.next],
+        actual: firstRefusal.actual,
+        source,
+        layer,
+      });
+    }
+
+    return ctx.respond("code_show", {
+      symbol: symbolName,
+      error: `Symbol '${symbolName}' not found`,
+      source,
+      layer,
+    });
+  }
+
+  if (visibleLocations.length > 1) {
+    ctx.recordFootprint({
+      paths: [...new Set(visibleLocations.map((m) => m.path))],
+      symbols: visibleLocations.map((m) => m.name),
+    });
+    return ctx.respond("code_show", {
+      symbol: symbolName,
+      ambiguous: true,
+      matches: visibleLocations,
+      source,
+      layer,
+    });
+  }
+
+  const loc = visibleLocations[0];
+  if (loc?.startLine === undefined || loc.endLine === undefined) {
+    return ctx.respond("code_show", {
+      symbol: symbolName,
+      kind: loc?.kind,
+      signature: loc?.signature,
+      path: loc?.path,
+      exported: loc?.exported,
+      error: "Symbol found but line range unavailable — use read_range with file_outline",
+      source,
+      layer,
+    });
+  }
+
+  const content = fileCache.get(loc.path) ?? await loadFileContent(ctx, loc.path, resolvedRef);
+  if (content === null) {
+    return ctx.respond("code_show", {
+      symbol: symbolName,
+      error: `File '${loc.path}' is no longer readable`,
+      source,
+      layer,
+    });
+  }
+
+  const rangeResult = resolvedRef !== undefined
+    ? readRangeFromContent(loc.path, content, loc.startLine, loc.endLine)
+    : await readRange(ctx.resolvePath(loc.path), loc.startLine, loc.endLine, { fs: ctx.fs });
+
+  ctx.recordFootprint({
+    paths: [loc.path],
+    symbols: [loc.name],
+    regions: [{ path: loc.path, startLine: loc.startLine, endLine: loc.endLine }],
+  });
+
+  return ctx.respond("code_show", {
+    symbol: loc.name,
+    kind: loc.kind,
+    signature: loc.signature,
+    path: loc.path,
+    exported: loc.exported,
+    startLine: loc.startLine,
+    endLine: loc.endLine,
+    content: rangeResult.content,
+    truncated: rangeResult.truncated ?? false,
+    ...(rangeResult.clipped === true ? { clipped: true } : {}),
+    source,
+    layer,
+  });
+}
+
+export const codeShowTool: ToolDefinition = {
+  name: "code_show",
+  description:
+    "Focus on a symbol by name and return its source code in one call. " +
+    "Provide a path to target a specific file, or omit to search the " +
+    "project. Returns source, signature, and location.",
+  schema: {
+    symbol: z.string(),
+    path: z.string().optional(),
+    ref: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return (args, ctx) => runCodeShow(ctx, args, { allowWarp: true });
+  },
+};

package/src/mcp/tools/daemon-monitors.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const daemonMonitorsTool: ToolDefinition = {
+  name: "daemon_monitors",
+  description:
+    "List daemon-managed persistent repo monitors with lifecycle, backlog, and recent failure state.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      return ctx.respond("daemon_monitors", {
+        monitors: await ctx.listDaemonMonitors(),
+      });
+    };
+  },
+};

package/src/mcp/tools/daemon-repos.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const daemonReposTool: ToolDefinition = {
+  name: "daemon_repos",
+  description:
+    "List authorized canonical repos with bounded worktree, session, backlog, and monitor summary for daemon-wide inspection.",
+  schema: {
+    repoId: z.string().optional(),
+    cwd: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("daemon_repos", {
+        ...await ctx.listDaemonRepos({
+          repoId: args["repoId"] as string | undefined,
+          cwd: args["cwd"] as string | undefined,
+        }),
+      });
+    };
+  },
+};

package/src/mcp/tools/daemon-sessions.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const daemonSessionsTool: ToolDefinition = {
+  name: "daemon_sessions",
+  description:
+    "List active daemon sessions with bind state, workspace identity, and capability posture, without exposing session-local receipts or shell output.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      return ctx.respond("daemon_sessions", {
+        sessions: await ctx.listDaemonSessions(),
+      });
+    };
+  },
+};

package/src/mcp/tools/daemon-status.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const daemonStatusTool: ToolDefinition = {
+  name: "daemon_status",
+  description:
+    "Return daemon-wide health, authorization counts, and default capability posture for the local control plane.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      return ctx.respond("daemon_status", { ...await ctx.getDaemonStatus() });
+    };
+  },
+};

package/src/mcp/tools/diagnostic-models.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Diagnostic tool response models — explicit types for diagnostic tool outputs
+// ---------------------------------------------------------------------------
+
+import type { BurdenByKind, BurdenKind } from "../burden.js";
+import type { RuntimeObservabilityState } from "../runtime-observability.js";
+import type { RuntimeCausalContext } from "../runtime-causal-context.js";
+import type { GovernorDepth } from "../../session/types.js";
+import type {
+  PersistedLocalHistorySummary,
+  RepoConcurrencySummary,
+} from "../persisted-local-history.js";
+import type { RuntimeWorkspaceOverlayFooting } from "../runtime-workspace-overlay.js";
+import type { CausalSurfaceNextAction } from "../../contracts/causal-surface-next-action.js";
+
+export interface SetBudgetResponse {
+  readonly budget: {
+    readonly total: number;
+    readonly consumed: number;
+    readonly remaining: number;
+    readonly fraction: number;
+  } | null;
+}
+
+export interface StatsResponse {
+  readonly totalReads: number;
+  readonly totalOutlines: number;
+  readonly totalRefusals: number;
+  readonly totalCacheHits: number;
+  readonly totalBytesReturned: number;
+  readonly totalBytesAvoidedByCache: number;
+  readonly totalNonReadBytesReturned: number;
+  readonly burdenByKind: Readonly<BurdenByKind>;
+}
+
+export interface ExplainResponse {
+  readonly code: string;
+  readonly meaning?: string | undefined;
+  readonly action?: string | undefined;
+  readonly error?: string | undefined;
+  readonly knownCodes?: string | undefined;
+}
+
+export interface DoctorBurdenSummary {
+  readonly totalBytesReturned: number;
+  readonly totalNonReadBytesReturned: number;
+  readonly topKind: BurdenKind | null;
+  readonly topBytesReturned: number;
+  readonly topCalls: number;
+}
+
+export interface DoctorResponse {
+  readonly projectRoot: string;
+  readonly parserHealthy: boolean;
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth: GovernorDepth;
+  readonly totalMessages: number;
+  readonly burdenSummary: DoctorBurdenSummary;
+  readonly runtimeObservability: RuntimeObservabilityState;
+  readonly causalContext: RuntimeCausalContext;
+  readonly latestReadEvent: PersistedLocalHistorySummary["latestReadEvent"];
+  readonly latestStageEvent: PersistedLocalHistorySummary["latestStageEvent"];
+  readonly latestTransitionEvent: PersistedLocalHistorySummary["latestTransitionEvent"];
+  readonly repoConcurrency: RepoConcurrencySummary | null;
+  readonly checkoutEpoch: unknown;
+  readonly lastTransition: unknown;
+  readonly semanticTransition: unknown;
+  readonly workspaceOverlayId: unknown;
+  readonly workspaceOverlay: unknown;
+  readonly workspaceOverlayFooting: RuntimeWorkspaceOverlayFooting | null;
+  readonly stagedTarget: unknown;
+  readonly attribution: PersistedLocalHistorySummary["attribution"];
+  readonly persistedLocalHistory: PersistedLocalHistorySummary;
+  readonly recommendedNextAction: CausalSurfaceNextAction;
+}
+
+export interface RunCapturePolicyBoundary {
+  readonly kind: "shell_escape_hatch";
+  readonly boundedReadContract: false;
+  readonly policyEnforced: false;
+}
+
+export interface RunCaptureResponse {
+  readonly output: string;
+  readonly totalLines: number;
+  readonly tailedLines: number;
+  readonly logPath: string | null;
+  readonly logRedactions: number;
+  readonly logPersistenceEnabled: boolean;
+  readonly truncated: boolean;
+  readonly policyBoundary: RunCapturePolicyBoundary;
+  readonly disabled?: boolean | undefined;
+  readonly error?: string | undefined;
+  readonly stderr?: string | undefined;
+}

package/src/mcp/tools/doctor.ts

@@ -1,20 +1,66 @@
 import { STATIC_THRESHOLDS } from "../../policy/evaluate.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { topBurdenKind, totalNonReadBytesReturned } from "../burden.js";
+import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
+import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { DoctorResponse } from "./diagnostic-models.js";
 
 export const doctorTool: ToolDefinition = {
   name: "doctor",
   description:
     "Runtime health check. Shows project root, parser status, active " +
-    "thresholds, session depth, and message count.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return () => {
-      return ctx.respond("doctor", {
+    "thresholds, session depth, message count, and burden summary.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      const repoState = ctx.getRepoState();
+      const causalContext = ctx.getCausalContext();
+      const workspaceOverlayFooting = await ctx.getWorkspaceOverlayFooting();
+      const metrics = ctx.metrics.snapshot();
+      const topBurden = topBurdenKind(metrics.burdenByKind);
+      const persistedLocalHistory = await ctx.getPersistedLocalHistorySummary();
+      const repoConcurrency = await ctx.getRepoConcurrencySummary();
+      const recommendedNextAction = deriveCausalSurfaceNextAction(
+        persistedLocalHistory.nextAction,
+        repoState.semanticTransition,
+        repoConcurrency,
+      );
+      const response: DoctorResponse = {
         projectRoot: ctx.projectRoot,
         parserHealthy: true,
         thresholds: { lines: STATIC_THRESHOLDS.lines, bytes: STATIC_THRESHOLDS.bytes },
-        sessionDepth: ctx.session.getSessionDepth(),
-        totalMessages: ctx.session.getMessageCount(),
-      });
+        sessionDepth: ctx.governor.getGovernorDepth(),
+        totalMessages: ctx.governor.getMessageCount(),
+        burdenSummary: {
+          totalBytesReturned: metrics.bytesReturned,
+          totalNonReadBytesReturned: totalNonReadBytesReturned(metrics.burdenByKind),
+          topKind: topBurden?.kind ?? null,
+          topBytesReturned: topBurden?.bytesReturned ?? 0,
+          topCalls: topBurden?.calls ?? 0,
+        },
+        runtimeObservability: ctx.observability,
+        causalContext,
+        latestReadEvent: persistedLocalHistory.latestReadEvent,
+        latestStageEvent: persistedLocalHistory.latestStageEvent,
+        latestTransitionEvent: persistedLocalHistory.latestTransitionEvent,
+        repoConcurrency,
+        checkoutEpoch: repoState.checkoutEpoch,
+        lastTransition: repoState.lastTransition,
+        semanticTransition: repoState.semanticTransition,
+        workspaceOverlayId: repoState.workspaceOverlayId,
+        workspaceOverlay: repoState.workspaceOverlay,
+        workspaceOverlayFooting,
+        stagedTarget: buildRuntimeStagedTarget(
+          ctx.getWorkspaceStatus(),
+          causalContext,
+          repoState,
+          persistedLocalHistory.attribution,
+        ),
+        attribution: persistedLocalHistory.attribution,
+        persistedLocalHistory,
+        recommendedNextAction,
+      };
+      return ctx.respond("doctor", toJsonObject(response));
     };
   },
 };

package/src/mcp/tools/explain.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const EXPLANATIONS: Readonly<Record<string, { meaning: string; action: string }>> = {
   CONTENT: {
@@ -38,6 +38,10 @@ const EXPLANATIONS: Readonly<Record<string, { meaning: string; action: string }>
     meaning: "File exceeds the budget-proportional byte cap. No single read may consume more than 5% of remaining budget.",
     action: "Use file_outline or read_range for targeted reads. Consider whether this file is worth the budget cost.",
   },
+  UNSUPPORTED_LANGUAGE: {
+    meaning: "The file type has no parser-backed structural outline in the current build of Graft.",
+    action: "Use read_range or a full read when appropriate. Do not treat the empty outline as parser-derived symbol structure.",
+  },
   GRAFTIGNORE: {
     meaning: "File matches a pattern in .graftignore.",
     action: "Check .graftignore if you believe this file should be readable.",
@@ -58,8 +62,8 @@ export const explainTool: ToolDefinition = {
     "Explain a graft reason code. Returns human-readable meaning and " +
     "recommended next action for any reason code returned by graft tools.",
   schema: { code: z.string() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
+  createHandler(): ToolHandler {
+    return (args, ctx) => {
       const code = (args["code"] as string).toUpperCase();
       const entry = EXPLANATIONS[code];
       if (entry === undefined) {

package/src/mcp/tools/file-outline.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
 import { fileOutline } from "../../operations/file-outline.js";
+import { detectStructuredFormat } from "../../parser/lang.js";
 import { hashContent } from "../cache.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
 
 export const fileOutlineTool: ToolDefinition = {
   name: "file_outline",
@@ -10,23 +12,30 @@ export const fileOutlineTool: ToolDefinition = {
     "exports. Includes a jump table mapping each symbol to its line range " +
     "for targeted read_range follow-ups.",
   schema: { path: z.string() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  policyCheck: true,
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const filePath = ctx.resolvePath(args["path"] as string);
+      ctx.recordFootprint({ paths: [filePath] });
 
       // Check cache
       let rawContent: string | null = null;
       try {
-        rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+        rawContent = await ctx.fs.readFile(filePath, "utf-8");
       } catch {
         // proceed to fileOutline for error handling
       }
 
-      if (rawContent !== null) {
+      const outlineSupported = detectStructuredFormat(filePath) !== null;
+
+      if (rawContent !== null && outlineSupported) {
         const cacheResult = ctx.cache.check(filePath, rawContent);
         if (cacheResult.hit) {
           cacheResult.obs.touch();
           ctx.metrics.recordCacheHit(cacheResult.obs.actual.bytes);
+          ctx.recordFootprint({
+            symbols: cacheResult.obs.outline.map((e) => e.name),
+          });
           return ctx.respond("file_outline", {
             path: filePath,
             outline: cacheResult.obs.outline,
@@ -39,9 +48,10 @@ export const fileOutlineTool: ToolDefinition = {
 
       const result = await fileOutline(filePath, { fs: ctx.fs });
       ctx.metrics.recordOutline();
+      ctx.recordFootprint({ symbols: result.outline.map((e) => e.name) });
 
       // Record observation
-      if (rawContent !== null) {
+      if (rawContent !== null && outlineSupported && result.reason !== "UNSUPPORTED_LANGUAGE") {
         ctx.cache.record(
           filePath,
           hashContent(rawContent),
@@ -51,7 +61,7 @@ export const fileOutlineTool: ToolDefinition = {
         );
       }
 
-      return ctx.respond("file_outline", result);
+      return ctx.respond("file_outline", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/git-files.ts

@@ -0,0 +1,73 @@
+import type { GitClient } from "../../ports/git.js";
+
+type GitFileListMode = "tracked" | "project";
+
+export class GitFileQuery {
+  readonly cwd: string;
+  readonly dirPath: string;
+  readonly mode: GitFileListMode;
+
+  constructor(opts: {
+    cwd: string;
+    dirPath: string;
+    mode: GitFileListMode;
+  }) {
+    if (opts.cwd.trim().length === 0) {
+      throw new Error("GitFileQuery: cwd must be non-empty");
+    }
+    this.cwd = opts.cwd;
+    this.dirPath = opts.dirPath.trim();
+    this.mode = opts.mode;
+    Object.freeze(this);
+  }
+
+  static tracked(cwd: string, dirPath: string): GitFileQuery {
+    return new GitFileQuery({ cwd, dirPath, mode: "tracked" });
+  }
+
+  static project(cwd: string, dirPath: string): GitFileQuery {
+    return new GitFileQuery({ cwd, dirPath, mode: "project" });
+  }
+
+  toArgs(): string[] {
+    if (this.mode === "tracked") {
+      return this.dirPath.length > 0 ? ["ls-files", "--", this.dirPath] : ["ls-files"];
+    }
+
+    return this.dirPath.length > 0
+      ? ["ls-files", "--cached", "--others", "--exclude-standard", "--", this.dirPath]
+      : ["ls-files", "--cached", "--others", "--exclude-standard"];
+  }
+}
+
+export class GitFileList {
+  readonly paths: readonly string[];
+
+  constructor(paths: readonly string[]) {
+    this.paths = Object.freeze([...paths]);
+    Object.freeze(this);
+  }
+}
+
+export async function listGitFiles(query: GitFileQuery, git: GitClient): Promise<GitFileList> {
+  try {
+    const result = await git.run({ args: query.toArgs(), cwd: query.cwd });
+    if (result.error !== undefined || result.status !== 0) {
+      throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
+    }
+    const output = result.stdout.trim();
+    const paths = output.length === 0 ? [] : output.split("\n");
+    return new GitFileList(paths);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`git file listing failed: ${message}`, { cause: err });
+  }
+}
+
+export async function listTrackedFiles(dirPath: string, cwd: string, git: GitClient): Promise<string[]> {
+  return [...(await listGitFiles(GitFileQuery.tracked(cwd, dirPath), git)).paths];
+}
+
+export async function listProjectFiles(dirPath: string, cwd: string, git: GitClient): Promise<string[]> {
+  return [...(await listGitFiles(GitFileQuery.project(cwd, dirPath), git)).paths];
+}